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 query under trunk flow reports the release from any branch, read from the remote base branch. Off the base branch it adds one line naming tp 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 query leaves "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 land waiting for the build and the merge (#211).
  • The manual's "planned" notes and ~/.claude/CLAUDE.md, which name tp release query as 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