<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/4.x/2026-10-17-1-explicit-migration-ledger/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-17-1-explicit-migration-ledger/</id>
  <title>ADR: the applied-migration ledger is an explicit, two-partition record that is the execution authority for what has run</title>
  <updated>2026-10-30T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/4.x/2026-10-17-1-explicit-migration-ledger/"/>
  <summary>An explicit two-partition migration ledger replaces metadata.yaml and the version window as the authority for what has run; selection becomes ledger-diff.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted (2026-10-17).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-10-17&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (operator).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; epic #2933 (explicit, machine-readable migration ledger); spike #5230
(decide ledger location/authority, declared ordering, selection, drift, visibility, adoption,
and the module/directory placement). Builds directly on #6233 / PR #6350 (&lt;code dir=&quot;auto&quot;&gt;clone_local_effect&lt;/code&gt;
on &lt;code dir=&quot;auto&quot;&gt;BaseMigration&lt;/code&gt;, the per-clone reselection seam) and its ADR amendment. Related: ADR
&lt;a href=&quot;/adr/4.x/2026-10-04-4-upgrade-writes-project-global-state-once/&quot;&gt;2026-10-04-4&lt;/a&gt; (upgrade writes
project-global state once), ADR &lt;a href=&quot;/adr/4.x/2026-10-07-1-upgrade-never-runs-mission-state-repair/&quot;&gt;2026-10-07-1&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Reader:&lt;/strong&gt; a maintainer working on the &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; migration subsystem, or authoring
a new migration.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Supersedes / extends:&lt;/strong&gt; ADR
&lt;a href=&quot;/adr/3.x/2026-07-07-1-ignored-surface-backfill-migration-pattern/&quot;&gt;2026-07-07-1&lt;/a&gt;, specifically
its &lt;strong&gt;Amendment 2026-10-17 (#6233)&lt;/strong&gt;, which introduced the per-clone reselection seam as an
interim fix and explicitly deferred “the explicit, machine-readable clone-local ledger that
would record the effect’s presence directly” to epic #2933. This ADR is that deferred design.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;The upgrade subsystem records which migrations have run in the &lt;code dir=&quot;auto&quot;&gt;migrations.applied&lt;/code&gt; block of
the tracked, pushed &lt;code dir=&quot;auto&quot;&gt;.kittify/metadata.yaml&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;ProjectMetadata.applied_migrations&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/metadata.py:71&lt;/code&gt;). Two authorities decide whether a migration runs:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;The &lt;strong&gt;version window&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;MigrationRegistry.get_applicable&lt;/code&gt; selects a migration when
&lt;code dir=&quot;auto&quot;&gt;from_v &amp;#x3C; target &amp;#x3C;= to_v&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/registry.py:119&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;The &lt;strong&gt;applied record&lt;/strong&gt; — the runner skips a migration already recorded applied
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/runner.py:357&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;ProjectMetadata.has_migration&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;metadata.py:276&lt;/code&gt;).&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;This design has accumulated three structural faults:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The ledger is the wrong authority for clone-local effects (#6233).&lt;/strong&gt; A migration whose
effect lives &lt;em&gt;outside&lt;/em&gt; version control — &lt;code dir=&quot;auto&quot;&gt;.git/info/exclude&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;git config --local&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;.git/hooks&lt;/code&gt; — records into the shared, pushed &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt;. The record propagates to
every clone, but the effect does not. A pulled clone inherits the record without the effect
and skips the migration forever. PR #6350 patched this with &lt;code dir=&quot;auto&quot;&gt;clone_local_effect&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/base.py:122&lt;/code&gt;) plus a version-window reselection branch
(&lt;code dir=&quot;auto&quot;&gt;registry.py:175 _clone_local_selected_below_window&lt;/code&gt;) and a skip-gate override
(&lt;code dir=&quot;auto&quot;&gt;base.py:135 reselect_when_recorded&lt;/code&gt;). That is a workaround for the authority being in the
wrong file.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The version window strands migrations.&lt;/strong&gt; Anything below &lt;code dir=&quot;auto&quot;&gt;from_v&lt;/code&gt; is never reconsidered —
the very reason the clone-local reselection branch and the symlink fail-closed path
(&lt;code dir=&quot;auto&quot;&gt;runner.py:366-393&lt;/code&gt;) had to be bolted on. A migration that failed, or that a pulled
&lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt; reset, can be stranded past the window.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt; is a multi-writer surface (#5229).&lt;/strong&gt; The applied list shares the file with
the version stamp, the schema-capabilities stamp (&lt;code dir=&quot;auto&quot;&gt;canonical_schema_capabilities&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;metadata.py:364&lt;/code&gt;), the environment block, &lt;code dir=&quot;auto&quot;&gt;project_uuid&lt;/code&gt; and operator keys. The
merge-preserving &lt;code dir=&quot;auto&quot;&gt;save&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;metadata.py:184-241&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_merge_onto_disk :348&lt;/code&gt;) &lt;em&gt;mitigates&lt;/em&gt; the
second-writer hazard; it does not remove it. A list that grows on every migration is the
part most in need of leaving that contested file.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Execution order has an implicit tiebreak.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;get_all&lt;/code&gt; sorts by &lt;code dir=&quot;auto&quot;&gt;Version(target_version)&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;registry.py:79-80&lt;/code&gt;); migrations that share a &lt;code dir=&quot;auto&quot;&gt;target_version&lt;/code&gt; (several exist, e.g. two
&lt;code dir=&quot;auto&quot;&gt;m_0_13_0_*&lt;/code&gt;, two &lt;code dir=&quot;auto&quot;&gt;m_2_1_2_*&lt;/code&gt;) fall back to filename import order from
&lt;code dir=&quot;auto&quot;&gt;auto_discover_migrations&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/__init__.py:46&lt;/code&gt;) — an
unstable, undeclared tiebreak.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Spike #5230 asked for a decisive design across six deliverables, led by a verdict on &lt;em&gt;where&lt;/em&gt;
the ledger and its machinery live, defended against the enforced modularity SSOT.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Correctness for clone-local effects without per-site compensation logic.&lt;/li&gt;
&lt;li&gt;Remove the applied record from the &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt; multi-writer surface.&lt;/li&gt;
&lt;li&gt;Make execution order and “what has run” explicit, auditable, and the single authority.&lt;/li&gt;
&lt;li&gt;Change no architectural layer rule and no wheel package set.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;h3 id=&quot;0-module--directory-placement--stays-in-specify_cliupgrade&quot;&gt;0. Module / directory placement — stays in &lt;code dir=&quot;auto&quot;&gt;specify_cli/upgrade&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;The ledger and all its machinery &lt;strong&gt;stay in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/&lt;/code&gt;&lt;/strong&gt;. A new module
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/ledger.py&lt;/code&gt; owns the ledger data, its read/write, and its authority.
It consumes two root-layer primitives &lt;em&gt;downward&lt;/em&gt; across the existing, legal boundary: atomic
writes via &lt;code dir=&quot;auto&quot;&gt;specify_cli/core/atomic.py:53 atomic_write&lt;/code&gt; (itself a thin wrapper over
&lt;code dir=&quot;auto&quot;&gt;kernel.atomic&lt;/code&gt;), and content hashing via &lt;code dir=&quot;auto&quot;&gt;kernel.content_digest.sha256_digest&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/kernel/content_digest.py:19&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;SSOT defense.&lt;/strong&gt; The enforced chain is
&lt;code dir=&quot;auto&quot;&gt;kernel &amp;#x3C;- charter &amp;#x3C;- {glossary, runtime, mission_runtime} &amp;#x3C;- specify_cli&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;tests/architectural/conftest.py:88-118&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;landscape&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_layer_rules.py:83-85&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;_DEFINED_LAYERS&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;pyproject.toml [tool.hatch.build.targets.wheel].packages&lt;/code&gt;). Every reader of
applied-migration state is already in &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt; and none is below it: &lt;code dir=&quot;auto&quot;&gt;registry.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;runner.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;detector.py:44&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;compat.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;core/version_checker.py&lt;/code&gt;, the doctor family
(&lt;code dir=&quot;auto&quot;&gt;cli/commands/_*_doctor.py&lt;/code&gt;), &lt;code dir=&quot;auto&quot;&gt;cli/commands/upgrade.py&lt;/code&gt;, and migrations that read other
migrations’ applied state (&lt;code dir=&quot;auto&quot;&gt;m_3_2_6_*&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;m_4_0_0rc6_charter_pack_cutover.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;m_3_1_1_charter_rename.py&lt;/code&gt;, all via &lt;code dir=&quot;auto&quot;&gt;has_migration&lt;/code&gt;). The whole subsystem — &lt;code dir=&quot;auto&quot;&gt;BaseMigration&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;MigrationRegistry&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;MigrationRunner&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;VersionDetector&lt;/code&gt; — is &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Placing the ledger in &lt;code dir=&quot;auto&quot;&gt;kernel&lt;/code&gt; (or a new sibling package) is &lt;strong&gt;rejected&lt;/strong&gt;: it would create
consumer-less public surface in the dependency-free root layer and would force a new
&lt;code dir=&quot;auto&quot;&gt;_DEFINED_LAYERS&lt;/code&gt; entry plus a new &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; wheel package (the meta-tests
&lt;code dir=&quot;auto&quot;&gt;test_no_unregistered_src_packages&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;test_layer_rules.py:421&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;test_all_defined_layers_match_at_least_one_module&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;:460&lt;/code&gt; require it), for zero benefit. The
genuinely root-layer mechanics (atomic write, hashing, locking) already live in &lt;code dir=&quot;auto&quot;&gt;kernel&lt;/code&gt; and are
consumed downward exactly as &lt;code dir=&quot;auto&quot;&gt;metadata.py:14&lt;/code&gt; already consumes &lt;code dir=&quot;auto&quot;&gt;atomic_write&lt;/code&gt;. &lt;strong&gt;No layer rule
and no wheel package set change.&lt;/strong&gt; Adding a file inside &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt; touches none of the three
enforced authorities.&lt;/p&gt;
&lt;h3 id=&quot;1-ledger-location--authority--two-partitions&quot;&gt;1. Ledger location &amp;#x26; authority — two partitions&lt;/h3&gt;
&lt;p&gt;The explicit ledger is &lt;strong&gt;two append-only JSONL files, partitioned by whether a migration’s
effect is tracked or clone-local&lt;/strong&gt;, and it becomes &lt;strong&gt;the&lt;/strong&gt; execution authority for “already
applied”, replacing both &lt;code dir=&quot;auto&quot;&gt;metadata.yaml.applied_migrations&lt;/code&gt; and the version window.&lt;/p&gt;






























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;/th&gt;&lt;th&gt;Tracked ledger&lt;/th&gt;&lt;th&gt;Per-clone ledger&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Path&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/migration-ledger.jsonl&lt;/code&gt; (tracked)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/migrations/clone-local.jsonl&lt;/code&gt; (untracked)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Authority for&lt;/td&gt;&lt;td&gt;migrations with &lt;code dir=&quot;auto&quot;&gt;clone_local_effect == False&lt;/code&gt;&lt;/td&gt;&lt;td&gt;migrations with &lt;code dir=&quot;auto&quot;&gt;clone_local_effect == True&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Propagates on clone/pull&lt;/td&gt;&lt;td&gt;yes — correct; a tracked effect travels with the commit&lt;/td&gt;&lt;td&gt;no — correct; the effect (&lt;code dir=&quot;auto&quot;&gt;.git/info/exclude&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;git config --local&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.git/hooks&lt;/code&gt;) does not travel&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Record shape&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;{id, applied_at, result, identity, content_hash, cli_version}&lt;/code&gt;&lt;/td&gt;&lt;td&gt;same, plus &lt;code dir=&quot;auto&quot;&gt;clone_local: true&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;This maps onto a split the repository already has. &lt;code dir=&quot;auto&quot;&gt;.kittify/metadata.yaml&lt;/code&gt; is tracked;
&lt;code dir=&quot;auto&quot;&gt;.kittify/migrations/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.kittify/logs/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.kittify/encoding-provenance/&lt;/code&gt; and the per-clone
sentinel files &lt;code dir=&quot;auto&quot;&gt;.kittify/legacy-warning-shown-*&lt;/code&gt; are untracked per-clone state. The tracked
ledger is a new tracked sibling of &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt; (confirmed not git-ignored). The per-clone
ledger lives &lt;strong&gt;inside the already-IGNORED &lt;code dir=&quot;auto&quot;&gt;.kittify/migrations/&lt;/code&gt; surface&lt;/strong&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/state/contract.py:308&lt;/code&gt;, back-compat ignore #4928; &lt;code dir=&quot;auto&quot;&gt;git check-ignore .kittify/migrations/clone-local.jsonl&lt;/code&gt; confirms it is ignored), so it needs no new gitignore
entry and is untracked by construction.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;clone_local_effect&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;base.py:122&lt;/code&gt;) &lt;strong&gt;stops being a reselection trigger and becomes a routing
key&lt;/strong&gt;: it decides which ledger a record is written to and read from. Because a clone-local
record lives only in the per-clone ledger, a freshly pulled clone has no such record, so the
migration is pending by plain ledger-diff (§3), applies, and records into &lt;em&gt;this clone’s&lt;/em&gt;
per-clone ledger.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;This supersedes the #6233 machinery.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;registry.py:175 _clone_local_selected_below_window&lt;/code&gt;
and the sub-window reselection it drives are &lt;strong&gt;removed&lt;/strong&gt;. &lt;code dir=&quot;auto&quot;&gt;base.py:135 reselect_when_recorded&lt;/code&gt;
collapses to “is this id in the applicable ledger for its partition?” &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt;
(e.g. &lt;code dir=&quot;auto&quot;&gt;m_4_0_0rc7_exclude_spec_kitty.py:detect&lt;/code&gt;) &lt;strong&gt;remains, as the idempotency guard only&lt;/strong&gt; — a
belt-and-suspenders check before &lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt; re-runs, never the authority for selection.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Atomic write, single-writer.&lt;/strong&gt; The ledger is a full-file atomic rewrite of the JSONL on each
append, consistent with &lt;code dir=&quot;auto&quot;&gt;metadata.py:240&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;VersionStamp&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;metadata.py:466/491&lt;/code&gt;), not
&lt;code dir=&quot;auto&quot;&gt;O_APPEND&lt;/code&gt;. The subsystem is single-writer: &lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt; runs in one process, worktrees
sequentially (&lt;code dir=&quot;auto&quot;&gt;runner.py&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;_upgrade_worktrees&lt;/code&gt;), and integrating worktrees are skipped (ADR
2026-10-04-4). If concurrent cross-process upgrade ever becomes real, wrap the append in
&lt;code dir=&quot;auto&quot;&gt;kernel.locks&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/kernel/locks.py:151&lt;/code&gt;); this is the named extension point, deliberately
&lt;strong&gt;not&lt;/strong&gt; built now.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Rejected:&lt;/strong&gt; keeping the applied record inside &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt;. It is the #5229 multi-writer
surface; a YAML block is a whole-document read-modify-write per record; and it cannot represent
the tracked/clone-local partition without a per-record scope flag inside a tracked file — which
re-creates the #6233 propagation bug for the clone-local rows.&lt;/p&gt;
&lt;h3 id=&quot;2-declared-ordering--a-checked-in-order-manifest&quot;&gt;2. Declared ordering — a checked-in order manifest&lt;/h3&gt;
&lt;p&gt;A single checked-in &lt;strong&gt;order manifest&lt;/strong&gt; (a changelog-style list of &lt;code dir=&quot;auto&quot;&gt;migration_id&lt;/code&gt;s in canonical
execution order) is the authority for order. &lt;code dir=&quot;auto&quot;&gt;Version(target_version)&lt;/code&gt; is demoted to a
validation cross-check (the manifest must be version-monotonic save for explicitly annotated
ties). A build-time check (a new &lt;code dir=&quot;auto&quot;&gt;tests/architectural/&lt;/code&gt; gate) enforces: every registered
&lt;code dir=&quot;auto&quot;&gt;migration_id&lt;/code&gt; appears in the manifest exactly once (orphan / missing-entry check); every
manifest entry resolves to a registered migration (dangling-entry check); the order is
version-monotonic except where annotated; and at most one &lt;code dir=&quot;auto&quot;&gt;runs_first&lt;/code&gt; migration leads (already
guarded &lt;code dir=&quot;auto&quot;&gt;registry.py:61-67&lt;/code&gt;). Touchpoints: the sort in &lt;code dir=&quot;auto&quot;&gt;registry.py:79-80 get_all&lt;/code&gt; becomes a
manifest-index lookup; discovery (&lt;code dir=&quot;auto&quot;&gt;__init__.py:18&lt;/code&gt;) is unchanged.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Rejected:&lt;/strong&gt; per-migration &lt;code dir=&quot;auto&quot;&gt;after:&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;before:&lt;/code&gt; DAG edges. They need a runtime topological sort
and cycle detection, and the total order is not readable at a glance. A single ordered list is
auditable in one read and the exactly-once / resolves checks are trivial. The &lt;code dir=&quot;auto&quot;&gt;runs_first&lt;/code&gt; flag
remains the escape hatch for the rare “must lead regardless of version” case.&lt;/p&gt;
&lt;h3 id=&quot;3-selection--ledger-diff-replaces-the-version-window&quot;&gt;3. Selection — ledger-diff replaces the version window&lt;/h3&gt;
&lt;p&gt;Selection becomes &lt;strong&gt;declared minus applied&lt;/strong&gt;:
&lt;code dir=&quot;auto&quot;&gt;pending = [m for m in manifest_order if m.id not in applicable_ledger(m)]&lt;/code&gt;, then filtered by
&lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;can_apply&lt;/code&gt;, where &lt;code dir=&quot;auto&quot;&gt;applicable_ledger(m)&lt;/code&gt; is the per-clone ledger when
&lt;code dir=&quot;auto&quot;&gt;m.clone_local_effect&lt;/code&gt; else the tracked ledger. The version window
(&lt;code dir=&quot;auto&quot;&gt;registry.py:119 from_v &amp;#x3C; target &amp;#x3C;= to_v&lt;/code&gt;) is &lt;strong&gt;retired as the applied authority&lt;/strong&gt;;
&lt;code dir=&quot;auto&quot;&gt;target_version&lt;/code&gt; survives only as the ordering/monotonicity reference (§2).&lt;/p&gt;
&lt;p&gt;Consequences:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Stranded / skipped migrations.&lt;/strong&gt; Ledger-diff re-selects any declared migration whose id is
not a &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; record, independent of the version stamp. The symlink fail-closed strand
(&lt;code dir=&quot;auto&quot;&gt;runner.py:366-393&lt;/code&gt;) and the pulled-clone strand (#6233) both resolve for free.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Retired pre-3.0 modules (#2322).&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;SupersededMigration&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;base.py:186&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;detect()==False&lt;/code&gt;)
and neutralised no-ops (&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/upgrade/test_neutralised_migrations.py&lt;/code&gt;) &lt;strong&gt;stay in
the manifest&lt;/strong&gt;. Ledger-diff selects them; &lt;code dir=&quot;auto&quot;&gt;detect()==False&lt;/code&gt; yields a &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; record; the
skipped record keeps them from re-firing. Behaviour is identical to today, now anchored on the
ledger rather than the version stamp.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Legacy-id aliases.&lt;/strong&gt; The legacy-id normalization map (&lt;code dir=&quot;auto&quot;&gt;metadata.py:18 _LEGACY_MIGRATION_ID_MAP&lt;/code&gt;, applied today by &lt;code dir=&quot;auto&quot;&gt;normalize_and_save_legacy_ids&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;metadata.py:158&lt;/code&gt;) is applied to ledger ids &lt;strong&gt;on read&lt;/strong&gt;, so a constitution-era id and its
charter-era id resolve to one record.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;4-drift-detection--auditreport-only-never-auto-reapply&quot;&gt;4. Drift detection — audit/report only, never auto-reapply&lt;/h3&gt;
&lt;p&gt;Each applied record carries an author-declared &lt;code dir=&quot;auto&quot;&gt;identity&lt;/code&gt; (defaulting to &lt;code dir=&quot;auto&quot;&gt;migration_id&lt;/code&gt;) and a
&lt;code dir=&quot;auto&quot;&gt;content_hash = sha256_digest(&amp;#x3C;migration module source bytes&gt;)&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;kernel.content_digest.sha256_digest&lt;/code&gt;). On a later run, a recorded migration whose current
&lt;code dir=&quot;auto&quot;&gt;content_hash&lt;/code&gt; differs from the stored one is flagged as &lt;strong&gt;drift&lt;/strong&gt; and surfaced read-only
(§5). Drift is &lt;strong&gt;never&lt;/strong&gt; acted on automatically.&lt;/p&gt;
&lt;p&gt;This matches established practice for &lt;em&gt;code&lt;/em&gt; migrations: Alembic and Django omit per-migration
checksums precisely because migrations are immutable once shipped, and editing a shipped
migration is itself the error (DIRECTIVE_044: do not edit shipped migrations). The hash does
not gate or re-run anything; it is the audit that makes a violation of that rule visible.
&lt;strong&gt;Rejected:&lt;/strong&gt; checksum-mismatch → auto re-apply — it would fight &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; idempotency and
could re-run destructive &lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt; against a project that already carries the old effect.&lt;/p&gt;
&lt;h3 id=&quot;5-visibility--one-pending-source-one-read-surface&quot;&gt;5. Visibility — one pending-source, one read surface&lt;/h3&gt;
&lt;p&gt;The shipped read surface is &lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate ledger&lt;/code&gt; (read-only; &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; emits the same
report as structured data). It renders: the declared set (manifest), the applied set (both
ledgers), the pending set, the tracked/clone-local partition, and drift flags. It consumes the
single pending-source &lt;code dir=&quot;auto&quot;&gt;VersionDetector.applicable_migrations&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;detector.py:49&lt;/code&gt;) — the same
method the compat planner and &lt;code dir=&quot;auto&quot;&gt;--dry-run&lt;/code&gt; already delegate to — so the reported pending set can
never diverge from the applied set. The command writes nothing and commits nothing; drift is
reported only (§4).&lt;/p&gt;
&lt;p&gt;The original proposal recorded here — a new doctor sub-surface (&lt;code dir=&quot;auto&quot;&gt;doctor migrations&lt;/code&gt;, following
the existing doctor family shape) plus an &lt;code dir=&quot;auto&quot;&gt;upgrade --list-applied&lt;/code&gt; flag
(&lt;code dir=&quot;auto&quot;&gt;cli/commands/upgrade.py&lt;/code&gt;) — is &lt;strong&gt;historical: it was not built.&lt;/strong&gt; Its own argument defeated it:
two renderers over the same report would have been two consumers that could drift from the
single pending-source, which is the failure §3 and this section exist to prevent. One read
surface carries the decision instead.&lt;/p&gt;
&lt;h3 id=&quot;6-adoption--backfill--hard-cutover-detect-gated-for-clone-local&quot;&gt;6. Adoption / backfill — hard cutover, detect-gated for clone-local&lt;/h3&gt;
&lt;p&gt;Transition is a &lt;strong&gt;hard cutover&lt;/strong&gt;. A one-way backfill migration reads the existing
&lt;code dir=&quot;auto&quot;&gt;ProjectMetadata.applied_migrations&lt;/code&gt; (normalizing legacy ids, &lt;code dir=&quot;auto&quot;&gt;metadata.py:171&lt;/code&gt;) and writes
records into the new ledgers, then &lt;code dir=&quot;auto&quot;&gt;metadata.yaml.applied_migrations&lt;/code&gt; is &lt;strong&gt;removed as the
authority — no dual-write mirror&lt;/strong&gt;. Backfill rules:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Tracked-effect records backfill unconditionally&lt;/strong&gt; into the tracked ledger.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Clone-local records are detect-gated.&lt;/strong&gt; The existing &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt; record for a
&lt;code dir=&quot;auto&quot;&gt;clone_local_effect&lt;/code&gt; migration is ambiguous — it was written into the shared file (the #6233
bug), so it does not prove the effect is present on &lt;em&gt;this&lt;/em&gt; clone. A clone-local record is
backfilled into the per-clone ledger &lt;strong&gt;only when &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; confirms the effect is present on
this checkout&lt;/strong&gt;; if &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; reports it absent, nothing is written and ledger-diff
re-applies it (safe, because &lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt; is idempotent).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The backfill is ordered first in the manifest so every later selection in the same run sees a
populated ledger. The new tracked ledger file is added to the state contract as a
&lt;code dir=&quot;auto&quot;&gt;GitClass.TRACKED&lt;/code&gt; surface (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/state/contract.py&lt;/code&gt;), and the repository’s own
&lt;code dir=&quot;auto&quot;&gt;.gitignore&lt;/code&gt; must not ignore it.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Positive.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Clone-local correctness falls out of the partition with no per-site reselection logic; the
#6233 compensation code is deleted.&lt;/li&gt;
&lt;li&gt;The applied record leaves the &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt; multi-writer surface; the runner stops being a
second writer of the growing list there (it still stamps &lt;code dir=&quot;auto&quot;&gt;version&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;schema_version&lt;/code&gt;),
shrinking the #5229 hazard.&lt;/li&gt;
&lt;li&gt;“What has run” and “in what order” are explicit, auditable, and the single authority.&lt;/li&gt;
&lt;li&gt;Stranded/skipped migrations and the retired pre-3.0 modules are handled uniformly by
ledger-diff; no version-window special cases.&lt;/li&gt;
&lt;li&gt;No architectural layer rule and no wheel package set change.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Negative / accepted costs.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Back-compat (accepted ruling).&lt;/strong&gt; After the hard cutover, an &lt;em&gt;older&lt;/em&gt; CLI reading a migrated
project no longer finds applied-migration state in &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt; and loses
applied-migration visibility. This is a documented, accepted consequence — the new CLI is the
authority; there is no dual-write mirror.&lt;/li&gt;
&lt;li&gt;A new tracked &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; file (&lt;code dir=&quot;auto&quot;&gt;migration-ledger.jsonl&lt;/code&gt;) is added to the state contract.&lt;/li&gt;
&lt;li&gt;One-time at adoption, a clone-local migration whose effect &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; cannot confirm on a
given checkout re-runs its idempotent &lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt; once.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;touchpoints&quot;&gt;Touchpoints&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/base.py:122&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;clone_local_effect&lt;/code&gt; (becomes routing key),
&lt;code dir=&quot;auto&quot;&gt;:135&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;reselect_when_recorded&lt;/code&gt; (collapses to a ledger lookup), &lt;code dir=&quot;auto&quot;&gt;:74&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;BaseMigration&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;:186&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;SupersededMigration&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/registry.py:79-80&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;get_all&lt;/code&gt; sort → manifest index; &lt;code dir=&quot;auto&quot;&gt;:82-135&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;get_applicable&lt;/code&gt; → ledger-diff; &lt;code dir=&quot;auto&quot;&gt;:175&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;_clone_local_selected_below_window&lt;/code&gt; (&lt;strong&gt;removed&lt;/strong&gt;);
&lt;code dir=&quot;auto&quot;&gt;:198&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;_runs_first_selected_outside_window&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;:212&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;_order_runs_first&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;:61-67&lt;/code&gt; one-runs_first guard.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/runner.py:206-310&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;:337-393&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;_apply_migration&lt;/code&gt;
(skip gate &lt;code dir=&quot;auto&quot;&gt;:357&lt;/code&gt;, symlink fail-closed &lt;code dir=&quot;auto&quot;&gt;:366-393&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/metadata.py:71&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;applied_migrations&lt;/code&gt; (removed as authority),
&lt;code dir=&quot;auto&quot;&gt;:184-241&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;save&lt;/code&gt; merge-preserving (#5229), &lt;code dir=&quot;auto&quot;&gt;:276&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;has_migration&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:287&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;record_migration&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;:18&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;_LEGACY_MIGRATION_ID_MAP&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:158&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;normalize_and_save_legacy_ids&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:410&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;VersionStamp&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/detector.py:44&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;detect_version&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:49&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;applicable_migrations&lt;/code&gt;
(single pending-source).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/__init__.py:18&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;auto_discover_migrations&lt;/code&gt; (discovery
unchanged; manifest is the order layer above it).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/atomic.py:53&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;atomic_write&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;src/kernel/content_digest.py:19&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;sha256_digest&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;src/kernel/locks.py:151/241&lt;/code&gt; (lock extension point, not built now).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/state/contract.py:308&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;.kittify/migrations/&lt;/code&gt; IGNORED surface (per-clone
ledger home); new &lt;code dir=&quot;auto&quot;&gt;GitClass.TRACKED&lt;/code&gt; surface for &lt;code dir=&quot;auto&quot;&gt;.kittify/migration-ledger.jsonl&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Reference clone-local migrations: &lt;code dir=&quot;auto&quot;&gt;m_4_0_0rc7_exclude_spec_kitty.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;m_0_13_1_exclude_worktrees.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;m_3_1_1_event_log_merge_driver.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;m_4_0_0rc5_install_lane_tip_recorder.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_merge_driver_seeding.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Layer SSOT: &lt;code dir=&quot;auto&quot;&gt;tests/architectural/conftest.py:88-118&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_layer_rules.py:83-85&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;pyproject.toml [tool.hatch.build.targets.wheel].packages&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Idempotency gates to extend: &lt;code dir=&quot;auto&quot;&gt;tests/upgrade/test_clone_local_migration_idempotent.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;tests/upgrade/test_clone_local_selection.py&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;follow-up-child-issues-spike-5230-output-epic-2933&quot;&gt;Follow-up child issues (spike #5230 output, epic #2933)&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;#A — Ledger module + dual-partition data model.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/ledger.py&lt;/code&gt;;
tracked &lt;code dir=&quot;auto&quot;&gt;.kittify/migration-ledger.jsonl&lt;/code&gt; + per-clone &lt;code dir=&quot;auto&quot;&gt;.kittify/migrations/clone-local.jsonl&lt;/code&gt;;
append-only JSONL via &lt;code dir=&quot;auto&quot;&gt;kernel.atomic&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;clone_local_effect&lt;/code&gt; as routing key. (Deliverable 1.)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;#B — Declared-ordering manifest + build-time check.&lt;/strong&gt; Order manifest file + new
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/&lt;/code&gt; gate (exactly-once / resolves / version-monotonic). (Deliverable 2.)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;#C — Ledger-diff selection; retire the version-window authority and the #6233 reselection
machinery.&lt;/strong&gt; Rewrite &lt;code dir=&quot;auto&quot;&gt;registry.get_applicable&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;get_all&lt;/code&gt;; delete
&lt;code dir=&quot;auto&quot;&gt;_clone_local_selected_below_window&lt;/code&gt;; collapse &lt;code dir=&quot;auto&quot;&gt;reselect_when_recorded&lt;/code&gt;; keep &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; as
idempotency guard. (Deliverable 3; depends on #A, #B.)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;#D — Drift identity/checksum on apply.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;identity&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;content_hash&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;kernel.content_digest&lt;/code&gt;) stored per record; audit/report only. (Deliverable 4; depends on #A.)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;#E — Visibility surface.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate ledger&lt;/code&gt; (read-only; &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; for the same
report) via &lt;code dir=&quot;auto&quot;&gt;detector.applicable_migrations&lt;/code&gt;: the declared, applied and pending sets, the
tracked/clone-local partition, and drift flags. The proposed &lt;code dir=&quot;auto&quot;&gt;doctor migrations&lt;/code&gt; sub-surface and
&lt;code dir=&quot;auto&quot;&gt;upgrade --list-applied&lt;/code&gt; flag were not built — one read surface shipped. (Deliverable 5;
depends on #A, #C.)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;#F — Adoption backfill (hard cutover, detect-gated for clone-local).&lt;/strong&gt; Backfill from
&lt;code dir=&quot;auto&quot;&gt;metadata.yaml.applied_migrations&lt;/code&gt;, then remove it as authority; no dual-write mirror; add the
tracked ledger to &lt;code dir=&quot;auto&quot;&gt;state/contract.py&lt;/code&gt;. (Deliverable 6; depends on #A.)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;#G — Docs / ADR.&lt;/strong&gt; Land this ADR; update the 2026-07-07-1 cross-reference; update the
&lt;code dir=&quot;auto&quot;&gt;CLAUDE.md&lt;/code&gt; migration-authoring guidance and the ADR 2026-07-07-1 author checklist to the
ledger model.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;ADR &lt;a href=&quot;/adr/3.x/2026-07-07-1-ignored-surface-backfill-migration-pattern/&quot;&gt;2026-07-07-1&lt;/a&gt;
(IGNORED-surface backfill pattern; this ADR supersedes its Amendment 2026-10-17).&lt;/li&gt;
&lt;li&gt;ADR &lt;a href=&quot;/adr/4.x/2026-10-04-4-upgrade-writes-project-global-state-once/&quot;&gt;2026-10-04-4&lt;/a&gt; (upgrade writes
project-global state once, skips integrating worktrees).&lt;/li&gt;
&lt;li&gt;Epic #2933 (explicit migration ledger); spike #5230; #6233 / PR #6350 (&lt;code dir=&quot;auto&quot;&gt;clone_local_effect&lt;/code&gt;);
#5229 (metadata.yaml second-writer); #2322 (retired pre-3.0 modules).&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;amendment-2026-10-18-closeout-findings&quot;&gt;Amendment 2026-10-18 (closeout findings)&lt;/h2&gt;
&lt;p&gt;Two design facts were discovered and ruled during the mission’s closeout. They are recorded
here so this ADR matches shipped behaviour; the Decision body above is unchanged.&lt;/p&gt;
&lt;h3 id=&quot;1-init-seed-baseline-finding-1-remediation&quot;&gt;1. Init-seed baseline (finding-1 remediation)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Problem found.&lt;/strong&gt; §3 retires the version window and makes selection a plain ledger-diff
(&lt;code dir=&quot;auto&quot;&gt;pending = declared − applied&lt;/code&gt;). A &lt;em&gt;fresh&lt;/em&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; wrote no ledger, so the first
&lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; on that brand-new project diffed an &lt;strong&gt;empty&lt;/strong&gt; ledger against the full
declared set and selected &lt;strong&gt;all ~114 historical migrations&lt;/strong&gt;. Replaying them against an
already-current project is not idempotent: &lt;code dir=&quot;auto&quot;&gt;m_3_2_0rc35_activate_builtin_mission_types&lt;/code&gt; and the
charter-bundle fold disagree over &lt;code dir=&quot;auto&quot;&gt;mission_type_activations&lt;/code&gt; (the rc35 migration adds it to
&lt;code dir=&quot;auto&quot;&gt;config.yaml&lt;/code&gt;; the fold relocates it into &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt;), so the first upgrade mutated config
and auto-committed — breaking NFR-002 (upgrade idempotency) on a second run.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision / shipped behaviour.&lt;/strong&gt; A fresh &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; now &lt;strong&gt;seeds&lt;/strong&gt; the ledger via
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/init_seed.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;seed_migration_ledger_for_init&lt;/code&gt;), consuming the
&lt;code dir=&quot;auto&quot;&gt;ledger.py&lt;/code&gt; API — it does not re-implement ledger I/O. It records every migration a
brand-new, current project has effectively already satisfied, so the first &lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt; selects
nothing. This is the Liquibase “changelog-sync for a new project” baseline: a &lt;strong&gt;one-time init
stamp&lt;/strong&gt;, explicitly &lt;strong&gt;not&lt;/strong&gt; a revived version-window selection authority (§3 stands).&lt;/p&gt;
&lt;p&gt;The seed is &lt;strong&gt;partition-correct&lt;/strong&gt; (§1): a tracked-effect migration (&lt;code dir=&quot;auto&quot;&gt;clone_local_effect == False&lt;/code&gt;) is seeded unconditionally into the tracked ledger; a clone-local migration
(&lt;code dir=&quot;auto&quot;&gt;clone_local_effect == True&lt;/code&gt;) is seeded into the per-clone (gitignored) ledger &lt;strong&gt;only when its
effect is already present on this checkout&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; reports the old state absent). Because
the per-clone ledger never travels, a pulled clone still has an empty per-clone partition and
re-applies the clone-local effect — the #6233 guarantee is preserved, not undone, by the seed.
The seed is idempotent (&lt;code dir=&quot;auto&quot;&gt;migration_settled&lt;/code&gt; skips a migration already recorded &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;The disagreement itself was also closed at its root: &lt;code dir=&quot;auto&quot;&gt;m_3_2_0rc35_activate_builtin_mission_types&lt;/code&gt;
now &lt;strong&gt;short-circuits&lt;/strong&gt; when &lt;code dir=&quot;auto&quot;&gt;mission_type_activations&lt;/code&gt; already lives in the resolved activation
write target — it reads the single authority
&lt;code dir=&quot;auto&quot;&gt;charter.activation.pack_manager.resolve_activation_write_target&lt;/code&gt; (which the fold points at
&lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; post-fold), so the rc35 migration and the provisioning predicate agree on
“already present” and the migration is a no-op there.&lt;/p&gt;
&lt;h3 id=&quot;2-recorded-elsewhere-vs-pending-for-a-fresh-clone-finding-2&quot;&gt;2. “Recorded elsewhere” vs “pending” for a fresh clone (finding-2)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Clarification.&lt;/strong&gt; §1 deliberately keeps &lt;strong&gt;no shared clone-local declaration marker&lt;/strong&gt; in the
tracked ledger (a per-record scope flag / dual-write was rejected because it would re-create the
#6233 propagation bug). A consequence, confirmed at closeout: for a &lt;strong&gt;genuine freshly-pulled
clone&lt;/strong&gt;, the &lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate ledger&lt;/code&gt; report state for a clone-local step is &lt;strong&gt;pending&lt;/strong&gt;
(“not yet applied” / not yet in place on this checkout), &lt;strong&gt;not&lt;/strong&gt; “recorded elsewhere”. The
per-clone ledger is gitignored and never travels, so a fresh clone has an &lt;strong&gt;empty&lt;/strong&gt; per-clone
partition; &lt;code dir=&quot;auto&quot;&gt;assemble_report&lt;/code&gt; finds no matching record (&lt;code dir=&quot;auto&quot;&gt;applied == False&lt;/code&gt;) and the surface
classifies the step as &lt;code dir=&quot;auto&quot;&gt;pending&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/migrate_cmd.py&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;_ledger_step_state&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;recorded-elsewhere&lt;/code&gt; state (&lt;code dir=&quot;auto&quot;&gt;_STATE_RECORDED_ELSEWHERE&lt;/code&gt;) remains valid only for the
&lt;strong&gt;distinct&lt;/strong&gt; real case of a clone that &lt;em&gt;applied&lt;/em&gt; the clone-local effect and then &lt;em&gt;lost&lt;/em&gt; it —
i.e. a per-clone record exists (&lt;code dir=&quot;auto&quot;&gt;applied == True&lt;/code&gt;) but &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; reports the effect absent now
(&lt;code dir=&quot;auto&quot;&gt;in_place_here is False&lt;/code&gt;). Acceptance scenario C was re-authored to assert the &lt;strong&gt;pending&lt;/strong&gt;
state for the fresh-clone case accordingly.&lt;/p&gt;
&lt;h3 id=&quot;3-incidental-notes&quot;&gt;3. Incidental notes&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Visibility surface command name.&lt;/strong&gt; §5 and #E now name the surface that shipped:
&lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate ledger&lt;/code&gt; (read-only; &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; emits the same report). The spike’s proposed
&lt;code dir=&quot;auto&quot;&gt;doctor migrations&lt;/code&gt; sub-surface and &lt;code dir=&quot;auto&quot;&gt;upgrade --list-applied&lt;/code&gt; flag were not built. One read
surface over the single pending-source (&lt;code dir=&quot;auto&quot;&gt;VersionDetector.applicable_migrations&lt;/code&gt;) makes §5’s
no-divergence property hold by construction rather than by two consumers staying in step.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;R4 mirror strip location.&lt;/strong&gt; The retirement of the stale on-disk &lt;code dir=&quot;auto&quot;&gt;migrations:&lt;/code&gt; block from
&lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt; (§6, no dual-write mirror) ships in &lt;code dir=&quot;auto&quot;&gt;metadata.py::save()&lt;/code&gt;, &lt;strong&gt;gated on ledger
adoption&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;_ledger_adopted&lt;/code&gt;), rather than inside the backfill migration — so a &lt;code dir=&quot;auto&quot;&gt;save()&lt;/code&gt; that
runs before the backfill never strips the block prematurely, and once the ledger owns the fact
the dead second authority is removed on the next write.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;4-amendment-2026-10-20-6539-the-requires_git_repository-classvar&quot;&gt;4. Amendment 2026-10-20 (#6539): the &lt;code dir=&quot;auto&quot;&gt;requires_git_repository&lt;/code&gt; ClassVar&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Contract.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;BaseMigration.requires_git_repository: ClassVar[bool] = False&lt;/code&gt;. A migration that
resolves the canonical repo root (&lt;code dir=&quot;auto&quot;&gt;charter.resolution.resolve_canonical_repo_root&lt;/code&gt;, directly or
through &lt;code dir=&quot;auto&quot;&gt;charter.activation.*&lt;/code&gt;) sets it. Outside a git repository the runner skips it &lt;strong&gt;before
&lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt;&lt;/strong&gt;, warns “not inside a git repository”, and writes &lt;strong&gt;no ledger record&lt;/strong&gt;, so it stays
selected and applies on a run inside a repository. “Inside” means exactly what the resolver
accepts (a project in a repository subdirectory counts). &lt;code dir=&quot;auto&quot;&gt;upgrade --dry-run --verbose&lt;/code&gt; reports
such a migration as skipped through the same probe.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt; failure.&lt;/strong&gt; A &lt;code dir=&quot;auto&quot;&gt;NotInsideRepositoryError&lt;/code&gt; raised from &lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt; is no longer a skip: an
&lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt; may already have written state. It is a recorded &lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt; (a &lt;code dir=&quot;auto&quot;&gt;runs_first&lt;/code&gt; migration
records nothing, as for any failure), the run stops and exits non-zero. The &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;can_apply()&lt;/code&gt; catches stay: they run before any write.
A repository probe that cannot run (&lt;code dir=&quot;auto&quot;&gt;GitCommonDirUnavailableError&lt;/code&gt;: git missing or unusable) is
neither inside nor outside: it is a recorded failure at all three sites, and
&lt;code dir=&quot;auto&quot;&gt;upgrade --dry-run --verbose&lt;/code&gt; says it would fail.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Accepted drift (C-002).&lt;/strong&gt; Adding the ClassVar changes the &lt;code dir=&quot;auto&quot;&gt;content_hash&lt;/code&gt; of each migration that
declares it, which surfaces as audit-only drift (it is never re-selected). Migrations that
declare it: &lt;code dir=&quot;auto&quot;&gt;3.2.0rc35_unified_bundle&lt;/code&gt;. The executed audit
&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/upgrade/test_requires_git_repository_audit.py&lt;/code&gt; fails for any migration that
reaches the resolver without declaring the flag.&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;amendment-2026-10-20-6431-adoption-baseline-requested-target-cap&quot;&gt;Amendment 2026-10-20 (#6431: adoption baseline, requested-target cap)&lt;/h2&gt;
&lt;p&gt;Three refinements, ruled by the operator on 2026-10-20 after the nightly found the first
ledger-era upgrade replaying older migrations (#6431, #6369). The Decision body above is
unchanged except where this amendment says so.&lt;/p&gt;
&lt;h3 id=&quot;1-6-adoption-also-settles-the-version-floor-reverses-the-2026-10-18-metadata-only-ruling&quot;&gt;1. §6 adoption also settles the version floor (reverses the 2026-10-18 metadata-only ruling)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Problem found.&lt;/strong&gt; Pre-ledger &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; stamped &lt;code dir=&quot;auto&quot;&gt;spec_kitty.version&lt;/code&gt; and wrote
&lt;code dir=&quot;auto&quot;&gt;migrations: applied: []&lt;/code&gt;; the retired version window then never selected a migration at or
below that version. So the version stamp, not the applied list, was what settled a
project’s older migrations, and the list of a real pre-ledger project is empty or partial.
The metadata-only backfill (closeout ruling 2026-10-18) left all those migrations pending,
and the first ledger-era upgrade replayed them against a current project:
&lt;code dir=&quot;auto&quot;&gt;2.0.6_consistency_sweep&lt;/code&gt; rewrote Mission &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;3.0.0_canonical_context&lt;/code&gt; rewrote
&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; (undoing a forced lane transition), and the upgrade auto-committed.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision.&lt;/strong&gt; On &lt;strong&gt;first adoption only&lt;/strong&gt;, until the backfill
(&lt;code dir=&quot;auto&quot;&gt;m_4_0_0rc8_backfill_migration_ledger.py&lt;/code&gt;, unreleased when amended) is itself recorded as
applied, it also records as &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; every registered migration whose &lt;code dir=&quot;auto&quot;&gt;target_version&lt;/code&gt; is below
both the recorded &lt;code dir=&quot;auto&quot;&gt;spec_kitty.version&lt;/code&gt; and the backfill’s own &lt;code dir=&quot;auto&quot;&gt;4.0.0rc8&lt;/code&gt;, and that neither
&lt;code dir=&quot;auto&quot;&gt;applied_migrations&lt;/code&gt; nor a ledger partition mentions. A migration AT the recorded version stays
pending, as the retired window still selected it when its &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; held. Adoption is keyed on the backfill’s own
record, not on a ledger file existing: a gitignored per-clone ledger survives a checkout of a
pre-ledger branch and is not adoption. The bound below &lt;code dir=&quot;auto&quot;&gt;4.0.0rc8&lt;/code&gt; exists because no CLI without
the ledger shipped a migration at that version, while an rc8 build that predates the ledger
stamped &lt;code dir=&quot;auto&quot;&gt;4.0.0rc8&lt;/code&gt;. The records are written with one atomic write per partition, so an
interrupted adoption leaves none of them. Partition routing is the same as the listed
records (§1): tracked unconditionally, clone-local only when its effect is present here (see
3). A listed &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt; record keeps its result, so §3’s “a failed migration is
retried” still holds. An unparseable recorded version stamps nothing. This is the adoption
counterpart of the init seed (Amendment 2026-10-18 §1), a one-time stamp. It does not revive
the selection window: once the backfill is recorded, nothing is stamped from the version.&lt;/p&gt;
&lt;p&gt;The backfill declares the new &lt;code dir=&quot;auto&quot;&gt;BaseMigration.ledger_adoption&lt;/code&gt; ClassVar. While it is unsettled,
&lt;code dir=&quot;auto&quot;&gt;get_applicable&lt;/code&gt; treats the ids it will settle (&lt;code dir=&quot;auto&quot;&gt;adoption_settled_ids&lt;/code&gt;) as already settled, so
&lt;code dir=&quot;auto&quot;&gt;upgrade --dry-run&lt;/code&gt;, the plan preview, the compat planner and &lt;code dir=&quot;auto&quot;&gt;migrate ledger&lt;/code&gt; list exactly what
the real run applies (§5’s single pending-source promise).&lt;/p&gt;
&lt;h3 id=&quot;2-3-the-runs-requested-target-stays-an-upper-bound&quot;&gt;2. §3 the run’s requested target stays an upper bound&lt;/h3&gt;
&lt;p&gt;§3 retired the version window as the &lt;strong&gt;applied&lt;/strong&gt; authority. Its upper bound
(&lt;code dir=&quot;auto&quot;&gt;target &amp;#x3C;= to_v&lt;/code&gt;) was the scope of the run the operator asked for, not an applied fact, and
retiring it let &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade --target X&lt;/code&gt; apply migrations declared for later
versions and then stamp the project as &lt;code dir=&quot;auto&quot;&gt;X&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;MigrationRegistry.get_applicable&lt;/code&gt; now selects
only migrations whose &lt;code dir=&quot;auto&quot;&gt;target_version &amp;#x3C;=&lt;/code&gt; the requested target. Selection is still a
ledger-diff, and a migration above the target is out of scope for that run: it is neither
selected nor settled. An unparseable target caps nothing. A &lt;code dir=&quot;auto&quot;&gt;ledger_adoption&lt;/code&gt; migration is
never capped: an upgrade to an older target that skipped adoption would still record the
migrations it ran, and those records would then hide the adoption for good. A default upgrade
(target = CLI version) is unaffected. &lt;code dir=&quot;auto&quot;&gt;target_version&lt;/code&gt; is therefore both the ordering cross-check (§2)
and this cap. The lower bound stays retired.&lt;/p&gt;
&lt;h3 id=&quot;3-a-clone-local-effect-is-present-only-inside-a-git-repository&quot;&gt;3. A clone-local effect is “present” only inside a git repository&lt;/h3&gt;
&lt;p&gt;The init seed and the adoption backfill record a clone-local migration without running it
only when its effect is present on this checkout. Both now ask one predicate,
&lt;code dir=&quot;auto&quot;&gt;ledger.clone_local_effect_in_place&lt;/code&gt;: a git repository exists &lt;strong&gt;and&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; reports
nothing to do. Without a repository, &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; of such a migration reports “nothing to do”
only because there is nowhere to put the effect yet, so an &lt;code dir=&quot;auto&quot;&gt;init&lt;/code&gt; outside git used to seed
the step as done, and the first upgrade after &lt;code dir=&quot;auto&quot;&gt;git init&lt;/code&gt; never installed it. A &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt;
error reads as “not in place”, leaving the migration pending.&lt;/p&gt;
&lt;h2 id=&quot;amendment-2026-10-22-6582-the-lead-block-the-charter-pack-cutover-after-its-prerequisites&quot;&gt;Amendment 2026-10-22 (#6582: the lead block, the charter-pack cutover after its prerequisites)&lt;/h2&gt;
&lt;p&gt;§2 allowed a single &lt;code dir=&quot;auto&quot;&gt;# runs-first:&lt;/code&gt; lead, and §6 gave it to the ledger backfill. That moved the
charter-pack cutover (&lt;code dir=&quot;auto&quot;&gt;charter_pack_cutover&lt;/code&gt;, spec FR-012 of mission
&lt;code dir=&quot;auto&quot;&gt;charter-pack-cutover-01M491G6&lt;/code&gt;) from the head of the run, where its retired front-pull used to
put it, back to its &lt;code dir=&quot;auto&quot;&gt;4.0.0rc6&lt;/code&gt; version slot. About forty pending migrations then ran ahead of it
on a pre-cutover project, so a refused collision (“moves nothing”) left &lt;code dir=&quot;auto&quot;&gt;.gitattributes&lt;/code&gt; merge
driver lines behind, and FR-012 (“runs before every other pending migration”) no longer held.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision (operator ruling, 2026-10-22).&lt;/strong&gt; The manifest’s &lt;code dir=&quot;auto&quot;&gt;# runs-first:&lt;/code&gt; annotation marks an
entry of the &lt;strong&gt;lead block&lt;/strong&gt;: a contiguous prefix of annotated entries that run first, in the order
listed, regardless of their &lt;code dir=&quot;auto&quot;&gt;target_version&lt;/code&gt;. The block holds the cutover and the two migrations
it depends on:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;4.0.0rc8_backfill_migration_ledger&lt;/code&gt; leads, as §6 requires.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;3.2.0rc35_charter_bundle_v2&lt;/code&gt; follows. The cutover parses &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/synthesis-manifest.yaml&lt;/code&gt;
with the current model, which accepts only schema &lt;code dir=&quot;auto&quot;&gt;2&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;3&lt;/code&gt;; only this migration upgrades a &lt;code dir=&quot;auto&quot;&gt;v1&lt;/code&gt;
bundle. Without it ahead, a pre-3.2.0rc35 project with a &lt;code dir=&quot;auto&quot;&gt;v1&lt;/code&gt; manifest failed at the cutover on
every run (found in pre-PR review; pinned by
&lt;code dir=&quot;auto&quot;&gt;test_fr012_v1_synthesis_manifest_upgrades_through_the_cutover&lt;/code&gt;). It changes only the charter
bundle under &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/&lt;/code&gt; and is detect-gated.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;charter_pack_cutover&lt;/code&gt;. It cannot lead ahead of the backfill: its first-application check
(&lt;code dir=&quot;auto&quot;&gt;_is_first_application&lt;/code&gt;, which gates the one-time activation-list resets) reads the ledger, so
on a pre-ledger project that already applied the cutover it would redo those resets against
deliberate &lt;code dir=&quot;auto&quot;&gt;[]&lt;/code&gt; lists. The shipped migration is not edited (DIRECTIVE_044), so ordering is the
fix.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;FR-012 is read as “the cutover runs before every other pending &lt;em&gt;project&lt;/em&gt; migration, after the
migrations it depends on”: the backfill only writes ledger records and the bundle upgrade only
brings the charter bundle to the schema the cutover reads.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Residual.&lt;/strong&gt; On a constitution-era project (&lt;code dir=&quot;auto&quot;&gt;.kittify/constitution/&lt;/code&gt;, before &lt;code dir=&quot;auto&quot;&gt;3.1.1_charter_rename&lt;/code&gt;)
the bundle upgrade now runs before the rename, finds no &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/&lt;/code&gt;, and records &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt;.
Later migrations in the same run bring the bundle current: the resulting &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; tree equals
the one the version-slot order produced. The step stays a re-skipped, &lt;code dir=&quot;auto&quot;&gt;pending&lt;/code&gt; row in
&lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate ledger&lt;/code&gt;, which is §3’s behaviour for a not-needed migration.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Assumption (legacy &lt;code dir=&quot;auto&quot;&gt;.specify/&lt;/code&gt; layout).&lt;/strong&gt; The cutover now runs before &lt;code dir=&quot;auto&quot;&gt;0.2.0_specify_to_kittify&lt;/code&gt;,
so on a project that still has &lt;code dir=&quot;auto&quot;&gt;.specify/&lt;/code&gt; the cutover finds no &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; inventory and records
&lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; in that run. This costs nothing: the CLI creates &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; before the migrations run, so
&lt;code dir=&quot;auto&quot;&gt;0.2.0_specify_to_kittify&lt;/code&gt; itself skips (“&lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; already exists - manual merge required”) with
or without this order, and a pre-0.2 project never reaches the cutover’s inputs through the rename.
A project whose &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; is brought to the legacy shape by hand converges on its next
&lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt;, because a &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; record does not settle the cutover. Checked with a
throwaway &lt;code dir=&quot;auto&quot;&gt;.specify/&lt;/code&gt; project (two runs), not pinned by a test.&lt;/p&gt;
&lt;p&gt;The build-time gate (&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_migration_order_manifest.py&lt;/code&gt;) now requires every
&lt;code dir=&quot;auto&quot;&gt;# runs-first:&lt;/code&gt; entry to sit in the lead block and checks version monotonicity over the entries
after it; the gate’s &lt;code dir=&quot;auto&quot;&gt;lead_block_length&lt;/code&gt; is the one definition. The
&lt;code dir=&quot;auto&quot;&gt;runs_first&lt;/code&gt; ClassVar is unchanged: it governs reselection, not order, and at most one migration
sets it.&lt;/p&gt;
&lt;h2 id=&quot;amendment-2026-10-25-6589-superseding-a-shipped-migration-without-editing-it&quot;&gt;Amendment 2026-10-25 (#6589: superseding a shipped migration without editing it)&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Correction.&lt;/strong&gt; The Consequences bullet on retired modules says the &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; record “keeps them
from re-firing”. It does not: §3 settles a migration only on a &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; record, so a
&lt;code dir=&quot;auto&quot;&gt;SupersededMigration&lt;/code&gt; is selected and re-skipped on every run. That is harmless for a no-op, and it
is why two live backfills could undo a later migration. &lt;code dir=&quot;auto&quot;&gt;3.2.5_agents_skills_gitignore_backfill&lt;/code&gt;
and &lt;code dir=&quot;auto&quot;&gt;3.2.6rc3_narrow_cursor_gitignore&lt;/code&gt;, once recorded &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt;, were selected again after
&lt;code dir=&quot;auto&quot;&gt;4.0.0rc8_narrow_agent_gitignore&lt;/code&gt; removed their rows. Their &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; then went True, and they
wrote &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; and the &lt;code dir=&quot;auto&quot;&gt;.cursor/&lt;/code&gt; rows back.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision (operator ruling, 2026-10-25).&lt;/strong&gt; Both are superseded by
&lt;code dir=&quot;auto&quot;&gt;4.0.0rc8_narrow_agent_gitignore&lt;/code&gt;. Their modules are not edited (DIRECTIVE_044). Instead,
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/supersession.py&lt;/code&gt; holds &lt;code dir=&quot;auto&quot;&gt;SUPERSEDED_MIGRATIONS&lt;/code&gt; (superseded id → successor
id). &lt;code dir=&quot;auto&quot;&gt;MigrationRegistry.register&lt;/code&gt; registers a &lt;code dir=&quot;auto&quot;&gt;SupersededMigration&lt;/code&gt; substitute for each listed id,
built at register time. The substitute keeps:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the shipped class’s id, &lt;code dir=&quot;auto&quot;&gt;target_version&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;description&lt;/code&gt;, routing key (&lt;code dir=&quot;auto&quot;&gt;clone_local_effect&lt;/code&gt;),
&lt;code dir=&quot;auto&quot;&gt;identity&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;requires_git_repository&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;runs_on_worktrees&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;its defining module, so &lt;code dir=&quot;auto&quot;&gt;content_hash&lt;/code&gt; stays the shipped module’s hash and recorded history never
reads as drift.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The decorator still returns the shipped class, so a direct import keeps the old behaviour (its
unit tests stay valid). Every registry consumer sees the no-op: selection, the runner, the
worktree loop, &lt;code dir=&quot;auto&quot;&gt;upgrade --dry-run&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;migrate ledger&lt;/code&gt;, the init seed and the adoption backfill.
The successor must come later in &lt;code dir=&quot;auto&quot;&gt;order_manifest.txt&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/upgrade/test_gitignore_backfills_superseded_6589.py&lt;/code&gt;
pins that, the byte-identical hash, and the no-re-add behaviour for a pre-ledger and a
ledger-era project.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;This is now the way to supersede a shipped migration.&lt;/strong&gt; The three earlier precedents
(&lt;code dir=&quot;auto&quot;&gt;m_2_1_2_fix_glossary_context_skill&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;m_3_2_x_normalize_activation_absence&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;m_3_2_0rc35_default_charter_pack&lt;/code&gt;) were rewritten in place before the ledger and its hash existed.
Do not repeat that.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Accepted loss.&lt;/strong&gt; A project upgrading from before 3.2.5 no longer gets two things the 3.2.5 backfill
provided:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the &lt;code dir=&quot;auto&quot;&gt;.kittify/skills-manifest.json&lt;/code&gt; ignore row (&lt;code dir=&quot;auto&quot;&gt;4.0.0rc8_narrow_agent_gitignore&lt;/code&gt; keeps that row
but does not add it);&lt;/li&gt;
&lt;li&gt;the &lt;code dir=&quot;auto&quot;&gt;git rm --cached&lt;/code&gt; of committed projected skills (#3393), so those files stay tracked while
the rc8 agent-files block ignores them.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;upgrade --dry-run --verbose&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;migrate ledger&lt;/code&gt; keep listing both ids as pending/&lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt;, and the runner reports them as “not needed” (its &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; is False before &lt;code dir=&quot;auto&quot;&gt;can_apply&lt;/code&gt; returns the &lt;code dir=&quot;auto&quot;&gt;superseded_by&lt;/code&gt; text); marking superseded ids in that read surface is left for later. A run capped below 4.0.0rc8 (&lt;code dir=&quot;auto&quot;&gt;upgrade --target 3.2.6rc3&lt;/code&gt;) no longer narrows a blanket &lt;code dir=&quot;auto&quot;&gt;.cursor/&lt;/code&gt;
row; the rc8 migration does. The #5443 upgrade-commit tests now use the untrack of
&lt;code dir=&quot;auto&quot;&gt;3.2.0rc35_kittify_runtime_git_hygiene&lt;/code&gt;. Other shipped migrations with the same re-selection shape
(&lt;code dir=&quot;auto&quot;&gt;0.4.8_gitignore_agents&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;3.1.2_globalize_commands&lt;/code&gt;, #6547) are not changed here.&lt;/p&gt;
&lt;h2 id=&quot;amendment-2026-10-25-6629-the-interview-promotion-is-superseded&quot;&gt;Amendment 2026-10-25 (#6629: the interview promotion is superseded)&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Decision.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;unify_charter_activation_promote_answers&lt;/code&gt; is superseded by
&lt;code dir=&quot;auto&quot;&gt;4.0.0rc8_promote_interview_selections&lt;/code&gt;, through the same &lt;code dir=&quot;auto&quot;&gt;SUPERSEDED_MIGRATIONS&lt;/code&gt; table and
with its module left byte-identical (DIRECTIVE_044). The shipped step seeded an absent
&lt;code dir=&quot;auto&quot;&gt;activated_&amp;#x3C;kind&gt;&lt;/code&gt; key with the kind’s whole in-force set before it appended the interview
selections. &lt;code dir=&quot;auto&quot;&gt;charter synthesize&lt;/code&gt; then read that list as an operator’s activation: it demanded a
companion tactic per directive and skipped the fresh-project seed. The step also read only
&lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;, so after the keys had moved it wrote a stale second list there (#6549).&lt;/p&gt;
&lt;p&gt;The successor works differently:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;it is listed after &lt;code dir=&quot;auto&quot;&gt;4.0.0rc8_activation_ledger&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;it appends only the interview selections a present list lacks, writing through the activation
write target and the promotion primitive;&lt;/li&gt;
&lt;li&gt;it never writes an absent key.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Settling.&lt;/strong&gt; The successor’s &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; is always True, and &lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt; succeeds even when nothing is
left to promote. Its first run is therefore recorded &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; and settles it. A &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; record would re-select it on every upgrade (the
correction above), and that run would append the interview ids back into a list an operator
had narrowed with &lt;code dir=&quot;auto&quot;&gt;charter activate --only&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Only where the shipped step never settled.&lt;/strong&gt; Since #2526 the interview record has not been an
activation source, so promotion is a one-time backstop for a project that crosses that change.
When the Migration Ledger records that &lt;code dir=&quot;auto&quot;&gt;unify_charter_activation_promote_answers&lt;/code&gt; ran, a
present list that lacks an interview id has had it removed, or never had it in force, so the
successor appends nothing. That is a &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; record (the shipped step ran, or the adoption
backfill settled it for a project created after it) or a &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; record the shipped step wrote
itself: the pre-ledger runner recorded &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; (“Not applicable”) when the interview had already
promoted, and the backfill copies it. The substitute’s own &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; does not count. The runner
marks it with the substitute’s &lt;code dir=&quot;auto&quot;&gt;superseded_by&lt;/code&gt; note (an optional record field, written only when
set), so the two read apart. On a project still being adopted, a dry run writes no record, so the
successor also asks the pending adoption what it will record (&lt;code dir=&quot;auto&quot;&gt;registry.pending_adoption_ids&lt;/code&gt;,
plus the legacy &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt;), as selection does. Appending would change
activation silently (#6499). This adds a reading rule. A successor may read the record of the
migration it supersedes, through its authoritative partition. It never branches on the record of
any other migration: the Migration Ledger stays the selection authority, not a general state input.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Residual.&lt;/strong&gt; A shipped &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; can also mean the step did nothing at all: it read only
&lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;, so on a project whose keys were in &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; and that had no
&lt;code dir=&quot;auto&quot;&gt;config.yaml&lt;/code&gt; it skipped without promoting (#6549). The successor appends nothing there either.
Interview-side promotion since #2526 covers most of those projects.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Version.&lt;/strong&gt; The successor sits at 4.0.0rc8. The ledger-adoption backfill settles only steps
below both the recorded version and 4.0.0rc8, so it is never settled without running.
&lt;code dir=&quot;auto&quot;&gt;tests/upgrade/test_upgrade_keeps_absent_activation_6629.py&lt;/code&gt; drives a project stamped
below 3.2.6rc1 through the runner and &lt;code dir=&quot;auto&quot;&gt;charter synthesize --dry-run --json&lt;/code&gt;. On a project stamped
above 3.2.6rc1, adoption settles the shipped step without running it in that upgrade, so a
reproduction stamped there would never witness the bug.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Accepted loss.&lt;/strong&gt; A project an earlier build already seeded keeps its list. The successor only
warns when a present list holds every available artifact while the interview selected fewer,
and it names &lt;code dir=&quot;auto&quot;&gt;charter interview --narrow-activation&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;charter activate &amp;#x3C;kind&gt; &amp;#x3C;id&gt; --only&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;amendment-2026-10-25b-6669-residue-aware-successors&quot;&gt;Amendment 2026-10-25b (#6669: residue-aware successors)&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Problem.&lt;/strong&gt; Four shipped migrations enumerate every &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; child and write into it:
&lt;code dir=&quot;auto&quot;&gt;0.9.0_frontmatter_only_lanes&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;0.9.1_complete_migration&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;2.0.6_consistency_sweep&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;3.1.1_normalize_status_json&lt;/code&gt;. A residue folder (no &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; on disk, and git does
not recognize it as a Mission) therefore had its lane folders flattened, its work packages
rewritten, a baseline &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; written and a &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; normalised. Their modules are
byte-frozen (DIRECTIVE_044, &lt;code dir=&quot;auto&quot;&gt;content_hash&lt;/code&gt;), so the fix cannot be an edit.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision (operator ruling, 2026-10-25).&lt;/strong&gt; Each is superseded, through the table of Amendment
2026-10-25, by a successor that is a &lt;strong&gt;new migration&lt;/strong&gt;, not a rewrite of the old module:&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Superseded (recorded no-op)&lt;/th&gt;&lt;th&gt;Successor&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;0.9.0_frontmatter_only_lanes&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;0.9.0_residue_safe_frontmatter_only_lanes&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;0.9.1_complete_migration&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;0.9.1_residue_safe_complete_migration&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;2.0.6_consistency_sweep&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;2.0.6_residue_safe_consistency_sweep&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;3.1.1_normalize_status_json&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;3.1.1_residue_safe_normalize_status_json&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;New migrations, not substitutes.&lt;/strong&gt; A &lt;code dir=&quot;auto&quot;&gt;SupersededMigration&lt;/code&gt; substitute is a no-op by design, so
it cannot carry the repair. The successor must repair the same real Missions, in one of two
patterns:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Subclass (&lt;code dir=&quot;auto&quot;&gt;0.9.0&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;0.9.1&lt;/code&gt;).&lt;/strong&gt; The successor subclasses the shipped class, so the shipped walk
still runs and every repair is inherited. It is made residue-safe only by the methods it
overrides: &lt;code dir=&quot;auto&quot;&gt;_is_legacy_format&lt;/code&gt; (0.9.0), &lt;code dir=&quot;auto&quot;&gt;_has_remaining_lane_dirs&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;_normalize_all_frontmatter&lt;/code&gt; (0.9.1). Both also list &lt;code dir=&quot;auto&quot;&gt;ResidueSafeLaneSuccessorMixin&lt;/code&gt; first in
their bases; it carries the shared &lt;code dir=&quot;auto&quot;&gt;detect&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;apply&lt;/code&gt; wrappers and the &lt;code dir=&quot;auto&quot;&gt;_is_residue&lt;/code&gt; decision the
overrides call. The walker gate pins each override, and the mixin’s &lt;code dir=&quot;auto&quot;&gt;_is_residue&lt;/code&gt;, to the residue
predicate.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Re-implementation (&lt;code dir=&quot;auto&quot;&gt;2.0.6&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;3.1.1&lt;/code&gt;).&lt;/strong&gt; The successor subclasses &lt;code dir=&quot;auto&quot;&gt;BaseMigration&lt;/code&gt;, re-implements
&lt;code dir=&quot;auto&quot;&gt;detect&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;apply&lt;/code&gt; over the Mission folders that &lt;code dir=&quot;auto&quot;&gt;partition_kitty_specs&lt;/code&gt; returns (3.1.1 also its
status writer), and reuses the shipped module’s helpers (&lt;code dir=&quot;auto&quot;&gt;_repair_feature&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;_needs_normalisation&lt;/code&gt;, and so on). Nothing of the shipped class is inherited.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;In both patterns the shipped module is imported as a module alias, or only its module-level
helpers, never the class by name: &lt;code dir=&quot;auto&quot;&gt;auto_discover_migrations&lt;/code&gt; skips a module whose &lt;code dir=&quot;auto&quot;&gt;dir()&lt;/code&gt; holds a
class with an already-registered &lt;code dir=&quot;auto&quot;&gt;migration_id&lt;/code&gt;, so a name import would make the successor vanish
after &lt;code dir=&quot;auto&quot;&gt;MigrationRegistry.clear()&lt;/code&gt;. Drift scope: each successor’s &lt;code dir=&quot;auto&quot;&gt;content_hash&lt;/code&gt; covers its own
module only. A change to the shared &lt;code dir=&quot;auto&quot;&gt;_residue_successor.py&lt;/code&gt; or to the residue predicate is outside
drift scope, as for any other migration that imports helpers.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Same slot.&lt;/strong&gt; Each successor sits immediately after its predecessor in &lt;code dir=&quot;auto&quot;&gt;order_manifest.txt&lt;/code&gt;, with
a &lt;code dir=&quot;auto&quot;&gt;# tie:&lt;/code&gt; annotation, because the successor has the predecessor’s &lt;code dir=&quot;auto&quot;&gt;target_version&lt;/code&gt;. A later step
(the lifecycle normalisation, the status migrations) must see the successor’s output exactly where
it saw the predecessor’s. &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_migration_order_manifest.py&lt;/code&gt; still gates the
order; &lt;code dir=&quot;auto&quot;&gt;test_each_successor_sits_right_after_its_predecessor_in_the_order_manifest&lt;/code&gt; pins the slot.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The selection-view gate.&lt;/strong&gt; A project that already ran the predecessor must not run the successor
on top of it. Each successor’s &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; returns False when
&lt;code dir=&quot;auto&quot;&gt;registry.settled_in_selection_view(project_path, predecessor_id)&lt;/code&gt; is True. That helper uses the one
predicate of &lt;code dir=&quot;auto&quot;&gt;MigrationRegistry.get_applicable&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_settled_in_view&lt;/code&gt;): the id is a &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; record
in its authoritative partition, or an unsettled ledger-adoption migration will settle it on apply.
Reading the ledger directly would miss the second case, so the successor would repair a project the
adoption backfill is about to mark as done. The gate is a &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; guard only: selection stays
ledger-diff (§3), and &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; remains the runner’s idempotency check. &lt;strong&gt;Extended by Amendment
2026-10-30 (#6688):&lt;/strong&gt; that same settlement view, applied to the &lt;em&gt;successor&lt;/em&gt;, is what reopens the
retry when the predecessor never settled.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;One residue rule, one walk.&lt;/strong&gt; The successors share &lt;code dir=&quot;auto&quot;&gt;_residue_successor.py&lt;/code&gt; (a non-migration
module, never auto-discovered): the lane mixin, &lt;code dir=&quot;auto&quot;&gt;partition_kitty_specs&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;partition_checkout_specs&lt;/code&gt; (a Mission walk that also covers &lt;code dir=&quot;auto&quot;&gt;.worktrees/*/kitty-specs/&lt;/code&gt;, each
worktree judged against itself as the checkout root) and one residue notice per folder. The tracked
paths are probed once per walk with &lt;code dir=&quot;auto&quot;&gt;mission_resolver.probe_tracked_mission_paths&lt;/code&gt;.
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_migration_walkers_use_mission_predicate.py&lt;/code&gt; fails a walker that does not
reach &lt;code dir=&quot;auto&quot;&gt;is_kitty_specs_residue&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;is_mission_dir&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;No edit to a shipped module.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;git diff --diff-filter=MDR origin/main -- &apos;src/specify_cli/upgrade/migrations/m_*.py&apos;&lt;/code&gt;
prints nothing.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Accepted residuals.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;C-006, closed by Amendment 2026-10-30 (#6688).&lt;/strong&gt; A retry used to be lost on first adoption: a
pre-ledger project whose &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt; records a predecessor as &lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; had the
successor stamped &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; by the first-adoption backfill (Amendment 2026-10-20), so the repair
the predecessor never finished was never retried. The retry rule in Amendment 2026-10-30 reopens
it without touching the frozen backfill or the manifest.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A stale “pending” listing.&lt;/strong&gt; A &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; record does not settle a migration (§3, Amendment
2026-10-25), and an inert successor is &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt;. On a project whose predecessor already ran,
&lt;code dir=&quot;auto&quot;&gt;migrate ledger&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;upgrade --dry-run --verbose&lt;/code&gt; therefore keep listing the successor as not yet
applied, and the runner re-skips it every run. This is idempotent and harmless; marking it in the
read surface is left for later, with the same item for the superseded ids.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Git-aware residue.&lt;/strong&gt; In a project where git tracks some Mission path, a committed folder holding only
&lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;tasks/&lt;/code&gt; counts as residue, and the successors leave it alone. The notice names the
folder and the remedy (add a &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;, or remove the folder).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The audit’s residue rule is stricter than upgrade’s.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;RESIDUE_DIRECTORY&lt;/code&gt; uses strict
&lt;code dir=&quot;auto&quot;&gt;is_mission_dir&lt;/code&gt;. Without usable git, or with &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; ignored, it reports a folder holding
only &lt;code dir=&quot;auto&quot;&gt;plan.md&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt; as residue, while upgrade’s file-presence mode treats that folder as a
Mission and repairs it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The mode flips on one tracked file.&lt;/strong&gt; Git-aware mode applies as soon as git tracks any path under
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt;. In a project where &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; is gitignored but one file was force-added,
untracked legacy Missions without &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; become residue and are left alone.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;FABRICATED_IDENTITY_SUSPECTED&lt;/code&gt; false negative.&lt;/strong&gt; The finding compares the slug’s trailing mid8
with the &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;. A fabricated &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; in a legacy &lt;code dir=&quot;auto&quot;&gt;NNN-slug&lt;/code&gt; residue folder, whose slug
carries no mid8, is not flagged.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A degraded probe only warns.&lt;/strong&gt; A non-timeout git failure of the tracked-path probe (for example a
corrupt index) falls back to file-presence mode and logs one warning per checkout and run. A timeout
is a retryable &lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt; record, in the main checkout and in each worktree.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-10-30-6613-the-runs_first-structural-reselection-and-the-ledger-lock&quot;&gt;Amendment 2026-10-30 (#6613: the &lt;code dir=&quot;auto&quot;&gt;runs_first&lt;/code&gt; structural reselection, and the ledger lock)&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Problem.&lt;/strong&gt; Two statements in this ADR did not match the code that implements it, so a reader
taking them at face value would be wrong about when a migration runs again.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;§1 says selection “collapses to ‘is this id in the applicable ledger’”. It does not, quite.
&lt;code dir=&quot;auto&quot;&gt;BaseMigration.reselect_when_recorded&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;upgrade/migrations/base.py&lt;/code&gt;) returns
&lt;code dir=&quot;auto&quot;&gt;runs_first and structural_detect(project_path)&lt;/code&gt;: a &lt;code dir=&quot;auto&quot;&gt;runs_first&lt;/code&gt; migration whose structural
predicate reports its old state present is re-selected &lt;strong&gt;even though a &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; record exists&lt;/strong&gt;.
&lt;code dir=&quot;auto&quot;&gt;structural_detect&lt;/code&gt; appeared nowhere in this ADR or in its amendments, and the touchpoint list
below still describes &lt;code dir=&quot;auto&quot;&gt;reselect_when_recorded&lt;/code&gt; as one that “collapses to a ledger lookup”.&lt;/li&gt;
&lt;li&gt;§1 (“Atomic write, single-writer”) said the ledger append takes no lock and that wrapping it in
&lt;code dir=&quot;auto&quot;&gt;kernel.locks&lt;/code&gt; was the named extension point, “deliberately &lt;strong&gt;not&lt;/strong&gt; built now”. #6613 built it.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Decision (recorded, not re-decided).&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;The selection rule is ledger-diff &lt;em&gt;plus&lt;/em&gt; one structural reselection.&lt;/strong&gt; For every migration the
authority is its applicable partition: a &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; record settles it. For the single migration
allowed to set &lt;code dir=&quot;auto&quot;&gt;runs_first&lt;/code&gt;, a recorded migration is still re-selected when
&lt;code dir=&quot;auto&quot;&gt;structural_detect(project_path)&lt;/code&gt; reports the old state present — state a pulled &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt;
or a merge can revive after the first application. &lt;code dir=&quot;auto&quot;&gt;structural_detect&lt;/code&gt; is therefore part of
selection, not an optimisation, and it must stay content-driven (never version-driven).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;It is bounded and it does not become a second authority.&lt;/strong&gt; At most one registered migration may
set &lt;code dir=&quot;auto&quot;&gt;runs_first&lt;/code&gt; (the &lt;code dir=&quot;auto&quot;&gt;MigrationRegistry.register&lt;/code&gt; guard in &lt;code dir=&quot;auto&quot;&gt;registry.py&lt;/code&gt;, which raises &lt;code dir=&quot;auto&quot;&gt;ValueError&lt;/code&gt; on a second one; the retired &lt;code dir=&quot;auto&quot;&gt;_order_runs_first&lt;/code&gt; helper is gone). &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; remains the pre-&lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt;
idempotency guard and never the skip authority (C-003 of §3); a &lt;code dir=&quot;auto&quot;&gt;runs_first&lt;/code&gt; migration’s &lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt;
must be idempotent, because reselection re-applies it. &lt;code dir=&quot;auto&quot;&gt;clone_local_effect&lt;/code&gt; is unaffected: it is
the ledger’s routing key only, and clone-local reselection is plain ledger-diff (§3).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Recording is not deciding.&lt;/strong&gt; Removing the reselection — making §1’s “collapses to a ledger
lookup” literally true — is an &lt;strong&gt;open operator decision&lt;/strong&gt;, filed as the other half of #6613. This
amendment documents the behaviour as shipped; it neither widens it nor removes it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The append is locked (supersedes the “deliberately not built now” sentence of §1).&lt;/strong&gt; Every
append holds a dedicated sidecar lock across its read and its &lt;code dir=&quot;auto&quot;&gt;os.replace&lt;/code&gt;, taken through
&lt;code dir=&quot;auto&quot;&gt;kernel.locks.machine_file_lock&lt;/code&gt; — the extension point §1 named — with a bounded wait
(&lt;code dir=&quot;auto&quot;&gt;ledger.LEDGER_LOCK_TIMEOUT_S&lt;/code&gt;, 30 s) that raises &lt;code dir=&quot;auto&quot;&gt;ledger.MigrationLedgerLockTimeoutError&lt;/code&gt;
having appended nothing. The lock file is
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;user state dir&gt;/spec-kitty/locks/migration-ledger/&amp;#x3C;sha256(resolved ledger path)[:32]&gt;.lock&lt;/code&gt;: a
dedicated sidecar (never the payload, which the primitive truncates on release) in the per-user
machine lock directory, &lt;strong&gt;never inside the checkout&lt;/strong&gt;. A lock under &lt;code dir=&quot;auto&quot;&gt;.kittify/migrations/&lt;/code&gt; was
tried first and rejected: it shows as an untracked &lt;code dir=&quot;auto&quot;&gt;git status&lt;/code&gt; entry on any project whose
&lt;code dir=&quot;auto&quot;&gt;.gitignore&lt;/code&gt; lacks the &lt;code dir=&quot;auto&quot;&gt;3.2.4_runtime_dirs_gitignore_backfill&lt;/code&gt; entry, so &lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt; would dirty a
clean checkout. Outside the checkout it can neither show in &lt;code dir=&quot;auto&quot;&gt;git status&lt;/code&gt; nor reach an autocommit.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The lock is per ledger &lt;em&gt;file&lt;/em&gt;, not per repository.&lt;/strong&gt; The file is the thing that can lose a
record; a git-common-dir key would over-serialize unrelated checkouts and would need a git
invocation on a path that must also run outside a repository (&lt;code dir=&quot;auto&quot;&gt;init&lt;/code&gt; outside git deliberately
leaves clone-local steps pending, #6431). No anchored-lock-path helper is added here: #6727 owns
consolidating that rule, and the ledger derives its path from a path it already holds.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Durability is unchanged (NFR-001).&lt;/strong&gt; The write is still the full-file atomic rewrite of
&lt;code dir=&quot;auto&quot;&gt;core/atomic.py&lt;/code&gt;, never &lt;code dir=&quot;auto&quot;&gt;O_APPEND&lt;/code&gt;; the lock serialises the read-modify-write, it does not change
the write.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Accepted residuals.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A timed-out append aborts the run.&lt;/strong&gt; A lock still held after 30 s raises out of &lt;code dir=&quot;auto&quot;&gt;runner&lt;/code&gt; at the
point the record was to be written — which can be after &lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt; succeeded, or before it ran at
all when the record is a &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; one. Nothing is recorded for that migration, the run stops, and
the message says what happened and to retry. Re-running is safe because &lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt; is idempotent
(above) and the record is simply re-attempted; no false &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; is ever written.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The duplicate pre-check is outside the lock.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;runner._record_ledger_result&lt;/code&gt; reads the
partition to skip a &lt;code dir=&quot;auto&quot;&gt;(id, result)&lt;/code&gt; it already has, then appends. Two concurrent runs can both
decide “not recorded” and both append, so a partition may hold the same &lt;code dir=&quot;auto&quot;&gt;(id, result)&lt;/code&gt; twice.
&lt;code dir=&quot;auto&quot;&gt;ledger._normalize_records&lt;/code&gt; collapses by id on every read, so the authority is unaffected and the
duplicate never settles anything twice; only the raw line count can grow.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Closure of gap-table row G-15 is deferred.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;docs/architecture/event-ledger-writers-and-readers.md&lt;/code&gt;
(the “No lock” writer row and the G-15 row) is frozen by &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_events_import_frozen.py&lt;/code&gt;
(ADR 2026-10-29-1 D-9, blob &lt;code dir=&quot;auto&quot;&gt;c2943d49…&lt;/code&gt;). Correcting it needs an operator-approved re-pin of
&lt;code dir=&quot;auto&quot;&gt;_FROZEN_OBJECTS&lt;/code&gt;; this amendment carries the facts in the meantime.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-10-30-6688-a-successors-settlement-follows-its-predecessors-outcome&quot;&gt;Amendment 2026-10-30 (#6688: a successor’s settlement follows its predecessor’s outcome)&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Problem.&lt;/strong&gt; First adoption settles every migration below the recorded version from the version
stamp (Amendment 2026-10-20), including a residue-safe successor whose superseded predecessor never
settled. On a pre-ledger project whose &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt; records the predecessor &lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt;,
the baseline therefore wrote a real &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; for the successor id while the predecessor became a
recorded no-op, and both consumers of “settled” — ledger-diff selection (§3) and the runner’s skip
gate — read that record. The repair the predecessor would have retried on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; was lost (residual
C-006 of Amendment 2026-10-25b, pinned there as a strict &lt;code dir=&quot;auto&quot;&gt;xfail&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision (issue #6688).&lt;/strong&gt; A successor’s settlement is derived from its &lt;strong&gt;predecessor’s recorded
outcome&lt;/strong&gt;, not from its own record:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A migration declares &lt;code dir=&quot;auto&quot;&gt;predecessor_id&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;BaseMigration&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/base.py&lt;/code&gt;)
when it replaces a shipped migration. The four residue-safe successors declare it; no other
migration does, and the default is empty.&lt;/li&gt;
&lt;li&gt;It is settled only when the predecessor’s own authoritative partition records &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt;, or a
pending adoption will record one — the same evidence that settles the predecessor itself, which is
what makes the retry behave as the predecessor did before #6669.&lt;/li&gt;
&lt;li&gt;Successor settlement is part of the &lt;strong&gt;ledger predicate&lt;/strong&gt;, not a second reselection. The rule body
is &lt;code dir=&quot;auto&quot;&gt;registry._predecessor_outcome_settled_in_view&lt;/code&gt;, composed into the one selection-view predicate
&lt;code dir=&quot;auto&quot;&gt;_settled_in_view&lt;/code&gt; that &lt;code dir=&quot;auto&quot;&gt;settled_in_selection_view&lt;/code&gt; exposes. The runner’s skip gate consults that
same predicate, so selection and apply-time settlement cannot disagree, and a run that adopts the
ledger and then reaches the successor in the same pass applies it.
&lt;code dir=&quot;auto&quot;&gt;BaseMigration.reselect_when_recorded&lt;/code&gt; is unchanged by this amendment: it stays the single
structural reselection of Amendment 2026-10-30 (#6613), so that amendment’s statement that
selection is ledger-diff plus one structural reselection still holds.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; remains the only thing that can trigger &lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt;. The rule widens &lt;em&gt;who is
re-evaluated&lt;/em&gt;, never &lt;em&gt;what is re-applied&lt;/em&gt;: on a repaired project &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; reports nothing to do,
and nothing is written: no Mission file changes and no ledger record. A re-evaluation that finds
nothing to do never downgrades a held &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; — the read view keeps the last record
per id, so that write would claim the repair never ran. The run reports the successor &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt;
without recording it.&lt;/li&gt;
&lt;li&gt;A predecessor id the registry cannot resolve keeps the migration’s own record’s word; a migration
with no declared predecessor is untouched, so every other registered migration keeps success-only
settlement and pays one attribute check.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Routes rejected.&lt;/strong&gt; Marking adoption-baseline records with provenance would edit the frozen
backfill (DIRECTIVE_044), require a supersession of the adoption migration itself and add a ledger
field. Moving each successor’s &lt;code dir=&quot;auto&quot;&gt;target_version&lt;/code&gt; above the adoption ceiling would change manifest
semantics and silently drop the repair from every &lt;code dir=&quot;auto&quot;&gt;upgrade --target&lt;/code&gt; between the successor’s version
and rc8. The issue records both routes as considered and rejected.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Consequences.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The runner no longer downgrades a held &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; when a re-evaluated migration finds
nothing to do (&lt;code dir=&quot;auto&quot;&gt;runner._record_ledger_result&lt;/code&gt;), so a completed repair keeps its record — and the
read view — instead of being reported as never applied.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;xfail&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/upgrade/test_residue_safe_successors_6669.py&lt;/code&gt; is removed;
&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/upgrade/test_successor_retry_6688.py&lt;/code&gt; pins the retry, the no-replay rule, the
dry-run preview, the worktree pass and the settled-predecessor gate through
&lt;code dir=&quot;auto&quot;&gt;MigrationRunner.upgrade&lt;/code&gt;, plus the declaration audit and the unresolvable-predecessor branch at
registry level.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;New accepted residual: a successor re-evaluates while its predecessor stays unsettled.&lt;/strong&gt; Any
predecessor that never recorded &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; leaves its successor re-evaluated once per upgrade run.
Two flavours are in scope: a &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; the shipped migration recorded itself (a real “not
applicable”) and the superseded no-op &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; that #6669’s substitution records once and then
re-skips on every run — so a project that only ever saw #6669’s no-op has an inert successor that
is now re-evaluated on each run. The cost is one residue &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; per run (and 2.0.6’s stale-asset probe), no re-apply,
no Mission file change and no ledger write. That is the same treatment a &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; successor
already gets, and it is the price of not trusting a record that first adoption can stamp without a
run; removing it would need the provenance marker of the rejected route.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The retained record can be an adoption stamp, not a run.&lt;/strong&gt; The rule cannot tell a &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; a run
wrote from the one first adoption stamps from the version, so on a project whose predecessor
recorded a real “not applicable”, &lt;code dir=&quot;auto&quot;&gt;migrate ledger&lt;/code&gt; can report the successor &lt;code dir=&quot;auto&quot;&gt;applied&lt;/code&gt; for work that
never happened — permanently, since the record is now kept. That is deliberate: &lt;code dir=&quot;auto&quot;&gt;applied&lt;/code&gt; answers
“the ledger holds a success”, and the &lt;em&gt;selection view&lt;/em&gt; (&lt;code dir=&quot;auto&quot;&gt;settled_in_selection_view&lt;/code&gt;) is the
authority for what may run. It is the same split the “stale pending listing” residual records from
the other direction.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Accepted cost: the substitute only records &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt;.&lt;/strong&gt; The predecessor is a
&lt;code dir=&quot;auto&quot;&gt;SupersededMigration&lt;/code&gt; substitute that never records &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt;, so a successor whose predecessor
never recorded &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; is selected on every &lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt; and re-runs &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; (one walk of
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt;). That is idempotent and writes nothing when there is nothing to do.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Accepted cost: the selection view takes no ledger lock.&lt;/strong&gt; It is read per successor without the
ledger lock, so within one live run it can see records that earlier migrations appended. That is
consistent with every other reader of the ledger.&lt;/li&gt;
&lt;li&gt;A predecessor with no record at all is unchanged on a pre-ledger project: the version stamp still
settles it and its successor, because nothing contradicts the stamp.&lt;/li&gt;
&lt;li&gt;The “stale pending listing” residual of Amendment 2026-10-25b is unchanged and now covers the
successor’s own &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; record too: the read surface reports what the record says, and the
settlement authority is the selection view.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
