tp story

Development-method stories (see the method): one file per story in docs/stories/NNN-slug.md, tracked by one issue on the release remote's Forgejo.

Command Does Prints
tp story new TITLE... writes the next story from the template, status proposed the new file's path
tp story issue NNN creates the story's issue and stamps (#N) onto its heading #N url
tp story offer at code level 3, on a story branch: the story is written and ready for the human. Commits the story file alone if it has changed and pushes the branch, once its acceptance has no blank cell #N offered, then the story's page on the forge
tp story accept at code level 3, on a story branch: labels the story's issue defined once its acceptance has no blank cell #N defined
tp story review CONCERN pass|fail [-body FILE|-] at code level 3, on a story branch: records a review of the story's change as a comment on its issue #N CONCERN: pass (change ID)
tp story call [-undefined] REASON... at code level 3, on a story branch: comments the reason on the story's issue and labels it called #N called
tp story answer [TEXT...] takes called off, with TEXT as a comment #N answered
tp story land [-dry-run] under trunk flow (maturity.flow: trunk, or code level 3), on a story branch: merges the remote base branch in when it has moved, runs the checks, pushes and opens the pull request into the base branch, titled by the story's fragment; at code level 3 it then merges the pull request once its reviews pass each step, then the pull request and Next step (human): merge it; at level 3 the reviews wanting, or Story #N has landed
tp story query [-offline] under trunk flow, on a story branch or in its worktree: reads the repository and the forge and changes nothing the story, where it stands, Next step with who takes it, and Not ready
tp story tidy at code level 3, in any checkout of the repository: removes the worktree and the local branch of every story that has landed on the base branch each landed story, with what was removed or why it was kept

Numbering — one above the highest NNN-*.md in docs/stories/, starting at 001. The slug is the title's lower-case words joined by hyphens, cut at a word boundary to 50 characters.

At code level 3 a story takes its issue's number instead (story 051), padded to three digits: tp idea story 261 writes 261-slug.md, headed # 261 — TITLE (#261), and tp idea story 7 writes 007-slug.md. The forge hands issue numbers out, so two stories scaffolded before either lands cannot share one. The highest number in docs/stories/ is not read; a file that already has the number is refused by name, to be renamed. Stories numbered before story 051 keep their numbers: a story is found by the (#N) on its heading, whatever its file's number.

The issue is titled Story NNN: <title>. Its body is the first paragraph of the story's Why section and a link to the file on the current branch — push the story for the link to resolve. The file is the source of truth; the issue is only ever written from it. issue refuses a story that already has an issue or has no Why paragraph, and leaves the file untouched if the forge call fails. Forge and token are resolved as for tp issue.

At code level 3 new and issue are refused: a story is the issue of the idea it came from, written by tp idea story N, with no **Status:** line (story 043).

Accepting a story (story 043)

A defined story can be built without a conversation: no blank cell in its acceptance, and its soft acceptance already judged by a human (agent flow). tp story accept records the human's acceptance as the label defined on the story's issue, beside story. It can check the first half only; run it when the human has accepted the story. The story is the one in docs/stories/ whose heading carries the branch's issue.

Branch Story file for #n Acceptance Issue #n Outcome
any — — — below code level 3: error
not story/<n>-<slug> — — — error: run it on the story's branch
story none — — error naming tp idea story
story present a blank cell, or no table any error naming the file; the forge not asked
story present every cell of every table filled labelled story defined added
story present filled labelled defined already says so; nothing changed
story present filled not labelled story, or closed error

Offering a story (story 280)

A story is written in its worktree, and until tp story land the forge has none of it, so the human can read it only where it was written. tp story offer is the agent saying "this is ready for you": it puts the story on the forge, where tp overview links it from its card and offers to accept it. No label is written: a story is offered when its file, on its branch on the forge, has its acceptance filled. Offer again after the story changes.

Branch Story file for #n Acceptance The file, against the branch on the remote Outcome
any — — — below code level 3: error
not story/<n>-<slug> — — — error: run it on the story's branch
story none — — error naming tp idea story
story present a blank cell, or no table any error naming the file; nothing committed, nothing pushed
story present filled untracked or changed the file alone committed, "Story n: offered"; the branch pushed; the story's URL printed
story present filled committed, the branch not on the remote or behind the branch pushed; the URL printed
story present filled the branch on the remote where the local one is says it is offered already; the URL printed
story present filled any, the push refused error; the commit stands

Other files, staged or not, are neither committed nor touched. The push is of the branch, so work already committed on it goes too.

Calling for a human (story 045)

An agent works alone only while the story holds. When it does not, it calls: it stops, and says why (when an agent calls). tp story call records the call where an overview reads it: the reason as a comment on the story's issue, Called: REASON, then the label called. The comment is written first, so a called story is never without its reason. When to call is the agent's judgement; tp only records it. tp story answer is run once the human has answered; the human can answer from the story's card on tp overview instead, which does the same against the forge and starts an agent to carry on.

Command Issue #n Outcome
call REASON... open, labelled story the comment; called added
call -undefined REASON... open, labelled story the same, and defined removed: the acceptance was wrong, and the story goes back to refinement until tp story accept
call REASON... labelled called already a second comment; the label stays
call with no reason any error; nothing written
call REASON... not labelled story, or closed error; no comment
answer [TEXT...] labelled called called removed; TEXT, when given, commented as Answered: TEXT
answer not labelled called error; nothing changed
either below code level 3, or on a branch not story/<n>-<slug> error

A called story is not abandoned and not merged. tp story query reports it as called with the next step the human's, in place of the step that would land it.

Landing a story (story 032)

tp story land is the story's half of trunk flow (ADR 0008): it integrates, and decides no version. The release is a separate run on the base branch (release workflow).

Branch State Outcome
any code level 1 without maturity.flow: trunk, or code level 0 error naming the key
the base branch any error: land runs on a story branch
not story/<n>-<slug> any error naming the form
story working tree dirty error
story release on the remote error: a batch is in flight
story no changes/<n>.<kind>.md error naming the file to add
story CHANGELOG names an untagged version error: land takes no release commits
story already in the base branch says so; nothing pushed
story its last pull request closed without merging error: reopen it or close the story
story its pull request open into another branch error: retarget or close it
story base has moved, conflicts the merge is left in progress and the files named; resolve, commit, run again
story otherwise base merged in if it has moved; checks; push; the pull request into the base opened, or reused when open

Checks that modify a tracked file fail, naming the files (story 036): nothing is pushed, and the changes stay in the working tree, since they are usually what the story should have committed.

The checks are skipped when the pull request is open and the branch tip is the one they last passed on. merge_wait is not read: the run ends at the open pull request.

Review and the agent's merge (story 046)

At code level 3 no human is needed between a defined story and its landing (ADR 0011): a reviewing agent passes the change and tp story land merges it. The review is a comment on the story's issue, where a call's reason is too, so the issue is the story's one thread. tp story review writes it; its first line is what tp story land reads back:

Review story: pass — change 3f9a1c0b7d2e4a51 at 1a2b3c4d5e6f

Every row of the acceptance is met; the docs name the new flag.

The concerns are reviews: in task-plus.yml, a list of names; absent, it is [story], the change against its story, so a level 3 project is never merged unreviewed. The latest review of a concern is the one that counts.

A review stands while the story's change is the one it reviewed: the diff from where the branch left the base branch to its tip, read without line numbers. Merging the base in cleanly leaves that diff as it was, so one story landing does not send every other back to review; new work, or a conflict resolved, changes it. A change next to the story's own lines changes it too. The checks run again on the merged tip either way.

tp story review CONCERN pass|fail Outcome
CONCERN in reviews:, the tree clean, pass the comment on #n, with the -body findings when given
the same, fail with findings the comment, with fail
fail with no findings error: a fail says what is wrong
CONCERN not in reviews:; a verdict neither pass nor fail error; no comment
uncommitted changes error: a review is of what is committed
no change against the base error: nothing to review
below code level 3; not a story branch; the issue closed or not a story error; no comment

tp story land at code level 3, after the rows of Landing a story:

Issue #n Reviews Outcome
labelled called any error: it waits for a human; nothing merged in, pushed or opened
not labelled defined any error naming tp story accept; nothing pushed or opened
defined, not called every concern's latest review passes and stands checks, push, pull request, then the pull request merged: Story #n has landed on main
defined, not called a concern not reviewed, failed, or stale (its pass was of another change) checks, push, pull request; not merged; each concern wanting is named with tp story review
defined, not called pass and stand, the forge refusing the merge error naming the pull request, which stays open
any any, -dry-run says whether it would merge; nothing pushed, opened or merged

tp is the only writer of a review by convention, as of the labels: developer and reviewer share a token, so the forge cannot tell a review from a comment typed to look like one.

Where a story stands (story 039)

tp story query is the story's query, as tp release query is the release's (release workflow); neither reads the other's facts. Run it before acting and do what it says. It fetches the release remote first; -offline skips the fetch and the forge. The report is Mode, Story: #n on story/<n>-<slug> with its open pull request, Stands, 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 with its fragment committed, released in vX released in vX tidy: git switch main && git branch -d the branch; at code level 3 tp story tidy, run from the main checkout agent
in the base branch with its fragment committed, untagged landed on main the same: its release is not the story's step agent
at code level 3, its issue labelled called (story 045; the forge not asked with -offline) called answer the call on #n, then tp story answer human
at code level 3, its issue not labelled defined (story 048; the labels not read with -offline, or when the issue is not open) not defined accept the story on #n: on tp overview, where tp story offer puts it, or with tp story accept human
in the base branch, no changes/<n>.<kind>.md committed: just cut from it not begun commit the story's work and its fragment 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 not pushed tp story land agent
commits not pushed N commit(s) not pushed tp story land agent
no pull request not in a pull request tp story land agent
the base has moved and conflicts with it in conflict with main tp story land: merges the base in and stops at the conflicts agent
the base has moved, no conflict behind main by N tp story land: merges the base in, runs the checks, pushes agent
the tip is not the commit the checks last passed on unbuilt tp story land: runs the checks agent
at code level 3, its pull request open, a concern not reviewed, failed or stale (story 046) in review: CONCERN: not reviewed review the change and record it with tp story review agent
at code level 3, its pull request open, every review passing and standing reviewed tp story land: merges it 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

A story behind the base goes back through tp story land, so that what is merged was built on the current trunk. The commit the checks passed on is recorded by tp story land in the repository's git config, so a fresh clone of a built branch reads as unbuilt until it is landed again.

Not ready: a dirty tree, release on the remote, a hand-edited [Unreleased], a .tp-release-comment, a missing fragment, commits not pushed.

Run Outcome
on the base branch error: run it on a story branch or in its worktree
code level 1 without maturity.flow: trunk, or code level 0 error naming the key

Tidying landed stories (story 053)

At code level 3 a story is written and built in a worktree of its own, which tp idea story makes. tp story tidy removes what the stories that have landed left on this machine: it fetches the release remote and, for every local story/<n>-<slug> branch that is in the remote base branch with its fragment committed, removes the branch's worktree and deletes the branch. It is run in any checkout or worktree of the repository and reads no forge. The remote branch is the forge's to remove, when the pull request merges.

Story's branch Its worktree Outcome
in the remote base clean the worktree removed, the local branch deleted; the story named
in the remote base uncommitted or untracked changes kept, and named with why
in the remote base the one the command is run in kept, and named with the main checkout to run it from
in the remote base none: a branch in the main checkout, not checked out the local branch deleted
in the remote base none: the branch the main checkout has out kept, and named with the switch to the base branch that frees it
in the remote base its directory deleted by hand kept, and named with git worktree prune, after which the branch has no worktree; the stories after it are still tidied
not in the remote base any untouched, not named
in the remote base, no fragment committed: just cut from it any the same: it has not landed
none landed — says so

"Clean" is what git status reports: no uncommitted and no untracked change. Ignored files do not count, so a landed worktree that holds only ignored files, build output for one, is removed with them.

The sandbox .claude/settings.json that tp idea story writes is kept out of git status by a line in the repository's info/exclude. Git reads that file from the repository, not from each worktree, so the line applies in every checkout of it, the main one included.

Below code level 3 it is refused: there the tidy step is the one tp story query names.

What is not built yet

The manual's trunk flow page is the specification of the cycle; tp does not yet do all of it.

Planned Does Until then
publishing on landing (#221) the documentation is published from the tip of main once a story's pull request merges tp pages deploy by hand, or the next tp release