<?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-07-01-1-no-legacy-compat-branches-in-resolvers/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-07-01-1-no-legacy-compat-branches-in-resolvers/</id>
  <title>ADR: No Legacy-Compat Branches in Resolvers — Require Canonical Identity, Migrate Legacy</title>
  <updated>2026-07-01T00: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-07-01-1-no-legacy-compat-branches-in-resolvers/"/>
  <summary>Resolvers never grow a legacy branch to rescue degraded input: make the field nullable or migrate the data, and fix stale fixtures instead of the product.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;The mission-identity model (083+) mints a canonical ULID &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; for &lt;strong&gt;every&lt;/strong&gt;
mission at &lt;code dir=&quot;auto&quot;&gt;mission create&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; is the sole runtime identity for lookup,
locking, and routing. Pre-083 missions are the only artifacts that can lack one, and
the sanctioned remedy for them is a one-time migration (&lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate backfill-identity&lt;/code&gt;), audited by &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor identity&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;When a fix is provoked by an input that lacks its canonical field — most concretely a
mission with no &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; — there is a standing temptation to make that degraded
input “just work” by adding a branch inside a &lt;strong&gt;resolver&lt;/strong&gt; (identity resolution,
surface resolution, topology classification, mission-id resolution):&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;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:#D6DEEB;--1:#403F53&quot;&gt;mission_id &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; identity.mission_id &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;or&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; identity.mission_slug   &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# slug into a ULID field&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;# or&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;if&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; identity.mission_id &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;is&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;None&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;&amp;#x3C;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;legacy fallback path&lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;&gt;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Both shapes reintroduce exactly the split-brain the SSOT / dedup line of work is
removing (see the SSOT ADR family below). Each such branch is a &lt;em&gt;second&lt;/em&gt; code path for
the same operation, permanently: it must be carried, tested, and kept in sync forever,
and it silently accepts a non-canonical value (a slug, an empty id) where a canonical
one is contractually required — the #2138 defect class.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Motivating incident (PR #2277, reliability-papercut-sweep).&lt;/strong&gt; WP04 correctly made the
identity path &lt;em&gt;fail closed&lt;/em&gt; — &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; is a ULID or &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt;, never a slug. CI then
surfaced two failures in shards the per-WP reviews had not run: &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; output that would
not parse as JSON, and a lifecycle event that never queued to the SaaS outbox — both for
scaffolds lacking a canonical identity. The tempting, reflexive read was “WP04’s
fail-closed over-reached; add a &lt;code dir=&quot;auto&quot;&gt;mission_id is None&lt;/code&gt; branch to the resolver so the no-id
case works again.” That branch is the anti-pattern this ADR forbids, and the guardrail
was issued &lt;strong&gt;before&lt;/strong&gt; any fix was written.&lt;/p&gt;
&lt;p&gt;Steered by the guardrail toward &lt;em&gt;require-canonical + migrate&lt;/em&gt; (option 2 below), the
investigation then found the reflexive read was wrong: the two failures were &lt;strong&gt;not&lt;/strong&gt; a
WP04 regression at all. They reproduce identically on the base commit and pre-date this
mission (introduced by the #2263 non-persisting-identity change), and their root was
&lt;strong&gt;stale test fixtures&lt;/strong&gt; that never minted a project/mission identity. The correct fix was
to make the fixtures canonical-shaped — mint a real identity, exactly as &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt;
does — with &lt;strong&gt;zero product change and zero new resolver branch&lt;/strong&gt;. The principle both
prevented a wrong resolver fallback and produced the right fix.&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;SSOT / no split-brain.&lt;/strong&gt; One canonical path per operation; a legacy branch in a
resolver is a second authority for the same decision — the recurring N+1 bug family.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fail-closed on the canonical contract&lt;/strong&gt;, not fall-open to a degraded value. A
&lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; field must never hold a slug or an empty string.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Migration converts legacy once; a runtime branch carries it forever.&lt;/strong&gt; Cost belongs
at the one-time migration boundary, not in every hot resolver.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Realistic, canonical-shaped fixtures.&lt;/strong&gt; Test data should mirror production (every
mission has an id); an id-less fixture is not a supported runtime state to be
accommodated, it is stale test data.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Do not add a legacy / missing-canonical-field branch to a resolver to make a degraded
input succeed.&lt;/strong&gt; When a resolver or a path fronting it encounters a missing canonical
identity, resolve it in this preference order:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Remove an over-broad raise / make the field nullable&lt;/strong&gt; — &lt;em&gt;only&lt;/em&gt; when the failure is
an over-aggressive &lt;code dir=&quot;auto&quot;&gt;raise&lt;/code&gt; in a path that does not need the identity (e.g. an
observability, output, or event-emit path). Letting the &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; &lt;strong&gt;field&lt;/strong&gt; be
&lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt; is permitted; a nullable field is not a legacy branch and adds &lt;strong&gt;zero&lt;/strong&gt;
conditional logic to any resolver. The command must still run and the event must
still emit, carrying &lt;code dir=&quot;auto&quot;&gt;mission_id=None&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Require the canonical shape; fix the tests, not the product.&lt;/strong&gt; Update stale fixtures
to mint a realistic ULID &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; so they exercise the real canonical path. Where
a test genuinely models a pre-083 legacy mission, it must assert a &lt;strong&gt;clean,
structured fail-closed error that points to &lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate backfill-identity&lt;/code&gt;&lt;/strong&gt; —
never silent success, never an ugly empty-output crash. “Allow only canonical
identities + provide a migration” is an explicitly endorsed resolution.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Forbidden:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;if &amp;#x3C;canonical field&gt; is None: &amp;#x3C;legacy fallback&gt;&lt;/code&gt; (or the
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;field&gt; or &amp;#x3C;slug&gt;&lt;/code&gt; degrade) inside any resolver / surface-resolution /
identity-resolution / topology seam. If a fix appears to need this, choose option 2.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The distinction is &lt;strong&gt;where&lt;/strong&gt; the change lands: removing a raise or nulling a field in a
non-resolver path is fine; adding a conditional &lt;em&gt;inside a resolver&lt;/em&gt; to accept a
non-canonical identity is not.&lt;/p&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A — Runtime legacy-compat branch (rejected).&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;mission_id or slug&lt;/code&gt;, or an
&lt;code dir=&quot;auto&quot;&gt;is None&lt;/code&gt; fallback, in the resolver. Restores old behavior at the cost of a permanent
second path and a slug leaking into a ULID field. This is the defect, not the fix.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;B — Require canonical + migrate (chosen).&lt;/strong&gt; Fail closed on the contract; migrate
legacy once via the existing &lt;code dir=&quot;auto&quot;&gt;backfill-identity&lt;/code&gt;; keep fixtures canonical-shaped.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;C — Nullable field, no branch (chosen where applicable).&lt;/strong&gt; For paths that don’t need
the identity, stop raising and carry &lt;code dir=&quot;auto&quot;&gt;mission_id=None&lt;/code&gt;. Adds no resolver logic.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Positive:&lt;/strong&gt; resolvers stay single-path and handle-blind by contract; no slug ever
lands in a &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; field; the legacy cost is paid once at migration; fixtures
document the real (id-bearing) production shape.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Negative / cost:&lt;/strong&gt; pre-083 missions must be migrated before they run cleanly (by
design, with a clear error + command pointer); some stale fixtures must be updated to
mint an id.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Enforcement (follow-up):&lt;/strong&gt; the prohibition on option-3 branches is a candidate for
the AST call-site gate mechanism already used for resolution boundaries (see the
single-authority-seam ADR) — a gate that flags &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;field&gt; or &amp;#x3C;slug&gt;&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;if &amp;#x3C;id&gt; is None&lt;/code&gt; degrade patterns inside the resolver allowlist. Until then it is a
review-time invariant and a recorded operator directive.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;related&quot;&gt;Related&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/adr/3.x/2026-06-26-1-single-authority-seam-and-call-site-gate.md&lt;/code&gt; (resolution boundaries; AST call-site gate)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/adr/3.x/2026-06-22-1-mission-topology-ssot.md&lt;/code&gt; (topology single source of truth)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/adr/3.x/2026-06-07-1-execution-state-canonical-surface.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Mission Identity Model (083+); runbook &lt;code dir=&quot;auto&quot;&gt;docs/migrations/mission-id-canonical-identity.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Incident: PR #2277 (reliability-papercut-sweep) — guardrail issued against a resolver &lt;code dir=&quot;auto&quot;&gt;mission_id is None&lt;/code&gt; fallback; real root was pre-existing stale fixtures (#2263 non-persisting identity), fixed canonically. Defect class #2138 (slug-in-mission_id-field).&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
