<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/operations/start-branch-coord-divergence/">
  <id>https://docs.spec-kitty.ai/operations/start-branch-coord-divergence/</id>
  <title>Recovery: --start-branch Coordination Divergence</title>
  <updated>2026-08-15T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/operations/start-branch-coord-divergence/"/>
  <summary>Recovery when agent mission create &lt;mission_slug&gt; --start-branch plus coord topology diverges the coordination branch from the primary planning commit, blocking every lane claim.</summary>
  <content type="html">&lt;h2 id=&quot;recovery-start-branch-coordination-divergence&quot;&gt;Recovery: —start-branch Coordination Divergence&lt;/h2&gt;
&lt;p&gt;Every &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent action implement WP##&lt;/code&gt; claim fails with an add/add
conflict on &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;, even after re-finalizing tasks.&lt;/p&gt;
&lt;h2 id=&quot;why-this-happens&quot;&gt;Why this happens&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent mission create &amp;#x3C;mission_slug&gt; --start-branch &amp;#x3C;start-branch&gt;&lt;/code&gt; (pr-bound) plus
coord topology produces a coordination branch (&lt;code dir=&quot;auto&quot;&gt;kitty/mission-&amp;#x3C;slug&gt;&lt;/code&gt;) that
does &lt;strong&gt;not&lt;/strong&gt; contain the primary planning commit: coord branches from the
old base and gets its own planning snapshot, while spec/plan/tasks and
&lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; land on &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;start-branch&gt;&lt;/code&gt;. Lanes seed from coord and merge the
primary &lt;code dir=&quot;auto&quot;&gt;planning_commit_sha&lt;/code&gt; — an add/add conflict on &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; (it
embeds the SHA) on every claim. Re-finalizing does not converge: the
allocator regenerates coord’s snapshot on each claim, and re-finalize
re-captures &lt;code dir=&quot;auto&quot;&gt;planning_commit_sha&lt;/code&gt; against the tip &lt;em&gt;before&lt;/em&gt; its own commit —
a self-inconsistent loop. Root cause: &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 split-brain
root-cause&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Contributing footgun:&lt;/strong&gt; never &lt;code dir=&quot;auto&quot;&gt;git add&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; on the primary branch of a coord-topology mission —
they are coord-authority under this topology. &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; has no merge
driver, so it is the first hard conflict layer if you do. Note that
&lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; itself commits &lt;code dir=&quot;auto&quot;&gt;status.*&lt;/code&gt; to primary under coord topology —
that is a known split-brain seed, not something you did wrong.&lt;/p&gt;
&lt;h2 id=&quot;no-shipped---fix-for-this-case&quot;&gt;No shipped &lt;code dir=&quot;auto&quot;&gt;--fix&lt;/code&gt; for this case&lt;/h2&gt;
&lt;p&gt;There is no &lt;code dir=&quot;auto&quot;&gt;doctor&lt;/code&gt; subcommand for coord/primary divergence of this shape.
&lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor coordination --fix&lt;/code&gt; only removes stale
&lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; keys and fast-forwards simple Gap-1 staleness — it does
not reconcile two branches that both hold independent planning commits.&lt;/p&gt;
&lt;h2 id=&quot;manual-fix-operator-approved&quot;&gt;Manual fix (operator-approved)&lt;/h2&gt;
&lt;p&gt;Reconcile coord FROM the start branch — merge the start branch into the
coord branch, not the other way round. (&lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor coordination&lt;/code&gt;
prints the exact &lt;code dir=&quot;auto&quot;&gt;.worktrees/&amp;#x3C;slug&gt;-&amp;#x3C;mid8&gt;-coord&lt;/code&gt; path for your mission —
use that instead of hand-constructing it.)&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;.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;merge&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;start-branch&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;Spec Kitty’s union merge drivers auto-reconcile &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;issue-matrix.json&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; auto-merges, or resolve
with &lt;code dir=&quot;auto&quot;&gt;git checkout --theirs -- lanes.json&lt;/code&gt; if it doesn’t. Coord now CONTAINS
the planning commit, so the next lane seed is a no-op merge and allocation
succeeds.&lt;/p&gt;
&lt;p&gt;Disable the sync fan-out while you work through claims — it hangs after the
local state persists, and claims already take 60-120s each on a
coord-topology mission:&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:#C5E478;--1:#3B61B0&quot;&gt;SPEC_KITTY_SYNC_DISABLE&lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;1&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;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;agent&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;action&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;implement&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;WP##&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;handle&gt;&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;--agent&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;agent&gt;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h2 id=&quot;related&quot;&gt;Related&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/operations/coord-off-main-addadd/&quot;&gt;Coordination branch created off main (add/add)&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>
