045 — tp story call stops a story for a human, and tp story answer releases it (#247)

Status: in progress Roadmap: #234

Why

At code level 3 an agent works alone only while the story holds (agent flow). When it does not (the build cannot be made green, the acceptance turns out wrong, the work needs more than the story says) the agent calls: it stops, and the reason goes on the issue, where the overview puts the story at the front. tp has no way to record that. An agent that stops leaves nothing behind, and the next one to ask tp story query is told to land the story.

What changes

  • tp story call [-undefined] REASON... (new): on a story branch at code level 3, comments the reason on the story's issue and labels it called. -undefined also takes defined off: the acceptance was wrong and the story goes back to refinement.
  • tp story answer [TEXT...] (new): takes called off, with TEXT as a comment when given.
  • tp story query at level 3 reports a called story as called, the next step the human's.
  • docs/story.md, docs/idea.md (the label table).

Acceptance

Both commands at maturity.code: 3, on a branch story/<n>-<slug>:

Command Issue #n Outcome
tp story call REASON... open, labelled story comment Called: REASON; called added; prints #n called
tp story call -undefined REASON... open, labelled story and defined the same, and defined removed
tp story call REASON... labelled called already a second comment; the label stays
tp story call with no reason any error: a call gives its reason; no comment, no label
tp story call REASON... not labelled story, or closed error giving its labels or state; no comment
tp story answer labelled called called removed; prints #n answered
tp story answer TEXT... labelled called the same, with the comment Answered: TEXT
tp story answer not labelled called error: it is not called; nothing changed
either any, below code level 3 error naming the level
either any, on a branch not story/<n>-<slug> error: run it on the story's branch

tp story query at level 3, on a story branch that has not landed:

Issue #n Stands Next step Who
labelled called called answer the call on #n, then tp story answer human
not labelled called as today as today as today
the forge not asked (-offline) as today as today as today

Out of scope

  • tp story land refusing a called story: with the agent's merge (#235).
  • How a call reaches the human beyond the label; the overview.
  • Deciding when to call: that is the agent's judgement, by the manual's table.

Decisions

None. The comment is written before the label, so a called story is never without its reason.

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