280 — Accept a story from tp overview: tp story offer puts it on the forge, the card links it and a button defines it (#280)
Roadmap: #280
Why
A story not yet defined is what most needs the human, and the board
(#279) shows it as a card with a title and nothing to do. To accept it
they find the worktree, read the file there, and tell an agent or a
terminal tp story define. The file is in the worktree alone until
tp story land pushes the branch, so the board cannot even link to it.
Two things are missing. The agent has no way to say "this story is written, read it": the moment exists, and nothing records it. And the human, looking at the card, has no way to read the story and say yes from where they are.
What changes
tp story offer, on a story branch at code level 3: checks the acceptance has no blank cell, commits the story file if it has changed, pushes the branch to the release remote and prints the story's page on the forge. Nothing else of the working tree is committed. No label is written: a story is offered when its file, on its branch on the forge, has its acceptance filled.tp overview, a card in "Not yet defined" whose story branch is on the forge with the story file: a link, "story", to the file as the forge shows it; and, when its acceptance is filled, an "accept" button.- The button does what
tp story definedoes, against the forge's copy: it checks the story again and adds the labeldefined, then shows the board, the card now in "In development". It is the first thing on the page that writes to a forge, with the token oftoken_env; the form carries a secret made whentp overviewstarts, so that no other page can press it. tp story queryon a story not yet defined: the human's step names the overview besidetp story define, andtp story offeras what puts the story there.docs/story.md,docs/overview.md, theCLAUDE.mdtable.
Acceptance
tp story offer. The story file is the one in docs/stories/ whose
heading carries the branch's issue.
| Level | Branch | Story file | Acceptance | The file, against the branch on the remote | Outcome |
|---|---|---|---|---|---|
| below 3 | any | — | — | — | error: offered at code level 3 |
| 3 | not story/<n>-<slug> |
— | — | — | error: run it on the story's branch |
| 3 | story | none | — | — | error naming tp idea story |
| 3 | story | present | a blank cell, or no table | any | error naming the file; nothing committed, nothing pushed |
| 3 | story | present | filled | untracked or changed in the working tree | the file alone committed, the branch pushed, the story's URL on the forge printed |
| 3 | story | present | filled | committed, the branch not on the remote or behind the local one | the branch pushed; the URL printed |
| 3 | story | present | filled | the same as the remote's | says it is offered already; the URL printed; nothing pushed |
| 3 | story | present | filled | any, with other files changed or untracked | as the rows above; the other files neither committed nor touched |
| 3 | story | present | filled | any, the push refused | error; the commit stands |
A card in "Not yet defined" on the board, for story N of a level 3
repository. The story file is the one tp idea story wrote, on the
branch story/<N>-<slug>: docs/stories/<NNN>-<slug>.md, NNN being N
to three digits or more.
| Branch on the forge | Story file on it | Acceptance | The card |
|---|---|---|---|
| none | — | — | as #279: no link, no button |
| present | absent | — | as #279 |
| present | present | a blank cell, or no table | the link "story"; no button |
| present | present | filled | the link "story" and the button "accept" |
| present | present | filled, the story flagged blocked | the same, and the flag |
Cards in the other columns have neither.
Pressing "accept" on the card of story N:
| The request | The story on the forge, read again | Issue N | Outcome |
|---|---|---|---|
| the page's form | filled | open, story, not defined |
defined added; the board shown, the card in "In development" |
| the page's form | filled | defined already |
nothing written; the board shown |
| the page's form | a blank cell now, or the file or branch gone | any | nothing written; the page says why, with a way back to the board |
| the page's form | filled | closed, or not story |
nothing written; the page says why |
| the page's form | filled | open, story, the forge refusing the label |
the page says why, the forge's words included |
| without the page's secret, or with another's | any | any | refused; nothing written |
| not a POST | any | any | refused; nothing written |
under a host name other than this machine's own (localhost, 127.0.0.1, ::1), the board's page included |
any | any | refused; nothing written (review of #288) |
| the page's form | filled, the repository no longer at level 3 | any | nothing written; the page says why (review of #288) |
| Command | Outcome |
|---|---|
tp story query, the story not defined |
the human's step: accept the story on tp overview or with tp story define; tp story offer named as what puts it on the overview |
Out of scope
- Showing the story's text or its acceptance tables on
tp's own page: the link goes to the forge. - A link to the story from cards in the other columns.
- Taking an acceptance back from the page (
tp story call -undefineddoes). - A label or a column for "offered", and
tp story querytelling an offered story from one that is not. - Refusing anything at the limit.
Decisions
none
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