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 define does, against the forge's copy: it checks the story again and adds the label defined, 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 of token_env; the form carries a secret made when tp overview starts, so that no other page can press it.
  • tp story query on a story not yet defined: the human's step names the overview beside tp story define, and tp story offer as what puts the story there.
  • docs/story.md, docs/overview.md, the CLAUDE.md table.

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 -undefined does).
  • A label or a column for "offered", and tp story query telling 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