0011 — A review is a comment on the story's issue, standing while the story's change is unchanged

Status: accepted Date: 2026-11-15 Story: stories/046-at-code-level-3-a-review-is-a-comment-on-the-story.md

Context

At code level 3 an agent merges a story once reviewing agents have passed it. The merge needs a record to stand on: without one the agent merges on its own word, and a human looking afterwards cannot see what was checked. The manual left the record open ("probably on the pull request, one record per concern").

Two things had to be settled: where the record lives, and when a pass stops counting. The second matters because tp story land merges the base branch into the story whenever it has moved, so the branch's tip changes each time another story lands.

Options

Where the record lives:

Option Complexity Testability Domain clarity Operational risk
A. A comment on the story's issue, written by tp the comment API tp has; a first line to parse text, the forge behind the existing fake the issue is the story's one thread, from idea to release, and holds a call's reason too nothing on the forge enforces it
B. A commit status per concern a second API on two forges a new fake bound to the commit by the forge; branch protection could require it carries one line, not the findings; a status is on the commit, so every merge of the base loses it
C. An approval of the pull request the forge's review API a new fake the forge's own notion of review developer and reviewer share an account, which a forge may not let approve its own pull request (not tested)

When a pass goes stale:

Option Complexity Testability Domain clarity Operational risk
D. On any new commit none: compare the tip one row simple to state every landing sends every other open story back to review
E. When the story's own change differs: its diff from where it left the base a fingerprint of that diff rows for a clean merge, new work, a conflict the review is of the change, which is what the reviewer read a pass can outlive a change in the code around it

Decision

A and E. tp story review CONCERN pass|fail writes the comment; its first line names the concern, the verdict, the change and the commit, and the findings follow. The change is named by a hash of git diff base...HEAD with blob ids and hunk positions left out, so it is the same before and after a clean merge of the base. The concerns are reviews: in task-plus.yml, [story] when absent. tp story land merges the story's pull request when the latest review of every concern passes the change now on the branch, and refuses a story that is called or not defined before doing anything.

Consequences

Easier: one place to read what happened to a story. Stories in flight do not invalidate one another's reviews. A fail is kept as history.

Harder: the gate is tp's, not the forge's: a human, or a comment typed by hand, can pass it, and with one token for developer and reviewer a forge-side gate would be no stronger. A change beside the story's own lines makes a review stale though the story did not change, which errs towards another review. What a pass can miss, code that moved under the story, is left to the checks, which run on the merged tip, and to the human's review of main after the fact.

A commit status can be added beside the comment if a project wants its forge to refuse the merge; the comment stays the record.