046 — At code level 3 a review is a comment on the story's issue and tp story land merges on it (#249)
Status: in progress Roadmap: #235
Why
At code level 3 no human is needed between a defined story and its
landing: reviewing agents pass the change, and the agent merges
(agent flow).
tp story land stops at the open pull request and hands the merge to a
human, and nothing records that a review happened, so an agent that
merged would be merging on its own word. The manual left open how a
passed review is recorded.
What changes
task-plus.yml:reviews:, the concerns a story is reviewed for at level 3. Absent, it is[story]: the change against its story.tp story review CONCERN pass|fail [-body FILE|-](new): on a story branch, records a review as a comment on the story's issue, its first line naming the concern, the verdict, the change reviewed and the commit. The reviewer gives its findings as the body.tp story landat level 3 refuses a story that iscalledor notdefined. After the push and the pull request it reads the reviews: when every concern's latest review passes and still stands it merges the pull request; otherwise it says which reviews are wanting.tp story queryat level 3 reports a story in a pull request as wanting review, or reviewed, the step the agent's either way.docs/story.md;docs/adr/0011.
Acceptance
A review stands while the story's change is the one reviewed: the diff from where the branch left the base to its tip. A clean merge of the base keeps it; new work, or a conflict resolved, does not.
tp story review CONCERN pass|fail, at maturity.code: 3, on a branch
story/<n>-<slug>:
| Concern | Verdict | Tree | Outcome |
|---|---|---|---|
in reviews: |
pass |
clean | comment on #n: Review CONCERN: pass — change ID at COMMIT, then the body when given; prints #n CONCERN: pass |
in reviews: |
fail, with a body |
clean | the same with fail; the body says what is wrong |
in reviews: |
fail, no body |
clean | error: a fail says what is wrong; no comment |
not in reviews: |
any | any | error naming the concerns; no comment |
in reviews: |
neither pass nor fail |
any | error; no comment |
in reviews: |
any | uncommitted changes | error: commit first; no comment |
in reviews: |
any | no change against the base | error: nothing to review |
| any | any | below level 3, another branch, issue not a story or closed |
error; no comment |
tp story land at maturity.code: 3; the rows of story 032 apply
first:
| Issue #n | Reviews, per concern in reviews: |
Outcome |
|---|---|---|
labelled called |
any | error: called, waits for a human; nothing merged in, pushed or opened |
not labelled defined |
any | error naming tp story define; nothing pushed or opened |
defined, not called |
every latest review passes and stands | checks, push, pull request; then the pull request merged; Story #n has landed |
defined, not called |
a concern has no review | checks, push, pull request, not merged; names the concern and tp story review |
defined, not called |
a concern's latest review fails | not merged; names it as failed |
defined, not called |
a concern's latest review passed another change | not merged; names it as stale |
defined, not called |
passed, then the base merged in cleanly | merged: the reviews stand |
defined, not called |
all pass and stand, the forge refuses the merge | error naming the pull request; it stays open |
| any | any, -dry-run |
says what it would do; nothing merged |
Below level 3 tp story land ends at the open pull request, as today.
tp story query at level 3, the story in an open pull request, built
and level with the base:
| Reviews | Stands | Next step | Who |
|---|---|---|---|
| a concern not reviewed, failed or stale | in review: CONCERN: not reviewed (or failed, stale) |
review it and record the review with tp story review |
agent |
| every concern passes and stands | reviewed |
tp story land: merges it |
agent |
the forge not asked (-offline) |
as today | as today | human |
Out of scope
- The reviewer itself: a role or skill that reads the change and the
story and calls
tp story review. A minimal one is written beside this story, outside the repository. - Which concerns every project has; critical code; the human's review
of
mainafter the fact. - Keeping a hand-written comment from passing for a review: developer and reviewer share a token, so the forge cannot tell them apart.
- Publishing the documentation after the merge (#221).
Decisions
ADR 0011:
the review is a comment on the issue, written by tp; it stands while
the story's own change is unchanged.
Done when
- tests express the acceptance table and pass
- spec updated
- ADR written if a fork was resolved
- roadmap ticked and stamped; changelog entry
- issue closed with a link to the release