@pareto4/pp-core 1.11.1 → 1.12.1

package/pp-core/bin/lib/discovery-rebaseline.cjs

@@ -0,0 +1,1372 @@
+"use strict";
+/**
+ * Discovery scope re-baselining enforcement engine (discovery-v2 Phase 5,
+ * VAR-02, D-65..D-77).
+ *
+ * Read-only structural validator over `.planning/discovery/_rebaseline.md` —
+ * the client-doc ↔ requirement ↔ built-phase matrix (D-66). It exists for one
+ * situation: a client scope document arrives AFTER build has started, and the
+ * functionality already built has to be reconciled against it, phase by phase,
+ * with a disposition on each and an argued reason attached to every disposition
+ * that is not "carry on".
+ *
+ * The spine is one row per BUILT unit (D-68), because the thing being
+ * dispositioned is built functionality — the only spine that gives a row to
+ * functionality the new document simply stops mentioning, which is the whole
+ * `lapsed` case. Row identity is the round number plus the built unit's
+ * existing roadmap phase number; this engine mints NO ID family at all (D-67).
+ *
+ * Fail-loud (D-72/D-73), one bullet per fault class this module can emit:
+ *   - bad_id — a `## Round` heading that CLAIMS the round family but does not
+ *     match the grammar (a three-digit round number lands here), and the matrix
+ *     row arity fault: a pipe line inside a round that is neither the header
+ *     nor the separator and does not carry exactly six cells
+ *   - duplicate_id — the same round number heading two sections, or the same
+ *     phase dispositioned twice inside one round. The first row keeps the slot;
+ *     the later row is reported rather than dropped, because its disposition may
+ *     contradict the one already recorded
+ *   - sequence_gap — round numbers that are not contiguous from 1 (D-41/D-66);
+ *     the locator names the MISSING number, so a deleted round cannot lapse
+ *   - missing_section — a PRESENT artifact holding no round at all, empty or
+ *     not: a bootstrap that never got its rows, not a project with nothing to
+ *     say. A zero-byte or whitespace-only file is the purest instance of that,
+ *     and exempting it would let the gate exit 0 while the report claimed the
+ *     artifact had been checked
+ *   - missing_round_metadata — a round that records no phase denominator. A
+ *     fault rather than a graceful skip on purpose (D-76): without a denominator
+ *     the phase-coverage rule can never fire, and a check that exits 0 having
+ *     verified nothing is precisely the fail-open this engine exists to close
+ *   - bad_phase_token — a token outside the phase grammar, in the denominator
+ *     line or in the `Phase` cell alike. ONE grammar for both, deliberately, so
+ *     coverage is a token-for-token comparison with no normalisation step
+ *   - bad_built_status — a `Built` cell outside `executed` / `in-flight` /
+ *     `not started` (D-69)
+ *   - bad_disposition — a `Disposition` value outside the four scope states
+ *     (D-70)
+ *   - disposition_without_reason — a bare `validate`, `dormant` or `lapsed`
+ *     (D-71). This is the mechanism that stops an agent proposing a lapse
+ *     without arguing it; a bare `active` is clean, and that polarity is
+ *     load-bearing rather than incidental
+ *   - bad_clause_citation — a malformed token in the `Clauses` cell, or a
+ *     `validate` whose parenthesised reason is prose rather than a D-23 citation
+ *   - unknown_requirement_id — a `Discovery requirements` token of the wrong
+ *     shape. The resolves-to-nothing arm of the same code, together with
+ *     missing_phase_row, requirements_unparseable and artifact_unreadable, is
+ *     emitted by the aggregator this module's sibling plan adds; all fifteen
+ *     codes are declared here so the tuple is complete from the start and the
+ *     reference agrees with it in both directions
+ *   - unterminated_fence — a code fence opened inside the artifact and never
+ *     closed. A fenced block is data and its contents are skipped, so an
+ *     UNBALANCED fence would otherwise skip every remaining round heading,
+ *     metadata bullet and matrix row and let the gate exit 0 having verified
+ *     nothing — the same fail-open `missing_round_metadata` exists to close,
+ *     with the whole rest of the file as its blast radius
+ *
+ * Graceful arms (D-42/D-66, wired into the aggregator): an ABSENT
+ * `_rebaseline.md` is a clean pass — most engagements never re-baseline, and a
+ * check that reddened on the absence would turn a variation nobody triggered
+ * into a red gate for everybody — while a PRESENT-BUT-UNREADABLE one is
+ * `artifact_unreadable`. Collapsing the two would let the gate exit 0 having
+ * validated nothing.
+ *
+ * Reads `.planning/discovery/` and NOTHING else (D-76). The phase denominator
+ * every coverage judgement is made against is recorded by the round itself, so
+ * this engine performs no roadmap access at all. That keeps each round the
+ * self-contained snapshot D-66 already says it is, keeps the dependency
+ * footprint identical to the four sibling engines, and dissolves the asymmetry
+ * that `.planning/discovery/` is hard-coded non-workstream-scoped while a
+ * roadmap path would follow `--ws`.
+ *
+ * Content-free contract (T-05-01): a violation carries the artifact name, a
+ * 1-based source row, a validated round number, a phase token that has already
+ * passed its grammar, a validated requirement ID, a closed-list field name and a
+ * BOUNDED closed-vocabulary cell prefix — and nothing else. The `Violation`
+ * interface has NO free-text member: the `Roadmap requirements` provenance cell
+ * (D-77a), the parenthesised disposition reason (D-71) and the round label are
+ * parsed and stored on the parse RESULT, and no code path can place any of them
+ * on a violation. `bad_phase_token` and the wrong-shape arm of
+ * `unknown_requirement_id` carry no echo at all — a cell that failed its grammar
+ * has passed no validation, so there is nothing about it that is safe to quote.
+ * The `ECHO_MAX_CHARS` bound is a confidentiality control, not a formatting
+ * preference: matrix prose is written out of client documents (D-24).
+ *
+ * Never-judges-a-disposition contract (D-72): this check tests STRUCTURE only —
+ * whether the value is in the enum, whether a non-`active` value carries a
+ * reason, whether a cited discovery requirement ID resolves, whether every
+ * recorded phase has a row, and whether the round headings and their metadata
+ * are well-formed. Whether a given `lapsed` is a GOOD call is not
+ * machine-checkable, and settling that is the job of the targeted-review walk,
+ * with a human in it. There is likewise no round-to-round monotonicity rule,
+ * and that is settled rather than pending (D-76): rounds are independent
+ * snapshots, a later round may reverse an earlier verdict, and both records
+ * survive.
+ *
+ * The single home for the matrix template, the vocabularies and the
+ * parser-contract table this module implements is
+ * `pp-core/references/discovery-rebaseline.md` (D-65).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { output, error, ERROR_REASON } = io;
+// `_requirements.md` is owned by `discovery rollup`; the D-77b resolution arm
+// consumes its single exported reader and nothing else, so a grammar fault
+// there is reported once by name rather than re-enumerated here.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const rollup = require("./discovery-rollup.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const table = require("./discovery-table.cjs");
+const { splitTableCells, SEPARATOR_ROW_RE, boundedSequenceMax } = table;
+// ─── Types ────────────────────────────────────────────────────────────────────
+/**
+ * The closed set of reason codes this engine can emit, in declaration order.
+ *
+ * Exported as a runtime VALUE, not merely as a type, specifically so the
+ * parser-contract table in `pp-core/references/discovery-rebaseline.md` can be
+ * pinned against it by a test instead of by a manual diff — in BOTH directions:
+ * a code here with no row there fails, and a row there naming a code this engine
+ * cannot emit fails too. `ViolationReason` is derived from the tuple, so a code
+ * added to one is a code added to both.
+ *
+ * Declared IN FULL here even though this module emits only the first ten and
+ * the fifteenth. Codes eleven through fourteen are raised by the aggregator
+ * added alongside the CLI arm; the declaration ORDER is part of the contract,
+ * so a code moved here is a row the reference table has to move too.
+ *
+ * Append-only by convention: `unterminated_fence` sits last so the fourteen
+ * earlier entries keep their positions and the reference table extends by a row
+ * rather than being reordered — which is what keeps a fault code's spelling
+ * stable for the readers and scripts that have already learned it. That is also
+ * why the unbalanced fence got a code of its OWN rather than reusing `bad_id`:
+ * a fault code that names the wrong condition is the defect this gap set exists
+ * to remove, not a saving.
+ */
+const VIOLATION_REASONS = Object.freeze([
+    'bad_id',
+    'duplicate_id',
+    'sequence_gap',
+    'missing_section',
+    'missing_round_metadata',
+    'bad_phase_token',
+    'bad_built_status',
+    'bad_disposition',
+    'disposition_without_reason',
+    'bad_clause_citation',
+    'unknown_requirement_id',
+    'missing_phase_row',
+    'requirements_unparseable',
+    'artifact_unreadable',
+    'unterminated_fence',
+]);
+// ─── Closed vocabularies ──────────────────────────────────────────────────────
+/**
+ * The four SCOPE-STATE values a row may be dispositioned with (D-70).
+ *
+ * `active` — the new scope still wants it as built, nothing to do.
+ * `validate` — still in scope, but the new document changes its expected
+ *   behaviour; it must be re-verified against the named clause.
+ * `dormant` — out of scope now but plausibly returns; the code stays,
+ *   unadvertised and unmaintained, with a named re-entry condition.
+ * `lapsed` — the new scope removes it outright; the code stays in the tree but
+ *   is no longer claimed as delivered.
+ *
+ * The cut between the last two is "may return" versus "won't". Nothing in this
+ * vocabulary demands deletion.
+ *
+ * NAMED `SCOPE_STATES` RATHER THAN A DISPOSITION-SHAPED NAME ON PURPOSE.
+ * `_requirements.md` already owns a vocabulary called dispositions, with the
+ * values MVP / Later / Dropped, exported from `discovery-rollup.cts` as
+ * `DISPOSITIONS`. D-03/D-70/D-74 make this a THIRD, orthogonal axis living in a
+ * different artifact on a different spine, and re-baselining writes no
+ * `_requirements.md` cell at all. Two frozen objects sharing one name across two
+ * engines is how a reader conflates two axes the design deliberately separated.
+ */
+const SCOPE_STATES = Object.freeze({
+    ACTIVE: 'active',
+    VALIDATE: 'validate',
+    DORMANT: 'dormant',
+    LAPSED: 'lapsed',
+});
+const SCOPE_VALUES = Object.values(SCOPE_STATES);
+/**
+ * The closed three-value `Built` enum (D-69), mapped by the workflow from the
+ * `disk_status` field of `pp-tools query roadmap analyze`: `complete` →
+ * `executed`; `partial` / `planned` → `in-flight`; everything else → `not
+ * started`.
+ *
+ * Every phase in the denominator gets a row, INCLUDING phases nobody has
+ * started: the cheapest scope kill is a phase nobody has started, and excluding
+ * queued work would hide precisely the decisions that cost nothing to make.
+ */
+const BUILT_STATES = Object.freeze({
+    EXECUTED: 'executed',
+    IN_FLIGHT: 'in-flight',
+    NOT_STARTED: 'not started',
+});
+const BUILT_VALUES = Object.values(BUILT_STATES);
+// ─── Module constants ─────────────────────────────────────────────────────────
+/**
+ * The confidentiality bound on every echoed detail. Not a formatting
+ * preference: matrix prose is derived from client documents (D-24), so an
+ * unbounded echo is a disclosure. Same value as all four sibling engines,
+ * deliberately — a bound that differs per engine is a bound somebody has to
+ * remember, and the one they misremember is the one that leaks.
+ */
+const ECHO_MAX_CHARS = 24;
+/**
+ * The cap on how many violations a failure message RENDERS. A pathological
+ * artifact would otherwise inline one line each into the `--json-errors` JSON
+ * `message`. The cap bounds the report, never the accounting: the count in the
+ * message prefix and the `violations` field of the failure-path summary both
+ * stay the true total.
+ */
+const MAX_REPORTED_VIOLATIONS = 50;
+/**
+ * Hard-coded exactly as all four sibling engines hard-code it, and deliberately
+ * NOT resolved through the workspace path helper. `.planning/discovery/` is not
+ * workstream-scoped, so a `--ws`-following roadmap path beside it would be an
+ * asymmetry the engine has to reconcile at every read. D-76 dissolves that
+ * asymmetry instead of papering over it, by recording the phase denominator in
+ * the round itself — an engine that never opens a roadmap never has to
+ * reconcile the two.
+ */
+const DISCOVERY_DIR = '.planning/discovery';
+const REBASELINE_FILE = '_rebaseline.md';
+const REQUIREMENTS_FILE = '_requirements.md';
+/** The em dash an author writes to mean "nothing here" in a list-bearing cell. */
+const NOT_APPLICABLE = '—';
+/**
+ * The gate's identity, exported under its own name as well as through
+ * `ERROR_REASON`: it is cited by the workflow steps that run it, by the
+ * reference, and by the derived-command audit that regexes the subcommand
+ * spelling straight out of this module rather than re-spelling it as a string
+ * literal in a second place.
+ */
+const REBASELINE_CHECK_FAILED = ERROR_REASON.DISCOVERY_REBASELINE_CHECK_FAILED;
+const REBASELINE_CHECK_USAGE = ERROR_REASON.USAGE;
+// ─── Grammar ──────────────────────────────────────────────────────────────────
+// Anchored, non-backtracking regexes (threat T-05-07). Every one of them is
+// applied either to a SINGLE already-split line or to a SINGLE already-split
+// table cell — never unanchored across whole-file untrusted content — and every
+// quantifier is bounded. The matrix is written out of client documents, so a
+// catastrophic backtracking pattern here would be a denial-of-service surface.
+/**
+ * D-66 round heading, byte-identical in shape to the `_feedback.md` one: a
+ * second-level heading, the word Round, a decimal round number, then an
+ * em-dash-separated ISO date and an em-dash-separated free-text label. The
+ * triggering accession lives in a metadata BULLET rather than in the heading
+ * precisely so this shape could transfer unchanged.
+ *
+ * ONLY the round number is validated. The date and the label are matched for
+ * SHAPE and their content is never inspected — stated here so the reference's
+ * parser-contract table can say so honestly rather than implying a date check
+ * this engine does not perform.
+ *
+ * The round number is BOUNDED to two digits, like every other discovery ID
+ * family. An unbounded `\d+` let a plain typo — the ISO date written into the
+ * round-number slot, `## Round 20250115` — drive `validateRoundSequence` into
+ * allocating twenty million gap violations and abort the process on a V8 heap
+ * fatal, which is not a JavaScript exception and therefore not something a
+ * try/catch can turn into a structured result.
+ */
+const ROUND_HEADING_RE = /^## Round (\d{1,2}) — ([^—]+) — (.+)$/;
+/**
+ * A heading that CLAIMS the round family. A claimed-but-malformed one is a
+ * reported fault, not a skipped line (T-05-04): a malformed heading a parser
+ * passes over is a whole section of the audit trail the gate never looked at.
+ * A heading that never claims the family is ignored outright — other
+ * second-level sections in the document are not this parser's business.
+ */
+const ROUND_CLAIM_RE = /^## Round\b/;
+/**
+ * The bound on the phase-denominator payload, in characters after the colon.
+ *
+ * Derived from the shape the rebaseline WORKFLOW actually instructs rather than
+ * chosen for roundness. A partitioned project prefixes every phase token with
+ * its workstream name — `discovery-v2:04, ` — which runs about seventeen
+ * characters, so the previous 400 was exhausted at roughly twenty-four phases:
+ * an ordinary project size, and a line the author had every reason to believe
+ * was correct (WR-03). 2000 admits well over a hundred such tokens, which no
+ * real roadmap reaches.
+ *
+ * The larger bound adds NO backtracking surface (T-05-07, T-05-31). The
+ * quantifier is still single, still non-nested, still anchored at both ends, and
+ * still applied to ONE already-split line, so the match is linear in the line
+ * length — and the split list it feeds is bounded by the same number.
+ *
+ * EXPORTED, and stated by number in the reference, because the whole of WR-03
+ * was a bound nobody could see reported under a code that named a different
+ * condition. A bound an author can neither read nor derive is a bound they can
+ * only discover by failing.
+ */
+const DENOMINATOR_MAX_CHARS = 2000;
+/**
+ * The per-round phase-denominator metadata bullet (D-76). Its capture is the
+ * comma-separated phase-token list every coverage judgement is made against.
+ *
+ * Built from `DENOMINATOR_MAX_CHARS` rather than restating it, so the bound the
+ * reference documents, the bound the tests derive their payloads from and the
+ * bound the grammar enforces are one number. The pattern is a fixed string
+ * composed at module load from a module constant — no input reaches it.
+ */
+const DENOMINATOR_LINE_RE = new RegExp(`^- Phases at this round:(.{0,${DENOMINATOR_MAX_CHARS}})$`);
+/**
+ * A line that CLAIMS the phase-denominator family. Same claim-versus-match
+ * idiom as `ROUND_CLAIM_RE` versus `ROUND_HEADING_RE`, and for the same reason:
+ * a claimed-but-malformed line a parser passes over is a line the author
+ * believes is recording a denominator that the gate never read.
+ *
+ * Before WR-03 an over-long bullet matched nothing at all and fell through the
+ * accession check, the separator check and the leading-pipe check to be dropped
+ * in silence — leaving the round to close with no denominator and report
+ * `missing_round_metadata`, a fault whose text describes a round that records no
+ * denominator about a round that records one perfectly well.
+ */
+const DENOMINATOR_CLAIM_RE = /^- Phases at this round:/;
+/**
+ * The per-round accession metadata bullet, matched for PRESENCE only. The
+ * accession is recorded for provenance and is never resolved against the
+ * input-package README — do not read a resolution guarantee into a passing run.
+ */
+const ACCESSION_LINE_RE = /^- Triggering document:(.{0,80})$/;
+/**
+ * A roadmap phase number, optionally prefixed by a lower-case workstream name
+ * and a colon when a project is partitioned across several roadmaps — `04`, or
+ * `discovery-v2:04`. An optional dotted sub-number covers a split phase.
+ *
+ * The SAME grammar governs the denominator line and the `Phase` cell,
+ * deliberately, so the two can be compared token for token without a
+ * normalisation step — the cheapest possible implementation of the coverage
+ * rule and the one least likely to drift.
+ */
+const PHASE_TOKEN_RE = /^(?:[a-z][a-z0-9-]{0,39}:)?\d{1,3}(?:\.\d{1,2})?$/;
+/**
+ * The D-23 bracketed accession-plus-locator citation, the same shape
+ * `discovery-id-conventions.md` defines and `discovery-rollup.cts` already
+ * enforces — `[03]`, `[03 §2.1]`. The eighty-character locator bound is a
+ * confidentiality control (D-24), not a formatting preference.
+ */
+const CLAUSE_CITE_RE = /^\[(\d{2})( §[^\]]{1,80})?\]$/;
+/**
+ * A discovery requirement ID as `_requirements.md` mints them. Bounded rather
+ * than the siblings' open `[A-Z0-9]*-\d+`, per the T-05-07 discipline; the
+ * bounds are a generous superset of every reserved discovery prefix, so nothing
+ * the owning gate accepts is rejected here.
+ */
+const REQUIREMENT_ID_RE = /^[A-Z][A-Z0-9]{0,15}-\d{1,6}$/;
+/**
+ * The D-71 value-plus-structured-reason `Disposition` cell — the same trick as
+ * `Closed (<evidence>)`, `Dropped (D-<ss>-<n>)` and `DEFERRED (<reason>)`.
+ * Capture 1 is the bounded lower-case value token, capture 2 the optional
+ * bounded parenthesised reason.
+ *
+ * A separate Reason COLUMN was rejected because a separate column lets the
+ * reason be empty without breaking the enum's grammar — decoupling precisely
+ * what this shape couples. The reason text is free text and is never echoed.
+ */
+const DISPOSITION_CELL_RE = /^([a-z][a-z-]{0,23})(?: \((.{0,400})\))?$/;
+/** A fenced block opener or closer. Contents are data, never parsed as rows. */
+const FENCE_RE = /^(?:```|~~~)/;
+/**
+ * The six column names in the fixed order the reference sets. The header row is
+ * recognised by COMPARISON against this array rather than by a regex, so the
+ * order is a value the reference and the engine can be pinned against rather
+ * than a pattern buried in a match.
+ */
+const MATRIX_HEADER_CELLS = Object.freeze([
+    'Phase',
+    'Built',
+    'Roadmap requirements',
+    'Discovery requirements',
+    'Clauses',
+    'Disposition',
+]);
+/** Column indices into a split matrix row, in the fixed order above. */
+const MATRIX_COL = Object.freeze({
+    PHASE: 0,
+    BUILT: 1,
+    ROADMAP_REQUIREMENTS: 2,
+    DISCOVERY_REQUIREMENTS: 3,
+    CLAUSES: 4,
+    DISPOSITION: 5,
+});
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Every control character the whitespace collapse below does NOT handle: the C0
+ * plane minus `\t\n\v\f\r`, DEL, and the whole C1 plane.
+ *
+ * Stripped BEFORE the collapse, and the ordering is the whole point. JavaScript
+ * `\s` matches only the five C0 whitespace characters plus the Unicode space
+ * separators; it does NOT match ESC (`\x1b`), BEL (`\x07`), BS (`\x08`) or NUL.
+ * `formatViolation` output reaches `error()`, which in the default
+ * non-`--json-errors` mode writes `'Error: ' + message` to fd 2 VERBATIM — the
+ * mode a human operator reads in a terminal. A complete OSC-52 clipboard-write
+ * sequence fits inside `ECHO_MAX_CHARS`, and an UNTERMINATED OSC string consumes
+ * the report text after it and continues into the next violation's line. The
+ * `Built` cell is echoed on the `bad_built_status` path and has passed no
+ * grammar at that point, so it is exactly this surface. Identical to the
+ * research-track and screens constants, deliberately — the three chokepoints
+ * defend the same fd-2 surface and must not drift apart.
+ */
+const CONTROL_CHARS_RE = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g;
+/**
+ * The single echo chokepoint. Strip the control planes, collapse whitespace,
+ * trim, then cap at `ECHO_MAX_CHARS`.
+ *
+ * Both the strip and the collapse run BEFORE the slice, and together they
+ * guarantee a cell can never inject a newline, carriage return, tab or terminal
+ * escape sequence into the one-line-per-violation report format, regardless of
+ * where the slice happens to land.
+ *
+ * A confidentiality control, not a formatting preference (D-24): matrix prose is
+ * written out of client documents, so an unbounded echo is a disclosure.
+ */
+function sanitizeEcho(value) {
+    // A non-string is not author data this function can meaningfully bound, and
+    // default stringification would emit `[object Object]` — so it renders as
+    // nothing rather than as a placeholder that looks like content.
+    if (typeof value !== 'string')
+        return '';
+    const collapsed = value.replace(CONTROL_CHARS_RE, '').replace(/\s+/g, ' ').trim();
+    if (collapsed.length <= ECHO_MAX_CHARS)
+        return collapsed;
+    return `${collapsed.slice(0, ECHO_MAX_CHARS)}…`;
+}
+/**
+ * Split a comma-separated in-cell list into non-empty trimmed tokens. Lists
+ * WITHIN one cell are comma-separated across this whole surface; the ` · `
+ * middle dot stays reserved for compound-field separation (D-27/D-37/D-45). A
+ * second spelling of either would be a join that silently matches nothing.
+ */
+function splitList(value) {
+    return value.split(',').map(t => t.trim()).filter(t => t !== '');
+}
+/**
+ * The content-free locator every fault raised INSIDE a round section is built
+ * from: the artifact, the 1-based source row, and the round number — but only
+ * when there is a round number that passed the grammar.
+ *
+ * The single place the round field is attached, so an anonymous section
+ * (WR-05) cannot leak a number into a report by one call site forgetting. The
+ * field is OMITTED rather than set to a sentinel: a sentinel is a value that
+ * can travel, and the content-free contract (T-05-01) turns on a violation
+ * never carrying anything that passed no validation.
+ */
+function roundLocator(round, line) {
+    if (round === null)
+        return { artifact: REBASELINE_FILE, line };
+    return { artifact: REBASELINE_FILE, line, round };
+}
+/**
+ * Open a round for a section whose heading claimed the family and failed it
+ * (WR-05), located at that heading's row.
+ *
+ * `date` and `label` are empty strings rather than anything taken from the
+ * line: the heading matched no grammar, so it has no date and no label — it has
+ * only a row number. The caller is responsible for the three exclusions the
+ * `AnonymousRound` docblock states; this factory deliberately does NOT touch
+ * the rounds map or the sequence list, so neither can happen by accident here.
+ */
+function openAnonymousRound(line) {
+    return {
+        round: null,
+        anonymous: true,
+        line,
+        date: '',
+        label: '',
+        accession: null,
+        denominator: null,
+        denominatorLine: null,
+        denominatorClaimLine: null,
+        metadataFaultReported: false,
+        rows: [],
+    };
+}
+/** True when a split row is the fixed six-column header. */
+function isHeaderRow(cells) {
+    return (cells.length === MATRIX_HEADER_CELLS.length &&
+        MATRIX_HEADER_CELLS.every((name, i) => cells[i] === name));
+}
+// ─── Sequence ─────────────────────────────────────────────────────────────────
+/**
+ * Report the round numbers missing from a contiguous `1..max` run (D-41/D-66).
+ * The locator names the MISSING number, so a deleted round cannot lapse
+ * unnoticed — a hole is information, it says a round was dropped.
+ *
+ * The maximum folds through `boundedSequenceMax` from the shared leaf and NEVER
+ * through a spread over the parsed numbers. Two hazards close there in one
+ * place: the spread throws `RangeError` on a large array, and an unbounded
+ * maximum turns
+ * one mistyped heading into one allocated violation per missing number and a
+ * heap abort that no try/catch can convert into a structured result. Past the
+ * bound this reports a SINGLE `sequence_gap` rather than enumerating.
+ *
+ * EXPORTED so the bounded-span floor can be falsified through THIS engine and
+ * not only through the shared leaf. `ROUND_HEADING_RE` is two digits, so the
+ * out-of-band arm is unreachable end to end and a test can only reach it by
+ * calling this validator with the numbers directly.
+ *
+ * The below-1 arm is an INDEPENDENT floor, not the primary guard: the round
+ * heading now rejects a number below 1 at the grammar, so nothing this parser
+ * produces can reach here out of range (WR-04). It is kept for the same two
+ * reasons the out-of-band arm above it is kept — the grammar is one edit away
+ * from being widened again, and the tests call this validator directly, so an
+ * exported validator that returned a CLEAN list for `[0, 1]` would be dishonest
+ * about a rule the family states in three places.
+ *
+ * The floor lives HERE and not in `boundedSequenceMax`. That leaf is shared with
+ * two sibling engines, it computes a MAXIMUM, and a family's low bound is not
+ * its business: widening it for one caller would reintroduce exactly the drift
+ * its extraction closed (ADR/04-PATTERNS, AR-04-02).
+ *
+ * Noted rather than silently changed: the out-of-band arm below returns
+ * `sequence_gap` where this engine's three siblings return `bad_id` for the same
+ * shape. That divergence is real and is recorded as an observation for plan
+ * 05-12; it is NOT changed here, because the case is unreachable through the
+ * grammar and moving its code would move a documented parser-contract row for a
+ * condition no artifact can produce.
+ */
+function validateRoundSequence(numbers) {
+    const violations = [];
+    if (numbers.length === 0)
+        return violations;
+    if (numbers.some(n => n < 1)) {
+        return [{ artifact: REBASELINE_FILE, reason: 'bad_id' }];
+    }
+    const seen = new Set(numbers);
+    const max = boundedSequenceMax(numbers);
+    if (max === null) {
+        return [{ artifact: REBASELINE_FILE, reason: 'sequence_gap' }];
+    }
+    for (let n = 1; n <= max; n += 1) {
+        if (!seen.has(n)) {
+            violations.push({ artifact: REBASELINE_FILE, round: n, reason: 'sequence_gap' });
+        }
+    }
+    return violations;
+}
+// ─── Parsing ──────────────────────────────────────────────────────────────────
+/**
+ * Parse `_rebaseline.md` into its rounds, its rows and the faults found WITHIN
+ * the artifact. Never throws; a non-string input yields an empty result.
+ *
+ * Lines are split on a carriage-return-optional newline so a Windows checkout
+ * parses identically. Fenced blocks are tracked and their contents skipped, so
+ * the bootstrap template pasted into the artifact — or any other fenced
+ * example — cannot be parsed as data. The contract that follows from those two
+ * halves in one sentence: a BALANCED fence is still data and its contents are
+ * still skipped, while an UNBALANCED fence is a fault, so the remainder it
+ * swallowed can never be skipped in silence.
+ *
+ * A FAULTED ROUND HEADING is reported AND its rows are still checked (WR-05),
+ * so an author sees every fault in the file on the first run rather than
+ * discovering a second wave after fixing the heading. A duplicated heading
+ * re-opens the round already registered under that number; a malformed or
+ * out-of-range one opens an anonymous round, which reaches the row walk and
+ * nothing else. Both arms used to leave no round open, so every line until the
+ * next heading fell through the `open === null` guard and the whole section's
+ * cells escaped every per-row check — the two-pass experience the
+ * collect-all-then-fail design (D-08) exists to avoid.
+ *
+ * `rounds` is a `Map` keyed by the validated integer round number and the
+ * per-round phase index is a `Set` (T-05-06 discipline: derived state is never
+ * keyed into a plain object literal, so a crafted key cannot reach it).
+ *
+ * Cross-artifact resolution — the resolves-to-nothing arm of
+ * `unknown_requirement_id` and the whole of `missing_phase_row` — is NOT done
+ * here. This function is handed a string and reads no filesystem, which is what
+ * lets every within-artifact fault be provoked by an in-memory fixture.
+ */
+function parseRebaselineMatrix(content) {
+    const rounds = new Map();
+    const rows = [];
+    const violations = [];
+    if (typeof content !== 'string')
+        return { rounds, rows, violations };
+    const lines = content.split(/\r?\n/);
+    const seqs = [];
+    let open = null;
+    let seenPhases = new Set();
+    let sawRoundClaim = false;
+    let inFence = false;
+    // The 1-based row of the fence that OPENED the block currently being skipped,
+    // held so an unbalanced fence can be located at the line that opened it. The
+    // missing closer has no row of its own to name, and the opening line is the
+    // one the author has to go and look at.
+    let fenceOpenLine = null;
+    // A round that reaches its end — the next round heading, or end of file —
+    // without a denominator line is the D-76 fault, located at its HEADING row
+    // because the missing line has no row of its own.
+    //
+    // A round whose bullet CLAIMED the family and failed its grammar is exempt: it
+    // already carries a `bad_id` naming the condition it actually violated, and
+    // adding `missing_round_metadata` on top would restate one malformed line as
+    // two faults, the second of them the misreport WR-03 exists to remove. A round
+    // whose bullet PARSED but recorded no usable token is not exempt — that round
+    // genuinely records no denominator (WR-01).
+    //
+    // An ANONYMOUS round is exempt too, and for the same shape of reason (WR-05):
+    // its heading already faulted, so a second derived fault about a section
+    // nobody can name would have to be located by row alone and would say nothing
+    // the `bad_id` above it does not — noise the author cannot act on.
+    //
+    // `metadataFaultReported` is what keeps this one fault per ROUND rather than
+    // one per SECTION. A round whose number heads two sections is re-opened for
+    // the second one (WR-05), so this close runs twice over the same round object;
+    // the count of sections is not the count of faults.
+    const closeRound = () => {
+        if (open !== null &&
+            !open.anonymous &&
+            !open.metadataFaultReported &&
+            open.denominator === null &&
+            open.denominatorClaimLine === null) {
+            violations.push({
+                artifact: REBASELINE_FILE,
+                line: open.line,
+                round: open.round,
+                reason: 'missing_round_metadata',
+            });
+            open.metadataFaultReported = true;
+        }
+    };
+    for (let i = 0; i < lines.length; i += 1) {
+        const raw = lines[i];
+        const line = raw.trim();
+        const num = i + 1;
+        if (FENCE_RE.test(line)) {
+            inFence = !inFence;
+            fenceOpenLine = inFence ? num : null;
+            continue;
+        }
+        // The skip stays EXACTLY as it was. A round heading is not tested ahead of
+        // it, deliberately: a heading inside a BALANCED fence is the pasted
+        // bootstrap template the module header promises to tolerate, and parsing it
+        // unconditionally would fault that documented shape with `duplicate_id` —
+        // trading a fail-open for a false positive. The unbalanced fence is
+        // reported after the loop instead, so the silent-pass path closes without
+        // the balanced shape becoming a fault.
+        if (inFence)
+            continue;
+        if (ROUND_CLAIM_RE.test(line)) {
+            sawRoundClaim = true;
+            closeRound();
+            open = null;
+            seenPhases = new Set();
+            const match = ROUND_HEADING_RE.exec(line);
+            if (match === null) {
+                // Located by row number ONLY, carrying no echo: a heading that failed
+                // its grammar has passed no validation, so nothing about it is safe to
+                // quote (T-05-01).
+                violations.push({ artifact: REBASELINE_FILE, line: num, reason: 'bad_id' });
+                // …and the section beneath it is STILL parsed, under an anonymous round
+                // (WR-05). The heading fault used to cost the gate every cell below it.
+                // `seenPhases` was reset above and stays reset: this is a distinct
+                // section, not the second half of an existing round.
+                open = openAnonymousRound(num);
+                continue;
+            }
+            const round = Number(match[1]);
+            // The three heading outcomes read as one group: malformed above, OUT OF
+            // RANGE here, duplicate below.
+            //
+            // Below 1 is the SAME condition the high end already rejects through the
+            // two-digit capture — a round number outside the family's range — so it is
+            // rejected in the same place, at the grammar. `ROUND_HEADING_RE` captures
+            // one or two digits and therefore matches `0` and `00`; before WR-04 a
+            // lone `## Round 0` parsed successfully, yielded a maximum of zero from
+            // `boundedSequenceMax` (which seeds at 0), ran the contiguity loop zero
+            // times and reported nothing — while the module header, the reference and
+            // the bootstrap template's own preamble all promise "contiguous from 1".
+            // It also left `latest_round` as the falsy 0, which a downstream
+            // `if (payload.latest_round)` reads as "no rounds" for an artifact with
+            // one. Carrying no echo: the heading did not pass its grammar (T-05-01).
+            if (round < 1) {
+                violations.push({ artifact: REBASELINE_FILE, line: num, reason: 'bad_id' });
+                // Anonymous for the same reason the malformed arm is (WR-05): the number
+                // failed a range rule, so there is no validated number to name, but the
+                // rows below are still the author's audit trail and are still checked.
+                open = openAnonymousRound(num);
+                continue;
+            }
+            const registered = rounds.get(round);
+            if (registered !== undefined) {
+                // The round number has passed the grammar, so naming it is safe — and
+                // naming it is the only way an author finds the second section.
+                violations.push({
+                    artifact: REBASELINE_FILE,
+                    line: num,
+                    round,
+                    reason: 'duplicate_id',
+                });
+                // RE-OPEN the round already registered under that number rather than
+                // leaving none open (WR-05), so the second section's rows land on the
+                // round they CLAIM and are cell-checked normally. Its denominator bullet
+                // then reaches the WR-02 duplicate guard as well, which is correct: the
+                // round really does carry two denominator bullets.
+                open = registered;
+                // Rebuilt from the rows already collected, NOT started empty. A phase
+                // dispositioned in both halves of a duplicated round IS dispositioned
+                // twice inside one round, and a fresh index would hide exactly that —
+                // which is the shortcut that would keep this fixture's old violation
+                // count and lose the finding.
+                seenPhases = new Set(registered.rows.map(r => r.phase).filter(p => p !== ''));
+                continue;
+            }
+            const opened = {
+                round,
+                anonymous: false,
+                line: num,
+                date: match[2].trim(),
+                label: match[3].trim(),
+                accession: null,
+                denominator: null,
+                denominatorLine: null,
+                denominatorClaimLine: null,
+                metadataFaultReported: false,
+                rows: [],
+            };
+            open = opened;
+            rounds.set(round, opened);
+            seqs.push(round);
+            continue;
+        }
+        if (open === null)
+            continue;
+        // The claim arm comes FIRST, and it continues, so a bullet that claims the
+        // denominator family can no longer fall through the accession check, the
+        // separator check and the leading-pipe check to be dropped without comment
+        // (WR-03). Same shape as the round heading's `ROUND_CLAIM_RE` arm above.
+        if (DENOMINATOR_CLAIM_RE.test(line)) {
+            const denominator = DENOMINATOR_LINE_RE.exec(line);
+            if (denominator === null) {
+                // Located by row number ONLY, carrying no echo: a line that claimed a
+                // family and failed its grammar has passed no validation, so nothing
+                // about it is safe to quote (T-05-01). The round number IS safe when
+                // there is one — it passed the heading grammar — and it is how an author
+                // finds the round; under an anonymous section (WR-05) there is none, and
+                // `roundLocator` omits the field rather than inventing one.
+                violations.push({ ...roundLocator(open.round, num), reason: 'bad_id' });
+                open.denominatorClaimLine = num;
+                continue;
+            }
+            // A REPEATED bullet is the same duplication the round heading above and
+            // the phase cell below already report, and it gets the same policy: the
+            // first record keeps the slot and the later one is reported rather than
+            // dropped in silence, because it may contradict what is already recorded.
+            //
+            // The FIRST bullet wins rather than the last, and that direction is the
+            // whole point. A reader scanning the artifact sees the first line under
+            // the heading and takes it as the denominator; a last-write-wins parser
+            // would judge coverage against a line the reader never read. Before WR-02
+            // every match overwrote unconditionally, so `- Phases at this round: 02,
+            // 03, 04` followed by `- Phases at this round: 02` narrowed the coverage
+            // denominator from three phases to one and raised NOTHING anywhere — the
+            // fully-silent instance of the no-op this engine exists to close. D-73
+            // accepts a hand-edited denominator understating the phase list as a
+            // cost, but the accepted cost is ONE line an operator can read and check;
+            // this keeps it there rather than extending it to a second line that
+            // overrides the first while the first still sits above it.
+            //
+            // Keyed on "has RECORDED a denominator", not on "has SEEN a bullet". A
+            // bullet that already faulted and recorded nothing — the WR-01 all-invalid
+            // case, or the WR-03 claimed-and-malformed case — has reported its own
+            // condition at its own row; turning the round's only usable bullet into a
+            // second fault on top of that would be the derived misreport WR-03
+            // removed. Located through `roundLocator`: a named round's number came out
+            // of the heading grammar so naming it is safe and is how an author finds
+            // the round, while an anonymous section (WR-05) carries no number at all.
+            if (open.denominatorLine !== null) {
+                violations.push({ ...roundLocator(open.round, num), reason: 'duplicate_id' });
+                continue;
+            }
+            const tokens = splitList(denominator[1]);
+            const valid = [];
+            for (const token of tokens) {
+                if (PHASE_TOKEN_RE.test(token))
+                    valid.push(token);
+                else {
+                    violations.push({
+                        ...roundLocator(open.round, num),
+                        reason: 'bad_phase_token',
+                        field: 'phase',
+                    });
+                }
+            }
+            // A bullet that records no USABLE token records no denominator at all, so
+            // it stays the D-76 fault rather than becoming a coverage rule that
+            // trivially passes — that would be exactly the fail-open the code exists
+            // to close. The test is `valid`, not `tokens` (WR-01): keying it on the
+            // SPLIT count let an all-invalid bullet leave `denominator === []`, which
+            // is non-null, which is the only thing `enforcePhaseCoverage` tests — so
+            // the round reported `bad_phase_token`, skipped `missing_round_metadata`,
+            // and handed the coverage rule an empty list to iterate.
+            //
+            // The PARTIAL case is deliberately unchanged: a bullet holding one good
+            // token and one bad one still records the good one and still faults the
+            // bad one. Refusing the whole bullet there would trade a fail-open for a
+            // second, wrong fault on every partially-mistyped round.
+            if (valid.length > 0) {
+                open.denominator = valid;
+                open.denominatorLine = num;
+            }
+            continue;
+        }
+        const accession = ACCESSION_LINE_RE.exec(line);
+        if (accession !== null) {
+            open.accession = accession[1].trim();
+            continue;
+        }
+        if (SEPARATOR_ROW_RE.test(raw))
+            continue;
+        if (!line.startsWith('|'))
+            continue;
+        const cells = splitTableCells(raw);
+        if (isHeaderRow(cells))
+            continue;
+        if (cells.length !== MATRIX_HEADER_CELLS.length) {
+            // A pipe line inside a round that is neither header nor separator CLAIMS
+            // the matrix family without matching it. Reported, never skipped past.
+            violations.push({ ...roundLocator(open.round, num), reason: 'bad_id' });
+            continue;
+        }
+        const at = roundLocator(open.round, num);
+        const phaseCell = cells[MATRIX_COL.PHASE];
+        let phase = '';
+        if (!PHASE_TOKEN_RE.test(phaseCell)) {
+            violations.push({ ...at, reason: 'bad_phase_token', field: 'phase' });
+        }
+        else if (seenPhases.has(phaseCell)) {
+            // Echoing the phase is safe: it has passed its grammar. The FIRST row
+            // keeps the slot and this one is reported rather than dropped in silence,
+            // because its disposition may contradict the one already recorded.
+            violations.push({ ...at, phase: sanitizeEcho(phaseCell), reason: 'duplicate_id' });
+            phase = phaseCell;
+        }
+        else {
+            seenPhases.add(phaseCell);
+            phase = phaseCell;
+        }
+        const built = cells[MATRIX_COL.BUILT];
+        if (!BUILT_VALUES.includes(built)) {
+            violations.push({
+                ...at,
+                reason: 'bad_built_status',
+                field: 'built',
+                cell: sanitizeEcho(built),
+            });
+        }
+        // D-77a: provenance for the built unit, carrying MILESTONE requirement IDs
+        // from a different ID plane. Stored and never inspected again — it matches
+        // the same ID shape as the cell beside it, which is exactly why the two are
+        // separate columns rather than one.
+        const roadmapRequirements = cells[MATRIX_COL.ROADMAP_REQUIREMENTS];
+        const discoveryCell = cells[MATRIX_COL.DISCOVERY_REQUIREMENTS];
+        const discoveryRequirements = [];
+        if (discoveryCell !== NOT_APPLICABLE) {
+            const tokens = splitList(discoveryCell);
+            if (tokens.length === 0) {
+                // An empty cell is not in the grammar: "one or more IDs, or the em
+                // dash". No echo — an empty token has passed nothing.
+                violations.push({ ...at, reason: 'unknown_requirement_id', field: 'discovery_requirements' });
+            }
+            for (const token of tokens) {
+                if (REQUIREMENT_ID_RE.test(token))
+                    discoveryRequirements.push(token);
+                // Wrong shape and resolves-to-nothing are the SAME code — both mean
+                // "this is not a requirement I can find" — but the wrong-shape arm
+                // carries no echo, because the token passed no grammar.
+                else
+                    violations.push({ ...at, reason: 'unknown_requirement_id', field: 'discovery_requirements' });
+            }
+        }
+        const clausesCell = cells[MATRIX_COL.CLAUSES];
+        const clauses = [];
+        if (clausesCell !== NOT_APPLICABLE) {
+            const tokens = splitList(clausesCell);
+            if (tokens.length === 0) {
+                // The em dash is how "no clause bearing on this phase" is spelled, and
+                // it is exactly the `lapsed` shape stated in the cell. A blank cell is
+                // silence, which is the thing this artifact exists to remove.
+                violations.push({ ...at, reason: 'bad_clause_citation', field: 'clauses' });
+            }
+            for (const token of tokens) {
+                if (CLAUSE_CITE_RE.test(token))
+                    clauses.push(token);
+                else
+                    violations.push({ ...at, reason: 'bad_clause_citation', field: 'clauses' });
+            }
+        }
+        const dispositionCell = cells[MATRIX_COL.DISPOSITION];
+        const dm = DISPOSITION_CELL_RE.exec(dispositionCell);
+        let disposition = '';
+        let dispositionReason = null;
+        if (dm === null) {
+            violations.push({ ...at, reason: 'bad_disposition', field: 'disposition' });
+        }
+        else {
+            disposition = dm[1];
+            dispositionReason = dm[2] === undefined ? null : dm[2];
+            if (!SCOPE_VALUES.includes(disposition)) {
+                violations.push({
+                    ...at,
+                    reason: 'bad_disposition',
+                    field: 'disposition',
+                    cell: sanitizeEcho(disposition),
+                });
+            }
+            else if (disposition !== SCOPE_STATES.ACTIVE) {
+                if (dispositionReason === null || dispositionReason.trim() === '') {
+                    // The mechanism that stops an agent proposing a lapse without
+                    // arguing it (D-71). `disposition` is a validated enum value here.
+                    violations.push({
+                        ...at,
+                        reason: 'disposition_without_reason',
+                        field: 'disposition',
+                        cell: disposition,
+                    });
+                }
+                else if (disposition === SCOPE_STATES.VALIDATE &&
+                    !CLAUSE_CITE_RE.test(dispositionReason.trim())) {
+                    // A `validate` must name the clause that changed the expected
+                    // behaviour; prose there is a citation fault, not a missing reason.
+                    violations.push({ ...at, reason: 'bad_clause_citation', field: 'disposition' });
+                }
+            }
+        }
+        // Every row is kept, including one whose phase failed: dropping it here
+        // would make a second fault on the same row invisible to a later pass.
+        const row = {
+            round: open.round,
+            line: num,
+            phase,
+            built,
+            roadmapRequirements,
+            discoveryRequirements,
+            clauses,
+            disposition,
+            dispositionReason,
+        };
+        open.rows.push(row);
+        rows.push(row);
+    }
+    closeRound();
+    // A fence that opened and never closed swallowed every line after it. That is
+    // the largest blast radius any structural fault in this artifact has: the
+    // remaining round headings, metadata bullets and matrix rows are all skipped,
+    // and because an earlier round already set `sawRoundClaim` and the swallowed
+    // rounds never reach `seqs`, neither `missing_section` nor `sequence_gap`
+    // fires either — the parse returns clean and the gate exits 0 having verified
+    // nothing. Reported at the OPENING row, carrying no cell and no round: the
+    // fence belongs to the artifact rather than to a section, and nothing inside a
+    // block the parser could not delimit has passed any grammar.
+    if (inFence) {
+        violations.push({
+            artifact: REBASELINE_FILE,
+            line: fenceOpenLine ?? undefined,
+            reason: 'unterminated_fence',
+        });
+    }
+    // A file that exists with no round at all is a bootstrap that never got its
+    // rows, not a project with nothing to disposition. Keyed off whether a round
+    // was ever CLAIMED, so a malformed heading reports its own `bad_id` without
+    // also collecting a spurious `missing_section`.
+    //
+    // The distinction is THREE-way and not two-way, and each arm is a different
+    // statement about what the gate actually verified:
+    //   - ABSENT is the D-42/D-66 graceful arm and is silent. Most engagements
+    //     never re-baseline, and reddening on the absence would turn a variation
+    //     nobody triggered into a red gate for everybody.
+    //   - PRESENT-AND-EMPTY is `missing_section`. A file that exists with no round
+    //     at all is a bootstrap that never got its rows, and a zero-byte or
+    //     whitespace-only file is the purest instance of that description.
+    //   - PRESENT-AND-UNREADABLE is `artifact_unreadable`, raised by the
+    //     aggregator, and the parser's non-string early return keeps it standing
+    //     alone with no derived cascade.
+    //
+    // There is deliberately NO emptiness exemption here. The `content.trim() !==
+    // ''` clause this replaces collapsed the middle arm into the first, and it did
+    // so while the aggregator was pushing the file into `artifacts_checked` — so
+    // the report claimed the artifact had been checked when nothing in it had
+    // been. That is exactly the second, quieter overstatement the unreadable arm
+    // one branch over was written to avoid.
+    if (!sawRoundClaim) {
+        violations.push({ artifact: REBASELINE_FILE, reason: 'missing_section' });
+    }
+    violations.push(...validateRoundSequence(seqs));
+    return { rounds, rows, violations };
+}
+// ─── Cross-artifact resolution ────────────────────────────────────────────────
+/**
+ * Resolve the cited discovery requirement IDs against the set `_requirements.md`
+ * actually mints (D-77b).
+ *
+ * `knownIds === null` means resolution is SKIPPED — `_requirements.md` is absent
+ * or the owning gate cannot parse it — and skipping returns an empty list rather
+ * than a fault. A citation then passes on shape alone, which is the same
+ * graceful arm the sibling gates take: a project that has not minted a
+ * requirement set yet must not be reddened for citing into one, and a gate that
+ * is already red elsewhere must not be reported twice here.
+ *
+ * ONLY the discovery-requirement column is resolved. The roadmap-provenance cell
+ * beside it (D-77a) holds MILESTONE IDs from a different ID plane and matches the
+ * same `[A-Z][A-Z0-9]*-\d+` shape, so resolving it would fault every
+ * roadmap-pre-filled row with a false `unknown_requirement_id` — which is
+ * precisely why the two planes are two columns rather than one.
+ *
+ * `row.discoveryRequirements` holds only tokens that already passed
+ * `REQUIREMENT_ID_RE`; the wrong-SHAPE arm of this same code was raised by the
+ * parser and carries no echo. Here the ID is safe to name precisely because it
+ * passed its family regex — and naming it is the only way an author finds the
+ * citation among six columns.
+ */
+function resolveRequirements(rows, knownIds) {
+    const violations = [];
+    if (knownIds === null)
+        return violations;
+    for (const row of rows) {
+        for (const id of row.discoveryRequirements) {
+            if (!knownIds.has(id)) {
+                // Through the same locator the parser uses, so a row that survived a
+                // faulted heading (WR-05) reaches this rule — it is still a citation
+                // somebody wrote — without the report inventing a round for it.
+                violations.push({
+                    ...roundLocator(row.round, row.line),
+                    reason: 'unknown_requirement_id',
+                    field: 'discovery_requirements',
+                    id: sanitizeEcho(id),
+                });
+            }
+        }
+    }
+    return violations;
+}
+/**
+ * Every phase the LATEST round recorded in its own denominator must have a row
+ * in that round (D-76). A phase with no row is functionality nobody
+ * dispositioned, and silence is the thing this artifact exists to remove.
+ *
+ * THE DENOMINATOR COMES FROM THE ROUND'S OWN RECORDED METADATA. This engine
+ * reads no roadmap — the rebaseline WORKFLOW enumerates the roadmap and writes
+ * the phase list as it stood when the round was taken into the round's metadata
+ * bullet. That is what keeps this engine's dependency footprint identical to its
+ * four siblings (`.planning/discovery/` and nothing else) and what dissolves the
+ * asymmetry that `.planning/discovery/` is hard-coded non-workstream-scoped while
+ * a roadmap path would follow `--ws`. An engine that never opens a roadmap never
+ * has to reconcile the two.
+ *
+ * The LATEST round only, and that is settled rather than pending (D-76): rounds
+ * are independent snapshots, a later round may reverse an earlier verdict, and
+ * there is no monotonicity rule. Re-evaluating an earlier round would make a
+ * roadmap that grew between rounds retroactively redden a round that was closed
+ * correctly at the time it was taken.
+ *
+ * `denominator` is non-null iff at least one token was recorded — an empty
+ * bullet, and a bullet whose every token fails the phase grammar, both leave it
+ * null and still fire `missing_round_metadata` — so there is no empty-list
+ * branch here, and no path by which a hand-edited bullet silently turns this
+ * rule into a no-op.
+ *
+ * That invariant is true BECAUSE of the `valid.length > 0` guard on the
+ * denominator arm of `parseRebaselineMatrix`, not by luck. It was false until
+ * WR-01: the arm keyed on the SPLIT token count, so an all-invalid bullet
+ * recorded `[]` — non-null, and non-null is the only thing the guard below
+ * tests. Anything that widens that arm back to "any token at all" breaks the
+ * contract this comment states, and is a change to the coverage rule rather
+ * than a change to the parser.
+ *
+ * The denominator tokens and the `Phase` cells
+ * share ONE grammar, so coverage is a plain set difference with no normalisation
+ * step to drift.
+ */
+function enforcePhaseCoverage(rounds) {
+    const violations = [];
+    let latest = null;
+    for (const round of rounds.values()) {
+        if (latest === null || round.round > latest.round)
+            latest = round;
+    }
+    if (latest === null || latest.denominator === null)
+        return violations;
+    // A `Set`, never an object literal keyed on parsed content (T-05-06).
+    const covered = new Set();
+    for (const row of latest.rows) {
+        if (row.phase !== '')
+            covered.add(row.phase);
+    }
+    for (const token of latest.denominator) {
+        if (covered.has(token))
+            continue;
+        violations.push({
+            artifact: REBASELINE_FILE,
+            line: latest.denominatorLine ?? latest.line,
+            round: latest.round,
+            reason: 'missing_phase_row',
+            phase: sanitizeEcho(token),
+        });
+    }
+    return violations;
+}
+// ─── Aggregation ──────────────────────────────────────────────────────────────
+/**
+ * Aggregate the full re-baselining check for a project root. Collect-all-then-
+ * fail (D-08 carried forward): every fault class runs, all violations are
+ * accumulated, and the result is returned once. This layer NEVER throws.
+ *
+ * Pure aggregation: the parser's within-artifact violations, then the
+ * requirement resolution, then the phase coverage. It adds no rule of its own,
+ * so every fault this gate can report is owned by exactly one function.
+ */
+function checkRebaseline(cwd) {
+    const violations = [];
+    const dir = node_path_1.default.join(cwd, DISCOVERY_DIR);
+    let names = [];
+    try {
+        names = node_fs_1.default.readdirSync(dir);
+    }
+    catch {
+        names = []; // no discovery package at all — graceful arm (D-42)
+    }
+    const present = new Set(names);
+    // The `present.has(file)` early return is what discriminates the two
+    // conditions, and it must stay that way: ABSENT is the D-42/D-66 graceful arm
+    // and is silent, while PRESENT-BUT-UNREADABLE (EACCES, EISDIR, a dangling
+    // symlink) is a fault. Re-collapsing them would let the gate exit 0 having
+    // validated nothing at all — a fail-open on a structural verifier.
+    // The caller does not add the file to `artifactsChecked` either: an unreadable
+    // artifact was not checked, and saying it was would be a second, quieter
+    // overstatement.
+    const readArtifact = (file) => {
+        if (!present.has(file))
+            return null;
+        try {
+            return node_fs_1.default.readFileSync(node_path_1.default.join(dir, file), 'utf-8');
+        }
+        catch {
+            violations.push({ artifact: file, reason: 'artifact_unreadable' });
+            return null;
+        }
+    };
+    const artifactsChecked = [];
+    const rebaselineContent = readArtifact(REBASELINE_FILE);
+    // Absent — and ONLY absent, which is why the unreadable fault is tested for
+    // rather than assumed away. A project that has never re-baselined is wholly
+    // unaffected by this gate: most engagements never re-baseline, and a check
+    // that reddened on the absence would turn a variation nobody triggered into a
+    // red gate for everybody (D-42/D-66).
+    if (rebaselineContent === null && violations.length === 0) {
+        return {
+            ok: true,
+            artifacts_checked: artifactsChecked,
+            rounds: 0,
+            latest_round: null,
+            requirements: 'absent',
+        };
+    }
+    if (rebaselineContent !== null)
+        artifactsChecked.push(REBASELINE_FILE);
+    // A null here is the unreadable arm; the parser guards non-string input and
+    // yields an empty result, so the `artifact_unreadable` fault stands alone
+    // rather than collecting a cascade of derived faults about a file nobody read.
+    const parsed = parseRebaselineMatrix(rebaselineContent);
+    violations.push(...parsed.violations);
+    // `_requirements.md` is owned by `discovery rollup`; this gate consumes its
+    // single exported reader and NOTHING else. A grammar fault there is reported
+    // ONCE, by name, pointing at the owning gate — never re-enumerated here.
+    let knownIds = null;
+    let requirements = 'absent';
+    const requirementsContent = readArtifact(REQUIREMENTS_FILE);
+    if (requirementsContent !== null) {
+        artifactsChecked.push(REQUIREMENTS_FILE);
+        const parsedRequirements = rollup.parseRequirementsArtifact(requirementsContent);
+        if (parsedRequirements.ok) {
+            knownIds = new Set(parsedRequirements.rows.map(r => r.id));
+            requirements = 'ok';
+        }
+        else {
+            requirements = 'unparseable';
+            violations.push({ artifact: REQUIREMENTS_FILE, reason: 'requirements_unparseable' });
+        }
+    }
+    violations.push(...resolveRequirements(parsed.rows, knownIds));
+    violations.push(...enforcePhaseCoverage(parsed.rounds));
+    // Folded, never spread: `Math.max(...keys)` throws `RangeError` on a large
+    // array, and the round map is keyed off artifact content.
+    let latestRound = null;
+    for (const round of parsed.rounds.keys()) {
+        if (latestRound === null || round > latestRound)
+            latestRound = round;
+    }
+    const summary = {
+        artifacts_checked: artifactsChecked,
+        rounds: parsed.rounds.size,
+        latest_round: latestRound,
+        requirements,
+    };
+    if (violations.length > 0)
+        return { ok: false, violations, ...summary };
+    return { ok: true, ...summary };
+}
+// ─── CLI adapter ──────────────────────────────────────────────────────────────
+/**
+ * One content-free line per violation, two-space indented (T-05-01).
+ *
+ * This is the SINGLE chokepoint at which a detail string is BUILT: every
+ * author-supplied value below routes through `sanitizeEcho`, so a reason code
+ * added to the tuple inherits the confidentiality bound by construction rather
+ * than by the author of that code remembering it. The reason code and the enum
+ * field name are deliberately NOT sanitized — both come from closed unions
+ * declared in this module and are not author data.
+ *
+ * Eight of the fifteen codes emit NO detail at all. That is deliberate and it
+ * is the interesting half: the cell behind each of them has passed no
+ * validation, so there is nothing about it that is safe to quote, and the
+ * `<artifact>:<row>` locator finds the row instead. The `default` arm emits
+ * nothing for the same reason — a new code must opt IN to an echo rather than
+ * inherit an unbounded one by falling through.
+ */
+function formatViolation(v) {
+    const where = v.artifact ?? '';
+    const locator = v.line === undefined ? where : `${where}:${v.line}`;
+    let detail = '';
+    switch (v.reason) {
+        case 'unknown_requirement_id':
+            // Populated only on the resolves-to-nothing arm; the wrong-shape arm
+            // leaves it undefined and therefore renders as locator-plus-reason.
+            detail = sanitizeEcho(v.id);
+            break;
+        case 'missing_phase_row':
+            // Both halves have passed their grammars: the round number came out of
+            // `ROUND_HEADING_RE` and the phase token out of `PHASE_TOKEN_RE`.
+            detail = `round ${v.round}: ${sanitizeEcho(v.phase)}`;
+            break;
+        case 'duplicate_id':
+            // A duplicated phase names the phase; a duplicated round heading names the
+            // round. Both are validated tokens.
+            detail = v.phase === undefined ? `round ${v.round}` : sanitizeEcho(v.phase);
+            break;
+        case 'sequence_gap':
+            // The locator names the MISSING round number, so a deleted round cannot
+            // lapse unnoticed (D-41/D-66). Past the shared bound there is no single
+            // missing number to name and the detail is correctly empty.
+            detail = v.round === undefined ? '' : `round ${v.round}`;
+            break;
+        case 'bad_disposition':
+        case 'bad_built_status':
+            // The bounded value token of a CLOSED-ENUM cell: the operator needs to see
+            // which value was rejected, and the alternative — naming the column and
+            // nothing else — makes a typo unfindable in a six-column row.
+            detail = sanitizeEcho(v.cell);
+            break;
+        case 'requirements_unparseable':
+            // Names the owning gate and stops. This gate never re-enumerates that
+            // gate's errors — one artifact, one owner, one report.
+            detail = 'run: discovery rollup --check';
+            break;
+        case 'bad_id':
+        case 'bad_phase_token':
+        case 'bad_clause_citation':
+        case 'disposition_without_reason':
+        case 'missing_round_metadata':
+        case 'missing_section':
+        case 'artifact_unreadable':
+        // The fence line is a LOCATOR and nothing more. Nothing inside or around a
+        // block the parser could not delimit has passed a grammar, so there is
+        // nothing about it that is safe to echo (T-05-01) — and echoing the fence
+        // line itself would quote the first line of a block whose whole content is
+        // unvalidated author text.
+        case 'unterminated_fence':
+            detail = '';
+            break;
+        default:
+            detail = '';
+    }
+    return detail === '' ? `  ${locator}: ${v.reason}` : `  ${locator}: ${v.reason} (${detail})`;
+}
+/**
+ * CLI adapter for `pp-tools discovery rebaseline-check` (dotted form
+ * `pp-tools query discovery.rebaseline-check`).
+ *
+ * Exit semantics (D-72/D-73): any structural violation exits non-zero via
+ * `DISCOVERY_REBASELINE_CHECK_FAILED`, naming each violation by artifact, row
+ * and reason. An ABSENT `_rebaseline.md` exits 0 — the graceful arm — while a
+ * present-but-unreadable one is a fault.
+ *
+ * The command accepts NO positional path argument at all: the convention paths
+ * under `.planning/discovery/` resolve against cwd, which ELIMINATES the
+ * traversal surface rather than guarding it (T-05-14). There is no path to
+ * normalise, no symlink to resolve and no allow-list to keep in step with the
+ * filesystem, because there is no caller-supplied path.
+ */
+function cmdDiscoveryRebaselineCheck(cwd, args, raw) {
+    // args arrive shaped ['discovery', 'rebaseline-check', ...]; global output and
+    // workstream flags are consumed by the dispatcher before dispatch, so anything
+    // left — a positional path or an unknown flag alike — is a usage error.
+    if (args.slice(2).length > 0) {
+        error('Usage: pp-tools discovery rebaseline-check', REBASELINE_CHECK_USAGE);
+        return; // unreachable — error() exits
+    }
+    const result = checkRebaseline(cwd);
+    if (!result.ok) {
+        const total = result.violations.length;
+        const rendered = result.violations.slice(0, MAX_REPORTED_VIOLATIONS).map(formatViolation);
+        if (total > MAX_REPORTED_VIOLATIONS) {
+            rendered.push(`  … and ${total - MAX_REPORTED_VIOLATIONS} more`);
+        }
+        // Emitted on stdout BEFORE the envelope goes to stderr, so the ordering is
+        // deterministic: `output` writes fd 1 synchronously and `error` exits. The
+        // payload is a second output surface and inherits the content-free contract
+        // (T-05-01) by construction: counts, a closed-vocabulary value and artifact
+        // filenames only, never a matrix cell.
+        output({
+            ok: false,
+            violations: total,
+            artifacts_checked: result.artifacts_checked,
+            rounds: result.rounds,
+            latest_round: result.latest_round,
+            requirements: result.requirements,
+        }, raw);
+        error(`discovery rebaseline-check: ${total} violation(s):\n${rendered.join('\n')}`, REBASELINE_CHECK_FAILED);
+        return; // unreachable — error() exits
+    }
+    output({
+        ok: true,
+        artifacts_checked: result.artifacts_checked,
+        rounds: result.rounds,
+        latest_round: result.latest_round,
+        requirements: result.requirements,
+    }, raw);
+}
+module.exports = {
+    SCOPE_STATES,
+    BUILT_STATES,
+    VIOLATION_REASONS,
+    MATRIX_HEADER_CELLS,
+    MATRIX_COL,
+    ECHO_MAX_CHARS,
+    // Exported so the tests derive their over-bound payload from the bound under
+    // test rather than from a second copy of the number, and so the value the
+    // reference states by number is pinnable against the engine (WR-03).
+    DENOMINATOR_MAX_CHARS,
+    MAX_REPORTED_VIOLATIONS,
+    DISCOVERY_DIR,
+    REBASELINE_FILE,
+    REQUIREMENTS_FILE,
+    NOT_APPLICABLE,
+    REBASELINE_CHECK_FAILED,
+    REBASELINE_CHECK_USAGE,
+    sanitizeEcho,
+    parseRebaselineMatrix,
+    // Exported so the bounded-span floor can be falsified through THIS engine
+    // rather than only through the shared leaf. The round grammar is two digits,
+    // so the out-of-band arm is unreachable end to end and a test can only reach
+    // it by calling the validator with the numbers directly.
+    validateRoundSequence,
+    resolveRequirements,
+    enforcePhaseCoverage,
+    checkRebaseline,
+    cmdDiscoveryRebaselineCheck,
+};