docs(#612): bracket phase-id convention ADR (PR-0)

PR-0 of the #612 tracer-bullet sequence: the ADR that locks the contract
PR-1..PR-6 execute against. No production code.

Rewrites the design for current next (v1.7.0-rc.5): phase-id surfaces now
live in src/phase-id.cts under the ADR-2121 single-owner regime (core.cts
retired, #1267), and M-NN is a shipped first-class convention rather than a
no-adopter RC intermediate. States every blocking requirement from the
approved-enhancement comment as an explicit design commitment:

- terminal M-NN deprecation, end state two conventions (null + bracket) by
  forward consolidation via the migrator, not "no adopters"
- EMIT/RENDER as one pure pair with fast-check round-trip properties, inside
  phase-id.cts under the #2128 token-source / drift-lint regime
- single-sourced, generated PR-6 injection block + verify parity check
- migrator dry-run-default / dirty-tree guard / atomic rollback (the current
  base's surgical reverse-rename #1542, a deliberate improvement over the
  requirement's literal "HEAD-sha reset" — flagged) + two-invariant fixture
  corpus + M-NN lift + HARD-REFUSE on absent project_code
- everything gated on phase_id_convention === 'bracket'; null / M-NN paths
  byte-untouched (never gate on project_code)
- concrete collision anchor normalizePhaseName('2-01.02-01') === '02',
  grounded in the live regexes at src/phase-id.cts:71/79

Guardrail: bracket is core config-gated behavior, not an add-only capability.
Per-PR implementation map (PR-1..6) targets current module homes and the
CARRY-FORWARD ledger. Adds the docs/adr/README.md index row.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Brandon Higgins
2026-07-11 09:57:50 -06:00
parent b5ce72f729
commit 8cfbdf167f
2 changed files with 199 additions and 0 deletions

View File

@@ -68,6 +68,7 @@ See **[CONTRIBUTING.md — "Proposing an ADR or PRD"](../../CONTRIBUTING.md#prop
| [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 |
| [2143-markdown-table-and-mutation-consolidation.md](2143-markdown-table-and-mutation-consolidation.md) | Markdown table model, bounded mutation, and fail-loud consolidation (#1372 part 2) | Accepted |
| [2164-statusline-scope-boundary.md](2164-statusline-scope-boundary.md) | Statusline draws its data boundary at local, read-only sources (no external/credentialed data) | Accepted |
| [612-bracket-phase-id-convention.md](612-bracket-phase-id-convention.md) | Bracket phase-ID convention — lift the milestone into a `[PROJECT.MM]` prefix; terminal deprecation of M-NN | Proposed |
## Seam map