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.