<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-09-26-2-lane-naming-keyed-on-creation-input/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-09-26-2-lane-naming-keyed-on-creation-input/</id>
  <title>ADR: Lane Naming Is Keyed on Creation Input, Never on Mission Identity</title>
  <updated>2026-09-26T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-09-26-2-lane-naming-keyed-on-creation-input/"/>
  <summary>Lane branch and worktree names come only from the slug and lane id recorded at creation; the Mission identity is never a naming input.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Lane branches and worktrees are &lt;strong&gt;created&lt;/strong&gt; from the Mission slug and lane id
alone (&lt;code dir=&quot;auto&quot;&gt;lanes/worktree_allocator.py::predict_lane_worktree&lt;/code&gt;, which calls
&lt;code dir=&quot;auto&quot;&gt;lane_branch_name(slug, lane_id)&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;worktree_path(..., mission_id=None, ...)&lt;/code&gt;). Before this mission, six &lt;em&gt;read&lt;/em&gt; sites re-derived a lane’s name using
the lanes manifest’s &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; instead of reusing the created name: the
reconciliation claim, pre-interrupt lane-tip capture, the pre-mutation safety
preflight, cleanup’s residue scan, the &lt;code dir=&quot;auto&quot;&gt;lifecycle_sync&lt;/code&gt; multi-candidate probe,
and acceptance’s lane source-root resolution.&lt;/p&gt;
&lt;p&gt;For a Mission whose slug-derived name and identity-derived name differ, this
produced four divergent shapes:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;a legacy &lt;code dir=&quot;auto&quot;&gt;NNN-slug&lt;/code&gt; Mission whose identity was backfilled after its lanes
were already created under the slug-only form;&lt;/li&gt;
&lt;li&gt;a slug that embeds a mid8 that differs from the Mission’s recorded
identity’s mid8;&lt;/li&gt;
&lt;li&gt;a lanes-manifest identity that is not a valid ULID, ≥ 8 characters (composed
a name creation never produced); and&lt;/li&gt;
&lt;li&gt;the same, &amp;#x3C; 8 characters (crashed inside &lt;code dir=&quot;auto&quot;&gt;_mid8&lt;/code&gt;).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty merge&lt;/code&gt; on any of these refused with “no approved lane resolved any
commits” — a message that named no branch and gave the operator nothing to
act on (issue #5108) — or crashed outright on the &amp;#x3C; 8 character shape.&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;Single canonical authority.&lt;/strong&gt; Exactly one decision may name a lane’s
branch and worktree, and it must be the same decision that creates them.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No probing (ADR &lt;a href=&quot;/adr/3.x/2026-07-01-1-no-legacy-compat-branches-in-resolvers/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-07-01-1&lt;/code&gt;&lt;/a&gt;).&lt;/strong&gt;
A read site may not fall back to trying several candidate names; a
degraded input is migrated or refused, never rescued by a second code path.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No manifest schema change.&lt;/strong&gt; The lanes manifest already stores what
creation needs (&lt;code dir=&quot;auto&quot;&gt;mission_slug&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;lane_id&lt;/code&gt;); no new per-lane name field
should be required to fix a divergence that already-created branches make
irrelevant.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Layer direction preserved.&lt;/strong&gt; The fix stays inside &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt;; no new
upward import and no growth of the shrink-only outbound ledgers.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Close the defect class by construction.&lt;/strong&gt; A future contributor must not
be able to reintroduce identity-aware lane naming by accident — the public
surface itself should make it inexpressible, backed by a gate.&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;A — Extend the existing creation-side authority&lt;/strong&gt; (chosen): remove the
identity parameter from the public lane-naming surface so the created name
is the only name any caller can compose, and reroute every read/match site
through it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;B — Persist per-lane branch names in the lanes manifest.&lt;/strong&gt; Rejected
(violates C-002): adds a schema field to carry information already
recomputable from data the manifest already holds.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;C — Move naming into a lower layer&lt;/strong&gt; (e.g. &lt;code dir=&quot;auto&quot;&gt;mission_runtime&lt;/code&gt; or
&lt;code dir=&quot;auto&quot;&gt;kernel&lt;/code&gt;). Rejected: lane naming is a &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt;-owned decision; moving
it down would grow the shrink-only outbound ledgers for no behavioral gain
and split one authority across two layers.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;D — Keep a private identity-aware composer&lt;/strong&gt; to satisfy any test or
caller that still wants an identity-derived name. Rejected: this is
exactly a second naming authority, and it is the thing FR-002 and C-004
forbid — it would keep the defect class alive under a different name.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;E — Probe candidate names at read time&lt;/strong&gt; (try the slug-only form, then
the identity-derived form, use whichever branch exists). Rejected by
C-004 / ADR &lt;code dir=&quot;auto&quot;&gt;2026-07-01-1&lt;/code&gt;: multi-candidate probing is the specific
anti-pattern that ADR forbids, and it would leave the ambiguity in place
for every future reader instead of resolving it once.&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: A.&lt;/strong&gt; The lane-naming authority is extended, not duplicated.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Signatures.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;lane_branch_name(mission_slug, lane_id, planning_base_branch=None)&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;worktree_dir_name(mission_slug, *, lane_id)&lt;/code&gt;
and &lt;code dir=&quot;auto&quot;&gt;worktree_path(repo_root, mission_slug, *, lane_id)&lt;/code&gt; no longer accept a
Mission-identity parameter. Their bodies are the pre-existing
&lt;code dir=&quot;auto&quot;&gt;mission_id is None&lt;/code&gt; branches, byte-identical. &lt;code dir=&quot;auto&quot;&gt;mission_branch_name&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;mission_branch_name_required&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;coord_branch_name&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;resolve_branch_name&lt;/code&gt; are unaffected — they name the Mission and
coordination branches, a distinct decision that still takes the identity.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;predict_lane_worktree&lt;/code&gt;&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;lanes/worktree_allocator.py&lt;/code&gt;) remains the
single placement decision every creation site calls.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Parsers, not probes.&lt;/strong&gt; Two additive parsers in &lt;code dir=&quot;auto&quot;&gt;lanes/branch_naming.py&lt;/code&gt;
replace ad-hoc name testing, never by testing whether a name exists on
disk or in git: &lt;code dir=&quot;auto&quot;&gt;parse_lane_worktree_dir&lt;/code&gt; recognizes a lane worktree
directory &lt;strong&gt;by shape alone&lt;/strong&gt; (a right-anchored match on the lane-id
grammar) — it is slug-free and never confirms that the recovered slug
names a real Mission; &lt;code dir=&quot;auto&quot;&gt;lane_id_for_worktree_dir&lt;/code&gt; recognizes &lt;strong&gt;by
recomposition&lt;/strong&gt; — it accepts a candidate only when re-composing it with
&lt;code dir=&quot;auto&quot;&gt;worktree_dir_name&lt;/code&gt; for the caller’s known Mission slug reproduces the
input byte-for-byte, which is what rejects the &lt;code dir=&quot;auto&quot;&gt;057-foo&lt;/code&gt; vs &lt;code dir=&quot;auto&quot;&gt;057-foobar&lt;/code&gt;
prefix trap. A caller that already knows the expected Mission slug must
use the recomposition form. &lt;code dir=&quot;auto&quot;&gt;is_lane_branch&lt;/code&gt; now also accepts the
plain-legacy grammar (&lt;code dir=&quot;auto&quot;&gt;kitty/mission-&amp;#x3C;slug&gt;-lane-&amp;#x3C;id&gt;&lt;/code&gt; with no numeric
prefix and no mid8). Every lane-id fragment (&lt;code dir=&quot;auto&quot;&gt;_LEGACY_LANE_RE&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;_PLAIN_LEGACY_LANE_RE&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_NEW_LANE_RE&lt;/code&gt;, and both new parsers) is built
from one private grammar fragment, &lt;code dir=&quot;auto&quot;&gt;_LANE_ID_RE = &quot;lane-[a-z]+&quot;&lt;/code&gt;, so there
is exactly one lane-id shape to keep in sync. This mission also widens
&lt;code dir=&quot;auto&quot;&gt;_LANE_ID_RE&lt;/code&gt; from the base branch’s single-letter &lt;code dir=&quot;auto&quot;&gt;lane-[a-z]&lt;/code&gt; to
&lt;code dir=&quot;auto&quot;&gt;lane-[a-z]+&lt;/code&gt;, so a multi-letter lane id (&lt;code dir=&quot;auto&quot;&gt;lane-aa&lt;/code&gt;) is recognized too —
a recognition-side change, not a minting-side one (see Residuals).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The reconciliation claim, pre-interrupt lane-tip capture, the
pre-mutation safety preflight, and post-merge cleanup&lt;/strong&gt; all resolve the
lane branch and worktree that creation actually produced. An approved,
non-canceled lane whose created branch does not exist in git now yields a
named refusal (the branch name appears in the message) instead of an empty,
generically reported commit set. The FOLD-3 git-probe-error tolerance is
unchanged.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The gate.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_worktree_name_guess.py&lt;/code&gt; is
extended with &lt;strong&gt;four&lt;/strong&gt; legs: a signature leg
(&lt;code dir=&quot;auto&quot;&gt;test_seam_signature_carries_no_mission_id&lt;/code&gt;, no &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; on the lane
surface), a compose leg (&lt;code dir=&quot;auto&quot;&gt;test_no_lane_name_compose_outside_authority&lt;/code&gt;, an
interpolated lane-token f-string composed outside the seam), a match leg
(&lt;code dir=&quot;auto&quot;&gt;test_no_lane_name_match_outside_authority&lt;/code&gt;,
regex/&lt;code dir=&quot;auto&quot;&gt;startswith&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;endswith&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;split&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;format&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;.join&lt;/code&gt;/etc. over lane
tokens), and a def-use leg
(&lt;code dir=&quot;auto&quot;&gt;test_no_lane_name_def_use_outside_authority&lt;/code&gt;, tracing every branch/path
argument that reaches a git mutation or lookup back to a naming-authority
call). Each leg carries its own shrink-only, capped allow-list
(&lt;code dir=&quot;auto&quot;&gt;_SIGNATURE_ALLOWLIST_FILES&lt;/code&gt; 0, &lt;code dir=&quot;auto&quot;&gt;_COMPOSE_ALLOWLIST_FILES&lt;/code&gt; 1,
&lt;code dir=&quot;auto&quot;&gt;_MATCH_ALLOWLIST_FILES&lt;/code&gt; 1, &lt;code dir=&quot;auto&quot;&gt;_DEF_USE_ALLOWLIST_FILES&lt;/code&gt; 1), combined into
one shared, file-qualified union (&lt;code dir=&quot;auto&quot;&gt;_NEW_LEG_ALLOWED&lt;/code&gt;) that every leg
consults — self-tested against injected offenders in each idiom.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Golden re-pin (the NFR-001 reading).&lt;/strong&gt; “Every golden describing a
&lt;em&gt;created&lt;/em&gt; name stays byte-identical” — not every golden that happens to
encode an identity-injected name. Lane and worktree golden rows that
encoded a name creation never produces (for example the row labelled
&lt;code dir=&quot;auto&quot;&gt;legacy-NNN-with-mid8-1589&lt;/code&gt; in the &lt;code dir=&quot;auto&quot;&gt;GOLDEN_ROWS&lt;/code&gt; tuple in
&lt;code dir=&quot;auto&quot;&gt;tests/lanes/test_branch_naming_seam.py&lt;/code&gt;, and several &lt;code dir=&quot;auto&quot;&gt;_PARITY_CASES&lt;/code&gt; rows
in &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/lanes/test_branch_naming_ssot_entrypoint.py&lt;/code&gt;) are
re-pinned to the created name, with new rows asserting that each divergent
shape composes that same created name. Mission-branch, coordination, and
Mission-dir golden columns are unchanged.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Mission-branch preservation on re-finalize (FR-011).&lt;/strong&gt; Re-finalizing
tasks keeps &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;’s recorded &lt;code dir=&quot;auto&quot;&gt;mission_branch&lt;/code&gt; byte-identical; only a
first-time finalize defines it. Consumers that used to recompose the
Mission branch from the identity when the manifest lacked a value now
prefer the recorded value first, and convert an invalid-identity failure
into a typed refusal (&lt;code dir=&quot;auto&quot;&gt;LaneComputationError&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;BranchIdentityUnresolved&lt;/code&gt;)
naming &lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate backfill-identity&lt;/code&gt; as the remedy, rather than
crashing.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Resume refusal on coordination topology (FR-005, H5).&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty merge --resume&lt;/code&gt; refuses, naming &lt;code dir=&quot;auto&quot;&gt;spec-kitty merge --abort&lt;/code&gt; as the remedy, when a
coordination-topology merge’s persisted pre-interrupt lane-tip record lacks
a tip for any non-canceled, non-planning lane under its created name. A
merge interrupted under a pre-mission release therefore cannot resume
silently under the armed guard — this is the intended upgrade behavior, not
a regression.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The reversal of the #1899 premise.&lt;/strong&gt; The naming gate’s own docstring
described the single canonical seam as composing every name “keyed on the
declared &lt;code dir=&quot;auto&quot;&gt;(slug, mission_id)&lt;/code&gt;”. That premise is reversed: the seam is now
keyed on &lt;code dir=&quot;auto&quot;&gt;(slug, lane_id)&lt;/code&gt; only for lanes: the Mission identity is not an
input to lane naming at all. Only Mission and coordination branch naming
still take the identity.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;residuals--follow-ups&quot;&gt;Residuals / Follow-ups&lt;/h2&gt;
&lt;p&gt;Recorded, not fixed here (ADJ-7 and the plan’s Risk 6):&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;kitty/mission-{slug}*&lt;/code&gt; recovery-enumeration prefix over-match (a
&lt;code dir=&quot;auto&quot;&gt;057-foo&lt;/code&gt; Mission’s enumeration also matches &lt;code dir=&quot;auto&quot;&gt;057-foobar&lt;/code&gt;) is a separate,
pre-existing defect, filed as a follow-up.&lt;/li&gt;
&lt;li&gt;A second lane-creation path exists in the review-workspace flow
(&lt;code dir=&quot;auto&quot;&gt;cli/commands/agent/workflow.py&lt;/code&gt;); it is naming-compliant today but was
not folded into the gate’s def-use leg, and is noted for a future audit.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;migration/mission_state.py&lt;/code&gt;’s rebuild path can construct lane state
without reading a prior manifest; whether that path can ever diverge from
the naming authority is unverified and left as a follow-up.&lt;/li&gt;
&lt;li&gt;The recognition-side grammar (&lt;code dir=&quot;auto&quot;&gt;_LANE_ID_RE = &quot;lane-[a-z]+&quot;&lt;/code&gt;) already
accepts multi-letter lane ids (e.g. &lt;code dir=&quot;auto&quot;&gt;lane-aa&lt;/code&gt;); the real ceiling is on the
minting side, &lt;code dir=&quot;auto&quot;&gt;lanes/compute.py::_next_free_lane_id&lt;/code&gt;, which walks
&lt;code dir=&quot;auto&quot;&gt;chr(letter)&lt;/code&gt; from &lt;code dir=&quot;auto&quot;&gt;&quot;a&quot;&lt;/code&gt; with no wraparound — after &lt;code dir=&quot;auto&quot;&gt;&quot;z&quot;&lt;/code&gt; it mints
&lt;code dir=&quot;auto&quot;&gt;&quot;lane-{&quot;&lt;/code&gt;, which no lane regex matches. No Mission has needed more than
26 lanes, but a minter fix (not a grammar change) would be required past
that ceiling.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;C-007 — legacy retirement tension (recorded, not decided).&lt;/strong&gt; This
mission keeps legacy (pre-3.2.x) Missions working, including the
numeric-prefix and plain-legacy lane grammars. Whether pre-3.2.x legacy
Mission support should be retired at all is tracked separately (see
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2463&quot;&gt;#2463&lt;/a&gt;) and is
explicitly not adjudicated by this ADR.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;links&quot;&gt;Links&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Spec: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/lane-branch-naming-authority-01M3EVC4/spec.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Plan: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/lane-branch-naming-authority-01M3EVC4/plan.md&lt;/code&gt; (PD-1
through PD-15)&lt;/li&gt;
&lt;li&gt;Issues: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5108&quot;&gt;#5108&lt;/a&gt;,
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5113&quot;&gt;#5113&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;No-probing ADR:
&lt;a href=&quot;/adr/3.x/2026-07-01-1-no-legacy-compat-branches-in-resolvers/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-07-01-1&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
