039 — tp story query reports where a story stands (#225)
Status: in progress Roadmap: #214
Why
The manual gives each act its own query
(method):
tp story query for a story, tp release query for the release,
neither knowing the other. tp has only the second, which answers for
the story when it is run on a story branch (story 034). So one command
gives two unrelated reports by where it is run, the release cannot be
asked about from a story branch, and the story report cannot say two
things the manual asks of it: that the story is unbuilt, or behind
main.
What changes
tp story query [-offline] [-dir DIR](new): under trunk flow, on a story branch or in its worktree, reports where the story stands and the one next step. It changes nothing.- Two states are new. Unbuilt: the branch tip is not the commit the
checks last passed on in this checkout. Behind: the base branch has
commits the story has not merged in. Either sends the story back
through
tp story land, so what a human merges was built on the current trunk. tp release queryunder trunk flow reports the release from any branch, read from the remote base branch. Off the base branch it adds one line namingtp story query, and leaves out the "Not ready" lines that describe the checkout (dirty tree,[Unreleased],.tp-release-comment): the release is not made from there.docs/story.md: the command and its table;tp story queryleaves "What is not built yet".docs/release-workflow.md: the story table goes, the release table stays.
Acceptance
tp story query on a branch other than the base. The report opens with
Mode, Story: #n on <branch> with its open pull request, and
Stands:; it closes with Next step and Not ready. The first
matching row wins.
| State | Stands | Next step | Who |
|---|---|---|---|
not named story/<n>-<slug> |
— | rename the branch | agent |
| in the base branch, no fragment committed: just cut from it | not begun | commit the story's work and its fragment | agent |
| in the base branch, released in vX | released in vX | tidy: switch to the base, delete the branch | agent |
| in the base branch, untagged | landed | the same | agent |
| its CHANGELOG names an untagged version | — | revert the release commits | agent |
no changes/<n>.<kind>.md |
— | add the fragment | agent |
| its pull request open into another branch | — | retarget or close it | human |
| not on the remote, commits not pushed, or no pull request | not pushed, N commit(s) not pushed, or not in a pull request | tp story land |
agent |
| the base has moved and conflicts with it | in conflict with the base | tp story land: merges the base in and stops at the conflicts |
agent |
| the base has moved, no conflict | behind the base by N | tp story land: merges the base in, builds, pushes |
agent |
| the tip is not the commit the checks passed on | unbuilt | tp story land: runs the checks |
agent |
| its pull request open | in pull request #p | review and merge it | human |
pushed, the forge not asked (-offline) |
pushed | review and merge its pull request | human |
Where it does not apply:
| Run | Outcome |
|---|---|
| on the base branch | error: run it on a story branch or in its worktree; tp release query reports the release |
without maturity.flow: trunk, or at code level 0 |
error naming the key |
tp release query under trunk flow:
| Run | Reports |
|---|---|
| on the base branch | as today (story 034) |
| on any other branch | the same release report and next step; a line naming tp story query for this branch; "Not ready" only for what is not the checkout's (release on the remote) |
| batch flow, code level 0 | unchanged |
Out of scope
- "Landed, site behind
main": it needs the published site to record its commit, and publishing on landing (#221). - A story's steps before it has a branch (
tp story new,issue), and asking about a story from another branch by its number. tp story landwaiting for the build and the merge (#211).- The manual's "planned" notes and
~/.claude/CLAUDE.md, which nametp release queryas the agent's query on a story branch.
Decisions
None recorded as an ADR; two choices were made with the user:
tp release query reports the release from any branch instead of
refusing or still answering for the story, and a story behind the base
goes back through tp story land instead of being merged as it is.
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