<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/architecture/branch-target-routing/">
  <id>https://docs.spec-kitty.ai/architecture/branch-target-routing/</id>
  <title>Branch-Target Routing</title>
  <updated>2026-10-18T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/architecture/branch-target-routing/"/>
  <summary>Explanation of which git branch a mission&apos;s code, coordination surface, and base-level artifacts land on.</summary>
  <content type="html">&lt;span id=&quot;branch-target-routing&quot;&gt;&lt;/span&gt;
&lt;p&gt;When spec-kitty runs a mission with execution lanes, different categories of change land on
different &lt;strong&gt;branches&lt;/strong&gt;. This page explains the branch-level destinations — lane branch,
coordination branch, target/base branch — and the &lt;strong&gt;simple case&lt;/strong&gt;: what happens when there are
no lanes or coordination branches at all.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;This page is about branches, not artifact kinds.&lt;/strong&gt; Which &lt;code dir=&quot;auto&quot;&gt;MissionArtifactKind&lt;/code&gt; (spec, status
event, work-package task, …) resolves to which physical &lt;em&gt;tree&lt;/em&gt; is a separate, more granular
question, answered by &lt;a href=&quot;/architecture/artifact-placement-seam/&quot;&gt;The Artifact Placement Seam&lt;/a&gt;. That page also
holds the normative citations (ADR &lt;code dir=&quot;auto&quot;&gt;2026-06-24-1&lt;/code&gt;, ADR &lt;code dir=&quot;auto&quot;&gt;2026-07-23-1&lt;/code&gt;) for the placement rule
itself — this page does not restate them.&lt;/p&gt;
&lt;h2 id=&quot;why-branch-target-routing-exists&quot;&gt;Why branch-target routing exists&lt;/h2&gt;
&lt;p&gt;Before execution lanes, every change from every work package landed on the same branch. That
worked fine for sequential missions, but breaks down when two work packages run in parallel:
their changes would collide, producing merge conflicts on files neither WP was supposed to
touch.&lt;/p&gt;
&lt;p&gt;The model solves this by giving each category of change a &lt;strong&gt;dedicated landing branch&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Work-package code stays in an isolated &lt;strong&gt;lane branch&lt;/strong&gt; so two lanes never touch each other’s
files.&lt;/li&gt;
&lt;li&gt;Mission-wide bookkeeping (status events and the other coordination-owned artifacts) lands on
a shared &lt;strong&gt;coordination branch&lt;/strong&gt; so every lane can read it without checking out a different
branch.&lt;/li&gt;
&lt;li&gt;Everything else — planning artifacts, documentation, the final merge target — resolves to the
mission’s &lt;strong&gt;target branch&lt;/strong&gt; (its base, e.g. &lt;code dir=&quot;auto&quot;&gt;feat/my-mission&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;), so it is accessible
from any context without a coordination round-trip.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The destination is decided automatically; you do not choose a landing branch manually.&lt;/p&gt;
&lt;h2 id=&quot;the-three-branch-level-destinations&quot;&gt;The three branch-level destinations&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Lane branch&lt;/strong&gt; — the branch checked out inside a lane’s worktree. Only the work packages
assigned to that lane write code here. Lane branches are isolated from each other.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Coordination branch&lt;/strong&gt; — the shared visibility surface for a mission’s coordination-owned
bookkeeping (status events, acceptance/issue/analysis records, and the other kinds
&lt;a href=&quot;/architecture/artifact-placement-seam/#the-layer-table&quot;&gt;The Artifact Placement Seam&lt;/a&gt; classifies to that
partition). All lanes read from it, keeping mission-wide bookkeeping out of the lane branches.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;target branch&lt;/strong&gt; (the mission’s base, e.g. &lt;code dir=&quot;auto&quot;&gt;feat/my-mission&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;) — where planning
artifacts, shared documentation, and the eventual merge target resolve. Every lane can reach it
without a coordination round-trip.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;Which artifact kind is classified into which of these — and by what authority — is the
question &lt;a href=&quot;/architecture/artifact-placement-seam/&quot;&gt;The Artifact Placement Seam&lt;/a&gt; answers; this page names
only the three branch-level destinations themselves.&lt;/em&gt;&lt;/p&gt;
&lt;h2 id=&quot;upgrade-and-project-global-state&quot;&gt;Upgrade and project-global state&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; writes project-global state (&lt;code dir=&quot;auto&quot;&gt;.kittify/metadata.yaml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.gitattributes&lt;/code&gt;)
on the branch checked out in the repository root checkout, and in linked worktrees on
ordinary branches. It skips every
&lt;a href=&quot;/context/execution/#integrating-worktree&quot;&gt;integrating worktree&lt;/a&gt;: a worktree on a
&lt;code dir=&quot;auto&quot;&gt;kitty/mission-…&lt;/code&gt; mission, lane or coordination branch, or on a branch that cannot be read.
So an upgrade run from the repository root checkout adds no upgrade commit to a lane, mission
or coordination branch; a lane keeps its pre-upgrade copy until it is consolidated. Where a pre-fix upgrade already left
divergent copies, the integration sites resolve the generated &lt;code dir=&quot;auto&quot;&gt;.kittify/metadata.yaml&lt;/code&gt; to a
fixed side. See &lt;a href=&quot;/adr/4.x/2026-10-04-4-upgrade-writes-project-global-state-once/&quot;&gt;ADR 2026-10-04-4&lt;/a&gt;
and the &lt;a href=&quot;/operations/upgrade-with-live-lanes-recovery/&quot;&gt;recovery runbook&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;Op records are non-mission state too. Closing an Op commits its &lt;code dir=&quot;auto&quot;&gt;kitty-ops/&amp;#x3C;id&gt;.jsonl&lt;/code&gt; record, or the doctor sweep’s closure spine, onto the branch checked out in the repository root checkout. That branch-target routing applies only where the repository keeps Op records: the commit is skipped when the record matches an ignore rule, or when the primary branch tracks no Op record or cannot be shown to (an unresolved primary branch, a failed git probe) (#6410). See &lt;a href=&quot;/architecture/trail-model/&quot;&gt;the trail model&lt;/a&gt;.&lt;/p&gt;
&lt;h2 id=&quot;the-simple-case-flat-topology-no-lanes-no-coordination&quot;&gt;The simple case: flat topology (no lanes, no coordination)&lt;/h2&gt;
&lt;p&gt;When a mission has only one work package and no coordination branch is configured, every
category above resolves to the &lt;strong&gt;target branch&lt;/strong&gt;. There are no lane worktrees and no
coordination surface — spec-kitty runs exactly as it did before lanes were introduced.&lt;/p&gt;
&lt;p&gt;This is the &lt;strong&gt;all-base collapse&lt;/strong&gt;: code, coordination bookkeeping, planning artifacts, and
documentation all resolve to the same branch. The result is byte-identical to the
single-branch workflow from earlier versions of spec-kitty. No worktree directories are created
or read; no coordination branch is touched.&lt;/p&gt;
&lt;p&gt;The flat topology is not a special mode you activate — it is simply what happens when a mission
has no coordination branch or lane worktrees declared. If you are running a straightforward,
single-threaded mission, you are already in the simple case.&lt;/p&gt;
&lt;h2 id=&quot;relationship-to-execution-lanes&quot;&gt;Relationship to execution lanes&lt;/h2&gt;
&lt;p&gt;This page describes &lt;em&gt;which branch&lt;/em&gt; changes land on. The execution lanes model describes &lt;em&gt;how&lt;/em&gt;
work packages are grouped and run in parallel. These two concerns are complementary:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Execution lanes allocate work packages to lane branches.&lt;/li&gt;
&lt;li&gt;Branch-target routing ensures the coordination surface and target branch remain accessible to
all lanes simultaneously.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;See &lt;a href=&quot;/architecture/execution-lanes/&quot;&gt;Execution Lanes&lt;/a&gt; for how lanes are computed, how worktrees are
created, and how lane branches merge back to the mission branch.&lt;/p&gt;
&lt;p&gt;See &lt;a href=&quot;/architecture/git-worktrees/&quot;&gt;Git Worktrees Explained&lt;/a&gt; for the underlying git mechanism that makes
isolated lane workspaces possible.&lt;/p&gt;
&lt;p&gt;See &lt;a href=&quot;/architecture/artifact-placement-seam/&quot;&gt;The Artifact Placement Seam&lt;/a&gt; for how an individual artifact
&lt;em&gt;kind&lt;/em&gt; is classified to a physical tree — the layer model, the two composition roots, and the
compliance taxonomy for call sites that bypass the seam.&lt;/p&gt;</content>
</entry>
