<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/operations/coord-worktree-missing/">
  <id>https://docs.spec-kitty.ai/operations/coord-worktree-missing/</id>
  <title>Recovery: Coordination Branch Declared but Worktree Missing</title>
  <updated>2026-11-11T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/operations/coord-worktree-missing/"/>
  <summary>Recovery when a mission&apos;s meta.json declares coordination_branch but the -coord worktree was never created, using spec-kitty doctor coordination --fix.</summary>
  <content type="html">&lt;span id=&quot;recovery-coordination-branch-declared-but-worktree-missing&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent context resolve&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;agent tasks map-requirements&lt;/code&gt; fail with
&lt;code dir=&quot;auto&quot;&gt;StatusReadPathNotFound&lt;/code&gt;, or &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor coordination&lt;/code&gt; reports a
&lt;code dir=&quot;auto&quot;&gt;COORDINATION_WORKTREE_NEVER_CREATED&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;COORDINATION_WORKTREE_MISSING&lt;/code&gt;
finding.&lt;/p&gt;
&lt;h2 id=&quot;why-this-happens&quot;&gt;Why this happens&lt;/h2&gt;
&lt;p&gt;The mission’s &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; carries a &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; key, but the
&lt;code dir=&quot;auto&quot;&gt;.worktrees/&amp;#x3C;slug&gt;-&amp;#x3C;mid8&gt;-coord/&lt;/code&gt; 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.&lt;/p&gt;
&lt;h2 id=&quot;lead-with-the-shipped-fix&quot;&gt;Lead with the shipped fix&lt;/h2&gt;
&lt;p&gt;Diagnose first:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;doctor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;coordination&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;This distinguishes two sub-cases:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The declared coordination branch was never created (or was deleted).&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;--fix&lt;/code&gt; handles this automatically — it removes the stale
&lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; key from &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; and re-derives topology:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;doctor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;coordination&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--fix&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;mission-handle&gt;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;--fix&lt;/code&gt; repairs only the Missions you name. &lt;code dir=&quot;auto&quot;&gt;--fix --all-missions&lt;/code&gt; sweeps
&lt;strong&gt;every&lt;/strong&gt; Mission; without &lt;code dir=&quot;auto&quot;&gt;--mission&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;--all-missions&lt;/code&gt; it refuses with
&lt;code dir=&quot;auto&quot;&gt;COORDINATION_FIX_SCOPE_REQUIRED&lt;/code&gt; and changes nothing.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The branch exists but the worktree was never materialized.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;doctor coordination&lt;/code&gt; prints the exact recreate command in its finding:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-C&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;repo-root&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;add&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.worktrees/&amp;#x3C;slug&gt;-&amp;#x3C;mid8&gt;-coord&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;kitty/mission-&amp;#x3C;slug&gt;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;if-you-dont-want-coordination-for-this-mission&quot;&gt;If you don’t want coordination for this mission&lt;/h2&gt;
&lt;p&gt;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 &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; key
and re-derive topology.&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;remove&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--force&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.worktrees/&amp;#x3C;slug&gt;-&amp;#x3C;mid8&gt;-coord&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;   &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# if it exists&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Edit &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;mission&gt;/meta.json&lt;/code&gt; to remove &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt;, then:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;migrate&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;backfill-topology&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Re-run &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent mission finalize-tasks --mission &amp;#x3C;handle&gt;&lt;/code&gt; to
re-bootstrap canonical status on the primary checkout.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Order matters:&lt;/strong&gt; removing &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; from &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; is not
enough by itself — the read resolver returns the coord worktree whenever it
exists on disk, checked &lt;em&gt;before&lt;/em&gt; the &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; field is even read. Remove
the worktree first (or in the same pass), or reads keep silently going to the
stale coord copy.&lt;/p&gt;
&lt;h2 id=&quot;related&quot;&gt;Related&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/operations/stale-lane-seed/&quot;&gt;Stale lane seed after re-finalizing tasks&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/docs/archive/plans/engineering-notes/coord-splitbrain-rootcause.md&quot;&gt;Coord-branch bookkeeping root-cause&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/recovery/&quot;&gt;Recovery &amp;#x26; Troubleshooting (agent-facing)&lt;/a&gt; — implementation-crash and merge recovery&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
