<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/architecture/execution-lanes/">
  <id>https://docs.spec-kitty.ai/architecture/execution-lanes/</id>
  <title>Execution Lanes</title>
  <updated>2026-11-20T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/architecture/execution-lanes/"/>
  <summary>Spec Kitty&apos;s lane-based execution model: finalize-tasks computes lanes.json from dependencies and file ownership, giving each lane one worktree and branch to preserve parallelism.</summary>
  <content type="html">&lt;span id=&quot;execution-lanes&quot;&gt;&lt;/span&gt;
&lt;p&gt;Spec Kitty uses a lane-based execution model.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;For &lt;code dir=&quot;auto&quot;&gt;lanes&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;lanes_with_coord&lt;/code&gt; missions, &lt;code dir=&quot;auto&quot;&gt;finalize_tasks&lt;/code&gt; computes &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; from dependencies, ownership, and predicted surfaces. A &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; mission gets a one-lane repo-root manifest instead.&lt;/li&gt;
&lt;li&gt;Each code lane gets exactly one git worktree and one lane branch.&lt;/li&gt;
&lt;li&gt;Sequential work packages in the same lane reuse that same worktree.&lt;/li&gt;
&lt;li&gt;Independent lanes can run in parallel in separate worktrees.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;core-rules&quot;&gt;Core Rules&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Planning happens in the primary repository checkout.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent action implement WP## --agent &amp;#x3C;name&gt;&lt;/code&gt; requires a valid &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The runtime chooses the lane worktree. Agents do not pick a base branch manually.&lt;/li&gt;
&lt;li&gt;If a &lt;code dir=&quot;auto&quot;&gt;lanes&lt;/code&gt; mission computes one lane, the mission uses one worktree. A &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; mission uses no lane worktree at all.&lt;/li&gt;
&lt;li&gt;Consolidation always follows &lt;code dir=&quot;auto&quot;&gt;lane branches -&gt; mission branch -&gt; target branch&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Code lanes are cut from the Mission branch: on a coordination topology that is the coordination branch, which shares the Mission branch’s name; for a default Mission settled to &lt;code dir=&quot;auto&quot;&gt;lanes_with_coord&lt;/code&gt; it is the &lt;a href=&quot;/context/topology/#topic-branch&quot;&gt;topic branch&lt;/a&gt;.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;workspace-resolution-contract&quot;&gt;Workspace Resolution Contract&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty implement WP##&lt;/code&gt; creates/reuses the execution workspace through
&lt;code dir=&quot;auto&quot;&gt;resolve_workspace_for_wp&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/workspace/context.py&lt;/code&gt;). For a
&lt;code dir=&quot;auto&quot;&gt;code_change&lt;/code&gt; WP, resolution ends at one of two places:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;An &lt;strong&gt;existing&lt;/strong&gt; lane workspace context (&lt;code dir=&quot;auto&quot;&gt;find_context_for_wp&lt;/code&gt;) — the lane
this WP’s mission already allocated a worktree for.&lt;/li&gt;
&lt;li&gt;Otherwise, the mapping in &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;, read through
&lt;code dir=&quot;auto&quot;&gt;require_lanes_json&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/lanes/persistence.py&lt;/code&gt;).&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;require_lanes_json&lt;/code&gt; is fail-closed: when &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; is absent it raises
&lt;code dir=&quot;auto&quot;&gt;MissingLanesError&lt;/code&gt; rather than degrading to a name-guessed path. &lt;strong&gt;There is
no &lt;code dir=&quot;auto&quot;&gt;-WP##&lt;/code&gt; legacy worktree fallback&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;LANES&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;LANES_WITH_COORD&lt;/code&gt;
missions require a computed &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;; a mission that hasn’t run
&lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; cannot resolve a workspace at all. A &lt;code dir=&quot;auto&quot;&gt;SINGLE_BRANCH&lt;/code&gt; mission
also needs its &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;, but that manifest is not computed from
dependencies: it is a one-lane repo-root manifest (&lt;code dir=&quot;auto&quot;&gt;lane-planning&lt;/code&gt;) whose WPs all
resolve to the write checkout (the repository root checkout, or a validated owned
checkout) with &lt;code dir=&quot;auto&quot;&gt;execution_mode: direct_repo&lt;/code&gt;. It has no lane worktree, no lane
branch and no dependency merge. See the
&lt;a href=&quot;/context/topology/&quot;&gt;topology glossary&lt;/a&gt;. (An earlier revision of
this repo’s &lt;code dir=&quot;auto&quot;&gt;AGENTS.md&lt;/code&gt; claimed such a fallback existed; that claim was
false and has been corrected — see the &lt;code dir=&quot;auto&quot;&gt;MissingLanesError&lt;/code&gt; contract above
for the real behavior.)&lt;/p&gt;
&lt;h2 id=&quot;lane-checkouts-status-and-cleanup&quot;&gt;Lane Checkouts, Status and Cleanup&lt;/h2&gt;
&lt;p&gt;Mission &lt;code dir=&quot;auto&quot;&gt;lane-worktree-model-hardening-01M6QY1M&lt;/code&gt; (#7276) fixed how lane checkouts relate to status and how they end.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;One lane-checkout helper.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;lanes/lane_checkout.py::open_lane_checkout&lt;/code&gt; creates every lane checkout: fresh, legacy and crash-recovery allocation, the lifecycle recreate, the review checkout and &lt;code dir=&quot;auto&quot;&gt;implement --recover&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No status files in a lane checkout.&lt;/strong&gt; The helper applies a managed sparse exclusion on every topology, so a lane checkout never shows the Mission’s &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt;. A status write aimed at a lane checkout refuses with &lt;code dir=&quot;auto&quot;&gt;STATUS_WRITE_TARGETS_LANE_CHECKOUT&lt;/code&gt; (the git worktree registry decides; an unreadable registry fails closed). Missions created before coordination topologies existed keep their earlier behavior. Existing lane worktrees are brought in line by a clone-local migration; see &lt;a href=&quot;/architecture/git-worktrees/#lane-checkouts-hide-status&quot;&gt;Git Worktrees §Lane checkouts hide status&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;One status read door.&lt;/strong&gt; Every status read goes through &lt;code dir=&quot;auto&quot;&gt;status/read_surface.py::resolve_status_read&lt;/code&gt; (ADR &lt;a href=&quot;/adr/4.x/2026-11-06-2-one-status-read-contract/&quot;&gt;4.x &lt;code dir=&quot;auto&quot;&gt;2026-11-06-2&lt;/code&gt;&lt;/a&gt;): the coordination branch on coordination topologies, the Mission branch (or the checkout that holds it) otherwise, the target once the Mission has landed. Read it from the CLI with &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent tasks status&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; gate reads the lane branch.&lt;/strong&gt; It counts commits with &lt;code dir=&quot;auto&quot;&gt;git rev-list &amp;#x3C;base&gt;..refs/heads/&amp;#x3C;lane&gt;&lt;/code&gt; from the repository root, so it needs no lane checkout.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Stale lanes are refreshed by the CLI.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; auto-rebases a stale lane. The stale-lane remedy first reopens the approved work package (&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent tasks move-task &amp;#x3C;WP&gt; --to planned --review-feedback-file &amp;#x3C;file&gt;&lt;/code&gt;, which costs a re-review, because &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; refuses an approved work package), then prints &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent action implement &amp;#x3C;WP&gt; --mission &amp;#x3C;handle&gt;&lt;/code&gt; (the lane sync point), never a &lt;code dir=&quot;auto&quot;&gt;cd .worktrees/...&lt;/code&gt; recipe. When the overlap comes from a sibling lane consolidated ahead of it, the refusal also gives the in-run auto-rebase halt reason and names the sibling lane’s branch to &lt;code dir=&quot;auto&quot;&gt;git merge&lt;/code&gt; in that checkout: the rollback restores the Mission branch without the sibling’s change, so refreshing from the Mission branch would bring in nothing (#7755).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Approval windows for &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt;.&lt;/strong&gt; A &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; Mission that lands a minted Mission branch is bounded per work package (&lt;code dir=&quot;auto&quot;&gt;consolidation/write_branch_bound.py&lt;/code&gt;, #7283): the approval-stamp check runs on the Mission branch, and every content commit must lie inside some approved work package’s window, from its first claim stamp to its newest approval stamp. A commit outside every window refuses with &lt;code dir=&quot;auto&quot;&gt;LANE_MOVED_AFTER_APPROVAL&lt;/code&gt;, naming the work package approved before it. An approval recorded without a stamp refuses with &lt;code dir=&quot;auto&quot;&gt;APPROVAL_STAMP_MISSING&lt;/code&gt;; attest it per work package with &lt;code dir=&quot;auto&quot;&gt;spec-kitty consolidate --attest-approved-reviewed &amp;#x3C;WP&gt; --attest-reason &quot;&amp;#x3C;why&gt;&quot;&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cleanup is consolidation’s last step.&lt;/strong&gt; After the landing is verified, &lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; removes lane and coordination checkouts and branches (&lt;code dir=&quot;auto&quot;&gt;consolidation/lane_cleanup.py&lt;/code&gt;, under the destructive guard) and prints one line per lane: &lt;code dir=&quot;auto&quot;&gt;Removed&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Kept&lt;/code&gt; (a guard refused; the line names the code and detail) or &lt;code dir=&quot;auto&quot;&gt;Retained&lt;/code&gt; (retention policy). A &lt;code dir=&quot;auto&quot;&gt;Kept&lt;/code&gt; lane does not fail the run. An interrupted cleanup resumes from a &lt;code dir=&quot;auto&quot;&gt;cleanup_started&lt;/code&gt; marker; &lt;code dir=&quot;auto&quot;&gt;--abort&lt;/code&gt; after it rolls nothing back and prints &lt;code dir=&quot;auto&quot;&gt;git branch &amp;#x3C;b&gt; &amp;#x3C;sha&gt;&lt;/code&gt; recreate hints.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;naming&quot;&gt;Naming&lt;/h2&gt;
&lt;p&gt;Mission and lane naming are two separate decisions, and only the Mission
decision takes the Mission identity.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Mission branch&lt;/strong&gt; — unchanged. As of mission
&lt;code dir=&quot;auto&quot;&gt;083-mission-id-canonical-identity-migration&lt;/code&gt;, every mission carries a ULID
identity (&lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;), and the Mission branch embeds the first 8 characters
of that ULID (&lt;code dir=&quot;auto&quot;&gt;mid8&lt;/code&gt;) to guarantee collision-free naming even when two
missions share the same human slug: &lt;code dir=&quot;auto&quot;&gt;kitty/mission-&amp;#x3C;human-slug&gt;-&amp;#x3C;mid8&gt;&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Lane branch and lane worktree&lt;/strong&gt; — keyed on the recorded Mission slug and the
lane id only. The Mission identity is never an input to lane naming (see ADR
&lt;a href=&quot;/adr/3.x/2026-09-26-2-lane-naming-keyed-on-creation-input/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-09-26-2&lt;/code&gt;&lt;/a&gt;):&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Lane branch: &lt;code dir=&quot;auto&quot;&gt;kitty/mission-&amp;#x3C;slug-body&gt;-&amp;#x3C;lane-id&gt;&lt;/code&gt;, where &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;slug-body&gt;&lt;/code&gt; is
the recorded Mission slug with a stale &lt;code dir=&quot;auto&quot;&gt;NNN-&lt;/code&gt; numeric prefix dropped only
when the slug itself embeds a mid8.&lt;/li&gt;
&lt;li&gt;Lane worktree: &lt;code dir=&quot;auto&quot;&gt;.worktrees/&amp;#x3C;slug&gt;-&amp;#x3C;lane-id&gt;/&lt;/code&gt;, verbatim — the recorded slug,
not recomposed.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;mid8&lt;/code&gt; therefore appears in a lane name only when the Mission slug happens to
embed it — never because lane naming looked up the identity.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Example — a modern mission&lt;/strong&gt; (slug embeds the mid8, so lane names look the
same as before this ADR): &lt;code dir=&quot;auto&quot;&gt;mission_slug=my-feature-01J6XW9K&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;mission_id=01J6XW9KQT7M0YB3N4R5CQZ2EX&lt;/code&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Mission branch: &lt;code dir=&quot;auto&quot;&gt;kitty/mission-my-feature-01J6XW9K&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Lane branch: &lt;code dir=&quot;auto&quot;&gt;kitty/mission-my-feature-01J6XW9K-lane-a&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Lane worktree: &lt;code dir=&quot;auto&quot;&gt;.worktrees/my-feature-01J6XW9K-lane-a/&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Example — a legacy mission&lt;/strong&gt; whose recorded slug is &lt;code dir=&quot;auto&quot;&gt;057-foo&lt;/code&gt; and whose
identity was later backfilled to a &lt;em&gt;different&lt;/em&gt; mid8 (&lt;code dir=&quot;auto&quot;&gt;01KV6510&lt;/code&gt;): lane naming
never sees the identity, so lane names are unaffected by the backfill:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Mission branch (recomposed only on first finalize; preserved after):
&lt;code dir=&quot;auto&quot;&gt;kitty/mission-057-foo&lt;/code&gt; (pre-backfill) — see the
&lt;a href=&quot;/migrations/mission-id-canonical-identity/&quot;&gt;mission identity migration runbook&lt;/a&gt;
for what backfill does and does not change.&lt;/li&gt;
&lt;li&gt;Lane branch: &lt;code dir=&quot;auto&quot;&gt;kitty/mission-057-foo-lane-a&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Lane worktree: &lt;code dir=&quot;auto&quot;&gt;.worktrees/057-foo-lane-a/&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Legacy (pre-083) lane forms such as &lt;code dir=&quot;auto&quot;&gt;kitty/mission-001-my-feature-lane-a&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;.worktrees/001-my-feature-lane-a/&lt;/code&gt; remain readable by current tooling.&lt;/p&gt;
&lt;h2 id=&quot;why-this-replaced-per-wp-worktrees&quot;&gt;Why This Replaced Per-WP Worktrees&lt;/h2&gt;
&lt;p&gt;Per-work-package worktrees allowed overlapping work packages to run in parallel and collide at merge time. Execution lanes eliminate that by forcing dependent or overlapping work packages into the same lane, branch, and worktree.&lt;/p&gt;
&lt;h2 id=&quot;parallelism-preservation&quot;&gt;Parallelism Preservation&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; groups WPs into lanes with a union-find over three rules
(&lt;code dir=&quot;auto&quot;&gt;compute_lanes&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/lanes/compute.py&lt;/code&gt;):&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;File ownership overlap&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;write_scope_overlap&lt;/code&gt;) — WPs whose &lt;code dir=&quot;auto&quot;&gt;owned_files&lt;/code&gt; overlap share a lane.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Shared surface&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;surface_heuristic&lt;/code&gt;) — WPs that share a predicted surface keyword share a lane unless their ownership is provably disjoint (see below).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Frozen lane membership&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;frozen_lane_membership&lt;/code&gt;) — on a re-finalize, started WPs that were recorded in the same lane stay together (see &lt;a href=&quot;#re-finalizing-an-active-mission&quot;&gt;Re-finalizing an active Mission&lt;/a&gt;).&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Dependency edges do not merge lanes by themselves. They become lane-level dependencies, so disjoint upstream lanes run in parallel and the WP that depends on them is the synchronization point. Inside one lane, WPs run in dependency order.&lt;/p&gt;
&lt;p&gt;When no rule forces a merge, WPs stay in separate lanes to maximise parallelism. Every merge is recorded in &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; under &lt;code dir=&quot;auto&quot;&gt;collapse_report&lt;/code&gt;:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;json&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;{&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;collapse_report&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: {&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;events&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: [&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;      &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;{&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;        &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;wp_a&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;WP02&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;        &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;wp_b&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;WP03&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;        &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;rule&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;write_scope_overlap&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;        &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;evidence&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;overlapping globs: &apos;src/foo.py&apos; vs &apos;src/foo.py&apos;&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;      &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;}&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;],&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;total_merges&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;1&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;independent_wps_collapsed&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;1&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;by_rule&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: {&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;write_scope_overlap&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;1&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;}&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;}&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;}&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Each event names the two WPs merged, the rule and its evidence. &lt;code dir=&quot;auto&quot;&gt;independent_wps_collapsed&lt;/code&gt; counts merges of WPs with no direct or transitive dependency between them; &lt;code dir=&quot;auto&quot;&gt;frozen_lane_membership&lt;/code&gt; merges are never counted there, because those WPs already shared a lane. Inspect this field after &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; to understand why two WPs share a lane.&lt;/p&gt;
&lt;h3 id=&quot;disjoint-ownership-vs-the-surface-heuristic-bulk-edit-missions&quot;&gt;Disjoint Ownership vs. the Surface Heuristic (bulk-edit missions)&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;compute_lanes&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/lanes/compute.py&lt;/code&gt;) has a second collapse
rule beyond file-overlap: two WPs that share an inferred &lt;em&gt;surface&lt;/em&gt; keyword
(e.g. both bodies mention “legacy” or “cleanup”, matching the
&lt;code dir=&quot;auto&quot;&gt;legacy-cleanup&lt;/code&gt; tag in &lt;code dir=&quot;auto&quot;&gt;_SURFACE_KEYWORDS&lt;/code&gt;) are also candidates for merging
into one lane — &lt;strong&gt;unless their &lt;code dir=&quot;auto&quot;&gt;owned_files&lt;/code&gt; are provably disjoint&lt;/strong&gt;
(&lt;code dir=&quot;auto&quot;&gt;_are_disjoint&lt;/code&gt;), in which case the merge is skipped.&lt;/p&gt;
&lt;p&gt;This matters most for bulk-edit missions (see the &lt;a href=&quot;/adr/3.x/2026-04-14-1-bulk-edit-occurrence-classification-guardrail/&quot;&gt;bulk-edit occurrence
classification guardrail
ADR&lt;/a&gt;):
a rename/replace mission routinely produces many WPs whose bodies all
describe the &lt;em&gt;same&lt;/em&gt; edit applied to &lt;em&gt;different&lt;/em&gt; files, so they trip the
same surface keyword nearly every time. Without the disjoint-ownership
check, the surface heuristic alone would collapse every one of those WPs
into a single giant lane, discarding the parallel partition the
occurrence-map classification was built to produce. The disjoint check is
what lets bulk-edit WPs with non-overlapping file scopes stay in separate
lanes and run in parallel.&lt;/p&gt;
&lt;p&gt;It also keeps the lane dependency graph (&lt;code dir=&quot;auto&quot;&gt;lane_deps&lt;/code&gt;) well-formed. Lane
depth is computed by &lt;code dir=&quot;auto&quot;&gt;_compute_lane_depths&lt;/code&gt;, which treats a self-loop or
cycle as a best-effort depth-0 anchor rather than crashing — see
&lt;a href=&quot;/api/finalize-tasks-internals/#2-lane-depth-cycle-safety&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;finalize-tasks internals&lt;/code&gt;&lt;/a&gt;
for why that fallback exists and why it is &lt;em&gt;not&lt;/em&gt; a substitute for a clean
input graph. An over-aggressive surface-only merge across many
similarly-worded bulk-edit WPs is exactly the kind of input that could
otherwise produce a lane graph the depth function has to paper over instead
of compute correctly; skipping the merge when ownership is disjoint avoids
manufacturing that situation in the first place.&lt;/p&gt;
&lt;h2 id=&quot;re-finalizing-an-active-mission&quot;&gt;Re-finalizing an active Mission&lt;/h2&gt;
&lt;p&gt;Re-running &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent mission finalize-tasks --mission &amp;#x3C;handle&gt;&lt;/code&gt; on a Mission that already has a &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; is supported: you can amend work packages mid-execution and re-finalize. Lanes are recomputed, but &lt;strong&gt;a started work package keeps its recorded lane&lt;/strong&gt; (ADR &lt;a href=&quot;/adr/4.x/2026-10-04-2-started-work-package-lane-membership-is-frozen/&quot;&gt;4.x &lt;code dir=&quot;auto&quot;&gt;2026-10-04-2&lt;/code&gt;&lt;/a&gt;, #5573).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Why.&lt;/strong&gt; A started work package has commits on its lane branch and a &lt;a href=&quot;/context/topology/#lane-work-tip&quot;&gt;lane work tip&lt;/a&gt;. Moving it to another lane would strand that work: the next &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; on it fails with &lt;code dir=&quot;auto&quot;&gt;LANE_WORK_TIP_UNKNOWN&lt;/code&gt;, and a lane-mate could be bound to a branch that carries foreign commits.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;What counts as started.&lt;/strong&gt; A &lt;a href=&quot;/context/topology/#started-work-package&quot;&gt;started work package&lt;/a&gt; is one whose 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;. A later reset to &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;, or a cancellation, does not unstart it. As fallback evidence, a prior code lane with no such work package but a recorded lane work tip counts as wholly started.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;How lane ids are assigned on a re-finalize.&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;A group that contains started work packages takes their recorded lane id.&lt;/li&gt;
&lt;li&gt;Every other 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.&lt;/li&gt;
&lt;li&gt;A group that shares no member with any unused prior lane gets the next free lane id. Lane ids that held started work are never handed to a new group, for as long as a started work package is bound to the lane or its lane branch has a recorded lane work tip.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Started work packages recorded in the same lane are kept in one group even when their ownership no longer overlaps. An unstarted work package can still move: if an amendment makes a planned WP01 overlap an in-progress WP02, WP01 joins WP02’s lane.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;When finalize refuses.&lt;/strong&gt; If an amendment cannot keep every started work package on its recorded lane, &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; refuses with &lt;code dir=&quot;auto&quot;&gt;LANE_MEMBERSHIP_FROZEN&lt;/code&gt; before its first status write (no status event, no &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;, no commit; work package files it edited earlier in the run are restored). The cases are:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the amendment would put started work packages from two lanes into one lane;&lt;/li&gt;
&lt;li&gt;a started work package’s task file was removed without canceling it;&lt;/li&gt;
&lt;li&gt;a started work package changed &lt;code dir=&quot;auto&quot;&gt;execution_mode&lt;/code&gt;, so it would cross the &lt;code dir=&quot;auto&quot;&gt;lane-planning&lt;/code&gt; boundary;&lt;/li&gt;
&lt;li&gt;the status log or the recorded lane work tips cannot be read.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;--validate-only&lt;/code&gt; reports the same refusal, and its lane preview now shows the lane ids a real run would write. &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; Missions are not affected: their one repo-root lane has nothing to move. The JSON envelope and the remedy for each case are in &lt;a href=&quot;/api/finalize-tasks-internals/#5-started-work-packages-keep-their-lane-lane_membership_frozen&quot;&gt;finalize-tasks internals §5&lt;/a&gt;.&lt;/p&gt;
&lt;h2 id=&quot;see-also&quot;&gt;See Also&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/branch-target-routing/&quot;&gt;Branch-Target Routing&lt;/a&gt; — where each diff type lands, decided
per artifact kind (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/artifacts.py&lt;/code&gt;): planning + identity artifacts
(spec, plan, tasks, work-package files, &lt;code dir=&quot;auto&quot;&gt;data-model.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;) go to
the primary target branch for every topology; coordination-owned artifacts (status events,
&lt;code dir=&quot;auto&quot;&gt;acceptance-matrix.json&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;issue-matrix.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;analysis-report.md&lt;/code&gt;) go to the coordination
branch; code changes go to the lane branch; shared documentation and the merge target go
to the base branch. Also explains the simple-case flat-topology collapse when no
coordination branch or lane worktrees are configured.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;lane-specific-test-database-isolation-fr-006&quot;&gt;Lane-Specific Test Database Isolation (FR-006)&lt;/h2&gt;
&lt;p&gt;Two parallel SaaS / Django lanes used to share a single test database when their per-lane test runners booted concurrently, which produced flaky failures. Each lane workspace now exposes a lane-suffixed identifier via &lt;code dir=&quot;auto&quot;&gt;LaneWorkspaceResult.lane_test_env&lt;/code&gt;, which sets &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_TEST_DB_NAME=test_&amp;#x3C;safe-mission&gt;_&amp;#x3C;safe-lane&gt;&lt;/code&gt;. Test settings modules (Django and otherwise) should read that env var when constructing their per-lane test database name; the helpers &lt;code dir=&quot;auto&quot;&gt;lane_test_db_name()&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;lane_test_env()&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;specify_cli.lanes.lane_env&lt;/code&gt; are the canonical entry points and guarantee distinct DB names for distinct &lt;code dir=&quot;auto&quot;&gt;(mission_slug, lane_id)&lt;/code&gt; pairs. A composed name longer than 63 bytes (PostgreSQL’s identifier limit) is cut to 63 bytes ending in &lt;code dir=&quot;auto&quot;&gt;_&lt;/code&gt; plus an 8-character sha1 digest of the full name, so two long pairs never collapse into one database at the engine boundary (#3122).&lt;/p&gt;</content>
</entry>
