<?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-04-2-started-work-package-lane-membership-is-frozen/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-04-2-started-work-package-lane-membership-is-frozen/</id>
  <title>ADR: a started work package keeps its recorded execution lane on re-finalize</title>
  <updated>2026-10-05T00: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-04-2-started-work-package-lane-membership-is-frozen/"/>
  <summary>Lane computation keeps started work packages on their recorded lane by construction and refuses unsatisfiable amendments with LANE_MEMBERSHIP_FROZEN before a status or lane write.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-10-04&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (owner). Design decisions D1 to D8 of Mission &lt;code dir=&quot;auto&quot;&gt;frozen-started-lanes-01M444FM&lt;/code&gt;, taken from its code grounding (2026-10-04).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5573&quot;&gt;#5573&lt;/a&gt;, Mission &lt;code dir=&quot;auto&quot;&gt;frozen-started-lanes-01M444FM&lt;/code&gt;. Earlier recurrences: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/3311&quot;&gt;#3311&lt;/a&gt;, &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/4945&quot;&gt;#4945&lt;/a&gt;.&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;Re-running &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent mission finalize-tasks&lt;/code&gt; on a Mission that already has a lane manifest (&lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;) is supported (ADR &lt;a href=&quot;/adr/3.x/2026-07-29-1-lane-base-recorded-planning-commit/&quot;&gt;3.x &lt;code dir=&quot;auto&quot;&gt;2026-07-29-1&lt;/code&gt;&lt;/a&gt;): operators amend work packages mid-execution and re-finalize. Each run recomputes execution lanes from ownership overlap and the surface heuristic.&lt;/p&gt;
&lt;p&gt;#5573 is the third recurrence of one defect class: a re-finalize changes lane identity under work that has already begun.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;#3311&lt;/strong&gt; — a re-finalize rewrote the recorded planning commit of active lanes.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;#4945&lt;/strong&gt; — lane ids were re-minted positionally, so removing a work package could re-letter a surviving lane onto another work package’s branch. terminus-merge-integrity FR-010 fixed this by binding a lane id to its git branch at creation and reading it back on re-finalize.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;#5573&lt;/strong&gt; — the id ↔ branch binding held, but &lt;em&gt;which lane a started work package belongs to&lt;/em&gt; was still a heuristic output. An amendment that made a planned WP01 overlap an in-progress WP02 merged both into one group, which read back &lt;code dir=&quot;auto&quot;&gt;lane-a&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; exited 0 with WP02 moved off &lt;code dir=&quot;auto&quot;&gt;lane-b&lt;/code&gt;, the branch holding its commits; the next &lt;code dir=&quot;auto&quot;&gt;implement WP02&lt;/code&gt; failed with &lt;code dir=&quot;auto&quot;&gt;LANE_WORK_TIP_UNKNOWN&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A started work package owns commits on its lane branch and its lane work tip (&lt;code dir=&quot;auto&quot;&gt;refs/spec-kitty/lane-tip/&amp;#x3C;branch&gt;&lt;/code&gt;). Its status transitions also carry a &lt;code dir=&quot;auto&quot;&gt;lane_head&lt;/code&gt; stamp that consolidation’s per-work-package attribution (#5046) reads. Moving it to another lane strands that work, rebinds a lane-mate onto a branch carrying foreign commits, and poisons that attribution.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;The recorded lane membership of started work packages is a &lt;strong&gt;constraint input&lt;/strong&gt; to lane computation, honoured by construction. It is not a check applied after the heuristic has decided.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;“Started” is history-based.&lt;/strong&gt; A work package is started when its status history has ever recorded a move into &lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;specify_cli.lanes.frozen_membership.started_wp_ids&lt;/code&gt;). A later reset to &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;, or a cancellation, does not unstart it. A move from &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt; straight to &lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;canceled&lt;/code&gt; does not start it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Lane-work-tip fallback.&lt;/strong&gt; A prior code lane with no history-started member whose branch has a recorded lane work tip counts as wholly started. The planning lane (&lt;code dir=&quot;auto&quot;&gt;lane-planning&lt;/code&gt;) is never frozen by a tip. The tips are listed on every re-finalize, and a listing git cannot produce refuses with &lt;code dir=&quot;auto&quot;&gt;status_unreadable&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Reserved lane ids.&lt;/strong&gt; A lane id is reserved while a started work package is bound to it, and for as long as its lane branch has a recorded lane work tip. The second rule keeps the id reserved on later re-finalizes, after a retired work package’s lane has left &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;: its branch and commits still exist, so a new work package must not be given that id.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Preserve by construction&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;specify_cli.lanes.compute&lt;/code&gt;, which stays pure: no git, no &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;). Started work packages that shared a recorded lane are kept in one group (collapse rule &lt;code dir=&quot;auto&quot;&gt;frozen_lane_membership&lt;/code&gt;). A group holding started work packages takes their recorded lane id before any overlap read-back. An unpinned group that shares at least one member with an unused prior lane reads back the one it shares the most members with; a tie goes to the lowest prior lane id. A group that shares no member with any unused prior lane mints the next free id, skipping every lane id that held started work.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Refuse only what cannot be satisfied&lt;/strong&gt;, with one code, &lt;code dir=&quot;auto&quot;&gt;LANE_MEMBERSHIP_FROZEN&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;LaneMembershipFrozenError&lt;/code&gt;), and one &lt;code dir=&quot;auto&quot;&gt;reason&lt;/code&gt; per case:
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;started_lanes_collapsed&lt;/code&gt;: one computed group holds started work packages recorded in two or more lanes;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;started_wp_removed&lt;/code&gt;: a started work package is missing from the plan and the cancellation projection did not retire it;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;started_wp_kind_changed&lt;/code&gt;: a started work package’s &lt;code dir=&quot;auto&quot;&gt;execution_mode&lt;/code&gt; now puts it on the other side of &lt;code dir=&quot;auto&quot;&gt;lane-planning&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;status_unreadable&lt;/code&gt;: a lane manifest exists, but the status surface cannot be resolved, its directory does not exist and is not an unmaterialized coordination worktree whose branch can be read locally, or its log cannot be read.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Refuse before the first status write.&lt;/strong&gt; finalize runs the check as a read-only preflight after its ownership gates and before its first status write. &lt;code dir=&quot;auto&quot;&gt;--validate-only&lt;/code&gt; runs it too. A refusal writes no status event, no &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; and no commit. The ownership gates run earlier and may already have edited work package files and &lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt;; finalize’s existing write-scope restore puts those back. Every remedy is non-destructive.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fail closed on status.&lt;/strong&gt; A status directory that exists but holds no event log means nothing started. When the coordination worktree of a &lt;code dir=&quot;auto&quot;&gt;lanes_with_coord&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;coord&lt;/code&gt; Mission is not materialized, the preflight reads the status log committed on the local coordination branch, read-only, and never materializes the worktree. It refuses when that branch is not a local head (the remedy materializes the worktree, fetching the branch first when it exists only on a remote), when the branch carries no committed log, or when the log is malformed. Any other missing status directory, an unresolvable surface or an unreadable log refuses, with the cause appended to the remedy. Unknown never reads as “nothing started”.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cycles surface before the first status write.&lt;/strong&gt; Keeping started lane-mates together can close a lane dependency cycle that the unfrozen inputs would not have. The preflight raises that &lt;code dir=&quot;auto&quot;&gt;LaneDependencyCycleError&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;LANE_DEPENDENCY_CYCLE&lt;/code&gt;, unchanged text) before the first status write, so &lt;code dir=&quot;auto&quot;&gt;--validate-only&lt;/code&gt; and a real run refuse identically.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Defence in depth.&lt;/strong&gt; The lane writer (&lt;code dir=&quot;auto&quot;&gt;compute_and_write_lanes&lt;/code&gt;) re-checks the invariant before it writes &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;, against the same evidence the preflight read. It also refuses to recompute over a manifest that has code lanes when the caller supplied no frozen membership at all, so a future caller cannot bypass the freeze by omission; a caller that means “nothing has started” says so with &lt;code dir=&quot;auto&quot;&gt;FrozenLaneMembership.empty()&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; Missions are exempt: their one repo-root lane has nothing to move.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;A post-hoc diff in finalize&lt;/strong&gt; (compare the new and old membership of started work packages, refuse on any difference). Rejected. The heuristic would stay the deciding authority, and it would refuse #5573’s own reproduction instead of keeping WP02 on &lt;code dir=&quot;auto&quot;&gt;lane-b&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Freeze every lane once execution has begun.&lt;/strong&gt; Rejected. It forbids the supported amendment of unstarted work packages (#4141, ADR 3.x &lt;code dir=&quot;auto&quot;&gt;2026-07-29-1&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Let lane computation read status and git itself.&lt;/strong&gt; Rejected. It breaks the documented purity of &lt;code dir=&quot;auto&quot;&gt;compute_lanes&lt;/code&gt;. The finalize shell gathers the evidence and passes it in, as it does for the planning commit.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Constraint input to the pure computation, refusing only unsatisfiable cases (chosen).&lt;/strong&gt; It closes the class by construction and keeps “refuse, never rescue” for degraded input (ADR &lt;a href=&quot;/adr/3.x/2026-09-26-2-lane-naming-keyed-on-creation-input/&quot;&gt;3.x &lt;code dir=&quot;auto&quot;&gt;2026-09-26-2&lt;/code&gt;&lt;/a&gt;).&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;A re-finalize that overlaps an unstarted work package with a started one succeeds; the unstarted work package joins the started one’s lane.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Intentional behaviour change:&lt;/strong&gt; removing a started work package’s task file now refuses with &lt;code dir=&quot;auto&quot;&gt;started_wp_removed&lt;/code&gt;. To retire it, cancel it with &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent tasks move-task &amp;#x3C;WP&gt; --to canceled --mission &amp;#x3C;handle&gt;&lt;/code&gt; without clearing its owned files.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;--validate-only&lt;/code&gt; lane preview now reads back the previous &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; and honours the frozen membership, so its lane ids match what a real run writes.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;collapse_report&lt;/code&gt; gains the additive rule value &lt;code dir=&quot;auto&quot;&gt;frozen_lane_membership&lt;/code&gt;. It is not counted in &lt;code dir=&quot;auto&quot;&gt;independent_wps_collapsed&lt;/code&gt;: it restates lane-mates that already shared a lane.&lt;/li&gt;
&lt;li&gt;A corrupt line in the planning-side status log is still refused earlier, by finalize’s existing work-package read, with its existing store error. &lt;code dir=&quot;auto&quot;&gt;status_unreadable&lt;/code&gt; is what the preflight reports when its own read fails, for example an unresolvable coordination status surface.&lt;/li&gt;
&lt;li&gt;The planning-pin probe (“has execution begun?”) is not yet the history-based predicate. The two can disagree: for a work package that worked and was then reset to &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;, the probe reads “not begun” while this decision freezes its lane (#5702).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;known-limits&quot;&gt;Known limits&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Work started in another clone.&lt;/strong&gt; The status read uses the local coordination branch and never fetches. A work package started in another clone looks unstarted until that clone’s coordination commits are fetched. The lane-work-tip fallback still freezes a lane that has recorded work in this clone.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No status log and no lane work tip.&lt;/strong&gt; A status directory with no event log, on a Mission whose lanes recorded no tip, means nothing is frozen.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;.&lt;/strong&gt; Without a previous manifest there is no recorded lane to keep, so nothing is frozen even when lane branches and tips exist. Rebuilding a lost manifest is #5703.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A claim made during the run.&lt;/strong&gt; The evidence is read once, at the preflight. A work package claimed between the preflight and the &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; write is not frozen by that run; the writer’s re-check uses the same evidence and is not a guard against concurrent claims.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;related&quot;&gt;Related&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;ADR &lt;a href=&quot;/adr/3.x/2026-07-29-1-lane-base-recorded-planning-commit/&quot;&gt;3.x &lt;code dir=&quot;auto&quot;&gt;2026-07-29-1&lt;/code&gt;&lt;/a&gt;: finalize-tasks is the single writer of &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;, and re-running it is supported.&lt;/li&gt;
&lt;li&gt;ADR &lt;a href=&quot;/adr/3.x/2026-09-26-2-lane-naming-keyed-on-creation-input/&quot;&gt;3.x &lt;code dir=&quot;auto&quot;&gt;2026-09-26-2&lt;/code&gt;&lt;/a&gt;: degraded input is migrated or refused, never rescued.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5080&quot;&gt;#5080&lt;/a&gt;: sibling lane-identity invariant.&lt;/li&gt;
&lt;li&gt;Follow-ups: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5701&quot;&gt;#5701&lt;/a&gt; (the #3432 cancellation residual), &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5702&quot;&gt;#5702&lt;/a&gt; (move the planning-pin probe and its doctor twin onto the history-based predicate), &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5703&quot;&gt;#5703&lt;/a&gt; (&lt;code dir=&quot;auto&quot;&gt;doctor mission-state --fix&lt;/code&gt; still rebuilds the lane manifest with fresh lane ids).&lt;/li&gt;
&lt;li&gt;Operator docs: &lt;a href=&quot;/architecture/execution-lanes/#re-finalizing-an-active-mission&quot;&gt;Execution Lanes&lt;/a&gt;, &lt;a href=&quot;/api/finalize-tasks-internals/#5-started-work-packages-keep-their-lane-lane_membership_frozen&quot;&gt;finalize-tasks internals&lt;/a&gt;, &lt;a href=&quot;/context/topology/#started-work-package&quot;&gt;topology glossary&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
