Skip to content

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:

Terminal window
spec-kitty doctor coordination

This distinguishes two sub-cases:

  • The declared coordination branch was never created (or was deleted). --fix handles this automatically — it removes the stale coordination_branch key from meta.json and re-derives topology:

    Terminal window
    spec-kitty doctor coordination --fix --mission <mission-handle>

    --fix repairs only the Missions you name. --fix --all-missions sweeps every Mission; without --mission or --all-missions it refuses with COORDINATION_FIX_SCOPE_REQUIRED and changes nothing.

  • The branch exists but the worktree was never materialized. doctor coordination prints 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.

Terminal window
git worktree remove --force .worktrees/<slug>-<mid8>-coord # if it exists

Edit kitty-specs/<mission>/meta.json to remove coordination_branch, then:

Terminal window
spec-kitty migrate backfill-topology

Re-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.