<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/1.x/2026-01-26-9-worktree-cleanup-at-merge-not-eager/">
  <id>https://docs.spec-kitty.ai/adr/1.x/2026-01-26-9-worktree-cleanup-at-merge-not-eager/</id>
  <title>Worktree Cleanup at Merge, Not Eager</title>
  <updated>2026-01-26T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/1.x/2026-01-26-9-worktree-cleanup-at-merge-not-eager/"/>
  <summary>Rejected eager deletion of a finished dependency&apos;s worktree so parallel and diamond-shaped work stayed runnable; cleanup waited for lane consolidation.</summary>
  <content type="html">&lt;blockquote&gt;
&lt;p&gt;Superseded by &lt;code dir=&quot;auto&quot;&gt;../2.x/adr/2026-04-03-1-execution-lanes-own-worktrees-and-mission-branches.md&lt;/code&gt;.
This ADR assumed one worktree per work package. The current execution model
uses one worktree per execution lane and one mission integration branch.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;In the workspace-per-work-package model (0.11.0+), each WP gets an isolated worktree. When WP02 depends on WP01 and is created with &lt;code dir=&quot;auto&quot;&gt;spec-kitty implement WP02 --base WP01&lt;/code&gt;, a natural question arises: &lt;strong&gt;Why don’t we immediately delete WP01’s worktree since its branch is now a parent of WP02’s branch?&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;The appeal of “eager cleanup”:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Disk space&lt;/strong&gt;: Worktrees accumulate quickly with many WPs&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Mental model&lt;/strong&gt;: “WP01 is done, it’s merged into WP02, delete it”&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Simplicity&lt;/strong&gt;: Cleanup happens at creation time, not later&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;However, investigation reveals critical edge cases that make eager cleanup &lt;strong&gt;unsafe for parallel workflows&lt;/strong&gt;.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Git branches persist independently of worktrees (worktrees are just working directories)&lt;/li&gt;
&lt;li&gt;Parallel development patterns (multiple WPs depend on same base)&lt;/li&gt;
&lt;li&gt;Diamond dependency patterns (WP needs same base as sibling)&lt;/li&gt;
&lt;li&gt;Review rework scenarios (WP back to “planned” after dependent created)&lt;/li&gt;
&lt;li&gt;Current validation expects worktrees to exist&lt;/li&gt;
&lt;li&gt;Legacy file filtering kept worktrees small enough that disk pressure was not the primary risk&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option 1:&lt;/strong&gt; Keep current behavior (cleanup at merge) - CHOSEN&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Eager cleanup with safety checks (when dependent created)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Manual cleanup command (user-triggered)&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; “Option 1: Keep current behavior (cleanup at merge)”, because:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Parallel workflows are safe (multiple WPs can use same base simultaneously)&lt;/li&gt;
&lt;li&gt;Diamond dependencies work correctly (all deps available at creation time)&lt;/li&gt;
&lt;li&gt;Review rework doesn’t break workflows (worktree available if WP reopened)&lt;/li&gt;
&lt;li&gt;Current validation logic is correct (checks worktree existence)&lt;/li&gt;
&lt;li&gt;Worktrees were small enough that disk usage was not the primary concern&lt;/li&gt;
&lt;li&gt;Merge cleanup is automatic, safe, and default behavior&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Parallel development is safe&lt;/strong&gt;: WP02 and WP03 can both use WP01 as base simultaneously&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Diamond patterns work&lt;/strong&gt;: All dependencies available when WP04 needs WP02+WP03&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Review rework resilient&lt;/strong&gt;: If WP01 reopened after WP02 created, worktree still exists&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Validation logic correct&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;implement.py:640&lt;/code&gt; checks worktrees exist (not just branches)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No race conditions&lt;/strong&gt;: Multiple agents can create dependencies concurrently&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Automatic cleanup&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;spec-kitty merge&lt;/code&gt; handles cleanup by default&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Deterministic behavior&lt;/strong&gt;: Same deps → same results regardless of timing&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Disk usage&lt;/strong&gt;: Worktrees accumulate until merge (historically mitigated by filtered worktrees)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Mental model mismatch&lt;/strong&gt;: Users may think worktree unnecessary after dependent created&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No explicit feedback&lt;/strong&gt;: Users don’t see “worktree cleaned” during implement&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Worktrees were small in the legacy model because not every file surface was present in every workspace&lt;/li&gt;
&lt;li&gt;Merge cleanup happens automatically unless &lt;code dir=&quot;auto&quot;&gt;--no-cleanup&lt;/code&gt; specified&lt;/li&gt;
&lt;li&gt;Branches persist independently (worktree deletion doesn’t affect git history)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;We’ll validate this decision by:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No reports of parallel implementation failures due to missing worktrees&lt;/li&gt;
&lt;li&gt;Diamond dependency patterns complete successfully&lt;/li&gt;
&lt;li&gt;Review rework scenarios don’t require worktree recreation&lt;/li&gt;
&lt;li&gt;Disk usage remains manageable under the legacy model&lt;/li&gt;
&lt;li&gt;Users find merge cleanup behavior intuitive&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-1-keep-current-cleanup-at-merge&quot;&gt;Option 1: Keep Current (Cleanup at Merge)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Parallel workflows safe (WP02, WP03 both use WP01 simultaneously)&lt;/li&gt;
&lt;li&gt;Diamond deps work (all bases available at WP04 creation)&lt;/li&gt;
&lt;li&gt;Review rework resilient (WP01 worktree exists if reopened)&lt;/li&gt;
&lt;li&gt;Current validation correct (checks worktree not just branch)&lt;/li&gt;
&lt;li&gt;No race conditions (concurrent dependency creation safe)&lt;/li&gt;
&lt;li&gt;Automatic cleanup (merge handles by default)&lt;/li&gt;
&lt;li&gt;Simple implementation (no additional logic needed)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Worktrees accumulate until merge (disk usage)&lt;/li&gt;
&lt;li&gt;Mental model mismatch (seems wasteful to keep WP01)&lt;/li&gt;
&lt;li&gt;No explicit feedback during implement&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-eager-cleanup-with-safety-checks&quot;&gt;Option 2: Eager Cleanup with Safety Checks&lt;/h3&gt;
&lt;p&gt;Delete worktree when dependent created, with extensive validation.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Immediate disk reclamation&lt;/li&gt;
&lt;li&gt;Matches mental model (“WP01 done → delete”)&lt;/li&gt;
&lt;li&gt;Cleanup happens at natural boundary (dependent creation)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;BREAKS PARALLEL WORKFLOWS&lt;/strong&gt;: If WP02 deletes WP01, WP03 creation fails&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;BREAKS DIAMOND DEPS&lt;/strong&gt;: WP04 can’t validate WP01 exists (deleted by WP02)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;BREAKS REVIEW REWORK&lt;/strong&gt;: WP01 back to “planned” but worktree gone&lt;/li&gt;
&lt;li&gt;Requires extensive safety checks:
&lt;ul&gt;
&lt;li&gt;Lock mechanism for concurrent access&lt;/li&gt;
&lt;li&gt;Dependency graph traversal (check for other dependents)&lt;/li&gt;
&lt;li&gt;Inverse dependency tracking (who else needs this base?)&lt;/li&gt;
&lt;li&gt;Worktree recreation logic (if WP reopened)&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;Changes validation semantics (&lt;code dir=&quot;auto&quot;&gt;implement.py:640&lt;/code&gt; must check branches not worktrees)&lt;/li&gt;
&lt;li&gt;Race conditions (WP02, WP03 both check “no other deps” then delete)&lt;/li&gt;
&lt;li&gt;20+ new tests for edge cases&lt;/li&gt;
&lt;li&gt;Complex implementation vs minimal benefit&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Critical edge cases:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Parallel Development Race&lt;/strong&gt;:&lt;/li&gt;
&lt;/ol&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;plaintext&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;Timeline:&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;1. WP02 created with --base WP01 (deletes WP01 worktree)&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;2. WP03 tries to create with --base WP01&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;3. Validation fails: worktree doesn&apos;t exist&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;ol start=&quot;2&quot;&gt;
&lt;li&gt;&lt;strong&gt;Diamond Dependency&lt;/strong&gt;:&lt;/li&gt;
&lt;/ol&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;plaintext&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;WP01 → WP02 ─┐&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;→ WP03 ─┴→ WP04&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;/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;Timeline:&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;1. WP01 done&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;2. WP02 created (deletes WP01 worktree)&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;3. WP03 tries to create → FAIL (WP01 worktree missing)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;ol start=&quot;3&quot;&gt;
&lt;li&gt;&lt;strong&gt;Review Rework&lt;/strong&gt;:&lt;/li&gt;
&lt;/ol&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;plaintext&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;Timeline:&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;1. WP01 done → WP02 created (deletes WP01 worktree)&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;2. Reviewer finds bug in WP01 → back to &quot;planned&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 style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;3. Agent needs to implement WP01 → worktree missing&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;4. Must recreate worktree (complexity)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;option-3-manual-cleanup-command&quot;&gt;Option 3: Manual Cleanup Command&lt;/h3&gt;
&lt;p&gt;Provide &lt;code dir=&quot;auto&quot;&gt;spec-kitty cleanup-worktrees&lt;/code&gt; for user-triggered cleanup.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;User control over disk usage&lt;/li&gt;
&lt;li&gt;Can cleanup specific worktrees or all&lt;/li&gt;
&lt;li&gt;No automatic behavior (explicit intent)&lt;/li&gt;
&lt;li&gt;Safe (user decides when ready)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Extra command to learn and remember&lt;/li&gt;
&lt;li&gt;No automatic cleanup (relies on user discipline)&lt;/li&gt;
&lt;li&gt;Still accumulates worktrees (most users won’t use)&lt;/li&gt;
&lt;li&gt;Doesn’t solve disk usage problem (users forget)&lt;/li&gt;
&lt;li&gt;Additional implementation complexity&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;h3 id=&quot;implementation-summary&quot;&gt;Implementation Summary&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Current Behavior:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Worktrees created on-demand via &lt;code dir=&quot;auto&quot;&gt;spec-kitty implement WP##&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Worktrees persist throughout feature development&lt;/li&gt;
&lt;li&gt;Merge command cleans up all worktrees by default&lt;/li&gt;
&lt;li&gt;Cleanup can be skipped with &lt;code dir=&quot;auto&quot;&gt;--no-cleanup&lt;/code&gt; flag&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Validation Logic:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;implement.py:640-646&lt;/code&gt;: Validates worktree exists (not just branch)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;multi_parent_merge.py:94-111&lt;/code&gt;: Validates all dependency worktrees exist&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;dependency_graph.py&lt;/code&gt;: Tracks dependency relationships&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cleanup Logic:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;merge.py:334-377&lt;/code&gt;: Removes worktrees after successful merge&lt;/li&gt;
&lt;li&gt;Default behavior: cleanup enabled&lt;/li&gt;
&lt;li&gt;Optional: &lt;code dir=&quot;auto&quot;&gt;--no-cleanup&lt;/code&gt; preserves worktrees&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Worktree Size:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Sparse checkout excludes &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; (large directory)&lt;/li&gt;
&lt;li&gt;Typical worktree: ~1-10 MB (code only)&lt;/li&gt;
&lt;li&gt;Even with 10 WPs: ~100 MB total (negligible)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;code-references&quot;&gt;Code References&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/implement.py:640-646&lt;/code&gt; - Worktree validation (checks existence)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/merge.py:334-377&lt;/code&gt; - Cleanup logic (removes worktrees)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/multi_parent_merge.py:94-111&lt;/code&gt; - Multi-parent validation (needs all deps)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/dependency_graph.py&lt;/code&gt; - Dependency tracking (build graph)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/integration/test_parallel_implementation.py&lt;/code&gt; - Parallel workflow tests&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;related-decisions&quot;&gt;Related Decisions&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/adr/1.x/2026-01-23-2-explicit-base-branch-tracking/&quot;&gt;2026-01-23-2-explicit-base-branch-tracking&lt;/a&gt; - Stores base_branch in frontmatter&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/1.x/2026-01-23-4-auto-merge-multi-parent-dependencies/&quot;&gt;2026-01-23-4-auto-merge-multi-parent-dependencies&lt;/a&gt; - Multi-parent merge needs all dependency branches&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/1.x/2026-01-23-6-config-driven-agent-management/&quot;&gt;2026-01-23-6-config-driven-agent-management&lt;/a&gt; - Parallel agent execution patterns&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;why-current-behavior-is-correct&quot;&gt;Why Current Behavior is Correct&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Git Architecture:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Worktrees are working directories (filesystem concept)&lt;/li&gt;
&lt;li&gt;Branches are git refs (independent of worktrees)&lt;/li&gt;
&lt;li&gt;Deleting worktree doesn’t delete branch&lt;/li&gt;
&lt;li&gt;Branches persist and remain mergeable&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Validation Semantics:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Current code validates worktree existence (correct for parallel workflows)&lt;/li&gt;
&lt;li&gt;Changing to branch-only validation would miss parallel conflicts&lt;/li&gt;
&lt;li&gt;Example: WP02 and WP03 both use WP01 base (worktree needed until both done)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Parallel Workflow Example:&lt;/strong&gt;&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&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:#919F9F;--1:#5F636F&quot;&gt;# Agent A&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:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;implement&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP02&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--base&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP01&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &amp;#x26;  &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Starts, checks WP01 worktree ✓&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;/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:#919F9F;--1:#5F636F&quot;&gt;# Agent B (concurrent)&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:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;implement&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP03&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--base&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP01&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &amp;#x26;  &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Starts, checks WP01 worktree ✓&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;/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:#919F9F;--1:#5F636F&quot;&gt;# Both succeed because WP01 worktree exists&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:#919F9F;--1:#5F636F&quot;&gt;# If WP02 deleted WP01 worktree → WP03 would fail&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Diamond Workflow Example:&lt;/strong&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;plaintext&quot;&gt;&lt;code&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;WP01&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;WP02    WP03&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;WP04&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;/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;Timeline:&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;1. WP01 done&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;2. WP02, WP03 created in parallel (both use WP01 base)&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;3. WP04 created (needs both WP02 and WP03)&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;4. Validation checks all worktrees exist ✓&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;5. Merge cleans up all worktrees together&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;if-implementing-eager-cleanup-not-recommended&quot;&gt;If Implementing Eager Cleanup (Not Recommended)&lt;/h3&gt;
&lt;p&gt;Would require:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Change validation semantics&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;implement.py:640&lt;/code&gt;: Check branch exists (not worktree)&lt;/li&gt;
&lt;li&gt;Risk: Misses parallel conflicts&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Add safety checks&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Lock mechanism (prevent race conditions)&lt;/li&gt;
&lt;li&gt;Inverse dependency tracking (&lt;code dir=&quot;auto&quot;&gt;get_dependents()&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Check if other WPs need this base&lt;/li&gt;
&lt;li&gt;Only delete if no other WPs depend on it&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Handle race conditions&lt;/strong&gt;:&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&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;python&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:#919F9F;--1:#5F636F&quot;&gt;# Pseudocode for safety check&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:#C792EA;--1:#8844AE&quot;&gt;def&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;safe_to_delete_worktree&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;wp_id&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;feature_dir&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&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:#C792EA;--1:#8844AE&quot;&gt;with&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; worktree_lock:&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;dependents &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;get_all_dependents&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;wp_id&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:#C792EA;--1:#8844AE&quot;&gt;if&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;any&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;d.status &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;!=&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;done&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;for&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt; d &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;in&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt; dependents&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:#C792EA;--1:#8844AE&quot;&gt;return&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;False&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Other WPs still need this&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:#C792EA;--1:#8844AE&quot;&gt;return&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;True&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;ol start=&quot;4&quot;&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Recreate worktrees on rework&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;If WP back to “planned”, recreate worktree&lt;/li&gt;
&lt;li&gt;Additional complexity, error-prone&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Testing&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;20+ new tests for edge cases&lt;/li&gt;
&lt;li&gt;Parallel race condition tests&lt;/li&gt;
&lt;li&gt;Diamond dependency tests&lt;/li&gt;
&lt;li&gt;Review rework tests&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Estimated effort:&lt;/strong&gt; ~5-8 hours implementation + testing vs &lt;strong&gt;0 hours&lt;/strong&gt; for current behavior.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Benefit:&lt;/strong&gt; Minimal (the legacy model already kept worktrees small).&lt;/p&gt;
&lt;h3 id=&quot;disk-usage-analysis&quot;&gt;Disk Usage Analysis&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Sparse Checkout Configuration:&lt;/strong&gt;&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&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:#919F9F;--1:#5F636F&quot;&gt;# legacy filtered-worktree metadata file&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:#82AAFF;--1:#3B61B0&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:#7FDBCA;--1:#096E72&quot;&gt;!&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;/kitty-specs/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Typical Worktree Size:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Source code: ~1-5 MB&lt;/li&gt;
&lt;li&gt;Dependencies (node_modules, .venv): Usually sparse-checked out&lt;/li&gt;
&lt;li&gt;Total: ~1-10 MB per worktree&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Worst Case:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;20 WPs in parallel: ~200 MB&lt;/li&gt;
&lt;li&gt;Modern dev machine: 512 GB - 2 TB storage&lt;/li&gt;
&lt;li&gt;Percentage: 0.01% - 0.04% (negligible)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Conclusion:&lt;/strong&gt; Disk usage not a critical concern.&lt;/p&gt;</content>
</entry>
