Skip to content

Both commit reviews receive the operator note and the stamp binds it #929

Description

@tbhb-agent

Problem

review.sh --note <file> gives the reviewer a decision the operator made and the reason. The initial review already snapshots the note, hashes it and records its digest in the stamp (packages/agents/source/skills/commit/shared/scripts/review.sh). The second review that commit.sh runs after its gates does not receive the note, and the commit's stamp validation does not check the note binding, so the two passes can disagree about the same draft and tree and a changed or removed note is not detected (#380). The missing behavior is the second pass reading the same retained note snapshot as the first, and the commit validating the note binding against that snapshot. The snapshot is the exact-head evidence of what the first reviewer saw; the original note file can change afterwards and is not evidence.

Part of #588 and #321. Fixes #380.

Acceptance criteria

  1. AC1: Given an initial review run with a note, when the second review runs inside the commit, then the reviewer receives text byte-identical to what the first review's reviewer received, and the caller supplies no note again.
  2. AC2: Given a passing review stamped with a note, when the original note file is changed or deleted before the second review runs, then the second review still receives the retained snapshot's bytes and the commit proceeds.
  3. AC3: Given a passing review stamped with a note, when the retained snapshot is changed or removed before the commit validates the stamp, then the commit refuses and a new review is required.
  4. AC4: Given a run with no note, when the commit reviews twice, then no note is passed to either review and the stamp verifies as before.
  5. AC5: Given a stamp fixture written by an older binary that has no note binding at all, when it is checked with no note present, then it still verifies.
  6. AC6: Given a consumer binary that lacks the replacement, when the wrapper runs, then it falls back to the frozen shell behavior and the N-2 compatibility policy holds; and given a present replacement that fails, then the commit refuses with no fallback to the shell and no usable stamp is left.
  7. AC7: Non-functional: within one review, the note is read once and its digest is computed from the same bytes the reviewer receives.

Scope and non-goals

Scope: both reviews of the commit workflow receive the same retained note snapshot, the stamp binds the snapshot's digest, and the commit validates that binding. The original note file is read once, by the first review.

Non-goal: the pull request and merge reviews, which also accept notes (packages/agents/source/skills/pr/shared/scripts/review.sh, packages/agents/source/skills/merge-pr/shared/scripts/review.sh) and stay out of scope for this issue. Non-goal: a caller-supplied note on the commit invocation. Non-goal: changing the stamp format for runs without a note. Non-goal: removing the shell fallback.

Approach

Meet AC1 to AC7 with failing cases first. The mechanism is the implementer's choice within those outcomes.

Dependencies

Blocked by: #769 (review snapshots and stamps), #753 (golden-file protection for the Go enforcement paths, before enforcement switches into Go).

Size

S. One pull request.

Verify plan

  • AC1: a test of the whole commit workflow, through its generated entry point, with a stub reviewer that records its inputs across both passes and a commit invocation that carries no note.
  • AC2: a test that changes, then deletes, the original note file after the first pass and checks the second pass input and the commit result.
  • AC3: tests that change, then remove, the retained snapshot after a pass and run the commit validation.
  • AC4: a no-note workflow run through the generated entry point.
  • AC5: a stamp fixture that has no note binding at all, built by hand and not produced by the current shell, checked with no note present.
  • AC6: a Bats case that runs the wrapper against a binary stub without the subcommand, and a case against a stub replacement that exits non-zero, asserting the refusal and that no stamp is usable.
  • AC7: a test that changes the note file between the read and the review and asserts the digest matches what the reviewer saw.
  • Definition of done: D1 each AC is verified at the merged head, with the commands and results cited in the pull request's Verification. D2 an independent review approves the exact merged head, and every finding has a recorded disposition. D3 required checks pass with no gate loosened. D4 the leak scans the repository specifies are clean, and every post made for this work passes the per-post leak review before it is posted. D5 every commit is signed. D6 the documentation matches the change or the Verification says why there is no impact. D7 every commit has an Assisted-by trailer and the pull request has the provenance:agent-assisted label. D8 the pull request stays within the size limits. D9 follow-ups are filed as issues and listed under Related. D10 the merge closes the issue through a closing reference, the board shows Done, and the final Status: comment names the merge commit.

Risks

A stamp that binds the note invalidates reviews in flight at upgrade. Undo: revert the change, which restores the current stamp behavior.

Operator authority

None.

Activity

  1. tbhb-agent commented on Oct 27, 2026

    @tbhb-agent
    ContributorAuthor

    Refinement: READY — Both commit reviews receive the operator note and the stamp binds it
    Model: gpt-6-astra

    Child 03 Both commit reviews receive the operator note and the stamp binds it

    Verdict: READY

    Checked: The retained-snapshot decision and verification remain sufficient against packages/agents/source/skills/commit/shared/scripts/review.sh:81 and packages/agents/source/skills/commit/shared/scripts/commit.sh:134. Gaps: None. Split: None.

    Definition of done

    The definition of done for this issue (Feature). Tick each item and give its evidence.

    • D1 The author verified each AC on the merged head, and the Verification section of the pull request cites each AC ID with its evidence: the command and its result, or a link.
    • D2 An independent reviewer approved the exact merged head, and the author resolved each finding or filed it as a follow-up.
    • D3 The required checks pass on that head, and any loosened gate has the owner's approval of that exact head.
    • D4 The leak scans come back clean: gitleaks, devtools' check-leaks.sh with the repository's private-strings list, and the leak review of each post.
    • D5 The author signed each commit, the squash included.
    • D6 The docs match the change (README, docs/, CHANGELOG or help text), or the Verification section says "No doc impact" and why.
    • D7 The commits and the squash have Assisted-by trailers, and the pull request has the provenance:agent-assisted label.
    • D8 The pull request stays within the size limits, or the owner approved its exact head over the hard limit.
    • D9 The author files follow-ups and deferred findings as issues with at least a Problem and numbered AC and lists them under the Related section of the pull request. Any work left in the code links its issue.
    • D10 The merge closes the issue through a closing reference and the board shows Done. The final Status: comment names the merge commit.
    • devtools-1 mise run check is green, and so are the coverage floors mise run cover-go-check and mise run cover-py-check, which check doesn't run.
    • devtools-2 A change to skill sources under packages/agents/source/ commits what mise run generate-skills, then mise run skill-tokens, then apm install rewrite, in that order, and check-generated-skills (part of lint) passes.
    • devtools-3 A consumer-visible change (the vendored payload, a skill, a reusable workflow, a task or a pin) has its consumer steps in docs/agent-skills-migration.md or the adoption docs, or the PR's Verification says "No consumer impact" and why.

    Round: 1 of 3

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    refinement:readyPassed the Definition of Ready; may be picked up

    Fields

    Priority

    None yet

    Work type

    None yet

    Projects

    • Status
      Backlog

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions