<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/migrations/legacy-to-coordination/">
  <id>https://docs.spec-kitty.ai/migrations/legacy-to-coordination/</id>
  <title>Migration: Legacy Topology to the Coordination Model</title>
  <updated>2026-09-26T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/migrations/legacy-to-coordination/"/>
  <summary>Operator runbook for the legacy-topology bookkeeping warning: what a pre-coordination mission is, how to detect one, and the supported paths forward.</summary>
  <content type="html">&lt;blockquote&gt;
&lt;p&gt;Migration note: This page documents a migration path or historical transition. It is not the current 3.2 happy path.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;span id=&quot;migration-legacy-topology-to-the-coordination-model&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;strong&gt;Source of the warning&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/coordination/transaction.py&lt;/code&gt;
(the bookkeeping transaction).
&lt;strong&gt;ADR&lt;/strong&gt;: &lt;a href=&quot;/adr/3.x/2026-06-22-1-mission-topology-ssot/&quot;&gt;2026-06-22-1 — MissionTopology SSOT&lt;/a&gt;
&lt;strong&gt;Audience&lt;/strong&gt;: Operators who saw the stderr warning below while running a
mission that predates the coordination-branch topology, or who need to
decide how to move such a mission forward.&lt;/p&gt;
&lt;h2 id=&quot;the-warning-you-saw&quot;&gt;The warning you saw&lt;/h2&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;text&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:#d6deeb;--1:#403f53&quot;&gt;warning: mission &apos;&amp;#x3C;slug&gt;&apos; uses the legacy topology (no coordination branch).&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;New atomicity invariants apply, but consider migrating: see&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;docs/migrations/legacy-to-coordination.md&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;It is emitted &lt;strong&gt;at most once per mission&lt;/strong&gt;, on the first bookkeeping write
(status event or planning-artifact commit) for a mission whose &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;
does not carry a &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt;. A marker file
&lt;code dir=&quot;auto&quot;&gt;.kittify/legacy-warning-shown-&amp;#x3C;mission_id&gt;&lt;/code&gt; records that the warning was
shown, so subsequent commands stay quiet.&lt;/p&gt;
&lt;p&gt;The warning is &lt;strong&gt;informational, not an error&lt;/strong&gt;. Your mission keeps working.
Every atomicity invariant of the bookkeeping transaction — the pre-flight
policy gate, the lock, the surgical truncate rollback, and outbound deferral
— applies to legacy missions exactly as it does to coordination missions.
Only the write destination differs (see below).&lt;/p&gt;
&lt;h2 id=&quot;what-a-legacy-mission-is&quot;&gt;What a legacy mission is&lt;/h2&gt;
&lt;p&gt;Under the current &lt;a href=&quot;/architecture/branch-target-routing/&quot;&gt;branch-target routing model&lt;/a&gt;,
a mission’s planning artifacts, status events, and lane definitions land on a
dedicated &lt;strong&gt;coordination branch&lt;/strong&gt;, hosted in a per-mission coordination
worktree (&lt;code dir=&quot;auto&quot;&gt;.worktrees/&amp;#x3C;slug&gt;-&amp;#x3C;mid8&gt;-coord/&lt;/code&gt;). The branch name is recorded in
the mission’s &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; under &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; at &lt;code dir=&quot;auto&quot;&gt;mission create&lt;/code&gt;
time, when the chosen topology calls for one.&lt;/p&gt;
&lt;p&gt;A &lt;strong&gt;legacy mission&lt;/strong&gt; is one whose &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; exists but carries no
&lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; — typically because the mission was created before the
coordination-branch topology landed. For those missions the bookkeeping
write target is the operator’s &lt;strong&gt;current lane worktree and its checked-out
branch&lt;/strong&gt;, resolved from your working directory. This is the pre-coordination
behavior, preserved on purpose.&lt;/p&gt;
&lt;p&gt;Two neighbouring states are &lt;em&gt;not&lt;/em&gt; legacy, and — since #2351 — do &lt;strong&gt;not&lt;/strong&gt; draw
the legacy-topology warning:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A coordination-less topology chosen at creation.&lt;/strong&gt; A mission created on a
current version with the &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;lanes&lt;/code&gt; topology also has no
&lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; — those shapes never mint one. Write-path routing
still treats them identically to a legacy mission (the key is absent either
way; &lt;code dir=&quot;auto&quot;&gt;lanes&lt;/code&gt; writes through the operator’s lane worktree, while &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt;
writes in its write checkout and has no lane worktree), but the warning
classifier is topology-aware: it reads the mission’s &lt;strong&gt;stored&lt;/strong&gt; topology
and no longer warns when that topology is a coordination-less shape chosen
on purpose.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A flattened mission.&lt;/strong&gt; A mission that &lt;em&gt;had&lt;/em&gt; a coordination branch and had
it deliberately removed is &lt;strong&gt;flattened&lt;/strong&gt;, recorded as a separate
&lt;code dir=&quot;auto&quot;&gt;flattened&lt;/code&gt; provenance flag in &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; — never as a topology value.
Flattened missions do not draw the legacy-topology warning either.
See the &lt;a href=&quot;/adr/3.x/2026-06-22-1-mission-topology-ssot/&quot;&gt;MissionTopology SSOT ADR&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;detect-the-state&quot;&gt;Detect the state&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Check &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; directly.&lt;/strong&gt; From the repository root:&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;jq&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&apos;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;.coordination_branch&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&apos;&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-specs/&amp;#x3C;mission-dir&gt;/meta.json&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;null&lt;/code&gt; (or a missing key) means the bookkeeping transaction treats the
mission as legacy. A missing &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; altogether is treated as
new-topology, not legacy — as is a corrupt (unparseable) one, which
additionally surfaces as an error via &lt;code dir=&quot;auto&quot;&gt;backfill-topology&lt;/code&gt; (exit 1, see
&lt;a href=&quot;#spec-kitty-migrate-backfill-topology-exits-1&quot;&gt;troubleshooting&lt;/a&gt;).&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Audit the stored topology.&lt;/strong&gt; The read-only audit walks &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt;
and reports each mission’s stored shape and &lt;code dir=&quot;auto&quot;&gt;flattened&lt;/code&gt; flag:&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;topology&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;--json&lt;/span&gt;&lt;/div&gt;&lt;/div&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;topology&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;slug&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;A &lt;code dir=&quot;auto&quot;&gt;topology&lt;/code&gt; of &lt;code dir=&quot;auto&quot;&gt;null&lt;/code&gt; means the mission predates the stored-topology
model and has not been backfilled yet (see Path A below). The four valid
stored values are &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;lanes&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;coord&lt;/code&gt;, and
&lt;code dir=&quot;auto&quot;&gt;lanes_with_coord&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;coord&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;lanes_with_coord&lt;/code&gt; are the shapes that
carry a coordination branch.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Check the worktree layout.&lt;/strong&gt; Coordination missions have a
&lt;code dir=&quot;auto&quot;&gt;.worktrees/&amp;#x3C;slug&gt;-&amp;#x3C;mid8&gt;-coord/&lt;/code&gt; worktree alongside any lane worktrees.
Legacy missions have only lane worktrees, laid out as
&lt;code dir=&quot;auto&quot;&gt;.worktrees/&amp;#x3C;slug&gt;-lane-&amp;#x3C;id&gt;/&lt;/code&gt; (or &lt;code dir=&quot;auto&quot;&gt;.worktrees/&amp;#x3C;slug&gt;-&amp;#x3C;mid8&gt;-lane-&amp;#x3C;id&gt;/&lt;/code&gt;
when the recorded slug itself embeds a mid8 — lane naming keys on the
slug and lane id, never on the Mission identity; see &lt;a href=&quot;/architecture/execution-lanes/#naming&quot;&gt;Execution Lanes
§Naming&lt;/a&gt;), or the pre-083
forms described in the &lt;a href=&quot;/migrations/mission-id-canonical-identity/&quot;&gt;mission identity runbook&lt;/a&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;path-a--stay-on-the-legacy-topology-and-backfill-the-stored-shape&quot;&gt;Path A — Stay on the legacy topology and backfill the stored shape&lt;/h2&gt;
&lt;p&gt;Running a legacy mission to completion is fully supported. The one piece of
maintenance worth doing is persisting the mission’s shape, so that readers
consult a &lt;strong&gt;stored&lt;/strong&gt; topology instead of re-inferring it from disk (the
drift class the SSOT ADR closes):&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;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--dry-run&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;--json&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;# preview&lt;/span&gt;&lt;/div&gt;&lt;/div&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;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;                    &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# write&lt;/span&gt;&lt;/div&gt;&lt;/div&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;topology&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;--json&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;# confirm&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;backfill-topology&lt;/code&gt; computes each mission’s topology from its current
on-disk signals and writes it into &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; as the authoritative
&lt;code dir=&quot;auto&quot;&gt;topology&lt;/code&gt; value. It is idempotent — a mission that already has a valid
&lt;code dir=&quot;auto&quot;&gt;topology&lt;/code&gt; is skipped and never overwritten. &lt;code dir=&quot;auto&quot;&gt;--mission &amp;#x3C;slug&gt;&lt;/code&gt; scopes it to
one mission. Exit code &lt;code dir=&quot;auto&quot;&gt;1&lt;/code&gt; means one or more missions had a corrupt or
unreadable &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;; repair the JSON and re-run.&lt;/p&gt;
&lt;p&gt;Note the backfill stores the &lt;em&gt;shape&lt;/em&gt;; it never mints a coordination branch.
A legacy mission stays on the legacy write path after backfill — routing is
unaffected. The warning behavior, however, changes deliberately (#2351):
backfilling a genuinely legacy mission’s stored topology &lt;strong&gt;suppresses&lt;/strong&gt; the
legacy-topology warning on the next invocation, since the classifier now
sees an affirmative stored shape instead of “absent.”&lt;/p&gt;
&lt;h2 id=&quot;path-b--adopt-the-coordination-model&quot;&gt;Path B — Adopt the coordination model&lt;/h2&gt;
&lt;p&gt;Coordination branches are minted &lt;strong&gt;only at &lt;code dir=&quot;auto&quot;&gt;mission create&lt;/code&gt;&lt;/strong&gt;, when the
chosen topology calls for one. There is no in-place converter that retrofits
a coordination branch onto an existing mission — an in-flight legacy mission
should simply run to merge under the legacy invariants.&lt;/p&gt;
&lt;p&gt;Missions created on current versions with a coordination topology carry
&lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; from creation, and their bookkeeping
routes through the coordination worktree automatically. In other words: the
migration to the coordination model happens per new mission, not by
converting old ones.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Do not hand-edit &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; into &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;.&lt;/strong&gt; The transaction
would treat the value as authoritative and re-create the coordination surface
fresh on the next write — a surface that never hosted the mission’s existing
planning and status history. The mission’s status log would then be split
across two surfaces.&lt;/p&gt;
&lt;h2 id=&quot;troubleshooting&quot;&gt;Troubleshooting&lt;/h2&gt;
&lt;h3 id=&quot;bookkeeping_legacy_resolution_failed&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;BOOKKEEPING_LEGACY_RESOLUTION_FAILED&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;The mission is legacy but the CLI could not resolve a legitimate write
target from your working directory. The stable error code covers three
causes, each with the same remedy — run the command from inside the
mission’s lane worktree with the lane branch checked out:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;em&gt;“no git worktree found above &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;cwd&gt;&lt;/code&gt;”&lt;/em&gt; — you are outside any checkout.&lt;/li&gt;
&lt;li&gt;&lt;em&gt;“HEAD is detached or symbolic-ref failed”&lt;/em&gt; — the worktree you are in has
a detached HEAD; check out the lane branch.&lt;/li&gt;
&lt;li&gt;&lt;em&gt;“HEAD resolves to an empty branch name”&lt;/em&gt; — same remedy.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;the-write-is-refused-from-the-primary-checkout&quot;&gt;The write is refused from the primary checkout&lt;/h3&gt;
&lt;p&gt;Running legacy bookkeeping from the main checkout while it sits on a
protected ref (for example &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;) is blocked by the pre-flight policy gate
in the transaction — the same machinery that guards the coordination
topology. Move to the mission’s lane worktree.&lt;/p&gt;
&lt;h3 id=&quot;the-warning-keeps-repeating&quot;&gt;The warning keeps repeating&lt;/h3&gt;
&lt;p&gt;The once-only behavior depends on writing the marker file
&lt;code dir=&quot;auto&quot;&gt;.kittify/legacy-warning-shown-&amp;#x3C;mission_id&gt;&lt;/code&gt;. If that write fails (for
example, a read-only &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt;), the failure is non-fatal and the warning
simply re-appears on the next invocation. Fix the permissions to restore the
once-only behavior. Conversely, delete the marker file to see the warning
again on purpose.&lt;/p&gt;
&lt;h3 id=&quot;spec-kitty-migrate-backfill-topology-exits-1&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate backfill-topology&lt;/code&gt; exits 1&lt;/h3&gt;
&lt;p&gt;One or more missions had a corrupt or unreadable &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;. The command
reports which; repair the JSON by hand and re-run — the backfill is safe to
re-run and skips missions that are already done.&lt;/p&gt;
&lt;h2 id=&quot;related-documentation&quot;&gt;Related Documentation&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/branch-target-routing/&quot;&gt;Branch-Target Routing&lt;/a&gt; — the
routing table, the coordination branch’s role, and the flat-topology
collapse when no coordination branch is configured.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/execution-lanes/&quot;&gt;Execution Lanes&lt;/a&gt; — lane worktree and
branch naming, and how lanes merge back.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-06-22-1-mission-topology-ssot/&quot;&gt;MissionTopology SSOT ADR&lt;/a&gt;
— why the shape is stored in &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; and resolved once, and why
&lt;code dir=&quot;auto&quot;&gt;flattened&lt;/code&gt; is a provenance flag rather than a topology.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/migrations/mission-id-canonical-identity/&quot;&gt;Mission ID canonical identity&lt;/a&gt; — the
sibling migration for pre-083 missions without a &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;; the same
audit-then-backfill pattern this page follows.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
