<?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-29-1-requirement-id-grammar-single-authority/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-09-29-1-requirement-id-grammar-single-authority/</id>
  <title>ADR: one requirement-ID grammar, one authority</title>
  <updated>2026-09-30T00: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-29-1-requirement-id-grammar-single-authority/"/>
  <summary>Accepted: every requirement-ID surface reads mission-scoped kinds through one shared grammar module, replacing six divergent parsers.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-09-29&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (owner), via the operator rulings recorded in
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/requirement-id-grammar-01M3NRCA/decisions/&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2991&quot;&gt;#2991&lt;/a&gt;
(the erasure defect), &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/3519&quot;&gt;#3519&lt;/a&gt;
part 2 (the invisible letter-suffixed requirement), and
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2066&quot;&gt;#2066&lt;/a&gt; (the undiagnosed
coverage failure) — Mission &lt;code dir=&quot;auto&quot;&gt;requirement-id-grammar-01M3NRCA&lt;/code&gt;.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Before this Mission, a requirement ID — &lt;code dir=&quot;auto&quot;&gt;FR-###&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;NFR-###&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;C-###&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;SC-###&lt;/code&gt;, each with
an optional letter suffix and an optional &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;mission-slug&gt;#&lt;/code&gt; qualifier — had no single
authority. &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt;’s SC-006 measured six separate definitions, four of them in scope for
this Mission’s consumers; the other two were deferred out of this Mission’s scope as frozen
divergences (orchestrator auto-mode scope deferral, Decision Moment
&lt;code dir=&quot;auto&quot;&gt;01M3P07HV88QNVVKP3E2W28VB6&lt;/code&gt;) and have since been migrated onto the grammar by
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5387&quot;&gt;#5387&lt;/a&gt; and
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5388&quot;&gt;#5388&lt;/a&gt; (see the amendment below). Each definition tokenised, canonicalised, or matched IDs on
its own regular expression, and they disagreed on kind coverage, digit width, suffix
handling, and qualifier syntax.&lt;/p&gt;
&lt;p&gt;That drift produced three concrete defects:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;#2991 (erasure):&lt;/strong&gt; a real &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; run could respell or drop an authored
&lt;code dir=&quot;auto&quot;&gt;requirement_refs&lt;/code&gt; list — the WP’s own citation of its requirements disappeared without a
trace.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;#3519 part 2 (invisible letter-suffixed requirement):&lt;/strong&gt; a declared, unmapped suffixed FR
(&lt;code dir=&quot;auto&quot;&gt;FR-006a&lt;/code&gt;) did not fail &lt;code dir=&quot;auto&quot;&gt;finalize-tasks --validate-only&lt;/code&gt;’s coverage gate, because the
runtime’s own pattern had no suffix support — a requirement could go completely unmapped
and unreported.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;#2066 (undiagnosed coverage failure):&lt;/strong&gt; the failure JSON carried no parsed spec-ID set,
so an operator debugging a rejected mapping could not see what the tool believed the spec
declared.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A fourth, structural risk (research R8): once refs are kept on disk rather than
respelled away, an &lt;strong&gt;all-or-nothing&lt;/strong&gt; rule — where one bad ref on a WP unmaps every valid
ref on that same WP — would silently discard coverage for correctly-cited requirements the
moment any other ref on the WP was malformed or foreign.&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; (&lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_044&lt;/code&gt;): one requirement-ID grammar, not six.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;“No authored ref disappears without a trace”&lt;/strong&gt; (spec Intent Summary): a rejected ref is
reported, never silently dropped or respelled.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Layering unchanged&lt;/strong&gt; (C-002): the grammar must be reachable from &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt; and from
the &lt;code dir=&quot;auto&quot;&gt;runtime&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;mission_runtime&lt;/code&gt; layers without inverting the enforced
&lt;code dir=&quot;auto&quot;&gt;kernel &amp;#x3C;- charter &amp;#x3C;- {glossary, runtime, mission_runtime} &amp;#x3C;- specify_cli&lt;/code&gt; chain.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;RE2-safe patterns&lt;/strong&gt; (C-005): no catastrophic-backtracking construct anywhere in the
grammar.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Upstream contract closed&lt;/strong&gt; (R7): the orchestrator-api &lt;code dir=&quot;auto&quot;&gt;upstream_contract.json&lt;/code&gt; schema is
not reopened by this Mission.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Grammar in &lt;code dir=&quot;auto&quot;&gt;kernel&lt;/code&gt;.&lt;/strong&gt; Rejected (R2): &lt;code dir=&quot;auto&quot;&gt;kernel&lt;/code&gt;’s own README admits only cross-package
infrastructure, and the runtime/&lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt; cores could not import a requirement-ID
grammar from there without inventing a new dependency direction anyway.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A mirror constant plus a parity test in each core.&lt;/strong&gt; Rejected (R3): this keeps a second
authority per consumer and trades “one shared module” for “N modules kept in sync by a
test”, exactly the shape that produced the six-definition drift in the first place.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Integer &lt;code dir=&quot;auto&quot;&gt;number&lt;/code&gt; digits field instead of a &lt;code dir=&quot;auto&quot;&gt;digits: str&lt;/code&gt;.&lt;/strong&gt; Rejected (R4): an integer
collapses &lt;code dir=&quot;auto&quot;&gt;C-1&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;C-001&lt;/code&gt; into the same value, losing the declared spelling’s
significant width.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Hyphen-joined qualifier (&lt;code dir=&quot;auto&quot;&gt;slug-FR-001&lt;/code&gt;).&lt;/strong&gt; Rejected (R4/R5): collides with an ordinary
prose compound such as &lt;code dir=&quot;auto&quot;&gt;FR-###-mandated&lt;/code&gt;, which must remain a non-match.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Path-style qualifier (&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;slug&gt;/ID&lt;/code&gt;).&lt;/strong&gt; Rejected (R5): collides with real file paths
appearing in spec/plan prose.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A check inside &lt;code dir=&quot;auto&quot;&gt;spec-commit&lt;/code&gt;.&lt;/strong&gt; Rejected (R6): &lt;code dir=&quot;auto&quot;&gt;spec-commit&lt;/code&gt; is a transport step: gating
there would block a legitimate work-in-progress commit that has not yet reached a valid
grammar state.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A new orchestrator-api error code for the setup-plan requirement-ID gate.&lt;/strong&gt; Rejected
(R7): would reopen &lt;code dir=&quot;auto&quot;&gt;upstream_contract.json&lt;/code&gt;’s schema before this Mission’s other
consumers had landed; the existing &lt;code dir=&quot;auto&quot;&gt;PLAN_SETUP_FAILED&lt;/code&gt; envelope with &lt;code dir=&quot;auto&quot;&gt;data.reason&lt;/code&gt; covers
it additively instead (see “Setup-plan gate and orchestrator-api parity” below).&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; a single shared grammar module,
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/requirement_mapping/grammar.py&lt;/code&gt;, injected by required argument into every
consumer, with a verdict table (FR-019) replacing the all-or-nothing rule.&lt;/p&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;h3 id=&quot;grammar-home&quot;&gt;Grammar home&lt;/h3&gt;
&lt;p&gt;The grammar lives at &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/requirement_mapping/grammar.py&lt;/code&gt;;
&lt;code dir=&quot;auto&quot;&gt;requirement_mapping&lt;/code&gt; became a package (&lt;code dir=&quot;auto&quot;&gt;__init__.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;grammar.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;lint.py&lt;/code&gt;) with no
import-path change for existing callers of the package’s re-exported names
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/requirement_mapping/__init__.py:15-48&lt;/code&gt;). Every requirement-ID-aware
surface — the planning hand-off, &lt;code dir=&quot;auto&quot;&gt;map-requirements&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; (including its
tasks.md fallback reader), the runtime readiness check, and the merge-cleanup retention
reader’s constraint-row check (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/consolidation/retention.py:10,70&lt;/code&gt;) — reads
IDs through this module and this module alone; the boundary is enforced by
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_requirement_id_grammar_single_source.py&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;requirementid-shape&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;RequirementId&lt;/code&gt; shape&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;RequirementId(kind, digits: str, suffix: str | None, mission: str | None)&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;grammar.py:123-135&lt;/code&gt;, frozen dataclass). Canonical form is &lt;code dir=&quot;auto&quot;&gt;KIND-digits[suffix]&lt;/code&gt;, kind
uppercase, digits verbatim (width significant — &lt;code dir=&quot;auto&quot;&gt;C-1&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;C-001&lt;/code&gt; are distinct), suffix
lowercase; the qualified form (&lt;code dir=&quot;auto&quot;&gt;__str__&lt;/code&gt;) renders &lt;code dir=&quot;auto&quot;&gt;mission#canonical&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;grammar.py:137-140&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;canonical&lt;/code&gt; property, &lt;code dir=&quot;auto&quot;&gt;:154-158&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;__str__&lt;/code&gt;).&lt;/p&gt;
&lt;h3 id=&quot;one-core-pattern&quot;&gt;One core pattern&lt;/h3&gt;
&lt;p&gt;Every pattern in the module is generated from one core kind alternation,
&lt;code dir=&quot;auto&quot;&gt;_KIND_ALT = &quot;FR|NFR|SC|C&quot;&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;grammar.py:74&lt;/code&gt;), matched case-insensitively
(&lt;code dir=&quot;auto&quot;&gt;_KIND_DIGITS&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;grammar.py:87&lt;/code&gt;). The default &lt;code dir=&quot;auto&quot;&gt;software-dev&lt;/code&gt; kind set remains
&lt;code dir=&quot;auto&quot;&gt;FR&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;NFR&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;C&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;SC&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;research&lt;/code&gt; adds &lt;code dir=&quot;auto&quot;&gt;DR&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;AR&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;QR&lt;/code&gt; through
&lt;code dir=&quot;auto&quot;&gt;grammar.kinds_for(mission_type)&lt;/code&gt;. Unknown types use the software-dev set.
All recognition patterns derive from this mission-scoped authority. Declared-shape scanning
(&lt;code dir=&quot;auto&quot;&gt;spec_scan=True&lt;/code&gt;) accepts only a lowercase suffix; ref-item matching
(&lt;code dir=&quot;auto&quot;&gt;spec_scan=False&lt;/code&gt;) is case-tolerant on the suffix (&lt;code dir=&quot;auto&quot;&gt;find_all&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;grammar.py:247-275&lt;/code&gt;;
Decision Moment &lt;code dir=&quot;auto&quot;&gt;01M3NRCVW5VPE1DC9J6G5F3RBC&lt;/code&gt;: accept the letter suffix, lowercase
canonical). The
C-001 architectural gate’s floor test asserts the one detectable site IS this named
constant (&lt;code dir=&quot;auto&quot;&gt;grammar.py:66-74&lt;/code&gt;).&lt;/p&gt;
&lt;h3 id=&quot;dotted-ids-are-dropped-not-truncated&quot;&gt;Dotted IDs are dropped, not truncated&lt;/h3&gt;
&lt;p&gt;A token immediately followed by a token-boundary &lt;code dir=&quot;auto&quot;&gt;-&amp;#x3C;alphanumeric&gt;&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;.&amp;#x3C;alphanumeric&gt;&lt;/code&gt;
is not an ID at all: &lt;code dir=&quot;auto&quot;&gt;is_compound_tail&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;grammar.py:202-222&lt;/code&gt;, backed by
&lt;code dir=&quot;auto&quot;&gt;_COMPOUND_TAIL&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;grammar.py:198&lt;/code&gt;) rejects the whole match. A dotted sub-requirement
id — &lt;code dir=&quot;auto&quot;&gt;FR-002.3&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;### FR-001.1 Title&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;**FR-004.1** x&lt;/code&gt; — is therefore DROPPED entirely
by both &lt;code dir=&quot;auto&quot;&gt;find_all&lt;/code&gt; and the declared-shape scan, not silently truncated to the
well-formed prefix (&lt;code dir=&quot;auto&quot;&gt;FR-002&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;FR-001&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;FR-004&lt;/code&gt;, folded from the earlier
truncate-to-parent behaviour): truncation would let a spec-scan/declared-id consumer
accept a token the setup-plan lint refuses as malformed (it reads the same
&lt;code dir=&quot;auto&quot;&gt;.&lt;/code&gt;-inclusive lead charset via &lt;code dir=&quot;auto&quot;&gt;MALFORMED_DECLARED_LEAD&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;grammar.py:330-337&lt;/code&gt;),
disagreeing about what the document declares. A sentence-final period is not a dotted
tail: &lt;code dir=&quot;auto&quot;&gt;.&lt;/code&gt; followed by whitespace or end-of-string (&lt;code dir=&quot;auto&quot;&gt;see FR-001.&lt;/code&gt;) leaves nothing
alphanumeric for the check to match, so it still yields &lt;code dir=&quot;auto&quot;&gt;FR-001&lt;/code&gt;. Verified directly
against this Mission’s tip: &lt;code dir=&quot;auto&quot;&gt;grammar.find_all(&quot;FR-002.3&quot;, spec_scan=False)&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;grammar.find_all(&quot;### FR-001.1 Title&quot;, spec_scan=False)&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;grammar.find_all(&quot;**FR-004.1** x&quot;, spec_scan=False)&lt;/code&gt; each return &lt;code dir=&quot;auto&quot;&gt;[]&lt;/code&gt;, while
&lt;code dir=&quot;auto&quot;&gt;grammar.find_all(&quot;see FR-001.&quot;, spec_scan=False)&lt;/code&gt; returns &lt;code dir=&quot;auto&quot;&gt;FR-001&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;qualified-citation&quot;&gt;Qualified citation&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;mission-slug&gt;#&amp;#x3C;ID&gt;&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_QUALIFIED_KIND_DIGITS&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;grammar.py:96&lt;/code&gt;; finder in &lt;code dir=&quot;auto&quot;&gt;find_all&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;grammar.py:247-275&lt;/code&gt;): never declared, never required, never flagged by the bare-prose
scan, never warned about at setup-plan, reported &lt;code dir=&quot;auto&quot;&gt;foreign_qualified&lt;/code&gt; when present in a
work package’s refs, and the qualifier itself is never resolved against anything local
(Decision Moment &lt;code dir=&quot;auto&quot;&gt;01M3NRD1N2PFH7MX82PH2D93PV&lt;/code&gt;: include the qualified foreign-citation
syntax). The bare-prose candidate helper &lt;code dir=&quot;auto&quot;&gt;_unqualified_unsuffixed_ids&lt;/code&gt; excludes any
qualified match (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/requirement_mapping/__init__.py:165-177&lt;/code&gt;, C-009),
consumed by the public &lt;code dir=&quot;auto&quot;&gt;find_bare_prose_requirement_ids&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;:270&lt;/code&gt;), and the setup-plan lint
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/requirement_mapping/lint.py&lt;/code&gt;) never treats a qualified citation as an
undeclared local ID.&lt;/p&gt;
&lt;h3 id=&quot;verdict-table-fr-019&quot;&gt;Verdict table (FR-019)&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;classify(raw, declared)&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;grammar.py:381-392&lt;/code&gt;) applies, in order: does not parse -&gt;
&lt;code dir=&quot;auto&quot;&gt;malformed&lt;/code&gt;; has a qualifier -&gt; &lt;code dir=&quot;auto&quot;&gt;foreign_qualified&lt;/code&gt; (never fails); not in &lt;code dir=&quot;auto&quot;&gt;declared&lt;/code&gt; by
canonical form -&gt; &lt;code dir=&quot;auto&quot;&gt;unknown_spec_id&lt;/code&gt;; otherwise &lt;code dir=&quot;auto&quot;&gt;Accepted&lt;/code&gt; (Decision Moment
&lt;code dir=&quot;auto&quot;&gt;01M3NSKBMEKR60XKRJSYQC41G3&lt;/code&gt;: malformed and unknown fail, foreign_qualified never
fails, a rejected ref never un-maps the WP’s valid refs).&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Reason&lt;/th&gt;&lt;th&gt;Fails the gate?&lt;/th&gt;&lt;th&gt;Example (placeholder)&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;malformed&lt;/code&gt;&lt;/td&gt;&lt;td&gt;yes&lt;/td&gt;&lt;td&gt;a token that does not full-match the grammar (e.g. an underscore where a hyphen is required)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;unknown_spec_id&lt;/code&gt;&lt;/td&gt;&lt;td&gt;yes (every kind, &lt;code dir=&quot;auto&quot;&gt;SC&lt;/code&gt; included)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;FR-###&lt;/code&gt; not present in the spec’s declared-ID set&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;foreign_qualified&lt;/code&gt;&lt;/td&gt;&lt;td&gt;never&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;mission-slug&gt;#FR-###&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;FAILING_REASONS = {malformed, unknown_spec_id}&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;grammar.py:358&lt;/code&gt;) is the shared set every
consumer classifies against — a &lt;code dir=&quot;auto&quot;&gt;foreign_qualified&lt;/code&gt; rejection is never counted as failing
anywhere. A rejected ref never un-maps a valid sibling: every consumer classifies &lt;strong&gt;per
ref&lt;/strong&gt;, not per WP.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/mission_finalize.py:1180-1197&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_classify_one_wp&lt;/code&gt;)
and &lt;code dir=&quot;auto&quot;&gt;:1201-1243&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_classify_wp_requirement_refs&lt;/code&gt;) — a WP is “missing” only when it has NO
accepted ref: a WP whose only refs are &lt;code dir=&quot;auto&quot;&gt;foreign_qualified&lt;/code&gt; is missing too (Decision
Moment &lt;code dir=&quot;auto&quot;&gt;01M3NYFZ1P6QBD2DX4DVDA323W&lt;/code&gt;), cited at &lt;code dir=&quot;auto&quot;&gt;:1214&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/tasks_map_requirements.py:538-564&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;_mr_classify_wp_refs&lt;/code&gt;) and &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/tasks_mapping_core.py:214-234&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;_classify_new_ref_offenders&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/runtime/next/runtime_bridge_cores.py:343-366&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_classify_wp_refs&lt;/code&gt;) — returns
&lt;code dir=&quot;auto&quot;&gt;(accepted, rejected)&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;rejected&lt;/code&gt; is populated only for &lt;code dir=&quot;auto&quot;&gt;FAILING_REASONS&lt;/code&gt; members, so a
&lt;code dir=&quot;auto&quot;&gt;foreign_qualified&lt;/code&gt; ref is dropped from the rejected list entirely while an accepted
sibling on the same WP survives regardless. The same missing-WP rule (Decision Moment
&lt;code dir=&quot;auto&quot;&gt;01M3NYFZ1P6QBD2DX4DVDA323W&lt;/code&gt;) is cited at &lt;code dir=&quot;auto&quot;&gt;:376&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;authored-refs-are-never-rewritten&quot;&gt;Authored refs are never rewritten&lt;/h3&gt;
&lt;p&gt;Decision Moment &lt;code dir=&quot;auto&quot;&gt;01M3NSKHE8T6TBKNFPSJ6BRD2G&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; never rewrites an existing
item; &lt;code dir=&quot;auto&quot;&gt;map-requirements&lt;/code&gt; writes added refs in canonical form, keeps existing items
byte-identical, and dedups by canonical form. &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt;’s bootstrap never rewrites
an authored &lt;code dir=&quot;auto&quot;&gt;requirement_refs&lt;/code&gt; list, whatever
the resolved/classified value looks like; its only write is a narrow populate-when-empty
one for the legacy tasks.md-fallback case
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/mission_finalize.py:1554-1619&lt;/code&gt;, guard at
&lt;code dir=&quot;auto&quot;&gt;:1615-1618&lt;/code&gt;). &lt;code dir=&quot;auto&quot;&gt;map-requirements&lt;/code&gt; is append-only: existing items are kept byte-identical
and in place, new refs are merged in canonical form, and duplicates are dropped by
canonical-form dedup (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/tasks_mapping_core.py:125&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;_dedup_key&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:136&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;_merge_refs&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:237-273&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;plan_mapping&lt;/code&gt;).&lt;/p&gt;
&lt;h3 id=&quot;map-requirements-input-tokenisation-and-stale-ref-reporting&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;map-requirements&lt;/code&gt; input tokenisation and stale-ref reporting&lt;/h3&gt;
&lt;p&gt;Both &lt;code dir=&quot;auto&quot;&gt;--refs&lt;/code&gt; (a space/comma-separated scalar) and &lt;code dir=&quot;auto&quot;&gt;--batch&lt;/code&gt; (a JSON &lt;code dir=&quot;auto&quot;&gt;{WP_ID: [refs]}&lt;/code&gt;
object) are tokenised through the shared &lt;code dir=&quot;auto&quot;&gt;grammar.tokenize_refs&lt;/code&gt; before classification —
&lt;code dir=&quot;auto&quot;&gt;_mr_build_new_mappings&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/tasks_map_requirements.py:239-270&lt;/code&gt;),
&lt;code dir=&quot;auto&quot;&gt;--batch&lt;/code&gt; at &lt;code dir=&quot;auto&quot;&gt;:259&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;--refs&lt;/code&gt; at &lt;code dir=&quot;auto&quot;&gt;:269&lt;/code&gt; — so neither input path re-splits or re-cases a
ref on its own. The pre-write gate (&lt;code dir=&quot;auto&quot;&gt;_mr_gate_offenders&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:430-475&lt;/code&gt;) and the post-write
stale gate (&lt;code dir=&quot;auto&quot;&gt;_mr_stale_gate&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:584-641&lt;/code&gt;) both classify through the same grammar verdict
table: a &lt;code dir=&quot;auto&quot;&gt;foreign_qualified&lt;/code&gt; ref is reported only in &lt;code dir=&quot;auto&quot;&gt;stale_ref_reasons&lt;/code&gt; (informational),
never in &lt;code dir=&quot;auto&quot;&gt;stale_refs&lt;/code&gt;, whose &lt;code dir=&quot;auto&quot;&gt;--replace to correct&lt;/code&gt; hint would otherwise invite deleting a
valid cross-mission citation, and a WP whose only stale refs are &lt;code dir=&quot;auto&quot;&gt;foreign_qualified&lt;/code&gt; never
sets the gate (&lt;code dir=&quot;auto&quot;&gt;:609-618&lt;/code&gt;). The unknown-ID refusal (&lt;code dir=&quot;auto&quot;&gt;_mr_gate_offenders&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:459-475&lt;/code&gt;) now
carries &lt;code dir=&quot;auto&quot;&gt;parsed_spec_ids&lt;/code&gt; alongside &lt;code dir=&quot;auto&quot;&gt;unknown_refs&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;:461,466&lt;/code&gt;), the same additive
diagnostic &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; carries — an operator debugging a rejected &lt;code dir=&quot;auto&quot;&gt;map-requirements&lt;/code&gt;
call sees the same “what does the tool believe the spec declares” answer #2066 asked for.&lt;/p&gt;
&lt;h3 id=&quot;sc-tracked-not-gating&quot;&gt;SC tracked, not gating&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;success_criteria_coverage&lt;/code&gt; is informational: an unreferenced declared SC never fails a run
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/mission_finalize.py:1275-1300&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;_build_success_criteria_coverage&lt;/code&gt;; Decision Moment &lt;code dir=&quot;auto&quot;&gt;01M3NRCRYFBC1QNN62EFGXDVBY&lt;/code&gt;: SC status
in the requirement graph is tracked, not gating). The prior “SC … dropped, not traced”
advisory warning is retired — &lt;code dir=&quot;auto&quot;&gt;find_discarded_sc_refs&lt;/code&gt; no longer exists anywhere in &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;diagnostics-parsed_spec_ids-and-rejected_requirement_refs&quot;&gt;Diagnostics: &lt;code dir=&quot;auto&quot;&gt;parsed_spec_ids&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;rejected_requirement_refs&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; reports both, additively, on the failure payload AND on the
&lt;code dir=&quot;auto&quot;&gt;--validate-only&lt;/code&gt;/real-run success payload alike
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/mission_finalize.py:1303-1328&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_build_requirement_diagnostics&lt;/code&gt;,
spread into success JSON at &lt;code dir=&quot;auto&quot;&gt;:2122&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;:3068&lt;/code&gt;).&lt;/p&gt;
&lt;h3 id=&quot;setup-plan-gate-and-orchestrator-api-parity&quot;&gt;Setup-plan gate and orchestrator-api parity&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;setup-plan&lt;/code&gt; refuses (exit 1) a spec.md that declares a malformed requirement ID
(Decision Moment &lt;code dir=&quot;auto&quot;&gt;01M3NRCYSGDJ3VDW6KJ2DVBWZF&lt;/code&gt;: block malformed declared ids, warn only on
prose citations): &lt;code dir=&quot;auto&quot;&gt;_evaluate_requirement_id_gate&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/mission_setup_plan.py:526-559&lt;/code&gt;) returns
&lt;code dir=&quot;auto&quot;&gt;error_code: SPEC_REQUIREMENT_IDS_INVALID&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;invalid_requirement_ids&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;:549,551&lt;/code&gt;),
via &lt;code dir=&quot;auto&quot;&gt;SetupPlanLocalOutcome(payload, 1, &quot;error&quot;)&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;:559&lt;/code&gt;). Prose suspects (unqualified,
unsuffixed FR/NFR/C tokens outside a declared position) are reported separately as
&lt;code dir=&quot;auto&quot;&gt;requirement_id_warnings&lt;/code&gt;, non-blocking (&lt;code dir=&quot;auto&quot;&gt;:996-1062&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_build_setup_plan_result&lt;/code&gt;). HTML
comments are blanked, position-preserving, before either scan sees the text
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/requirement_mapping/lint.py:190&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;grammar.blank_html_comments&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;orchestrator-api&lt;/code&gt;’s &lt;code dir=&quot;auto&quot;&gt;plan&lt;/code&gt; verb keeps its envelope in contract rather than leaking a newly
unregistered delegate code (Decision Moment &lt;code dir=&quot;auto&quot;&gt;01M3NSKEGC7QNXA1G3711AP77X&lt;/code&gt;: the envelope
keeps &lt;code dir=&quot;auto&quot;&gt;PLAN_SETUP_FAILED&lt;/code&gt;, the real reason travels in &lt;code dir=&quot;auto&quot;&gt;data&lt;/code&gt;, and the direct setup-plan JSON
still uses the typed &lt;code dir=&quot;auto&quot;&gt;SPEC_REQUIREMENT_IDS_INVALID&lt;/code&gt; code): &lt;code dir=&quot;auto&quot;&gt;_plan_contract_error&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/orchestrator_api/commands.py:497-516&lt;/code&gt;) degrades an unregistered code (for
example &lt;code dir=&quot;auto&quot;&gt;SPEC_REQUIREMENT_IDS_INVALID&lt;/code&gt;) to the already-registered &lt;code dir=&quot;auto&quot;&gt;PLAN_SETUP_FAILED&lt;/code&gt;, with
the real code preserved as &lt;code dir=&quot;auto&quot;&gt;data.reason&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;:516&lt;/code&gt;); a registered code passes through
unchanged. The shared &lt;code dir=&quot;auto&quot;&gt;_classify_delegate_error&lt;/code&gt; helper and
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/upstream_contract.json&lt;/code&gt; are unchanged by this Mission —
&lt;code dir=&quot;auto&quot;&gt;git diff 0ec391f39c..HEAD -- src/specify_cli/core/upstream_contract.json&lt;/code&gt; is empty
(&lt;code dir=&quot;auto&quot;&gt;0ec391f39c&lt;/code&gt; is the Mission’s last planning commit).&lt;/p&gt;
&lt;h3 id=&quot;runtime-injection&quot;&gt;Runtime injection&lt;/h3&gt;
&lt;p&gt;The runtime cores take the grammar by &lt;strong&gt;required&lt;/strong&gt; dependency injection, never a local
fallback pattern: &lt;code dir=&quot;auto&quot;&gt;RequirementGrammarLike(Protocol)&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/runtime/next/runtime_bridge_cores.py:298-317&lt;/code&gt;) declares only the members the cores
call, satisfied structurally by the real &lt;code dir=&quot;auto&quot;&gt;specify_cli.requirement_mapping.grammar&lt;/code&gt; module;
&lt;code dir=&quot;auto&quot;&gt;RequirementMappingFacts.grammar: RequirementGrammarLike&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;:327-340&lt;/code&gt;) has no default. The
supplier call site passes the real module in: &lt;code dir=&quot;auto&quot;&gt;_cores.RequirementMappingFacts(..., grammar=grammar, ...)&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/runtime/next/runtime_bridge.py:1105-1111&lt;/code&gt;).&lt;/p&gt;
&lt;h3 id=&quot;c-001-gate-and-frozen-divergences&quot;&gt;C-001 gate and frozen divergences&lt;/h3&gt;
&lt;p&gt;The single-source architectural gate
(&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_requirement_id_grammar_single_source.py&lt;/code&gt;) AST-scans &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; for a
second requirement-ID kind-alternation literal, against a shrink-only allowlist
(&lt;code dir=&quot;auto&quot;&gt;tests/architectural/requirement_id_pattern_allowlist.yaml&lt;/code&gt;) whose &lt;code dir=&quot;auto&quot;&gt;baseline&lt;/code&gt; is checked
two-sided against the file’s own entry count. At this Mission’s tip, &lt;code dir=&quot;auto&quot;&gt;baseline: 2&lt;/code&gt;, exactly
the two frozen divergences below; an earlier transitional third entry
(&lt;code dir=&quot;auto&quot;&gt;runtime_bridge_cores.py&lt;/code&gt;’s own local pattern) was removed by WP04 once the cores took the
grammar as an injected, required argument, lowering the baseline from 3 to 2 in that same
edit.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/_substantive.py&lt;/code&gt;, constant &lt;code dir=&quot;auto&quot;&gt;_FR_TABLE_ROW&lt;/code&gt; — the setup-plan
substantive-spec gate’s own functional-requirement table-row pattern, a cheap structural
heuristic independent of the grammar’s full ID space (SC, suffixes, qualifiers). Follow-up ticket: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5387&quot;&gt;#5387&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/retrospective/generator.py&lt;/code&gt;, constant &lt;code dir=&quot;auto&quot;&gt;_FR_REF_RE&lt;/code&gt; — the retrospective
generator’s narrower, retrospective-specific FR-only scan (3+ digit FRs, no NFR/C/SC, no
suffix or qualifier), predating this Mission. Follow-up ticket: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5388&quot;&gt;#5388&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Provenance correction (2026-09-30).&lt;/strong&gt; An earlier revision of this ADR attributed both
frozen divergences to a HiC ruling. That was wrong. They came from a scope deferral the
orchestrator made in auto mode (Decision Moment &lt;code dir=&quot;auto&quot;&gt;01M3P07HV88QNVVKP3E2W28VB6&lt;/code&gt;: “outside
every issue’s scope and locality forbids migrating it in-mission”). The only HiC ruling
(Decision Moment &lt;code dir=&quot;auto&quot;&gt;01M3P2HXKASQY2ZKSEY3MAWA9H&lt;/code&gt;) decided one thing: migrate
&lt;code dir=&quot;auto&quot;&gt;consolidation/retention.py&lt;/code&gt; in-mission rather than freeze it. No human ruled that the two
remaining patterns must stay separate by design.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/consolidation/retention.py&lt;/code&gt; is &lt;strong&gt;not&lt;/strong&gt; a divergence: WP01 migrated its
constraint-row check onto &lt;code dir=&quot;auto&quot;&gt;grammar.parse&lt;/code&gt; in this Mission
(&lt;code dir=&quot;auto&quot;&gt;consolidation/retention.py:10,70&lt;/code&gt;), per that HiC ruling.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Amendment 2026-09-30 (#5387, #5388): both divergences drained, &lt;code dir=&quot;auto&quot;&gt;baseline: 0&lt;/code&gt;.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The setup-plan substantive-spec gate (&lt;code dir=&quot;auto&quot;&gt;missions/_substantive.py&lt;/code&gt;) now counts a
functional-requirement row only when its lead is a local FR id in a grammar-declared shape
(&lt;code dir=&quot;auto&quot;&gt;grammar.DECLARED_TABLE_ROW&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;grammar.DECLARED_LIST_ITEM&lt;/code&gt;, both named out of
&lt;code dir=&quot;auto&quot;&gt;DECLARED_SHAPE_PATTERNS&lt;/code&gt;), with HTML comments blanked as the declared-id scan does. A
spec whose FRs are all letter-suffixed (&lt;code dir=&quot;auto&quot;&gt;FR-006a&lt;/code&gt;) or wider than three digits (&lt;code dir=&quot;auto&quot;&gt;FR-1001&lt;/code&gt;)
is no longer judged “not substantive”.&lt;/li&gt;
&lt;li&gt;The retrospective generator (&lt;code dir=&quot;auto&quot;&gt;retrospective/generator.py&lt;/code&gt;) takes this spec’s FRs from
&lt;code dir=&quot;auto&quot;&gt;parse_requirement_ids_from_spec_md(...)[&quot;functional&quot;]&lt;/code&gt; and judges every WP-file citation
with &lt;code dir=&quot;auto&quot;&gt;grammar.classify&lt;/code&gt; against that set. A prose citation of another mission’s FR is no
longer reported as an uncovered requirement, a suffixed FR is no longer invisible, and a
foreign-qualified citation (&lt;code dir=&quot;auto&quot;&gt;other-mission#FR-001&lt;/code&gt;) no longer covers a local FR.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;known-residuals&quot;&gt;Known residuals&lt;/h3&gt;
&lt;p&gt;Six accepted, honestly-recorded low residuals (WP01 review; see
&lt;code dir=&quot;auto&quot;&gt;traces/design-decisions.md:23-24&lt;/code&gt; for the original acceptance of the first four, and the
pre-PR review fold for the last two) remain live at this Mission’s tip:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;The C-001 literal gate cannot see a runtime-joined alternation.&lt;/strong&gt; The architectural
gate (&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_requirement_id_grammar_single_source.py&lt;/code&gt;) walks only
&lt;code dir=&quot;auto&quot;&gt;ast.Constant&lt;/code&gt; string nodes, including &lt;code dir=&quot;auto&quot;&gt;JoinedStr&lt;/code&gt; f-string parts, EXCEPT docstrings
(&lt;code dir=&quot;auto&quot;&gt;:23-24&lt;/code&gt;); it never visits a &lt;code dir=&quot;auto&quot;&gt;Call&lt;/code&gt; node, so a kind alternation assembled at runtime
(for example via &lt;code dir=&quot;auto&quot;&gt;&quot;|&quot;.join([...])&lt;/code&gt;) is invisible to it (&lt;code dir=&quot;auto&quot;&gt;:281&lt;/code&gt; gates on
&lt;code dir=&quot;auto&quot;&gt;isinstance(node, ast.Constant)&lt;/code&gt;). The grammar’s own core literal is a detectable
constant asserted by name, so copying the idiom is caught; deliberate obfuscation of a
second authority stays a review concern, not a gate one.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A truncated slug parses as foreign with the wrong slug, never as local.&lt;/strong&gt; A qualifier
missing its own token boundary — &lt;code dir=&quot;auto&quot;&gt;foo/bar#FR-001&lt;/code&gt; — captures only the trailing &lt;code dir=&quot;auto&quot;&gt;bar&lt;/code&gt; as
the mission slug (&lt;code dir=&quot;auto&quot;&gt;_SLUG&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;grammar.py:83&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;_QUALIFIED_KIND_DIGITS&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:96&lt;/code&gt;), so
&lt;code dir=&quot;auto&quot;&gt;grammar.find_all(&quot;foo/bar#FR-001&quot;, spec_scan=False)&lt;/code&gt; returns a &lt;code dir=&quot;auto&quot;&gt;foreign&lt;/code&gt; id with
&lt;code dir=&quot;auto&quot;&gt;mission=&quot;bar&quot;&lt;/code&gt; — never a local &lt;code dir=&quot;auto&quot;&gt;FR-001&lt;/code&gt;. Verified directly against this Mission’s tip.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;issue #FR-003&lt;/code&gt; is dropped entirely.&lt;/strong&gt; A &lt;code dir=&quot;auto&quot;&gt;#&lt;/code&gt; immediately preceding a kind-digits token
with no valid slug before it (the qualifier attempt backs off to zero-width) is treated
as a leaked/truncated qualifier and the whole match is discarded, not read as local
&lt;code dir=&quot;auto&quot;&gt;FR-003&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_has_invalid_qualifier_prefix&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;grammar.py:225&lt;/code&gt;, checked against
&lt;code dir=&quot;auto&quot;&gt;_INVALID_QUALIFIER_LEAD&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:199&lt;/code&gt;). Verified directly:
&lt;code dir=&quot;auto&quot;&gt;grammar.find_all(&quot;issue #FR-003&quot;, spec_scan=False)&lt;/code&gt; returns &lt;code dir=&quot;auto&quot;&gt;[]&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;An ID declared only inside an HTML comment is no longer declared.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;_declared_ids&lt;/code&gt;
blanks every &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;!-- ... --&gt;&lt;/code&gt; span, position-preserving, before scanning for declared
shapes (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/requirement_mapping/__init__.py:125,147&lt;/code&gt;, calling
&lt;code dir=&quot;auto&quot;&gt;grammar.blank_html_comments&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;grammar.py:352&lt;/code&gt;). This is an intended behaviour change
from the pre-Mission scanner, pinned by tests; WP08’s corpus scan reports affected
specs. Listed here and under &lt;code dir=&quot;auto&quot;&gt;#### Negative&lt;/code&gt; below, not silently absorbed into the
general “re-finalizing may newly fail” bullet.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;An unterminated &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;!--&lt;/code&gt; blanks the rest of the spec.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;blank_html_comments&lt;/code&gt; has no
terminated/unterminated distinction for scanning purposes: &lt;code dir=&quot;auto&quot;&gt;_HTML_COMMENT_UNTERMINATED&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;grammar.py:345&lt;/code&gt;) blanks from an un-closed &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;!--&lt;/code&gt; to end-of-text, so a spec.md with a
stray, never-closed &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;!--&lt;/code&gt; loses every declared ID and every prose token after it to
both the declared-ID scan and the lint, silently. By design (mirrors an HTML renderer’s
own unterminated-comment behaviour); the corpus has zero hits for this shape.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A fenced code block is not honoured.&lt;/strong&gt; Neither &lt;code dir=&quot;auto&quot;&gt;_declared_ids&lt;/code&gt; nor
&lt;code dir=&quot;auto&quot;&gt;lint_spec_requirement_ids&lt;/code&gt; special-case a markdown code fence (&lt;code dir=&quot;auto&quot;&gt;```&lt;/code&gt;): a requirement-ID
token inside a fenced example block is scanned exactly like prose or a declaration, the
same as every other span of text. By design (the grammar has no markdown-structure
awareness beyond HTML comments); the corpus has zero hits for this shape.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;supersession&quot;&gt;Supersession&lt;/h3&gt;
&lt;p&gt;This ADR supersedes the policy recorded by commit &lt;code dir=&quot;auto&quot;&gt;f11791683a&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;docs/changelog/CHANGELOG.md:1616&lt;/code&gt;): &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; previously warned, advisory-only,
when an &lt;code dir=&quot;auto&quot;&gt;SC-###&lt;/code&gt; ref was discarded by the pre-Mission &lt;code dir=&quot;auto&quot;&gt;(?:FR|NFR|C)&lt;/code&gt;-only scanner, while
stating explicitly that “&lt;code dir=&quot;auto&quot;&gt;SC&lt;/code&gt; is &lt;strong&gt;not&lt;/strong&gt; admitted as a first-class ref (the graph is
unchanged)”. Under this Mission’s single grammar, &lt;code dir=&quot;auto&quot;&gt;SC&lt;/code&gt; &lt;strong&gt;is&lt;/strong&gt; a first-class kind: it
participates in the same verdict table as every other kind (an undeclared &lt;code dir=&quot;auto&quot;&gt;SC&lt;/code&gt; ref fails as
&lt;code dir=&quot;auto&quot;&gt;unknown_spec_id&lt;/code&gt;, exactly like an undeclared &lt;code dir=&quot;auto&quot;&gt;FR&lt;/code&gt;), its coverage is tracked
(&lt;code dir=&quot;auto&quot;&gt;success_criteria_coverage&lt;/code&gt;, informational, never gating), and the discard-specific
advisory warning is retired as redundant with the general verdict table. No prior ADR
records the superseded policy (&lt;code dir=&quot;auto&quot;&gt;grep -rln -i &apos;success.criteri&apos; docs/adr/&lt;/code&gt; returns three
unrelated hits, none of which document this discard rule), so no other ADR needs a
“Superseded by” note.&lt;/p&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;One place to read, and one place to fix, requirement-ID recognition; the six-definition
drift SC-006 measured cannot recur silently.&lt;/li&gt;
&lt;li&gt;No authored ref disappears without a trace (#2991 closed): a rejected ref is always
reported, with its reason, never respelled or dropped.&lt;/li&gt;
&lt;li&gt;A previously invisible unmapped suffixed requirement now fails coverage loudly (#3519
part 2 closed).&lt;/li&gt;
&lt;li&gt;A rejected ref never discards a valid sibling’s coverage (research R8’s structural risk
closed) — the shared FR-019 verdict table is per-ref everywhere.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Re-finalizing an existing Mission may newly fail on a previously-silent suffixed FR or a
malformed/undeclared ref that the old, looser scanners let through (intended; WP08’s
corpus scan lists the affected Missions).&lt;/li&gt;
&lt;li&gt;The four known specs identified in NFR-001(b) are refused on re-plan under the new
setup-plan gate until their declared IDs are corrected.&lt;/li&gt;
&lt;li&gt;Dossier parity hashes change for any WP whose refs were previously silently erased by the
pre-Mission bug (the hash now reflects the preserved, authored refs).&lt;/li&gt;
&lt;li&gt;The byte-contract fixture (NFR-002) flips to the new additive JSON keys.&lt;/li&gt;
&lt;li&gt;An ID declared only inside an HTML comment no longer counts as declared (see “Known
residuals” above) — an intended, tested behaviour change from the pre-Mission scanner.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;requirement_refs_parsed&lt;/code&gt; (both the failure and success payloads,
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/mission_finalize.py:1355,3033&lt;/code&gt;) changed meaning: it
now lists every WP’s authored raw tokens verbatim (case preserved, including malformed
and foreign ones) via the raw reader &lt;code dir=&quot;auto&quot;&gt;read_all_wp_raw_requirement_refs&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/requirement_mapping/__init__.py:541-559&lt;/code&gt;, wired in at
&lt;code dir=&quot;auto&quot;&gt;mission_finalize.py:1068&lt;/code&gt;), not the pre-Mission normalised/accepted-only subset. A
consumer that read this key as “the accepted refs” must instead classify each token
itself (or read &lt;code dir=&quot;auto&quot;&gt;rejected_requirement_refs&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;unknown_requirement_refs&lt;/code&gt; alongside it).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;unknown_requirement_refs&lt;/code&gt; now includes every ref whose rejection reason is in
&lt;code dir=&quot;auto&quot;&gt;FAILING_REASONS&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;malformed&lt;/code&gt; as well as &lt;code dir=&quot;auto&quot;&gt;unknown_spec_id&lt;/code&gt;), not &lt;code dir=&quot;auto&quot;&gt;unknown_spec_id&lt;/code&gt;
alone (&lt;code dir=&quot;auto&quot;&gt;_classify_wp_requirement_refs&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/mission_finalize.py:1201-1243&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:1236-1238&lt;/code&gt;) — a
malformed ref that previously surfaced only via a separate error path now shows up in
this key too.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;requirement_mapping&lt;/code&gt; becoming a package is an internal reorganisation only; every
existing import path is preserved via re-export.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The C-001 architectural gate (&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_requirement_id_grammar_single_source.py&lt;/code&gt;)
stays green with an empty allow-list (&lt;code dir=&quot;auto&quot;&gt;baseline: 0&lt;/code&gt;) since the 2026-09-30 amendment.&lt;/li&gt;
&lt;li&gt;The cross-command parity test (&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/test_requirement_reason_parity.py&lt;/code&gt;, WP06
T038) proves &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;map-requirements&lt;/code&gt; and the runtime readiness check agree on
both the pass/fail verdict and the per-ref reason, through production entry points only.&lt;/li&gt;
&lt;li&gt;The per-surface tests WP02 (finalize), WP03 (map-requirements), WP04 (runtime), and WP05
(setup-plan/orchestrator-api) each added in their own lanes.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;links&quot;&gt;Links&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-06-06-1-plan-concerns-to-work-package-traceability/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-06-06-1-plan-concerns-to-work-package-traceability.md&lt;/code&gt;&lt;/a&gt;
— implementation-concern IDs (&lt;code dir=&quot;auto&quot;&gt;IC-##&lt;/code&gt;) stay a separate, plan-level grammar (C-004); this
Mission’s grammar never recognises an &lt;code dir=&quot;auto&quot;&gt;IC&lt;/code&gt; kind (&lt;code dir=&quot;auto&quot;&gt;grep -rn &apos;&quot;IC&quot;&apos; src/specify_cli/requirement_mapping/&lt;/code&gt;
and &lt;code dir=&quot;auto&quot;&gt;grep -rn &apos;IC-&apos; src/specify_cli/requirement_mapping/&lt;/code&gt; both return no matches).&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-07-17-1-red-main-is-honest-ci-is-release-authority/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-07-17-1-red-main-is-honest-ci-is-release-authority.md&lt;/code&gt;&lt;/a&gt;
— the red-first repro discipline (NFR-005) this Mission’s WP02-WP06 each followed.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;erratum-2026-10-04-5627&quot;&gt;Erratum (2026-10-04, #5627)&lt;/h2&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;mission_finalize.py:&amp;#x3C;line&gt;&lt;/code&gt; citations above point to that file as it was when this ADR was written. Mission &lt;code dir=&quot;auto&quot;&gt;mission-finalize-degod-01M43EW2&lt;/code&gt; later split it into phase modules, with bodies moved verbatim. The requirement-mapping functions cited here (&lt;code dir=&quot;auto&quot;&gt;_classify_one_wp&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_classify_wp_requirement_refs&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_build_requirement_diagnostics&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_validate_requirement_mapping&lt;/code&gt;, and others) now live in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/mission_finalize_validation.py&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;mission_finalize&lt;/code&gt; still re-exports them. The decision is unchanged.&lt;/p&gt;</content>
</entry>
