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 land at level 3 refuses a story that is called or not defined. 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 query at 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 main after 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