<?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-13-target-branch-routing-for-status-commits/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-01-29-13-target-branch-routing-for-status-commits/</id>
  <title>Target Branch Routing for Status Commits</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-13-target-branch-routing-for-status-commits/"/>
  <summary>Replaced status commits hard-wired to main with an explicit target_branch recorded in meta.json, ending the silent divergence between the two release tracks.</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;.
&lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; remains the feature’s merge destination, but the runtime no
longer models implementation/status ancestry as “target branch plus one WP
branch”. Mission and lane branches now derive from the target branch instead.&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-12 established a two-branch strategy: &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; (1.x product) and &lt;code dir=&quot;auto&quot;&gt;2.x&lt;/code&gt; (SaaS product). However, spec-kitty’s status commit logic was &lt;strong&gt;hard-coded to commit to &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;&lt;/strong&gt;, causing race conditions and branch divergence for 2.x features.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Manifestation (Feature 025 on 2.x):&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;t=0: Feature 025 created, targets 2.x branch&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;t=1: WP01 implement creates branch from main (WRONG - should be 2.x)&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;t=2: Status commits go to main (WRONG - should be 2.x)&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;t=3: Implementation commits go to WP01 branch&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;t=4: 2.x advances with new commits (diverges from 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;t=5: Review fails: git merge-base --is-ancestor 2.x HEAD → FAIL&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;t=6: Manual rebase onto 2.x required&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;t=7: More status commits to main (race repeats)&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;Problem:&lt;/strong&gt; How do we route status commits (move-task, mark-status) to the correct target branch (main for 1.x features, 2.x for SaaS features) instead of hard-coding to main?&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;Dual-branch development&lt;/strong&gt; - Must support parallel 1.x and 2.x development (ADR-12)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Branch isolation&lt;/strong&gt; - Main and 2.x must not contaminate each other&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Race condition prevention&lt;/strong&gt; - Status commits must share ancestry with implementation commits&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Backward compatibility&lt;/strong&gt; - Existing features (pre-0.13.8) must continue working&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Explicit configuration&lt;/strong&gt; - Target branch should be visible in metadata (no magic)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Hotfix urgency&lt;/strong&gt; - Need minimal changes to ship quickly (defer full git state machine to 2.0)&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; Metadata-driven routing with &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; field in meta.json&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Git branch detection (infer target from current branch)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Environment variable (SPEC_KITTY_TARGET_BRANCH)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4:&lt;/strong&gt; Feature number convention (025+ → 2.x, 001-024 → main)&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: Metadata-driven routing with target_branch field”, because:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Explicit and visible in meta.json (debugging-friendly)&lt;/li&gt;
&lt;li&gt;Deterministic (same feature → same target)&lt;/li&gt;
&lt;li&gt;Flexible (can change per feature, not per number)&lt;/li&gt;
&lt;li&gt;Self-documenting (grep for “target_branch”: “2.x”)&lt;/li&gt;
&lt;li&gt;Supports future multi-branch scenarios (3.x, dev, staging)&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;Branch isolation maintained&lt;/strong&gt; - Main never sees 2.x status commits&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Race condition eliminated&lt;/strong&gt; - Status and implementation share target branch&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Explicit configuration&lt;/strong&gt; - Target visible in &lt;code dir=&quot;auto&quot;&gt;cat meta.json&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Backward compatible&lt;/strong&gt; - Legacy features default to “main”&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Debuggable&lt;/strong&gt; - Can grep for features by target: &lt;code dir=&quot;auto&quot;&gt;grep -r &apos;&quot;target_branch&quot;: &quot;2.x&quot;&apos;&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Flexible&lt;/strong&gt; - Can route any feature to any branch (not just 1.x/2.x)&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;Migration required&lt;/strong&gt; - Must add target_branch to existing features (m_0_13_8_target_branch)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Manual specification&lt;/strong&gt; - Users must set target_branch during feature creation&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Potential confusion&lt;/strong&gt; - Users might forget to set for 2.x features&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Not fully automated&lt;/strong&gt; - Could infer from branch, but chose explicit over implicit&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;Default to “main”&lt;/strong&gt; - Safe fallback for legacy features&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Detection function&lt;/strong&gt; - &lt;code dir=&quot;auto&quot;&gt;get_feature_target_branch(repo_root, feature_slug)&lt;/code&gt; → string&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Routing pattern&lt;/strong&gt; - Checkout target, commit, restore original branch&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;✅ 12 integration tests for dual-branch routing (all passing)&lt;/li&gt;
&lt;li&gt;✅ Feature 025 successfully developing on 2.x&lt;/li&gt;
&lt;li&gt;✅ Main branch completely isolated (zero 2.x commits)&lt;/li&gt;
&lt;li&gt;✅ git merge-base —is-ancestor checks passing&lt;/li&gt;
&lt;li&gt;✅ Migration adds target_branch to all existing features&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-metadata-driven-routing-chosen&quot;&gt;Option 1: Metadata-driven routing (CHOSEN)&lt;/h3&gt;
&lt;p&gt;Explicit &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; field in meta.json, read by status commands.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Explicit and visible (cat meta.json shows config)&lt;/li&gt;
&lt;li&gt;Deterministic (not environment-dependent)&lt;/li&gt;
&lt;li&gt;Self-documenting (grep finds features by target)&lt;/li&gt;
&lt;li&gt;Flexible (supports any branch name)&lt;/li&gt;
&lt;li&gt;Testable (can mock meta.json)&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;Requires migration (add field to existing features)&lt;/li&gt;
&lt;li&gt;Manual specification during feature creation&lt;/li&gt;
&lt;li&gt;Could forget to set for new features&lt;/li&gt;
&lt;li&gt;Adds to meta.json schema&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-git-branch-detection&quot;&gt;Option 2: Git branch detection&lt;/h3&gt;
&lt;p&gt;Infer target from current git branch (if on 2.x, route to 2.x).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No metadata changes required&lt;/li&gt;
&lt;li&gt;Automatic (no user input needed)&lt;/li&gt;
&lt;li&gt;Follows current context&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;Implicit and invisible (debugging hard)&lt;/li&gt;
&lt;li&gt;Environment-dependent (CWD affects behavior)&lt;/li&gt;
&lt;li&gt;Ambiguous (what if on feature branch?)&lt;/li&gt;
&lt;li&gt;Not self-documenting&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-environment-variable&quot;&gt;Option 3: Environment variable&lt;/h3&gt;
&lt;p&gt;Set &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_TARGET_BRANCH=2.x&lt;/code&gt; in environment.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Override capability&lt;/li&gt;
&lt;li&gt;No file changes&lt;/li&gt;
&lt;li&gt;Easy to test&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;Not persisted (lost on shell restart)&lt;/li&gt;
&lt;li&gt;Not visible in feature metadata&lt;/li&gt;
&lt;li&gt;Easy to forget or misconfigure&lt;/li&gt;
&lt;li&gt;Environment pollution&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-4-feature-number-convention&quot;&gt;Option 4: Feature number convention&lt;/h3&gt;
&lt;p&gt;Features 025+ automatically route to 2.x.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No configuration needed&lt;/li&gt;
&lt;li&gt;Clear convention&lt;/li&gt;
&lt;li&gt;Automatic&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;Magic number threshold (not explicit)&lt;/li&gt;
&lt;li&gt;Inflexible (what about 3.x?)&lt;/li&gt;
&lt;li&gt;Not self-documenting&lt;/li&gt;
&lt;li&gt;Assumes numeric ordering = product split&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/feature_detection.py::get_feature_target_branch()&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/tasks.py&lt;/code&gt; (lines 669-728: move_task routing)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/tasks.py&lt;/code&gt; (lines 839-887: mark_status routing)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/m_0_13_8_target_branch.py&lt;/code&gt;&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_dual_branch_status_routing.py&lt;/code&gt; (9 tests)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/integration/test_feature_025_workflow.py&lt;/code&gt; (3 tests)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/core/test_feature_detection.py::test_get_feature_target_branch_*&lt;/code&gt; (6 tests)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/upgrade/test_m_0_13_8_target_branch.py&lt;/code&gt; (11 tests)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Related ADRs:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;ADR-12: Two-Branch Strategy for SaaS Transformation (establishes need for dual-branch support)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Version:&lt;/strong&gt; 0.13.8 (hotfix enabling 2.x development)&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Supersedes:&lt;/strong&gt; None (new capability)&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Superseded by:&lt;/strong&gt; Will be replaced by full Git State Machine in 2.0 (Phase 2 plan deferred to 2.x branch)&lt;/p&gt;</content>
</entry>
