<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-07-07-1-ignored-surface-backfill-migration-pattern/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-07-07-1-ignored-surface-backfill-migration-pattern/</id>
  <title>ADR: IGNORED-Surface Backfill Migration Pattern</title>
  <updated>2026-07-07T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-07-07-1-ignored-surface-backfill-migration-pattern/"/>
  <summary>Every new `GitClass.IGNORED` surface ships a frozen companion gitignore backfill migration in the same pull request, covering entry variants and lane worktrees.</summary>
  <content type="html">&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;When a new &lt;code dir=&quot;auto&quot;&gt;IGNORED&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;StateSurface&lt;/code&gt; is added to &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/state/contract.py&lt;/code&gt;,
fresh &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; immediately covers new projects via
&lt;code dir=&quot;auto&quot;&gt;GitignoreManager.protect_all_agents()&lt;/code&gt; — which derives its runtime entries
from &lt;code dir=&quot;auto&quot;&gt;get_runtime_gitignore_entries()&lt;/code&gt; at module load.  But &lt;strong&gt;existing projects
never receive the entry&lt;/strong&gt; until they run &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt;; those projects
continue to commit machine-local artefacts until the next upgrade.&lt;/p&gt;
&lt;p&gt;Three separate incidents exposed this gap before this ADR was written:&lt;/p&gt;





























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Issue&lt;/th&gt;&lt;th&gt;Surface added&lt;/th&gt;&lt;th&gt;PR adding surface&lt;/th&gt;&lt;th&gt;PR adding backfill&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;#2369&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/encoding-provenance/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;unknown&lt;/td&gt;&lt;td&gt;#2370&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;#2384&lt;/td&gt;&lt;td&gt;&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;/td&gt;&lt;td&gt;#2384&lt;/td&gt;&lt;td&gt;#2388&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;#2412&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.agents/skills/&amp;#x3C;skill_name&gt;/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.kittify/skills-manifest.json&lt;/code&gt;&lt;/td&gt;&lt;td&gt;#2412&lt;/td&gt;&lt;td&gt;#2423&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Each time, the defect was discovered independently, and an ad-hoc backfill
migration was authored to remedy existing projects.  The three migrations are
structurally identical: detect the missing entries, add them, record the
migration so repeat runs skip it.  Without a standing pattern the same mistake
will recur on the fourth new surface.&lt;/p&gt;
&lt;h3 id=&quot;why-not-a-live-contract-migration&quot;&gt;Why not a live-contract migration?&lt;/h3&gt;
&lt;p&gt;An alternative would be a single “live contract” migration that always checks
whether every current &lt;code dir=&quot;auto&quot;&gt;IGNORED&lt;/code&gt; surface is present in &lt;code dir=&quot;auto&quot;&gt;.gitignore&lt;/code&gt; and adds
missing entries.  This approach was considered and rejected:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Non-determinism under concurrent development&lt;/strong&gt;: a live migration re-runs
whenever any new surface is added, making the migration’s behaviour
change retroactively for projects that already ran it.  Upgrade runners
record migrations by &lt;code dir=&quot;auto&quot;&gt;migration_id&lt;/code&gt;; a live migration would be recorded once
and never re-fire, creating silent coverage gaps as new surfaces land.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Hard-to-audit change sets&lt;/strong&gt;: a migration that adds N entries in a single
apply() call makes it impossible to attribute which surface caused which
gitignore entry to appear, complicating reversal or review.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Regression risk for &lt;code dir=&quot;auto&quot;&gt;runs_on_worktrees&lt;/code&gt;&lt;/strong&gt;: worktree-scoped upgrade runs
replay migrations flagged &lt;code dir=&quot;auto&quot;&gt;runs_on_worktrees=True&lt;/code&gt;.  A live migration would
need its own idempotency logic to avoid re-running on every worktree upgrade
as the surface list grows.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Frozen migrations are the established pattern&lt;/strong&gt;: every other migration in
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/&lt;/code&gt; is frozen — it detects a concrete
historical gap and closes it once.  Introducing a live migration would be
the only dynamic one in the registry, requiring special-case handling.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;One frozen backfill migration per IGNORED-surface addition&lt;/strong&gt; is the standing
pattern.  Whenever a new &lt;code dir=&quot;auto&quot;&gt;GitClass.IGNORED&lt;/code&gt; surface is added to the state
contract and its gitignore entry is not already guaranteed by an existing
migration, a companion migration MUST be authored in the same PR.&lt;/p&gt;
&lt;p&gt;The migration:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Has a &lt;code dir=&quot;auto&quot;&gt;migration_id&lt;/code&gt; of the form &lt;code dir=&quot;auto&quot;&gt;&quot;X.Y.Z_&amp;#x3C;slug&gt;_gitignore_backfill&quot;&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Declares &lt;code dir=&quot;auto&quot;&gt;target_version&lt;/code&gt; that matches the release that introduces the surface.&lt;/li&gt;
&lt;li&gt;Does NOT override &lt;code dir=&quot;auto&quot;&gt;runs_on_worktrees&lt;/code&gt;; inherits the &lt;code dir=&quot;auto&quot;&gt;True&lt;/code&gt; default so lane
worktrees receive the same gitignore protection on upgrade.&lt;/li&gt;
&lt;li&gt;Implements &lt;code dir=&quot;auto&quot;&gt;_EQUIVALENT_ENTRIES&lt;/code&gt; covering all reasonable variant forms of
the entry (trailing-slash, no-slash, parent-directory wholesale) for
idempotency against hand-edited gitignores.&lt;/li&gt;
&lt;li&gt;Uses &lt;code dir=&quot;auto&quot;&gt;GitignoreManager&lt;/code&gt; for the write so section headers are consistent.&lt;/li&gt;
&lt;li&gt;Registers automatically via &lt;code dir=&quot;auto&quot;&gt;auto_discover_migrations()&lt;/code&gt; — no manual
&lt;code dir=&quot;auto&quot;&gt;MIGRATIONS&lt;/code&gt; list edit required.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The companion ADR (this document) is not required for every backfill — it is
the single reference that all future backfills cite in their docstrings or PR
descriptions.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Authors receive a clear checklist (see below) instead of rediscovering the
pattern.&lt;/li&gt;
&lt;li&gt;The three existing backfill migrations
(&lt;code dir=&quot;auto&quot;&gt;m_3_2_3_encoding_provenance_gitignore_backfill&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;m_3_2_4_runtime_dirs_gitignore_backfill&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;m_3_2_5_agents_skills_gitignore_backfill&lt;/code&gt;) are the reference implementations.&lt;/li&gt;
&lt;li&gt;A live migration or a blanket “always re-sync everything” approach remains
explicitly out of scope.&lt;/li&gt;
&lt;li&gt;Any future work that introduces a second mutable class of surfaces (e.g.,
surfaces that should always be tracked) should author its own ADR rather
than extending this one.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;author-checklist&quot;&gt;Author Checklist&lt;/h2&gt;
&lt;p&gt;When adding a &lt;code dir=&quot;auto&quot;&gt;GitClass.IGNORED&lt;/code&gt; surface to &lt;code dir=&quot;auto&quot;&gt;state/contract.py&lt;/code&gt;:&lt;/p&gt;
&lt;ul class=&quot;contains-task-list&quot;&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; &lt;strong&gt;Contract&lt;/strong&gt;: add &lt;code dir=&quot;auto&quot;&gt;StateSurface&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;git_class=GitClass.IGNORED&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/state/contract.py&lt;/code&gt;.  Include a &lt;code dir=&quot;auto&quot;&gt;notes&lt;/code&gt; field that
cross-references any visually similar TRACKED surfaces to prevent naming
confusion.&lt;/li&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; &lt;strong&gt;Init coverage&lt;/strong&gt;: confirm &lt;code dir=&quot;auto&quot;&gt;get_runtime_gitignore_entries()&lt;/code&gt; emits the
new entry.  The test
&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/test_gitignore_contract.py::test_contract_runtime_entries_include_skill_projection_surfaces&lt;/code&gt;
shows the assertion pattern.&lt;/li&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; &lt;strong&gt;Manager test&lt;/strong&gt;: add a &lt;code dir=&quot;auto&quot;&gt;test_gitignore_manager_protects_&amp;#x3C;surface&gt;&lt;/code&gt; test
that calls &lt;code dir=&quot;auto&quot;&gt;GitignoreManager(tmp_path).protect_all_agents()&lt;/code&gt; and asserts
the surface path is git-ignored.&lt;/li&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; &lt;strong&gt;Backfill migration&lt;/strong&gt;: create
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/m_&amp;#x3C;X_Y_Z&gt;_&amp;#x3C;slug&gt;_gitignore_backfill.py&lt;/code&gt;
following the structure of &lt;code dir=&quot;auto&quot;&gt;m_3_2_5_agents_skills_gitignore_backfill.py&lt;/code&gt;.
Include &lt;code dir=&quot;auto&quot;&gt;_EQUIVALENT_ENTRIES&lt;/code&gt; for idempotency.  Do NOT override
&lt;code dir=&quot;auto&quot;&gt;runs_on_worktrees&lt;/code&gt; — the &lt;code dir=&quot;auto&quot;&gt;True&lt;/code&gt; default is correct.&lt;/li&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; &lt;strong&gt;Migration tests&lt;/strong&gt;: cover &lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt;, equivalence variants,
idempotency, dry-run, end-to-end via &lt;code dir=&quot;auto&quot;&gt;MigrationRunner&lt;/code&gt;, and the worktree
composition path (&lt;code dir=&quot;auto&quot;&gt;include_worktrees=True&lt;/code&gt;).&lt;/li&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; &lt;strong&gt;Order-manifest entry&lt;/strong&gt; (ledger model, ADR
&lt;a href=&quot;/adr/4.x/2026-10-17-1-explicit-migration-ledger/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-10-17-1&lt;/code&gt;&lt;/a&gt;): add the
&lt;code dir=&quot;auto&quot;&gt;migration_id&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/order_manifest.txt&lt;/code&gt; in
execution order — the single ordering authority. Annotate an intentional
equal-&lt;code dir=&quot;auto&quot;&gt;target_version&lt;/code&gt; run with a trailing &lt;code dir=&quot;auto&quot;&gt;# tie: &amp;#x3C;reason&gt;&lt;/code&gt;. The build-time
gate &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_migration_order_manifest.py&lt;/code&gt; requires every
registered migration to appear in the manifest exactly once. Selection is now
&lt;strong&gt;ledger-diff&lt;/strong&gt;, not the version window, so a migration is reconsidered until
it records &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; in its ledger partition — &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; stays the
idempotency guard, never the selection authority.&lt;/li&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; &lt;strong&gt;Ledger routing&lt;/strong&gt; (ledger model, ADR
&lt;a href=&quot;/adr/4.x/2026-10-17-1-explicit-migration-ledger/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-10-17-1&lt;/code&gt;&lt;/a&gt;): a gitignore
backfill lands in the TRACKED &lt;code dir=&quot;auto&quot;&gt;.gitignore&lt;/code&gt;, so keep the &lt;code dir=&quot;auto&quot;&gt;clone_local_effect&lt;/code&gt;
ClassVar at its &lt;code dir=&quot;auto&quot;&gt;False&lt;/code&gt; default — its applied record goes to the tracked
&lt;code dir=&quot;auto&quot;&gt;.kittify/migration-ledger.jsonl&lt;/code&gt; and correctly propagates to every clone.
ONLY a migration whose effect lives outside 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;) sets
&lt;code dir=&quot;auto&quot;&gt;clone_local_effect = True&lt;/code&gt;, routing its record to the per-clone
&lt;code dir=&quot;auto&quot;&gt;.kittify/migrations/clone-local.jsonl&lt;/code&gt;. Optionally declare &lt;code dir=&quot;auto&quot;&gt;identity&lt;/code&gt; (a
stable drift key) / &lt;code dir=&quot;auto&quot;&gt;content_hash_sources&lt;/code&gt; (multi-file hash input); drift is
audit-only. &lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate ledger&lt;/code&gt; reports what ran.&lt;/li&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; &lt;strong&gt;Ratchet baseline&lt;/strong&gt;: (superseded 2026-09, mission
ratchet-baseline-census-gate-remediation-01M3EW3Z: the &lt;code dir=&quot;auto&quot;&gt;category_1&lt;/code&gt; baseline
leaf was retired; adding the migration to &lt;code dir=&quot;auto&quot;&gt;_CATEGORY_1_AUTO_DISCOVERED_MIGRATIONS&lt;/code&gt;
is sufficient)&lt;/li&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; &lt;strong&gt;Dead-module allowlist&lt;/strong&gt;: add the new migration to the allowlist in
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_dead_modules.py&lt;/code&gt;.&lt;/li&gt;
&lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; &lt;strong&gt;Repo .gitignore&lt;/strong&gt;: add the entry to the repo root &lt;code dir=&quot;auto&quot;&gt;.gitignore&lt;/code&gt; under the
&lt;code dir=&quot;auto&quot;&gt;# Project specific&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;# Added by Spec Kitty CLI (auto-managed)&lt;/code&gt; section
so the repo itself does not accumulate the surface.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/state/contract.py&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;GitClass&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;StateSurface&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;get_runtime_gitignore_entries()&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/gitignore_manager.py&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;RUNTIME_PROTECTED_ENTRIES&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;GitignoreManager.protect_all_agents()&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Reference implementations:
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;../../../src/specify_cli/upgrade/migrations/m_3_2_3_encoding_provenance_gitignore_backfill.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/m_3_2_3_encoding_provenance_gitignore_backfill.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;../../../src/specify_cli/upgrade/migrations/m_3_2_4_runtime_dirs_gitignore_backfill.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/m_3_2_4_runtime_dirs_gitignore_backfill.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;../../../src/specify_cli/upgrade/migrations/m_3_2_5_agents_skills_gitignore_backfill.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/m_3_2_5_agents_skills_gitignore_backfill.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;Contract tests:
&lt;a href=&quot;../../../tests/specify_cli/test_gitignore_contract.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/test_gitignore_contract.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Migration tests:
&lt;a href=&quot;../../../tests/specify_cli/upgrade/migrations/test_m_3_2_5_agents_skills_gitignore.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/upgrade/migrations/test_m_3_2_5_agents_skills_gitignore.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;PR #2370 (provenance backfill), PR #2388 (runtime-dirs backfill),
PR #2423 (agents-skills backfill — defect-class trigger for this ADR)&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-10-04-5457&quot;&gt;Amendment 2026-10-04 (#5457)&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Decision item 3 no longer reaches integrating worktrees.&lt;/strong&gt; Item 3 said the migration inherits &lt;code dir=&quot;auto&quot;&gt;runs_on_worktrees=True&lt;/code&gt; “so lane worktrees receive the same gitignore protection on upgrade”. Since &lt;a href=&quot;/adr/4.x/2026-10-04-4-upgrade-writes-project-global-state-once/&quot;&gt;ADR 2026-10-04-4&lt;/a&gt;, &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; skips an integrating worktree: a worktree whose branch is a &lt;code dir=&quot;auto&quot;&gt;kitty/mission-…&lt;/code&gt; mission, lane or coordination branch, or whose branch cannot be read (&lt;code dir=&quot;auto&quot;&gt;_is_integrating_worktree&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_worktrees_to_upgrade&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/runner.py&lt;/code&gt;). The &lt;code dir=&quot;auto&quot;&gt;True&lt;/code&gt; default therefore still applies to worktrees that upgrade does visit (a worktree on any other branch), and the migration is still correct to inherit it.&lt;/p&gt;
&lt;p&gt;Lanes receive the gitignore protection through integration instead: the repository root checkout carries the backfilled &lt;code dir=&quot;auto&quot;&gt;.gitignore&lt;/code&gt;, and a lane picks it up when it next merges the Mission branch.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Residual window.&lt;/strong&gt; Between the upgrade and that merge, an integrating worktree keeps its pre-upgrade &lt;code dir=&quot;auto&quot;&gt;.gitignore&lt;/code&gt; (and &lt;code dir=&quot;auto&quot;&gt;.gitattributes&lt;/code&gt;). A new &lt;code dir=&quot;auto&quot;&gt;IGNORED&lt;/code&gt; surface that the backfill covers can be untracked-visible in that worktree until the lane integrates. The original decision text above is unchanged.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Updated 2026-11-05 (#7173).&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;_is_integrating_worktree&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;_worktrees_to_upgrade&lt;/code&gt; no longer exist. The Mission check is now &lt;code dir=&quot;auto&quot;&gt;is_integrating_worktree&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/worktree_selection.py&lt;/code&gt;, and upgrade also skips every other worktree under &lt;code dir=&quot;auto&quot;&gt;.worktrees/&lt;/code&gt; unless the operator names it with &lt;code dir=&quot;auto&quot;&gt;--include-worktree&lt;/code&gt; or passes &lt;code dir=&quot;auto&quot;&gt;--all-worktrees&lt;/code&gt;. The &lt;code dir=&quot;auto&quot;&gt;True&lt;/code&gt; default therefore reaches only the worktrees the operator selected. See the 2026-11-05 amendment to &lt;a href=&quot;/adr/4.x/2026-10-04-4-upgrade-writes-project-global-state-once/&quot;&gt;ADR 2026-10-04-4&lt;/a&gt;.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;amendment-2026-10-17-6233--the-recorded-once-frozen-choice-assumes-a-tracked-effect&quot;&gt;Amendment 2026-10-17 (#6233) — the “recorded-once, frozen” choice assumes a TRACKED effect&lt;/h2&gt;
&lt;p&gt;The frozen-migration decision above records a migration by &lt;code dir=&quot;auto&quot;&gt;migration_id&lt;/code&gt; and skips it on every later run (the runner short-circuits at &lt;code dir=&quot;auto&quot;&gt;metadata.has_migration(id)&lt;/code&gt; before it ever calls &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt;). That is sound &lt;strong&gt;only because a gitignore backfill lands in the TRACKED &lt;code dir=&quot;auto&quot;&gt;.gitignore&lt;/code&gt;&lt;/strong&gt;: the effect travels with the commit, so the shared, pushed &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt; ledger is a faithful record of the effect’s presence on every clone.&lt;/p&gt;
&lt;p&gt;For a migration whose effect lives &lt;strong&gt;outside version control&lt;/strong&gt; — clone-local state such as &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;, or &lt;code dir=&quot;auto&quot;&gt;.git/hooks&lt;/code&gt; — the ledger is &lt;strong&gt;not&lt;/strong&gt; authoritative. It records one clone’s untracked state yet propagates to every clone, so a pulled clone whose own &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; reports the effect absent would skip the migration forever and never gain the local effect.&lt;/p&gt;
&lt;p&gt;The fix tags such migrations &lt;code dir=&quot;auto&quot;&gt;clone_local_effect = True&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;BaseMigration&lt;/code&gt;, default &lt;code dir=&quot;auto&quot;&gt;False&lt;/code&gt;) and routes the skip decision to &lt;strong&gt;this checkout’s own &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt;&lt;/strong&gt; at &lt;strong&gt;two&lt;/strong&gt; layers — both are required, because the ledger is consulted at two distinct points:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Selection&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;MigrationRegistry.get_applicable&lt;/code&gt;): the version window selects only in-window migrations (&lt;code dir=&quot;auto&quot;&gt;from_v &amp;#x3C; target &amp;#x3C;= to_v&lt;/code&gt;) or a &lt;code dir=&quot;auto&quot;&gt;target == from_v&lt;/code&gt; migration whose &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; is True. On a pulled clone fully stamped at the current version (&lt;code dir=&quot;auto&quot;&gt;from_v == to_v == current&lt;/code&gt;), a clone-local migration whose &lt;code dir=&quot;auto&quot;&gt;target&lt;/code&gt; is &lt;strong&gt;below&lt;/strong&gt; the current version would never be selected — so the skip-gate route below would never be reached for it. A sub-current (&lt;code dir=&quot;auto&quot;&gt;target &amp;#x3C; from_v&lt;/code&gt;) branch now pulls a &lt;code dir=&quot;auto&quot;&gt;clone_local_effect&lt;/code&gt; migration back into the applicable set when the shared ledger &lt;strong&gt;records it applied&lt;/strong&gt; yet &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; reports the effect absent. Keying on the ledger record targets exactly the pulled-clone case: the ledger is tracked and pushed, so a pulled clone carries the record without the clone-local effect. A migration the ledger never recorded keeps the version-window authority (its version stamp is past it) and is not re-selected, so a project that genuinely never ran it is left to the version window — this preserves the no-migrations no-op contract. These migrations are not &lt;code dir=&quot;auto&quot;&gt;runs_first&lt;/code&gt;, so they keep normal version order. The detector preview delegates to &lt;code dir=&quot;auto&quot;&gt;get_applicable&lt;/code&gt;, so &lt;code dir=&quot;auto&quot;&gt;--dry-run&lt;/code&gt; reports them in parity.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Skip gate&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;runner._apply_migration&lt;/code&gt;): a selected migration recorded in the ledger is normally skipped before &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; runs; &lt;code dir=&quot;auto&quot;&gt;reselect_when_recorded()&lt;/code&gt; overrides that for a clone-local migration whose effect is absent. This gate is itself reached only for a recorded migration (&lt;code dir=&quot;auto&quot;&gt;has_migration&lt;/code&gt;), which is why the selection branch keys on the same record.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Together: a recorded clone-local migration re-applies whenever its effect is absent on this checkout, and settles once &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; reports it present. A TRACKED-effect migration (the backfills this ADR governs included) keeps the default &lt;code dir=&quot;auto&quot;&gt;False&lt;/code&gt; and is excluded at &lt;strong&gt;both&lt;/strong&gt; layers — the sub-current selection branch skips it and the skip gate trusts the ledger — so it stays recorded-once-and-skipped. Reselection requires an idempotent &lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt;; the &lt;code dir=&quot;auto&quot;&gt;tests/upgrade/test_clone_local_migration_idempotent.py&lt;/code&gt; gate pins the clone-local member set and its idempotency.&lt;/p&gt;
&lt;p&gt;This is a per-clone reselection seam, not the explicit, machine-readable clone-local ledger that would record the effect’s presence directly; that longer-term home is tracked by epic &lt;strong&gt;#2933&lt;/strong&gt;.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Superseded 2026-10-17 (#5230 / epic #2933) — the explicit ledger has landed.&lt;/strong&gt; The per-clone reselection seam described in this amendment is retired. ADR &lt;a href=&quot;/adr/4.x/2026-10-17-1-explicit-migration-ledger/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-10-17-1&lt;/code&gt;&lt;/a&gt; replaced &lt;code dir=&quot;auto&quot;&gt;metadata.yaml.applied_migrations&lt;/code&gt; and the version window with an explicit two-partition applied-migration ledger (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;). &lt;code dir=&quot;auto&quot;&gt;clone_local_effect&lt;/code&gt; is now the ledger’s &lt;strong&gt;routing key&lt;/strong&gt;, no longer a reselection trigger: the sub-window selection branch (&lt;code dir=&quot;auto&quot;&gt;_clone_local_selected_below_window&lt;/code&gt;) is removed and &lt;code dir=&quot;auto&quot;&gt;reselect_when_recorded&lt;/code&gt; collapses to a ledger lookup. Selection is &lt;strong&gt;ledger-diff&lt;/strong&gt;; &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; remains only the runner’s idempotency guard. See the Author Checklist above and ADR &lt;code dir=&quot;auto&quot;&gt;2026-10-17-1&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;</content>
</entry>
