Recovery: Coordination Branch Declared but Worktree Missing
spec-kitty agent context resolve / agent tasks map-requirements fail with
StatusReadPathNotFound, or spec-kitty doctor coordination reports a
COORDINATION_WORKTREE_NEVER_CREATED or COORDINATION_WORKTREE_MISSING
finding.
Why this happens
The mission’s meta.json carries a coordination_branch key, but the
.worktrees/<slug>-<mid8>-coord/ worktree was never created — commonly
because all planning happened on a separate feature branch instead of
through the coordination worktree. Read resolvers intentionally fail closed
rather than silently read stale primary status when coord topology is
declared but its authority surface is absent.
Lead with the shipped fix
Diagnose first:
spec-kitty doctor coordinationThis distinguishes two sub-cases:
-
The declared coordination branch was never created (or was deleted).
--fixhandles this automatically — it removes the stalecoordination_branchkey frommeta.jsonand re-derives topology:Terminal window spec-kitty doctor coordination --fix --mission <mission-handle>--fixrepairs only the Missions you name.--fix --all-missionssweeps every Mission; without--missionor--all-missionsit refuses withCOORDINATION_FIX_SCOPE_REQUIREDand changes nothing. -
The branch exists but the worktree was never materialized.
doctor coordinationprints the exact recreate command in its finding:Terminal window git -C <repo-root> worktree add .worktrees/<slug>-<mid8>-coord kitty/mission-<slug>
If you don’t want coordination for this mission
If you never intended to use the coordination worktree (all planning already
lives on a plain feature branch), flatten instead of recreating: remove any
already-materialized coord worktree, then drop the coordination_branch key
and re-derive topology.
git worktree remove --force .worktrees/<slug>-<mid8>-coord # if it existsEdit kitty-specs/<mission>/meta.json to remove coordination_branch, then:
spec-kitty migrate backfill-topologyRe-run spec-kitty agent mission finalize-tasks --mission <handle> to
re-bootstrap canonical status on the primary checkout.
Order matters: removing coordination_branch from meta.json is not
enough by itself — the read resolver returns the coord worktree whenever it
exists on disk, checked before the meta.json field is even read. Remove
the worktree first (or in the same pass), or reads keep silently going to the
stale coord copy.
Related
- Stale lane seed after re-finalizing tasks
- Coord-branch bookkeeping root-cause
- Recovery & Troubleshooting (agent-facing) — implementation-crash and merge recovery