<?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-29-1-lane-base-recorded-planning-commit/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-07-29-1-lane-base-recorded-planning-commit/</id>
  <title>ADR: Lane Base Merges the Recorded Planning-Artifact Commit (FR-009)</title>
  <updated>2026-10-04T00: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-29-1-lane-base-recorded-planning-commit/"/>
  <summary>Each lane gains the planning-artifact commit recorded at finalize-tasks as an extra ancestor, leaving its git parentage intact and never reading a live branch tip.</summary>
  <content type="html">&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;ADR &lt;a href=&quot;/adr/3.x/2026-04-03-1-execution-lanes-own-worktrees-and-mission-branches/&quot;&gt;2026-04-03-1&lt;/a&gt;
made the execution lane the git branch/worktree unit and required “every mission gets
one integration branch.” WP04 (#1348) extended lane parenting so a coordination-topology
mission’s lanes branch from &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;), not the legacy
&lt;code dir=&quot;auto&quot;&gt;mission_branch&lt;/code&gt; field, and registered the status-files sparse-checkout exclusion so a
lane worktree cannot see &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; is minted at &lt;code dir=&quot;auto&quot;&gt;mission create&lt;/code&gt; — &lt;strong&gt;before&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;plan.md&lt;/code&gt;
/ &lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;tasks/WP*.md&lt;/code&gt; exist. Those planning artifacts are PRIMARY-partition kinds
(&lt;code dir=&quot;auto&quot;&gt;SPEC&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;FINALIZED_EXECUTION_PLAN&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;TASKS_INDEX&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;WORK_PACKAGE_TASK&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;LANE_STATE&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;PRIMARY_METADATA&lt;/code&gt;) and commit to &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; for every topology (ADR
&lt;a href=&quot;/adr/3.x/2026-06-24-1-kind-and-topology-aware-artifact-placement/&quot;&gt;2026-06-24-1&lt;/a&gt;). A lane
branched purely from &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt;’s pre-planning mint point therefore has &lt;strong&gt;no
common ancestor containing the planning artifacts&lt;/strong&gt; with the primary &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt;
tip the mission later consolidates against. This is issue
&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2993&quot;&gt;#2993&lt;/a&gt;: the pinned regression
&lt;code dir=&quot;auto&quot;&gt;tests/regression/test_issue_2993_lane_planning_ancestry.py&lt;/code&gt; demonstrates the lane’s
tree carries no &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt; at all, so a later 3-way merge between the lane
and an amended/retracted planning artifact fabricates a stale or resurrected result
instead of the planning branch’s real content — a silent revert, not a conflict, so
nothing prompts a human to notice.&lt;/p&gt;
&lt;p&gt;The same pinned regression fixes the &lt;strong&gt;shape&lt;/strong&gt; the fix must take: Assert A requires the
lane branch to descend from the planning-artifact commit; Assert A’ (the “coord-descent
guard”) requires the lane branch to &lt;strong&gt;still&lt;/strong&gt; descend from &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; —
because a fix that satisfies Assert A by branching lanes off &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; instead
would silently discard coordination-branch lifecycle state (status events, WP claim
history) the coord/primary partition depends on. Both must hold simultaneously.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Merge the recorded finalize-tasks planning-artifact commit into the lane on top of its
existing &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;mission_branch&lt;/code&gt; parentage.&lt;/strong&gt; The lane’s primary git
parent is unchanged; the recorded commit becomes an additional ancestor via one
idempotent, per-lane merge — never a mutation of the shared &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; ref
itself, and never a base derived from a &lt;em&gt;live&lt;/em&gt; read of &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt;’s tip.&lt;/p&gt;
&lt;h3 id=&quot;1-the-recorded-sha-is-captured-once-at-finalize-tasks-and-is-immutable-thereafter&quot;&gt;1. The recorded SHA is captured once, at &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt;, and is immutable thereafter&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent mission finalize-tasks&lt;/code&gt; is the single write authority for
&lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;LANE_STATE&lt;/code&gt;, PRIMARY-partition — &lt;code dir=&quot;auto&quot;&gt;mission_finalize.py: _compute_and_write_lanes&lt;/code&gt;). Immediately after &lt;code dir=&quot;auto&quot;&gt;compute_lanes&lt;/code&gt; returns and before
&lt;code dir=&quot;auto&quot;&gt;write_lanes_json&lt;/code&gt; persists the manifest, the command captures &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt;’s
&lt;strong&gt;current&lt;/strong&gt; tip (&lt;code dir=&quot;auto&quot;&gt;git rev-parse --verify &amp;#x3C;target_branch&gt;&lt;/code&gt; in the primary checkout) and
sets it as &lt;code dir=&quot;auto&quot;&gt;LanesManifest.planning_commit_sha&lt;/code&gt;. At this point in the finalize-tasks
pipeline, &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; already carries every planning-artifact commit
(&lt;code dir=&quot;auto&quot;&gt;spec-commit&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;setup-plan&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tasks-commit&lt;/code&gt; all land before &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; runs) —
so the captured value is, by construction, the recorded planning-artifact tip, not a
value that could still move. The field is written into the SAME &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; write that
already lands in the finalize-tasks commit — no second commit, no read-back, no
chicken-and-egg with the finalize-tasks commit’s own hash. &lt;code dir=&quot;auto&quot;&gt;LanesManifest&lt;/code&gt; gained the
field (&lt;code dir=&quot;auto&quot;&gt;str | None = None&lt;/code&gt;, backward-compatible default for pre-fix &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Never re-derive it live.&lt;/strong&gt; The allocator MUST NOT call &lt;code dir=&quot;auto&quot;&gt;git rev-parse target_branch&lt;/code&gt;
(or read &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt;’s tip) at allocate time to answer “what should the lane
descend from” — that is the moving-tip trap this ADR exists to close: the tip depends on
when &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; happens to run, and a mission’s &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; may legitimately advance
for reasons unrelated to this mission between &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt;. Only the
value frozen in &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; at finalize-tasks time is used.&lt;/p&gt;
&lt;h3 id=&quot;2-the-lanes-git-parent-coordination_branch--mission_branch-does-not-change&quot;&gt;2. The lane’s git parent (&lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;mission_branch&lt;/code&gt;) does not change&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;allocate_lane_worktree&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;worktree_allocator.py&lt;/code&gt;) still creates the lane branch from
&lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; (new-topology missions) or the legacy &lt;code dir=&quot;auto&quot;&gt;mission_branch&lt;/code&gt; field
(no-coordination missions), exactly as WP04 established. This preserves the
coord-descent guard (Assert A’) by construction — there is no behavior to regress
because the parent selection is untouched.&lt;/p&gt;
&lt;h3 id=&quot;3-the-recorded-commit-is-merged-into-the-lane-immediately-after-creation--idempotent-per-lane-non-mutating&quot;&gt;3. The recorded commit is merged into the lane immediately after creation — idempotent, per-lane, non-mutating&lt;/h3&gt;
&lt;p&gt;A new helper (&lt;code dir=&quot;auto&quot;&gt;_merge_recorded_planning_commit&lt;/code&gt;) runs &lt;code dir=&quot;auto&quot;&gt;git merge-base --is-ancestor &amp;#x3C;planning_commit_sha&gt; HEAD&lt;/code&gt; inside the freshly created (or reused / crash-recovered)
lane worktree; if not already an ancestor, it runs &lt;code dir=&quot;auto&quot;&gt;git merge --no-edit -m &quot;...&quot; &amp;#x3C;planning_commit_sha&gt;&lt;/code&gt;. This:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;satisfies Assert A: the lane branch now descends from the planning-artifact commit;&lt;/li&gt;
&lt;li&gt;leaves Assert A’ untouched: &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; is still the lane’s direct parent,
so &lt;code dir=&quot;auto&quot;&gt;git merge-base --is-ancestor coordination_branch &amp;#x3C;lane&gt;&lt;/code&gt; still holds trivially;&lt;/li&gt;
&lt;li&gt;is scoped to the ONE lane branch being created — &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt;’s own history
is never mutated, so no other lane, no status-write machinery, and no
&lt;code dir=&quot;auto&quot;&gt;_refuse_preexisting_lane_status_deletions&lt;/code&gt; merge-base computed against
&lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; is affected (§5);&lt;/li&gt;
&lt;li&gt;is idempotent (ancestor-check short-circuits), so it runs safely on the
worktree-reuse path, the crash-recovery path, and the fresh-create path alike — an
existing lane created before &lt;code dir=&quot;auto&quot;&gt;planning_commit_sha&lt;/code&gt; existed self-heals the next time
any WP in that lane is (re-)allocated, and a lane re-entered after a
&lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; re-run (e.g. a later WP added) picks up the newer recorded value;&lt;/li&gt;
&lt;li&gt;is &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt;-safe: a &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; written before this fix has no
&lt;code dir=&quot;auto&quot;&gt;planning_commit_sha&lt;/code&gt;, and the merge step no-ops, reproducing pre-fix behavior
byte-for-byte (&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/lanes/test_worktree_allocator_coord.py&lt;/code&gt; is
unaffected — its hand-built manifests never set the field);&lt;/li&gt;
&lt;li&gt;fails &lt;strong&gt;closed&lt;/strong&gt;, not silently: a genuine conflict (expected to be rare to
non-existent in practice, because &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt;’s own commits are
COORD-partition status/matrix files, disjoint from the PRIMARY-partition planning
files the recorded commit carries) aborts the merge and raises a structured
&lt;code dir=&quot;auto&quot;&gt;PlanningCommitMergeConflictError&lt;/code&gt; with an operator-actionable &lt;code dir=&quot;auto&quot;&gt;next_step&lt;/code&gt;, mirroring
the existing &lt;code dir=&quot;auto&quot;&gt;DependencyLaneMergeConflictError&lt;/code&gt; (#1684) shape. The half-merged state
is never left on disk.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;4-resolving-the-coord-status-lineage-question-fr-007--adr-2026-06-24-1-5&quot;&gt;4. Resolving the coord-status-lineage question (FR-007 / ADR 2026-06-24-1 §5)&lt;/h3&gt;
&lt;p&gt;ADR 2026-06-24-1 §5 partitions PRIMARY (planning) writes from COORD (status/matrix/
tracer) writes, and this mission’s FR-007 routes matrix/tracer/status writes off the
lane onto the coordination surface entirely — a lane never authors or commits a COORD-
partition artifact. Combined with §2 above (the lane’s &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; parentage
is untouched by this fix), the coord-status-lineage question resolves as follows:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision: no change to coord-status lineage is required or made.&lt;/strong&gt; The lane’s
relationship to &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; — and therefore
&lt;code dir=&quot;auto&quot;&gt;auto_rebase._refuse_preexisting_lane_status_deletions&lt;/code&gt;’s &lt;code dir=&quot;auto&quot;&gt;git merge-base HEAD &amp;#x3C;mission_branch-or-coordination_branch&gt;&lt;/code&gt; reasoning — is exactly what WP04 established.
This fix is strictly additive: it gives the lane a &lt;strong&gt;second&lt;/strong&gt;, disjoint ancestry line
(the planning commit) without touching the first (coordination_branch). Since
&lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;lanes_manifest.mission_branch&lt;/code&gt; are the SAME branch for
coordination-topology missions (both composed by the identical
&lt;code dir=&quot;auto&quot;&gt;branch_naming.mission_branch_name&lt;/code&gt; grammar — &lt;code dir=&quot;auto&quot;&gt;coord_branch_name&lt;/code&gt; delegates to it
verbatim), this holds for both call shapes of &lt;code dir=&quot;auto&quot;&gt;attempt_auto_rebase&lt;/code&gt;’s &lt;code dir=&quot;auto&quot;&gt;mission_branch&lt;/code&gt;
parameter (&lt;code dir=&quot;auto&quot;&gt;lifecycle_sync.py&lt;/code&gt; passes &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;lanes/merge.py&lt;/code&gt;’s
&lt;code dir=&quot;auto&quot;&gt;consolidate_lane_into_mission&lt;/code&gt; passes &lt;code dir=&quot;auto&quot;&gt;lanes_manifest.mission_branch&lt;/code&gt; — the same ref).&lt;/p&gt;
&lt;p&gt;FR-009 ancestry (this ADR, PRIMARY partition) and FR-008 row-aware-merge durability
(COORD partition, matrix/tracer) are hereby explicitly disentangled: FR-009 governs only
whether a lane’s &lt;code dir=&quot;auto&quot;&gt;git log&lt;/code&gt; contains the planning-artifact commit; it says nothing about,
and does not gate, how the FR-008 merge driver resolves &lt;code dir=&quot;auto&quot;&gt;%O&lt;/code&gt; for &lt;code dir=&quot;auto&quot;&gt;ISSUE_MATRIX&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;ACCEPTANCE_MATRIX&lt;/code&gt; conflicts (§5).&lt;/p&gt;
&lt;h3 id=&quot;5-the-fr-008-merge-driver-o-partition-is-orthogonal-to-this-adr-e-b-adjudicated-2026-07-29&quot;&gt;5. The FR-008 merge-driver &lt;code dir=&quot;auto&quot;&gt;%O&lt;/code&gt; partition is orthogonal to this ADR (E-B, adjudicated 2026-07-29)&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;ISSUE_MATRIX&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;ACCEPTANCE_MATRIX&lt;/code&gt; are COORD-partition kinds
(&lt;code dir=&quot;auto&quot;&gt;mission_runtime/artifacts.py:172-183&lt;/code&gt;) that &lt;code dir=&quot;auto&quot;&gt;resolve_placement_only&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;declared_read_surface&lt;/code&gt; place topology-dependently
(&lt;code dir=&quot;auto&quot;&gt;resolution.py:1602-1607&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:1211-1217&lt;/code&gt;). Under coordination topology they serialize
onto the single coordination worktree (&lt;code dir=&quot;auto&quot;&gt;commit_router.py:248-306&lt;/code&gt;) and &lt;strong&gt;never diverge
on lane branches&lt;/strong&gt; — a lane worktree never holds a divergent copy of &lt;code dir=&quot;auto&quot;&gt;issue-matrix.json&lt;/code&gt;
/ &lt;code dir=&quot;auto&quot;&gt;acceptance-matrix.json&lt;/code&gt; to merge in the first place. The FR-008 row-aware merge
driver’s &lt;code dir=&quot;auto&quot;&gt;%O&lt;/code&gt; (common ancestor) therefore comes from the &lt;strong&gt;seam-resolved matrix surface
for the active topology&lt;/strong&gt; (coord lineage under coordination topology, primary /
&lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; lineage under flat), never from this WP’s recorded &lt;code dir=&quot;auto&quot;&gt;planning_commit_sha&lt;/code&gt;.
There is no hard FR-008↔FR-009 coupling; WP11-T045 seeds &lt;code dir=&quot;auto&quot;&gt;%O&lt;/code&gt; from the resolved matrix
surface, not from the lane base this ADR governs.&lt;/p&gt;
&lt;h3 id=&quot;6-no-consolidation-abort-path&quot;&gt;6. No consolidation abort path&lt;/h3&gt;
&lt;p&gt;Consistent with ADR &lt;a href=&quot;/adr/3.x/2026-07-23-2-post-consolidation-deferral-and-external-enforcement/&quot;&gt;2026-07-23-2&lt;/a&gt;,
this fix introduces no new abort trigger into lane consolidation or mission-branch
integration. A merge conflict while incorporating the recorded planning commit is
surfaced at &lt;strong&gt;lane-allocation time&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;spec-kitty implement&lt;/code&gt;), before any consolidation
begins, as a normal fail-closed allocator error the operator resolves like any other
&lt;code dir=&quot;auto&quot;&gt;allocate_lane_worktree&lt;/code&gt; failure (e.g. &lt;code dir=&quot;auto&quot;&gt;DependencyLaneMergeConflictError&lt;/code&gt;) — it is not a
new consolidation-time or post-consolidation gate.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;#2993 is closed at the root: a lane’s own &lt;code dir=&quot;auto&quot;&gt;git log&lt;/code&gt; contains the mission’s
planning-artifact commit, so a later amendment or retraction of &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt;
on the primary checkout unions or deletes correctly against the lane instead of
fabricating stale/resurrected content at consolidation.&lt;/li&gt;
&lt;li&gt;Zero regression to the WP04 (#1348) coordination-branch contract: &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt;
remains the lane’s direct git parent; every test asserting
&lt;code dir=&quot;auto&quot;&gt;merge-base --is-ancestor coordination_branch &amp;#x3C;lane&gt;&lt;/code&gt; keeps passing unmodified.&lt;/li&gt;
&lt;li&gt;The fix self-heals: because the merge step is idempotent and runs on every allocate
path (fresh-create, reuse, crash-recovery), a lane created by pre-fix tooling, or a
lane re-entered after a later &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; run recorded a newer SHA, picks up the
correct ancestry the next time it is touched — no one-shot migration is required.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;merge/ordering.py&lt;/code&gt;’s topological sort is confirmed untouched (D-5): it is a pure
frontmatter-dependency sort with no git-ancestry input, so this base change cannot
perturb merge order.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative--accepted-trade-offs&quot;&gt;Negative / accepted trade-offs&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Every freshly created (or first-touched) lane worktree gains one extra merge commit.
This is judged acceptable: it is a single, deterministic, disjoint-file-set merge
(COORD-partition status files vs. PRIMARY-partition planning files essentially never
overlap), and the alternative (no merge, the pre-fix state) is the #2993 defect itself.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;planning_commit_sha&lt;/code&gt; is captured once per &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; invocation and can advance
on a re-finalize (e.g. after a later WP or dependency edit); an &lt;strong&gt;already-allocated&lt;/strong&gt;
lane does not retroactively rewrite its own history when this happens — it only picks
up the newer value the next time that lane is allocated/recovered. This is judged
correct, not a violation of “immutable once recorded”: the field’s &lt;em&gt;value&lt;/em&gt; at any
given finalize-tasks run is frozen and auditable; a later run recording a &lt;em&gt;new&lt;/em&gt; value
is a fresh, equally-frozen snapshot, not a mutation of the old one.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Legacy (no-&lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt;) missions already lazily create &lt;code dir=&quot;auto&quot;&gt;mission_branch&lt;/code&gt; from
&lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt;’s tip at first-lane-allocation time, which in practice already
postdates &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt;. The merge step still runs there (idempotent, uniform code
path) but is expected to be a no-op in the common case.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives considered&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Branch the lane directly from &lt;code dir=&quot;auto&quot;&gt;planning_commit_sha&lt;/code&gt;, dropping &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt;
as the parent entirely.&lt;/strong&gt; Rejected: this is exactly the shape the pinned regression’s
Assert A’ (coord-descent guard) forbids — it would silently sever the lane from
coordination-branch lifecycle state (status events, WP claim history) to fix #2993,
trading one defect for another.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fast-forward or merge &lt;code dir=&quot;auto&quot;&gt;planning_commit_sha&lt;/code&gt; into the shared &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt;
ref itself before branching lanes from it.&lt;/strong&gt; Rejected: this mutates a branch shared by
every lane and by the status-write machinery for a single lane’s benefit, widening the
blast radius far beyond what #2993 requires, and would need its own conflict/locking
story across concurrently-allocating lanes. The per-lane merge achieves the same
ancestry outcome with a strictly smaller footprint.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Re-derive the base live at allocate time (&lt;code dir=&quot;auto&quot;&gt;git rev-parse target_branch&lt;/code&gt;).&lt;/strong&gt; Rejected
as the moving-tip trap this ADR exists to close (see the WP01 Reviewer guidance): the
value would depend on unrelated activity landing on &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; between
&lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; and whenever &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; happens to run for a given WP.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Give the base full coord-status lineage parity (e.g., re-derive &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt;
from a common synchronized point).&lt;/strong&gt; Rejected: unnecessary — §4/§5 above show FR-009
ancestry and FR-008 matrix-merge durability are orthogonal; conflating them would
reintroduce the SC-003 bundling risk research.md’s D-5 explicitly warns against.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fix the root cause upstream, in &lt;code dir=&quot;auto&quot;&gt;implement.py&lt;/code&gt;’s &lt;code dir=&quot;auto&quot;&gt;_ensure_planning_artifacts_committed_git&lt;/code&gt;
/ &lt;code dir=&quot;auto&quot;&gt;resolve_placement_only&lt;/code&gt; auto-commit no-op (Cause A/B per the #2993 regression
triage), instead of the allocator.&lt;/strong&gt; Not rejected as wrong, but out of this WP’s scope
(&lt;code dir=&quot;auto&quot;&gt;worktree_allocator.py&lt;/code&gt; is WP01’s authoritative surface): the allocator-level merge
closes the defect regardless of whether that upstream no-op is ever separately fixed,
and is the mechanism &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; (this WP’s &lt;code dir=&quot;auto&quot;&gt;create_intent&lt;/code&gt;) already
points at.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Amends:&lt;/strong&gt; &lt;a href=&quot;/adr/3.x/2026-04-03-1-execution-lanes-own-worktrees-and-mission-branches/&quot;&gt;2026-04-03-1 — Execution Lanes Own Worktrees and Mission Branches&lt;/a&gt;
(extends the Lane Computation Contract: the lane base is now the recorded
&lt;code dir=&quot;auto&quot;&gt;planning_commit_sha&lt;/code&gt;, merged onto the existing &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;mission_branch&lt;/code&gt;
parent, not a bare branch pointer).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Cites:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-06-24-1-kind-and-topology-aware-artifact-placement/&quot;&gt;2026-06-24-1 — Kind- and Topology-Aware Artifact Placement&lt;/a&gt;
(§5 partition: planning on PRIMARY for every topology; status/matrix/tracer on COORD
under coordination topology).&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-06-24-2-write-branch-resolution-primary-anchor/&quot;&gt;2026-06-24-2 — Write-Branch Resolution Anchors &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; on the PRIMARY Surface&lt;/a&gt;
(the write-branch/&lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; resolution this ADR’s SHA capture reuses).&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-07-23-2-post-consolidation-deferral-and-external-enforcement/&quot;&gt;2026-07-23-2 — Post-Consolidation Deferral and External Enforcement of Negative Invariants&lt;/a&gt;
(no new consolidation abort path — §6 above).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Issues:&lt;/strong&gt; &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2993&quot;&gt;#2993&lt;/a&gt; (lane lacks
common ancestor with planning artifacts — closed by this ADR),
&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1684&quot;&gt;#1684&lt;/a&gt; (dependent-lane
cross-lane-tip propagation invariant — preserved unchanged, §3),
&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2274&quot;&gt;#2274&lt;/a&gt; (lane-hygiene guard
compares &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; by commit-history, not content — &lt;strong&gt;noted, not fixed, here&lt;/strong&gt;: the
extra planning-commit merge this ADR introduces changes a lane’s commit history under
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;slug&gt;/&lt;/code&gt; without changing its &lt;em&gt;content&lt;/em&gt; relative to the planning branch, so
a commit-history-based hygiene check can false-positive immediately after this fix ships
on any mission whose lanes predate it. Coordinate the actual fix with
&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2273&quot;&gt;#2273&lt;/a&gt;,
&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2626&quot;&gt;#2626&lt;/a&gt;,
&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2570&quot;&gt;#2570&lt;/a&gt; — out of WP01’s scope).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Mission:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;kitty-specs/write-side-seam-matrix-tracer-01KYP3MH/&lt;/code&gt; (WP01, FR-009,
NFR-005). Research: &lt;code dir=&quot;auto&quot;&gt;research.md&lt;/code&gt; D-5. Plan: &lt;code dir=&quot;auto&quot;&gt;plan.md&lt;/code&gt; (Risks). Tasks: &lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt; T001-T005.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Regression pin:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;tests/regression/test_issue_2993_lane_planning_ancestry.py&lt;/code&gt;
(Assert A / Assert A’ shape this ADR’s decision satisfies).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Canonical seams:&lt;/strong&gt; &lt;a href=&quot;../../../src/specify_cli/lanes/worktree_allocator.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/lanes/worktree_allocator.py&lt;/code&gt;&lt;/a&gt;
(&lt;code dir=&quot;auto&quot;&gt;_merge_recorded_planning_commit&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;allocate_lane_worktree&lt;/code&gt;),
&lt;a href=&quot;../../../src/specify_cli/lanes/models.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/lanes/models.py&lt;/code&gt;&lt;/a&gt;
(&lt;code dir=&quot;auto&quot;&gt;LanesManifest.planning_commit_sha&lt;/code&gt;),
&lt;a href=&quot;../../../src/specify_cli/cli/commands/agent/mission_finalize.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/mission_finalize.py&lt;/code&gt;&lt;/a&gt;
(&lt;code dir=&quot;auto&quot;&gt;_compute_and_write_lanes&lt;/code&gt;, the SHA-capture producer),
&lt;a href=&quot;../../../src/specify_cli/lanes/auto_rebase.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/lanes/auto_rebase.py&lt;/code&gt;&lt;/a&gt;
(&lt;code dir=&quot;auto&quot;&gt;_refuse_preexisting_lane_status_deletions&lt;/code&gt; — reconciled, unchanged, §4).&lt;/p&gt;
&lt;h2 id=&quot;erratum-2026-10-04-5627&quot;&gt;Erratum (2026-10-04, #5627)&lt;/h2&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;mission_finalize.py: _compute_and_write_lanes&lt;/code&gt; citations above (the producer reference in section 1 and the canonical-seams list) point to that file as it was when this ADR was written. Mission &lt;code dir=&quot;auto&quot;&gt;mission-finalize-degod-01M43EW2&lt;/code&gt; later split it into phase modules, with bodies moved verbatim. &lt;code dir=&quot;auto&quot;&gt;_compute_and_write_lanes&lt;/code&gt; now lives in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/mission_finalize_lanes.py&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;mission_finalize&lt;/code&gt; still re-exports it. The decision is unchanged.&lt;/p&gt;
&lt;h2 id=&quot;amendment-2026-11-06-lane-checkouts-carry-no-live-status&quot;&gt;Amendment 2026-11-06: lane checkouts carry no live status&lt;/h2&gt;
&lt;p&gt;Mission &lt;code dir=&quot;auto&quot;&gt;lane-worktree-model-hardening-01M6QY1M&lt;/code&gt; (S6, #7281; FR-040 to FR-046), Proposed until the
operator accepts it. It records the operator’s restated ruling 3 (DM &lt;code dir=&quot;auto&quot;&gt;01M6QY3XQJ5NAYVF3GMZ7ZPPRE&lt;/code&gt;,
2026-11-06) for every lane topology, &lt;code dir=&quot;auto&quot;&gt;lanes&lt;/code&gt; included, and keeps Assert A’.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Rule.&lt;/strong&gt; A lane checkout never shows the Mission’s status files, Spec Kitty never changes them in a
lane, and no reader reads them. The fork-time blob stays in lane history and is inert.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Checkouts never show them.&lt;/strong&gt; Every lane checkout, on every topology with code lanes (&lt;code dir=&quot;auto&quot;&gt;lanes&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;coord&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;lanes_with_coord&lt;/code&gt;), is created by the one lane-checkout helper
(&lt;code dir=&quot;auto&quot;&gt;lanes/lane_checkout.py::open_lane_checkout&lt;/code&gt;), which registers the sparse exclusion of
&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; (FR-040). This widens the exclusion described in the
Context above, which only coordination-topology lanes registered, and covers every route by which
Spec Kitty creates a lane checkout: allocation, crash recovery, lifecycle sync, the review checkout
and &lt;code dir=&quot;auto&quot;&gt;implement --recover&lt;/code&gt;. The recreate command that &lt;code dir=&quot;auto&quot;&gt;doctor workspaces&lt;/code&gt; prints
(&lt;code dir=&quot;auto&quot;&gt;workspace/landed_worktrees.py&lt;/code&gt;) is a &lt;code dir=&quot;auto&quot;&gt;git worktree add&lt;/code&gt; for the operator to run, not a Spec Kitty
route, so it does not register the exclusion; a checkout made that way shows the status files until
&lt;code dir=&quot;auto&quot;&gt;doctor sparse-checkout&lt;/code&gt; reports it (&lt;code dir=&quot;auto&quot;&gt;LANE_STATUS_NOT_EXCLUDED&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Lanes never change them.&lt;/strong&gt; The status write seam refuses a write whose target is inside a lane
checkout, classified through the worktree registry and not by path shape
(&lt;code dir=&quot;auto&quot;&gt;STATUS_WRITE_TARGETS_LANE_CHECKOUT&lt;/code&gt;, FR-041). Spec Kitty-owned lane commits, the deliverable
auto-commit included, leave the status files unstaged (FR-042).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Readers never read them.&lt;/strong&gt; Every status read goes through the one read door of
&lt;a href=&quot;/adr/4.x/2026-11-06-2-one-status-read-contract/&quot;&gt;ADR 2026-11-06-2&lt;/a&gt;, which never returns a lane
path (FR-043).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No lane-side deletion commit (C-008).&lt;/strong&gt; The fork-time status blob stays in the lane branch’s
history. Assert A’ is kept, and this is why: a commit that deleted the files on a lane would be
carried onto the Mission or coordination branch at consolidation, deleting the real log, and it
would trip &lt;code dir=&quot;auto&quot;&gt;auto_rebase._refuse_preexisting_lane_status_deletions&lt;/code&gt;. Excluding the files from disk
keeps the lane’s parentage and tree exactly as §2 and §4 above describe.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Existing lane worktrees.&lt;/strong&gt; A re-runnable clone-local migration applies the exclusion to clean
worktrees, flags and excludes a dirty copy whose events are all on the resolved surface, leaves a
worktree untouched when its copy holds events found nowhere else (reporting their ids), and skips
worktrees that are mid-merge or mid-rebase; it never drops an event (FR-044, C-009). The doctor
finding &lt;code dir=&quot;auto&quot;&gt;LANE_STATUS_AUTHORED&lt;/code&gt; lists every live lane branch whose status files differ from their
merge-base with the branch the lane consolidates into (FR-045); it gates any later retirement of
the auto-rebase status union merger. Both are delivered by Mission WP10.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Confirmation.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;tests/lanes/test_lane_checkout_helper.py&lt;/code&gt; (Mission WP09, every-route exclusion on
every topology with code lanes), the WP10 write-refusal, migration and doctor tests, and
&lt;code dir=&quot;auto&quot;&gt;tests/lanes/test_issue_2993_lane_planning_ancestry.py&lt;/code&gt; (Assert A and Assert A’, unchanged; the
pin cited above as &lt;code dir=&quot;auto&quot;&gt;tests/regression/...&lt;/code&gt; now lives there).&lt;/p&gt;</content>
</entry>
