docs(#2121): add ADR-2121 phase-identifier parsing consolidation (Phase 0)

Phase 0 of the #2121 epic — an ADR-only PR that LOCKS the contract Phases
1-4 execute against. No production code lands here.

Locks:
- phase-id.cts as the single canonical owner of phase-identifier parsing.
- New pure exports Phase 1 adds: parsePhaseFromProse (anchored; fixes the
  #2111 "Milestone v0.5 complete -> 5" class), stripConfiguredProjectCodePrefix
  / isForeignPrefixedPhaseQuery (config-aware; the #2104 fix's home),
  and roadmapPhaseLookupSources moved in as sole owner of the 3-source
  ordering (fixes the #2114 2-vs-3-source divergence).
- Extend-never-mutate on the 12 existing exports (normalizePhaseName has a
  CRITICAL 84-symbol / 20-caller blast radius) — Hyrum's Law.
- The exact exact->numeric->prefix-tolerant lookup ordering.
- A behavioral anti-divergence contract: reference-identity guard +
  scripts/lint-phase-id-drift.cjs scanner, modeled on the repo's proven
  capability-precedence-parity / package-identity-drift patterns.

#2104 remains blocked on PR #2105 and off this epic's critical path.

Adds the docs/adr/README.md index row. Docs-only; no changeset required
(no-changelog).

Closes #2121

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-07-09 15:09:53 -04:00
parent d0745a0e91
commit 12d50093e1
2 changed files with 169 additions and 0 deletions

View File

@@ -65,6 +65,7 @@ See **[CONTRIBUTING.md — "Proposing an ADR or PRD"](../../CONTRIBUTING.md#prop
| [1817-state-md-rebuild-derivability-contract.md](1817-state-md-rebuild-derivability-contract.md) | STATE.md rebuild — derivability contract (capstone 11th transition) | Accepted |
| [2008-command-exit-zero-gate.md](2008-command-exit-zero-gate.md) | Generic gate-predicate evaluator with a `command-exit-zero` kind (#2008) | Accepted |
| [1990-existing-code-onboarding.md](1990-existing-code-onboarding.md) | Existing Code Onboarding Module owns deterministic repo-state detection and onboarding route selection | Proposed |
| [2121-phase-identifier-parsing-consolidation.md](2121-phase-identifier-parsing-consolidation.md) | Phase-identifier parsing consolidation — single canonical owner (phase-id.cts) + anti-divergence guard | Accepted |
## Seam map