<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-01-29-15-merge-first-suggestion-for-completed-dependencies/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-01-29-15-merge-first-suggestion-for-completed-dependencies/</id>
  <title>Merge-First Suggestion for Completed Multi-Parent Dependencies</title>
  <updated>2026-01-29T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-01-29-15-merge-first-suggestion-for-completed-dependencies/"/>
  <summary>Detected that every declared parent was already finished and advised consolidating them first, instead of walking into predictable add/add conflicts.</summary>
  <content type="html">&lt;blockquote&gt;
&lt;p&gt;Superseded on 2026-04-05 by
&lt;code dir=&quot;auto&quot;&gt;2026-04-03-1-execution-lanes-own-worktrees-and-mission-branches.md&lt;/code&gt;.
The lane-only runtime no longer uses per-WP branch stacking, merge-first
implement guidance, or &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt; escape hatches in &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt;. Dependency
coupling is resolved by lane computation before execution starts.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;ADR-4 established auto-merge for multi-parent dependencies (e.g., WP04 depends on WP01, WP02, WP03). However, real-world testing (~/tmp Feature 001) revealed a problematic scenario:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;What happened:&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 style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;1. WP01, WP02, WP03 all completed (in &quot;done&quot; lane)&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. Each modified .gitignore independently&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 ran: spec-kitty implement 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;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;4. Auto-merge attempted: WP01 + 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 style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;5. FAILED: .gitignore add/add conflicts&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;6. Agent manually merged each WP to main&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;7. Then started WP04 from main&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;The pattern:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;When dependencies are &lt;strong&gt;in progress&lt;/strong&gt; (doing/for_review), auto-merge makes sense (combine work-in-progress)&lt;/li&gt;
&lt;li&gt;When dependencies are &lt;strong&gt;completed&lt;/strong&gt; (done lane), auto-merge is &lt;strong&gt;risky&lt;/strong&gt; (likely conflicts on shared files)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Question:&lt;/strong&gt; Should we detect when all multi-parent dependencies are complete and suggest merging them to main &lt;strong&gt;before&lt;/strong&gt; implementing the dependent WP?&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Conflict prevention&lt;/strong&gt; - Completed WPs likely modified shared files (.gitignore, package.json, etc.)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;User experience&lt;/strong&gt; - Agents got stuck with auto-merge failures (trial-and-error)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Workflow clarity&lt;/strong&gt; - Merge-first vs auto-merge have different use cases&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Agent guidance&lt;/strong&gt; - LLMs need explicit recommendations, not trial-and-error&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;ADR-4 enhancement&lt;/strong&gt; - Build on auto-merge, don’t replace it&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Backward compatibility&lt;/strong&gt; - Existing workflows must still work&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; Detect all-done and suggest merge-first (error + guidance)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Attempt auto-merge, fall back on conflict (reactive)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Always require manual merge for multi-parent (strict)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4:&lt;/strong&gt; Status quo (auto-merge always, user handles conflicts)&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: Detect all-done and suggest merge-first”, because:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Proactive (detects problem before attempting)&lt;/li&gt;
&lt;li&gt;Educational (explains why merge-first is safer)&lt;/li&gt;
&lt;li&gt;Flexible (—force override for auto-merge if needed)&lt;/li&gt;
&lt;li&gt;Agent-friendly (clear guidance, not trial-and-error)&lt;/li&gt;
&lt;li&gt;Prevents common failure mode (all-done + auto-merge = conflicts)&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;Proactive guidance&lt;/strong&gt; - Detects problem before attempting auto-merge&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Clear workflow&lt;/strong&gt; - Agent knows to run merge command first&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Conflict control&lt;/strong&gt; - Merge conflicts resolved in structured manner&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Prevents confusion&lt;/strong&gt; - No trial-and-error with auto-merge failures&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Explicit choice&lt;/strong&gt; - Agent can choose merge-first or —force auto-merge&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;ADR-4 enhancement&lt;/strong&gt; - Auto-merge still available for work-in-progress scenarios&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;Extra step&lt;/strong&gt; - Must run merge command before implement&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Two commands&lt;/strong&gt; - merge then implement (instead of one)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Code complexity&lt;/strong&gt; - Adds detection logic to implement command&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;User decision&lt;/strong&gt; - Agent must choose between merge-first and —force&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Detection trigger&lt;/strong&gt; - Multi-parent + all done → suggest merge&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Override mechanism&lt;/strong&gt; - —force flag bypasses suggestion&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Error message&lt;/strong&gt; - Blocks implement, suggests merge command&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Still automatic&lt;/strong&gt; - If not all done, auto-merge proceeds normally&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;We validated this decision by:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;✅ 7 tests for dependency detection logic&lt;/li&gt;
&lt;li&gt;✅ check_dependency_status() correctly identifies all-done scenarios&lt;/li&gt;
&lt;li&gt;✅ get_merge_strategy_recommendation() provides clear guidance&lt;/li&gt;
&lt;li&gt;✅ implement command blocks with actionable error message&lt;/li&gt;
&lt;li&gt;✅ ~/tmp WP04 scenario would now get clear guidance upfront&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-detect-all-done-and-suggest-merge-first-chosen&quot;&gt;Option 1: Detect all-done and suggest merge-first (CHOSEN)&lt;/h3&gt;
&lt;p&gt;Pre-flight check before auto-merge. If all dependencies done, error with suggestion.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Proactive detection (before failure)&lt;/li&gt;
&lt;li&gt;Clear guidance (suggests exact command)&lt;/li&gt;
&lt;li&gt;Explains trade-offs (merge-first vs auto-merge)&lt;/li&gt;
&lt;li&gt;Prevents common failure mode&lt;/li&gt;
&lt;li&gt;Agent-friendly (no trial-and-error)&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 step (two commands instead of one)&lt;/li&gt;
&lt;li&gt;Code complexity (detection logic)&lt;/li&gt;
&lt;li&gt;Requires —force to override&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-attempt-auto-merge-fall-back-on-conflict-status-quo&quot;&gt;Option 2: Attempt auto-merge, fall back on conflict (status quo)&lt;/h3&gt;
&lt;p&gt;Try auto-merge, if fails, guide user to manual merge.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Works for non-conflicting cases&lt;/li&gt;
&lt;li&gt;No pre-flight overhead&lt;/li&gt;
&lt;li&gt;Simpler code (no detection)&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;Reactive (fails first, then suggests)&lt;/li&gt;
&lt;li&gt;Trial-and-error experience&lt;/li&gt;
&lt;li&gt;Wastes time on predictable failures&lt;/li&gt;
&lt;li&gt;Confusing for agents (did it fail or not?)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-always-require-manual-merge&quot;&gt;Option 3: Always require manual merge&lt;/h3&gt;
&lt;p&gt;Block multi-parent entirely, force user to merge first.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No surprises (never attempts auto-merge)&lt;/li&gt;
&lt;li&gt;Explicit control over all merges&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;Loses auto-merge benefits for work-in-progress&lt;/li&gt;
&lt;li&gt;Too restrictive (many WPs could auto-merge cleanly)&lt;/li&gt;
&lt;li&gt;Breaks existing workflows&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-4-status-quo-auto-merge-always&quot;&gt;Option 4: Status quo (auto-merge always)&lt;/h3&gt;
&lt;p&gt;Always attempt auto-merge for multi-parent, let git handle it.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No changes needed&lt;/li&gt;
&lt;li&gt;Works for non-conflicting cases&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;Predictable failures (all-done + shared files = conflict)&lt;/li&gt;
&lt;li&gt;No guidance (agent stuck)&lt;/li&gt;
&lt;li&gt;Poor UX (trial-and-error)&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;Implementation:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/dependency_resolver.py&lt;/code&gt; (new module)
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;check_dependency_status()&lt;/code&gt; - Detects if all deps done&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;get_merge_strategy_recommendation()&lt;/code&gt; - Suggests workflow&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;predict_merge_conflicts()&lt;/code&gt; - Future: dry-run prediction&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/implement.py&lt;/code&gt; - Pre-flight check integration&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/software-dev/command-templates/tasks.md&lt;/code&gt; - Updated guidance&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Tests:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/integration/test_auto_merge_dependencies.py&lt;/code&gt; (7 tests)&lt;/li&gt;
&lt;li&gt;All scenarios validated: all-done, partial-done, single-parent, multi-parent&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Decision Logic:&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 style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;IF multi-parent AND all dependencies in &quot;done&quot; lane:&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;→ Suggest: spec-kitty merge --feature &amp;#x3C;slug&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;→ Block: Cannot proceed without --force&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;→ Explain: Merge-first avoids conflicts&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;ELSE IF multi-parent AND any dependency doing/for_review:&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;→ Proceed: Auto-merge (combine work-in-progress)&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;ELSE IF single-parent:&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;→ Suggest: Use --base flag&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;Related ADRs:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;ADR-4: Auto-Merge Multi-Parent Dependencies (original design)&lt;/li&gt;
&lt;li&gt;ADR-13: Target Branch Routing (status commits advance target, causing staleness)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Enhances:&lt;/strong&gt; ADR-4 (historical only)&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Superseded by:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;2026-04-03-1-execution-lanes-own-worktrees-and-mission-branches.md&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Version:&lt;/strong&gt; 0.13.8 improvement (agent guidance enhancement)&lt;/p&gt;</content>
</entry>
