053 — At code level 3 a story is written and built in a worktree of its own (#193)

Roadmap: #193

Why

At level 3 several stories are in flight at once: one being interviewed, others being built or reviewed by agents. tp idea story writes the story file into whatever checkout it is run in, and the branch is then cut by hand, so one checkout is switched from story to story. An interview of five ideas switched it ten times, each switch a chance to scaffold on the wrong branch, carry an uncommitted file across, or cut from a main nobody pulled.

tp wt gives a worktree, but for the flow before the ladder: a WT-prefixed task branch, and a wt clean that merges locally into whatever the main checkout has out. At level 3 the branch is story/<N>-<slug>, cut from the remote base, and the merge is the forge's. The worktree is the story's, so the story's commands make and remove it.

What changes

  • tp idea story N [TITLE]: fetches the release remote, cuts story/<N>-<slug> from its base branch in a new worktree beside the main checkout, <repo>-<N>-<slug>, and writes the story file there, with the sandbox .claude/settings.json that tp wt start writes. The checkout it is run in is not written to. It prints the story's path.
  • tp story tidy: removes the worktree and the local branch of every story that has landed on the base branch.
  • tp story query: a landed story's tidy step names tp story tidy.
  • tp wt start, review and clean at level 3: refused, naming tp idea story and tp story tidy.
  • docs/idea.md, docs/story.md, docs/worktrees.md, and the "ready" row of CLAUDE.md.

Acceptance

maturity.code: 3. The slug is the story file's. "Beside the main checkout" holds from wherever the command is run, another story's worktree included.

tp idea story N [TITLE], issue N open and labelled idea or roadmap:

Run from story/<N>-<slug> and <repo>-<N>-<slug> Outcome
the main checkout, on the base branch, clean neither exists the worktree made on the branch, cut from the remote base's tip; the story file and the sandbox settings in it; the issue relabelled story; the path printed
the main checkout, its base branch behind the remote neither exists the same: cut from the remote's tip, the local base not moved
a story's worktree, or a tree with uncommitted changes neither exists the same; where it was run is as it was
any the branch exists, local or on the remote error naming it; no worktree, no file, the issue's labels unchanged
any the directory exists error naming it; the same
any neither exists, the fetch failing error; the same
any the worktree made, the forge refusing the label error naming the worktree and the label, as story 043 does the file

tp story tidy, run in any checkout or worktree of the repository:

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
not in the remote base any untouched, not named
none landed — says so
Command Outcome
tp story query on a landed story the tidy step is tp story tidy, run from the main checkout
tp wt start, review, clean error naming tp idea story N and tp story tidy
tp wt list, agent, dashboard; tp claude as today
any of these at maturity.code 0 or 1 as today: tp idea story and tp story tidy are refused, tp wt is as it was

Out of scope

  • Level 1: tp wt there is left as it is.
  • Opening VS Code on the worktree, and tp wt agent and the dashboard finding a story's worktree: they take a WT task name still.
  • Starting a builder in the worktree once the story is defined.
  • Adopting a worktree Claude Code made under .claude/worktrees/.
  • Story numbers from the issue, the third point of #193: story 051.
  • The roadmap line's worktree: story 052, built on this one.
  • Removing the remote branch: the forge does, when the pull request merges.

Decisions

None.

Done when

  • tests express the acceptance table and pass
  • spec updated
  • changelog entry
  • issue closed with a link to the release