write the worktree lifecycle contract into the design doc #89

New Issue

2026-08-24T09:38:54+01:00

naps62-yolo commented

2026-08-24 09:38:54 +01:00

Six Spawn v2 review rounds each re-decided the worktree lifecycle, and five of them had their worst finding in it. There is no written contract for this area: DESIGN.md covers the web visual system, and CLAUDE.md describes the architecture without saying what happens to a worktree.

Write it down. Either a new section in CLAUDE.md or a docs/WORKTREES.md that CLAUDE.md points at — whichever the person landing this judges better, but it must be reachable from CLAUDE.md, since that is what an agent reads first.

It should state, in the repo's terse register:

Nothing is ever adopted; a collision is sidestepped with a numeric suffix (#77).
Where worktrees are placed, and what the worktree_root override changes.
What blocks a kill, and explicitly that ignored files do not (#79).
That --force ends the session and keeps the tree, and why those are two separate acts (#81).
What a natural exit does (#82).
What the retained store is for, and that it is not an ownership record (#78).
What reclaim does and does not touch — the directory, never the branch (#80).

Write the reasoning for the non-obvious rules, not just the rules. The decisions that got re-litigated were the ones whose justification lived only in a review comment.

Depends on: #77, #78, #79, #81, #82, #80

Six Spawn v2 review rounds each re-decided the worktree lifecycle, and five of them had their worst finding in it. There is no written contract for this area: DESIGN.md covers the web visual system, and CLAUDE.md describes the architecture without saying what happens to a worktree. Write it down. Either a new section in CLAUDE.md or a `docs/WORKTREES.md` that CLAUDE.md points at — whichever the person landing this judges better, but it must be reachable from CLAUDE.md, since that is what an agent reads first. It should state, in the repo's terse register: - Nothing is ever adopted; a collision is sidestepped with a numeric suffix (#77). - Where worktrees are placed, and what the `worktree_root` override changes. - What blocks a kill, and explicitly that ignored files do not (#79). - That `--force` ends the session and keeps the tree, and why those are two separate acts (#81). - What a natural exit does (#82). - What the retained store is for, and that it is not an ownership record (#78). - What reclaim does and does not touch — the directory, never the branch (#80). Write the reasoning for the non-obvious rules, not just the rules. The decisions that got re-litigated were the ones whose justification lived only in a review comment. Depends on: #77, #78, #79, #81, #82, #80

naps62-yolo added this to the Worktree lifecycle milestone 2026-08-24 09:38:54 +01:00

naps62-yolo added the type/docs difficulty/easy labels 2026-08-24 09:38:54 +01:00

naps62-yolo added a new dependency 2026-08-24 09:39:01 +01:00

#77 worktrees: sidestep path collisions with a numeric suffix, never adopt

naps62-yolo added a new dependency 2026-08-24 09:39:01 +01:00

#78 daemon: persist a retained-worktree store in state_dir

naps62-yolo added a new dependency 2026-08-24 09:39:01 +01:00

#79 daemon: refuse a kill when the session's worktree holds unsaved work

naps62-yolo added a new dependency 2026-08-24 09:39:01 +01:00

#81 kill --force ends the session and retains the worktree

naps62-yolo added a new dependency 2026-08-24 09:39:01 +01:00

#82 daemon: apply the same worktree rule when a session exits on its own

naps62-yolo added a new dependency 2026-08-24 09:39:01 +01:00

#80 daemon: GET /api/worktrees plus a reclaim endpoint

naps62-yolo referenced this issue from a commit

2026-08-24 10:29:43 +01:00

docs(maestro): write the worktree lifecycle contract

naps62-yolo commented

2026-08-24 10:29:55 +01:00

Landed first, on blitz/worktree-lifecycle as 35c75f9, rather than last.

The dependency edges said this issue needed every implementation issue to exist before it could describe them. That ordering is what let six Spawn v2 review rounds each re-decide the same rules — there was no shared written model for a worker to read, so each one inferred a slightly different one from the code in front of it.

Inverting it: docs/WORKTREES.md now states the contract, CLAUDE.md points at it, and every worker on this milestone reads it before implementing. The issues become the schedule for making the code match a document that already exists.

If implementation turns up a rule the document gets wrong, the document is what gets amended — in the same commit as the code, not afterwards.

Landed first, on `blitz/worktree-lifecycle` as 35c75f9, rather than last. The dependency edges said this issue needed every implementation issue to exist before it could describe them. That ordering is what let six Spawn v2 review rounds each re-decide the same rules — there was no shared written model for a worker to read, so each one inferred a slightly different one from the code in front of it. Inverting it: `docs/WORKTREES.md` now states the contract, CLAUDE.md points at it, and every worker on this milestone reads it before implementing. The issues become the schedule for making the code match a document that already exists. If implementation turns up a rule the document gets wrong, the document is what gets amended — in the same commit as the code, not afterwards.