Skip to content

Execution Lanes Own Worktrees and Mission Branches

Context and Problem Statement

Spec Kitty currently treats WorkPackage as both the planning/review unit and the git/worktree execution unit. That coupling is wrong.

WorkPackage is a planning artifact. It is useful for decomposition, review accounting, and acceptance scoping. A worktree is an execution-isolation mechanism. It is useful for preventing overlapping edits from colliding, keeping context warm for a coherent slice of work, and making integration predictable.

Feature 028-saas-active-projects-shell exposed the failure mode clearly:

  1. A correct landing-page implementation landed.
  2. Later work in another parallel execution branch touched overlapping dashboard files.
  3. A stale merge reintroduced old code.
  4. The feature was declared complete before the integrated mission branch actually satisfied the spec.

The problem was not “too much parallelism”. The problem was “parallel branches were created on the wrong boundary”. We need git isolation based on conflict and integration surfaces, not on planning-document boundaries.

Decision Drivers

  • Safe parallelism — parallel work should be enabled only where write scopes are materially disjoint.
  • Deterministic integration — the product should be validated on one integrated mission branch before merging to main.
  • Reduced stale-merge regressions — branches that overlap on the same surfaces must not drift independently for long periods.
  • Warm execution context — sequential work on the same surface should reuse the same branch/worktree.
  • Planner/runtime coherence — planning artifacts should express both dependency order and merge-risk boundaries.

Considered Options

  • Option 1: Continue with one worktree per work package
  • Option 2: One worktree per execution lane, with a mission integration branch
  • Option 3: One worktree per mission, even when work is safely parallelisable

Decision Outcome

Chosen option: Option 2, because it preserves useful parallelism while moving git isolation to the correct unit: the execution lane.

Core Decision

  1. WorkPackage remains the planning, review, and accounting unit.
  2. ExecutionLane becomes the git branch and worktree unit.
  3. Every active lane gets one long-lived branch and one worktree.
  4. Multiple sequential WPs may execute inside the same lane branch/worktree.
  5. Every mission gets one integration branch.
  6. Only the mission integration branch may merge to main.

Lane Computation Contract

The planner MUST emit a machine-readable lanes.json artifact after tasks are finalized.

Lane computation MUST consider both:

  1. the WP dependency DAG, and
  2. predicted write-scope / product-surface overlap.

Two WPs MUST be placed in the same lane when any of the following are true:

  1. one depends on the other,
  2. they share predicted file paths,
  3. they share predicted product surfaces,
  4. one is a cleanup/deprecation WP for a surface changed by the other,
  5. one is an integration/QA WP validating the other in integrated form.

The lane manifest is mandatory runtime input. implement, review, accept, and merge MUST fail closed when lanes.json is absent or malformed. There is no runtime fallback to per-WP worktrees, per-WP branches, or structure “detection” logic.

Branch Model

  1. Mission integration branch naming MUST follow: kitty/mission-<feature-slug>
  2. Lane branch naming MUST follow: kitty/mission-<feature-slug>-lane-<id>
  3. Lane branches merge into the mission integration branch continuously at stable checkpoints.
  4. main is updated only from the mission integration branch, never directly from a lane branch.
  5. When the planner computes exactly one lane, the feature gets exactly one worktree and one lane branch. Sequential DAGs are valid single-lane features, not a reason to recreate per-WP worktrees.

Stale-Lane Merge Guard

A lane branch MUST NOT merge into the mission integration branch when:

  1. the mission branch has advanced since the lane last synced, and
  2. the changed-file intersection between lane and mission branch is non-empty.

In that case, the lane MUST first rebase or merge mission-branch changes, then re-run review on the overlapping diff before merging.

Consequences

Positive

  • Parallelism is preserved where it is actually safe.
  • Sequential work on one surface stops paying the overhead of creating new branches/worktrees for every WP.
  • Mission integration becomes explicit instead of being an accidental side effect of a final merge.
  • Stale branch merges that reintroduce reverted code become blockable by policy, not just discoverable after damage.

Negative

  • Planner complexity increases because lane computation now needs conflict heuristics, not just dependency ordering.
  • Lane branches are longer-lived than transient task branches and therefore need better merge discipline.
  • Progress accounting becomes two-dimensional: WPs are still tracked, but lane state must also be visible.

Neutral

  • Existing WP review checkpoints remain valid; they now happen inside a lane rather than implying one branch per WP.
  • Cleanup WPs are no longer presumed independent. They inherit the lane of the surface they clean unless proven otherwise.

Confirmation

This decision is validated when all of the following are true:

  1. Planner output includes lanes.json for each mission.
  2. Missions with no safe parallelism produce exactly one lane and one worktree.
  3. Missions with safe disjoint work produce multiple lanes without overlapping write scopes.
  4. QA and final acceptance happen on the mission integration branch, not on a stale lane branch.
  5. Regressions of the Feature 028 class are blocked by stale-lane merge guards before they reach main.
  6. No shipped runtime command creates or merges .worktrees/<feature>-WP## worktrees or <feature>-WP## branches.

Pros and Cons of the Options

Option 1: One worktree per work package

Each WP gets its own branch and worktree regardless of write overlap.

Pros:

  • Simple mental model on paper.
  • Easy to explain if planning and execution boundaries are treated as identical.

Cons:

  • Wrong isolation boundary — overlapping surfaces still diverge independently.
  • Sequential WPs on the same surface pay repeated worktree and merge overhead.
  • Encourages QA to review non-integrated branch states.
  • Caused the stale-merge regression class seen in Feature 028.

Option 2: One worktree per execution lane

Use conflict-aware lanes as the execution unit and keep WPs as planning units.

Pros:

  • Aligns branch isolation with actual merge risk.
  • Preserves context for sequential work on one surface.
  • Makes integrated mission-branch QA the natural default.

Cons:

  • Requires new planner output and new scheduling/orchestration logic.
  • Lane boundaries must be explained and visualized clearly.

Option 3: One worktree per mission

All work for a mission happens in one branch/worktree, even if disjoint.

Pros:

  • Simplest branch topology.
  • No cross-lane merge risk inside a mission.

Cons:

  • Sacrifices legitimate parallelism.
  • Creates needless serial bottlenecks on disjoint surfaces.
  • Makes large missions slower and noisier than necessary.

More Information

Supersedes:

  • architecture/1.x/adr/2026-01-26-9-worktree-cleanup-at-merge-not-eager.md
  • 2026-01-29-15-merge-first-suggestion-for-completed-dependencies.md
  • 2026-01-30-18-auto-detect-merged-single-parent-dependencies.md

Related ADRs:

  • 2026-02-17-1-canonical-next-command-runtime-loop.md
  • 2026-04-03-2-review-approval-and-integration-completion-are-distinct.md
  • 2026-04-03-3-feature-acceptance-runs-on-the-integrated-mission-branch.md

Related Product Document:

  • Companion planning artifact: prd-lane-based-execution-and-feature-acceptance-gates-v1.md in the planning repo

Amendment 2026-11-06: lane branches are long-lived, lane checkouts belong to one workflow action

Status of this amendment: Proposed (2026-11-06). Operator ruling 5 of epic #7276 (DM 01M6QY3BFCGCA7CXE4TZ9W70WH, Mission lane-worktree-model-hardening-01M6QY1M): “Short-lived per-command lane checkouts: amend ADR 2026-04-03-1 now. Releasing a checkout commits or refuses.” Slice S3, #7279. The earlier text of this record is a snapshot and still says “feature” and “merge”; this amendment uses Mission and lane consolidation.

Core Decision 3 is amended. It read: “Every active lane gets one long-lived branch and one worktree.” It now reads:

  1. Every active lane gets one long-lived lane branch. A lane checkout (a worktree of that branch under .worktrees/) is held for one workflow action and released at its end.

Core Decision 4 follows: sequential work packages of one lane share its lane branch; each action gets its own checkout. The lane branch, not the checkout, carries the lane’s work: every gate reads the lane branch ref and the lane_head stamps, never a checkout (the for_review gate on the lane branch, Mission WP08). Lane consolidation and the Branch Model are unchanged.

What the amendment fixes, for the follow-up that builds it:

  • Acquire and release points. A checkout is acquired at the start of spec-kitty agent action implement <WP> and spec-kitty agent action review <WP>, and released at the end of that action: for implement, at the in_progress -> for_review hand-off; for review, at the verdict. No other command holds a lane checkout across its own exit.
  • Releasing commits or refuses. A release never discards work. Work in the checkout is committed by the action before release, or the release refuses and keeps the checkout, naming the paths. A release is a destructive operation under ADR 2026-11-06-1 (PR #7275, branch issue-7211-safe-landed-prune): O1, O2, O4 (with O6), O5, O7 and O8 apply as written. Only O3 does not arise, because a release never deletes the lane branch. O4 applies although the branch survives: removing the checkout drops its HEAD reflog, so a commit made in the checkout and then orphaned (commit --amend, reset, an aborted rebase) that only that reflog reaches is recorded under refs/spec-kitty/discarded/reflog/ before the removal, or the release refuses and keeps the checkout.
  • The lane tip is recorded before a guarded removal. The release writes refs/spec-kitty/lane-tip/<branch> (lanes/lane_tip.py) before the guard removes the checkout, so DESTROYED_LANE and LANE_WORK_TIP_UNKNOWN keep their evidence.
  • Attached checkouts. A lane checkout is created on the lane branch, attached, never detached, so the post-commit / post-rewrite lane-tip recorder hook fires on every commit made in it.
  • Re-entry. Work resumes with spec-kitty agent action implement <WP>, which acquires a fresh checkout of the existing lane branch (the route that finds the branch present and the worktree gone). A stale lane is refreshed by auto-rebase on re-entry (Mission assumption A-10). No manual cd .worktrees/... && git merge recipe is taught.
  • Harness working directories across turns. A checkout path is valid only for the action that printed it. A harness that keeps a working directory across turns re-runs the action command to get a checkout again, and must not write into a released path. A harness isolation worktree (one the harness creates for itself) is not a lane checkout and never a status surface.
  • The review lock lives outside the checkout. .spec-kitty/review-lock.json sits inside the lane worktree today (review/lock.py); a short-lived checkout would take the lock with it. The lock moves to a location that survives a release (for example under the git common dir), as part of the follow-up.
  • Auto-rebase without a held checkout. Auto-rebase (lanes/auto_rebase.py) merges inside a lane worktree today. With short-lived checkouts it runs inside the checkout the re-entry action acquires. A merge with no checkout at all (git merge-tree --write-tree, then a compare-and-swap ref update, git 2.38 or later) is a possible later optimisation for clean merges only; a conflicted merge always needs the action’s checkout.
  • Migration of existing checkouts. Existing long-lived lane worktrees stay valid. The first action that runs in one adopts it as acquired and releases it at its end. Idle ones are removed by consolidation’s final cleanup (ruling 6, slice S5) or by the spec-kitty doctor workspaces --prune backstop, under the same proofs; never with --force.

The one lane-checkout helper is the future lease acquire. Every lane checkout is created by one helper, open_lane_checkout (Mission WP09, lanes/lane_checkout.py), on every route: allocation, recovery, the lifecycle-sync recreate, the review checkout and the printed recreate command. It installs the lane-tip hook, the local excludes and the status exclusion. That helper is where the lease is acquired once leases exist.

The lease implementation is a follow-up Mission (Mission constraint C-007): lease state, the review-lock relocation and release-on-transition wiring are not built by Mission lane-worktree-model-hardening-01M6QY1M. Until that follow-up ships, lane checkouts keep today’s lifetime; what ships now is the single helper and the for_review gate on the lane branch, which together make the release safe to add.

Confirmation (replaces Confirmation item 2’s “exactly one lane and one worktree” with “exactly one lane branch, and a checkout only during an action”):

  • the for_review gate needs no lane checkout: tests/specify_cli/lanes/test_for_review_gate_parity.py (Mission WP08);
  • every lane checkout comes from the one helper, attached, with the hook and the exclusions: tests/architectural/test_lane_checkout_single_seam.py (with planted-violation self-tests) and tests/lanes/test_lane_checkout_helper.py (Mission WP09);
  • the release itself (commit or refuse, tip recorded before removal, a reflog-only commit in the checkout recorded under refs/spec-kitty/discarded/reflog/ before removal (O4, O6), review lock outside the checkout) is confirmed by the lease follow-up Mission’s own tests.