<?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-11-08-1-upgrade-worktree-pass-is-plan-then-apply-and-migrations-must-converge/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-11-08-1-upgrade-worktree-pass-is-plan-then-apply-and-migrations-must-converge/</id>
  <title>ADR: the upgrade worktree pass is plan-then-apply, and every registered migration must converge</title>
  <updated>2026-11-08T00: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-11-08-1-upgrade-worktree-pass-is-plan-then-apply-and-migrations-must-converge/"/>
  <summary>The upgrade worktree pass becomes a read-only plan step plus an apply step, and a run-twice check holds migrations the fixtures reach, and each upgrade, to converge.</summary>
  <content type="html">&lt;h2 id=&quot;the-upgrade-worktree-pass-is-plan-then-apply-and-every-registered-migration-must-converge&quot;&gt;The upgrade worktree pass is plan-then-apply, and every registered migration must converge&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Proposed (2026-11-08). The operator accepts or amends it on the pull request.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-11-08&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;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;#7405: slice S2 of epic #3347, “extract &lt;code dir=&quot;auto&quot;&gt;_upgrade_worktrees&lt;/code&gt; and prove migrations convergent”.&lt;/li&gt;
&lt;li&gt;#3347: upgrade/migration atomicity and recoverability (epic).&lt;/li&gt;
&lt;li&gt;#6549: a migration that is not needed on pass 1 and applied on pass 2 (the defect class).&lt;/li&gt;
&lt;li&gt;#7429: a non-convergent migration this check found (#6549 is the earlier, separately reported one).&lt;/li&gt;
&lt;li&gt;Related: #5934, #5712, #5472, #5470.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Reader:&lt;/strong&gt; a maintainer who changes &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; or writes a migration, and an agent doing
either. It assumes you know the migration ledger (ADR &lt;code dir=&quot;auto&quot;&gt;2026-10-17-1&lt;/code&gt;) and the worktree selection
rule (#5457, #7173).&lt;/p&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/runner.py&lt;/code&gt; is the most-fixed file in the upgrade surface: 51 changes in
three months, 35 of them fixes. Most of its control flow sat in one method,
&lt;code dir=&quot;auto&quot;&gt;MigrationRunner._upgrade_worktrees&lt;/code&gt; (radon F, 43). One loop decided which worktrees to touch,
synthesized metadata, ran each migration’s &lt;code dir=&quot;auto&quot;&gt;detect&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;can_apply&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;apply&lt;/code&gt; with four exception
paths, tracked five per-worktree flags (dirty, held, errored, failed, migrated), recorded ledger
results, and then saved, stamped and committed each worktree. Every fix in that area had to reason
about the whole loop at once, and there was no unit to test below the runner.&lt;/p&gt;
&lt;p&gt;Separately, nothing checked that a migration converges. ADR &lt;code dir=&quot;auto&quot;&gt;2026-10-17-1&lt;/code&gt; makes the ledger the
execution authority, and &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; is the guard that keeps a re-run safe (C-003). A record does
not always settle a migration, though: a clone-local record never travels, &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt;
do not settle, a structural reselection re-runs a recorded &lt;code dir=&quot;auto&quot;&gt;runs_first&lt;/code&gt; migration, and a
residue-safe successor stays unsettled until its predecessor records &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; (#6688). So
&lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; is what stops a second run, and a migration whose verdict depends on state the run
itself moves (the version stamp, a fold an earlier migration performs) behaves differently on the
next run. #6549 is one such case. This change found another, #7429: on a 2.1.0 project, the second
&lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt; deletes every generated &lt;code dir=&quot;auto&quot;&gt;.claude/commands&lt;/code&gt; file the first run installed, exit 0.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Each branch of the worktree loop should be testable on its own, without driving git.&lt;/li&gt;
&lt;li&gt;The preview and the run already share one selection rule (&lt;code dir=&quot;auto&quot;&gt;worktree_dispositions&lt;/code&gt;). The split
must keep that.&lt;/li&gt;
&lt;li&gt;Behaviour preservation must be provable. Existing patch points (&lt;code dir=&quot;auto&quot;&gt;runner.VersionDetector&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;MigrationRunner._record_migration_result&lt;/code&gt;) and the dict &lt;code dir=&quot;auto&quot;&gt;_upgrade_worktrees&lt;/code&gt; returns are used
by callers and tests.&lt;/li&gt;
&lt;li&gt;A shipped migration’s bytes are its &lt;code dir=&quot;auto&quot;&gt;content_hash&lt;/code&gt; (DIRECTIVE_044). A convergence check may pin
a defect but never fixes it by editing the shipped module.&lt;/li&gt;
&lt;li&gt;An allowlist is priced debt: each entry needs an issue and must fail once its defect is fixed.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A.&lt;/strong&gt; Decompose &lt;code dir=&quot;auto&quot;&gt;_upgrade_worktrees&lt;/code&gt; into more private methods on &lt;code dir=&quot;auto&quot;&gt;MigrationRunner&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;B.&lt;/strong&gt; Move the pass into its own module as a read-only plan step and an apply step, with the
runner supplying what it owns as hooks.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;C.&lt;/strong&gt; Move the pass and everything it calls (record, settle, schema stamp, commit) into its own
module.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;For convergence:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;D.&lt;/strong&gt; Rely on per-migration tests that each migration’s authors write.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;E.&lt;/strong&gt; One generated check: every registered migration, run twice on representative fixtures,
plus the whole upgrade run twice.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen options:&lt;/strong&gt; “B” and “E”.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;The worktree pass is two steps in &lt;code dir=&quot;auto&quot;&gt;specify_cli.upgrade.worktree_pass&lt;/code&gt;.&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;plan_worktree_pass&lt;/code&gt; reads only. It returns a &lt;code dir=&quot;auto&quot;&gt;WorktreePassPlan&lt;/code&gt;: the migrations that run on
worktrees, the result each directory under &lt;code dir=&quot;auto&quot;&gt;.worktrees/&lt;/code&gt; reports when the pass writes nothing
there, and the target worktrees (selected, with upgradeable state, in name order). It reads
selection through &lt;code dir=&quot;auto&quot;&gt;worktree_dispositions&lt;/code&gt;, the rule the preview also reads. &lt;code dir=&quot;auto&quot;&gt;WorktreePass&lt;/code&gt;
applies a plan and returns a &lt;code dir=&quot;auto&quot;&gt;WorktreePassReport&lt;/code&gt;. Per-worktree state is a &lt;code dir=&quot;auto&quot;&gt;WorktreeRun&lt;/code&gt;, and
each per-migration branch (&lt;code dir=&quot;auto&quot;&gt;detect&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;apply&lt;/code&gt;, result handling, record) is its own method.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The runner keeps what it owns and passes it as hooks.&lt;/strong&gt; These are the ledger and metadata
record (&lt;code dir=&quot;auto&quot;&gt;_record_migration_result&lt;/code&gt;), metadata synthesis for a worktree without one (which still
looks up &lt;code dir=&quot;auto&quot;&gt;VersionDetector&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;runner&lt;/code&gt;), and &lt;code dir=&quot;auto&quot;&gt;_settle_worktree&lt;/code&gt; (save, schema stamp, commit).
&lt;code dir=&quot;auto&quot;&gt;_upgrade_worktrees&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;upgrade_worktrees_only&lt;/code&gt; keep their signatures and their returned dict.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Every registered migration must converge, and so must the whole upgrade.&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;tests/upgrade/test_migration_convergence.py&lt;/code&gt; runs every registered migration twice, the way the
runner runs it, on its own copy of each fixture (a fresh &lt;code dir=&quot;auto&quot;&gt;init&lt;/code&gt; project and a legacy 2.1.0
project). The second run must change nothing in the tree, including &lt;code dir=&quot;auto&quot;&gt;.git/config&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.git/info&lt;/code&gt;
and &lt;code dir=&quot;auto&quot;&gt;.git/hooks&lt;/code&gt;. It also runs &lt;code dir=&quot;auto&quot;&gt;MigrationRunner.upgrade&lt;/code&gt; twice on each fixture and on an
older-version lanes project, and the second run must apply nothing and change nothing.
A floor on how many migrations each fixture selects as needed (&lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; returns True), together
with a check that &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; writes nothing, keeps the check from being vacuous as a whole; it does
not prove each migration (see Negative).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A non-convergent migration is pinned, never patched in place.&lt;/strong&gt; Per migration, the entry goes
in &lt;code dir=&quot;auto&quot;&gt;NOT_CONVERGENT&lt;/code&gt; as a strict &lt;code dir=&quot;auto&quot;&gt;xfail&lt;/code&gt;. Per run, &lt;code dir=&quot;auto&quot;&gt;KNOWN_EXTRA_PASS&lt;/code&gt; names exactly the
migrations the second run still applies, and the third run must then change nothing. Each entry
names its follow-up issue. Both pins fail once the migration converges, so the entry is removed
with its fix, which ships as a superseding migration (ADR &lt;code dir=&quot;auto&quot;&gt;2026-10-17-1&lt;/code&gt;, Amendment 2026-10-25).
Today &lt;code dir=&quot;auto&quot;&gt;NOT_CONVERGENT&lt;/code&gt; is empty and &lt;code dir=&quot;auto&quot;&gt;KNOWN_EXTRA_PASS&lt;/code&gt; holds one entry, #7429.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;_upgrade_worktrees&lt;/code&gt; drops from radon F (43) to A. Every function in the new module is at most B
(9). &lt;code dir=&quot;auto&quot;&gt;_upgrade&lt;/code&gt; drops from D (21) to C (15).&lt;/li&gt;
&lt;li&gt;Each worktree-loop rule has a unit test with fake hooks (&lt;code dir=&quot;auto&quot;&gt;test_worktree_pass_unit.py&lt;/code&gt;), and the
end-to-end behaviour is pinned by a characterization net (&lt;code dir=&quot;auto&quot;&gt;test_worktree_pass_characterization.py&lt;/code&gt;)
that was written before the move and did not change across it.&lt;/li&gt;
&lt;li&gt;A new migration enters the convergence check the moment it is registered, with no test of its
own, and it converges where the fixtures reach its &lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt;. A new #6549-class defect on the
fixtures fails CI instead of reaching a user.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The convergence check runs 285 cases, about 30 seconds on one worker. It is an integration
test, not part of the fast tier.&lt;/li&gt;
&lt;li&gt;The check proves convergence only where the fixtures reach &lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt;. A migration whose old
state neither fixture carries runs as “not needed” twice and proves nothing: today that is about
98 of the 140 registered migrations, including 6 of the 14 clone-local ones. The floor counts
migrations whose &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; returns True on a fixture, not migrations proven convergent, and it
guards the total, not each migration. Closing that coverage gap stays with #7405’s next steps.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;_settle_worktree&lt;/code&gt; changed signature (it takes the &lt;code dir=&quot;auto&quot;&gt;WorktreeRun&lt;/code&gt; and the pass context). It is
private and has no other caller.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;append_warnings&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;metadata_bytes&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;skip_as_applied&lt;/code&gt; moved to &lt;code dir=&quot;auto&quot;&gt;worktree_pass&lt;/code&gt;, because both
the pass and the main-checkout loop use them.&lt;/li&gt;
&lt;li&gt;The pass stays not sequenced-view aware (#6552, C-004), as before.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;The characterization net stays green across the split. The convergence check is green with its pins
in place, and it reproduced #7429 independently through &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade --yes&lt;/code&gt;. Adding a fixture
for a migration family the current fixtures do not reach widens the proof without changing this
decision.&lt;/p&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;a-private-methods-on-migrationrunner&quot;&gt;A. Private methods on &lt;code dir=&quot;auto&quot;&gt;MigrationRunner&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The smallest diff, and no hook wiring.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The loop’s state still lives in local variables threaded through methods, or on the runner
instance, and there is still no unit below the runner to test.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;b-plan-and-apply-module-runner-hooks&quot;&gt;B. Plan and apply module, runner hooks&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The plan is pure apart from reads, and the apply step tests with fakes.&lt;/li&gt;
&lt;li&gt;The runner keeps its persistence and commit rules in one place.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Three hooks to wire, and one more module.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;c-move-everything&quot;&gt;C. Move everything&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The pass is fully self-contained.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;It moves the schema stamp and commit code that the main checkout also uses, and it breaks the
runner’s patch points. That doubles the diff for no behavioural gain.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-per-migration-authored-tests&quot;&gt;D. Per-migration authored tests&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Each test knows its migration’s real legacy state.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Coverage depends on each author remembering, and nothing tests the whole-run interaction that
#6549 and #7429 come from.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;e-generated-run-twice-check&quot;&gt;E. Generated run-twice check&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;It covers every registered migration and the whole run, with no per-migration work.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Its proof is only as wide as its fixtures.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
