@pareto4/pp-core 1.11.0 → 1.12.0

package/pp-core/bin/lib/discovery-research-track.cjs

@@ -0,0 +1,979 @@
+"use strict";
+/**
+ * Discovery research-track enforcement engine (discovery-v2 Phase 3,
+ * RTRK-01/RTRK-02/RTRK-03 + TRACE-05, D-33..D-48).
+ *
+ * Read-only structural validator over the three per-engagement research
+ * registers — `.planning/discovery/_research.md` (the backlog),
+ * `_risks.md` (the data-gathering register) and `_sparring.md` (the position
+ * tracker) — plus every `⚠️ CONDITIONAL —` marker in the session files and
+ * `_context.md` that cites them.
+ *
+ * Fail-loud (D-42), one bullet per fault class:
+ *   - bad_id / duplicate_id — a register row whose ID is not `^(RS|DG|SP)-\d{2}$`,
+ *     or a second row claiming an ID already seen
+ *   - sequence_gap — a family's observed numbers are not exactly `01..max`;
+ *     the reported id is the MISSING one, so a deleted row cannot lapse (D-41)
+ *   - bad_enum — Priority (D-34), Affects, Source (D-37), Feeds (D-40) or
+ *     Status outside its closed vocabulary, carrying the offending `field`
+ *   - closed_without_evidence — a bare `Closed`, or `Closed (<evidence>)` whose
+ *     evidence is neither `D-<ss>-<n>` nor a repo-relative file that exists (D-35)
+ *   - missing_owner — an `Open` row with an empty Owner cell
+ *   - unknown_requirement_id / gates_nothing — a `Gates what?` / `Blocks` ID
+ *     absent from `_requirements.md`, or a `Gates-MVP` item gating nothing (D-36)
+ *   - unknown_marker_target / stale_marker — a ⚠️ marker naming an ID with no
+ *     register row, or citing an item already `Closed` (TRACE-05)
+ *   - conditional_frontmatter_drift — a file's `conditional:` frontmatter and its
+ *     body markers disagree; derived state is validated, never trusted (D-12)
+ *   - requirements_unparseable — `_requirements.md` fails its own gate; reported
+ *     ONCE, naming the owning gate, never by re-enumerating rollup's errors
+ *   - artifact_unreadable — an artifact the directory listing named but that
+ *     could not be read. Deliberately distinguished from the D-42 absent arm:
+ *     "could not read it, so it's fine" is a fail-open on a gate whose whole
+ *     purpose is structural verification
+ *
+ * Graceful arms (D-42), all three independent: no `.planning/discovery/`
+ * directory at all exits 0 with an empty `artifacts_checked`; a register absent
+ * while a sibling is present checks the one it has and stays silent about the
+ * one it does not; `_requirements.md` absent skips only the D-36 existence
+ * check and every other fault class still runs.
+ *
+ * Content-free contract (T-03-04): output names artifact paths, `<file>:<row>`
+ * locators, item IDs that have already passed their family regex, field names,
+ * BOUNDED enum-cell prefixes, BOUNDED marker literals and snake_case reason
+ * codes — and nothing else. An unvalidated cell is never echoed at all: a
+ * malformed ID is located by row number, and every remaining detail is
+ * whitespace-collapsed and capped at `ECHO_MAX_CHARS` by `sanitizeEcho`, the
+ * single chokepoint inside `formatViolation`. The bound is a confidentiality
+ * control, not a formatting preference — register prose is derived from client
+ * documents (D-24). Never-blocks contract (D-43): unfinished research
+ * is not a fault — a register whose only notable feature is an `Open`
+ * `Gates-MVP` item exits 0 and reports that item under `open_by_priority`.
+ */
+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;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const fm = require("./frontmatter.cjs");
+// 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, 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-research-track.md` can
+ * be pinned against it by a test instead of by a manual diff. Verification gap 6
+ * was a documented-but-unenforced claim in that table, and what made the audit
+ * manual in the first place was that this was a compile-time-only union with
+ * nothing to enumerate at runtime. `ViolationReason` is derived from the tuple,
+ * so a code added to one is a code added to both.
+ *
+ * Append-only by convention: `artifact_unreadable` sits last so the twelve
+ * earlier entries keep their positions and the reference table extends by a row
+ * rather than being reordered.
+ */
+const VIOLATION_REASONS = Object.freeze([
+    'bad_id',
+    'duplicate_id',
+    'sequence_gap',
+    'bad_enum',
+    'missing_owner',
+    'gates_nothing',
+    'closed_without_evidence',
+    'unknown_requirement_id',
+    'unknown_marker_target',
+    'stale_marker',
+    'requirements_unparseable',
+    'conditional_frontmatter_drift',
+    'artifact_unreadable',
+]);
+// ─── Constants ────────────────────────────────────────────────────────────────
+/** D-34: the three research priorities. `Gates-MVP` is the only blocking-shaped one. */
+const PRIORITY = Object.freeze({
+    GATES_MVP: 'Gates-MVP',
+    BEFORE_GO_LIVE: 'Before-go-live',
+    PARALLEL: 'Parallel',
+});
+/** D-35: one close grammar across all three registers — `Open` or `Closed (<evidence>)`. */
+const ITEM_STATUS = Object.freeze({ OPEN: 'Open', CLOSED: 'Closed' });
+/** The `_risks.md` Affects vocabulary (lowercase). */
+const AFFECTS = Object.freeze({ INPUT: 'input', PROCESS: 'process', OUTPUT: 'output' });
+/** The marker literal — single home: references/discovery-id-conventions.md § Conditional Marker. */
+const CONDITIONAL_MARKER = '⚠️ CONDITIONAL —';
+/**
+ * The confidentiality bound on every echoed detail (T-03-04, D-24) — a
+ * whitespace-collapsed prefix length, not a formatting preference. Register
+ * prose is derived from client documents, so the report caps what it can
+ * repeat rather than trusting each call site to be careful; applying it at ONE
+ * place (`sanitizeEcho`, inside `formatViolation`) is what stops a future
+ * fault class from reopening the hole.
+ *
+ * The value is chosen from BOTH sides. Above it sits nothing legitimate: the
+ * longest echo the contract itself produces is the marker literal
+ * `⚠️ CONDITIONAL — RS-01`, which is 22 JS characters because `⚠️` is two code
+ * units — so 24 leaves exactly 2 characters of headroom and a well-formed
+ * value is never truncated. Below it sits the security suite's 33-character
+ * canary, which must not fit. Both sides are pinned by test rather than by
+ * this comment: 2 characters of headroom is thin enough that a longer ID
+ * family or an edit to the marker literal would silently truncate valid
+ * output, and an unpinned floor would let a later edit lower the constant into
+ * legitimate output with no test explaining the breakage.
+ */
+const ECHO_MAX_CHARS = 24;
+/**
+ * The cap on how many violations the failure message RENDERS. A register with
+ * thousands of malformed rows would otherwise inline one line each into the
+ * `--json-errors` JSON `message` (03-REVIEW IN-05). 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, and the tail line
+ * names how many were withheld.
+ */
+const MAX_REPORTED_VIOLATIONS = 50;
+const DISCOVERY_DIR = '.planning/discovery';
+const RESEARCH_FILE = '_research.md';
+const RISKS_FILE = '_risks.md';
+const SPARRING_FILE = '_sparring.md';
+const REQUIREMENTS_FILE = '_requirements.md';
+const CONTEXT_FILE = '_context.md';
+/** The em dash an author writes to mean "nothing here" in an ID-bearing cell. */
+const NOT_APPLICABLE = '—';
+// Anchored, non-backtracking regexes (threat T-03-02). 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. The
+// register content may be derived from client documents, so a catastrophic
+// backtracking pattern here would be a denial-of-service surface.
+const RS_ID_RE = /^RS-\d{2}$/;
+const DG_ID_RE = /^DG-\d{2}$/;
+const SP_ID_RE = /^SP-\d{2}$/;
+const SEPARATOR_ROW_RE = /^\s*\|[\s:|-]+\|\s*$/;
+/** D-35 evidence form 1: a decision ID. Form 2 is an existing repo-relative path. */
+const EVIDENCE_DECISION_RE = /^D-\d{2}-\d+$/;
+const CLOSED_EVIDENCE_RE = /^Closed \((.+)\)$/;
+/** D-37 Source vocabulary. */
+const SOURCE_RE = /^(DG-\d{2}|SP-\d{2}|S\d+|D-\d{2}-\d+)$/;
+/** D-40 Feeds: comma-separated session refs. */
+const FEEDS_RE = /^S\d+$/;
+/** A requirement ID as `_requirements.md` mints them (rollup's ROW_ID_RE shape). */
+const REQUIREMENT_ID_RE = /^[A-Z][A-Z0-9]*-\d+$/;
+/**
+ * Deliberately PERMISSIVE: it captures any non-whitespace token before the em
+ * dash rather than baking `SP-\d{2}` into the pattern. The strict form made
+ * `SP_ID_RE` unreachable, so a malformed heading matched nothing, fell through
+ * the `### ` flush and vanished with zero violations (03-REVIEW WR-01) — a
+ * warn-and-skip in all but name, which D-08 forbids. The family claim is what
+ * scopes the parser now, exactly as the two table parsers scope themselves on
+ * their first cell; validation is `SP_ID_RE`'s job, done in the loop.
+ */
+const SPARRING_HEAD_RE = /^### (\S+) — (.+)$/;
+const SPARRING_FIELD_RE = /^- \*\*(Position|Key point|To nail down|DECISION|Residual risk accepted|Feeds|Status):\*\* (.*)$/;
+/** D-45: the marker owns its whole line; the optional continuation is ` · <description>`. */
+const CONDITIONAL_RE = /^⚠️ CONDITIONAL — (RS-\d{2}|DG-\d{2})( · .+)?$/;
+/** Fixed-shape filename filter — never a regex over untrusted content. */
+const SESSION_FILE_RE = /^session-\d{2}\.md$/;
+const PRIORITY_LOOKUP = new Map(Object.values(PRIORITY).map(v => [v.toLowerCase(), v]));
+const AFFECTS_LOOKUP = new Map(Object.values(AFFECTS).map(v => [v.toLowerCase(), v]));
+// ─── Shared cell helpers ──────────────────────────────────────────────────────
+// The escape-aware cell splitter this module used to own now lives in the
+// `discovery-table.cjs` leaf as `splitTableCells` (discovery-v2 Phase 4, D-60), so the
+// screen-inventory parser reads free-text cells by exactly the same rule rather
+// than by a second copy of it. The behaviour is unchanged: `Item`
+// (`_research.md`) and `Data to obtain` (`_risks.md`) are declared FREE TEXT by
+// the reference, so a naive `.split('|')` would shift every subsequent column
+// (`03-REVIEW.md` § CR-02); the correctly-escaped `\|` is the author's
+// documented workaround, written into the Shared grammar by Plan 03-09. The
+// regex rationale (fixed-width, quantifier-free lookbehind over a single
+// already-split line — T-03-02) travelled with the function.
+/**
+ * Collect the pipe-table row lines of a register. Unlike the rollup parser's
+ * `sectionRows`, a `## ` heading here is a section START, not a stop: D-32
+ * makes H2s theme groupings inside `_research.md`, so the register is the union
+ * of every themed table. Header and separator rows are skipped by SHAPE, not by
+ * header text — the positional contract (D-26 precedent).
+ */
+function registerRows(content) {
+    const lines = content.split(/\r?\n/);
+    const rows = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (!trimmed.includes('|'))
+            continue;
+        if (SEPARATOR_ROW_RE.test(line))
+            continue;
+        if (i + 1 < lines.length && SEPARATOR_ROW_RE.test(lines[i + 1]))
+            continue;
+        rows.push({ line, num: i + 1 });
+    }
+    return rows;
+}
+/**
+ * D-41 sequence integrity. For a family with any rows, the observed numbers
+ * must be exactly `01..max`; each hole is reported as a `sequence_gap` whose
+ * `id` is the MISSING id — that is what makes non-lapse mechanical: a deleted
+ * row leaves a hole the parser names, so history is never the enforcement
+ * mechanism. A family with zero rows has no gaps.
+ *
+ * The maximum is taken through the shared `boundedSequenceMax` fold rather than
+ * `Math.max(...seqs)`. This engine's exposure was never the screens engine's
+ * uncatchable out-of-memory abort — `RS-`/`DG-`/`SP-` are all two digits, so
+ * the value cannot exceed 99 and the loop below cannot amplify — it was a
+ * `RangeError` from the spread on a register of a few hundred thousand rows,
+ * which the CLI already catches. Symmetry and defence in depth, adopted so the
+ * two engines cannot drift again (04-SECURITY AR-04-02).
+ */
+function validateSequence(artifact, family, seqs) {
+    const violations = [];
+    if (seqs.length === 0)
+        return violations;
+    const seen = new Set(seqs);
+    const max = boundedSequenceMax(seqs);
+    if (max === null) {
+        // Unreachable through the two-digit family grammars, and stated as such:
+        // this is the independent floor, not the primary guard. One bounded fault
+        // instead of a gap list nobody could read.
+        return [{ artifact, reason: 'bad_id' }];
+    }
+    for (let n = 1; n <= max; n += 1) {
+        if (!seen.has(n)) {
+            violations.push({ artifact, id: `${family}-${String(n).padStart(2, '0')}`, reason: 'sequence_gap' });
+        }
+    }
+    return violations;
+}
+/**
+ * Does a `Closed (<path>)` evidence cell name an existing REGULAR FILE strictly
+ * beneath the project root?
+ *
+ * That is the whole rule, and it is the only mechanism enforcing the Definition
+ * of Done: closing a research item means pointing at the decision that settled
+ * it or the artifact that answered it, so a directory is neither and is
+ * refused. The project root is refused with it — `existsSync` plus the old
+ * `target !== root` allowance made `Closed (.)` a one-character bypass of the
+ * whole rule (03-REVIEW WR-02). A symlink to a directory is refused for the
+ * same reason, since `statSync` resolves it before the type test.
+ *
+ * The T-03-07 posture is unchanged and merely narrowed from exists to
+ * is-a-regular-file: an absolute path, a null byte, or anything escaping `cwd`
+ * after resolution is refused outright rather than probed, the file is NEVER
+ * read, and nothing but resolves / does-not-resolve is ever reported — so the
+ * cell remains unusable as an exfiltration channel.
+ */
+function evidenceResolves(cwd, evidence) {
+    if (evidence.includes('\0') || node_path_1.default.isAbsolute(evidence))
+        return false;
+    const root = node_path_1.default.resolve(cwd);
+    const target = node_path_1.default.resolve(root, evidence);
+    // Strictly beneath: with the root allowance gone, `.` resolves to the root
+    // itself and is refused here, before any filesystem call happens at all.
+    if (!target.startsWith(root + node_path_1.default.sep))
+        return false;
+    try {
+        return node_fs_1.default.statSync(target).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * D-35 status grammar, shared by all three registers. `Open` passes.
+ * `Closed (<evidence>)` passes when the evidence is a decision ID or an
+ * existing repo-relative file. A bare `Closed`, or evidence that does not
+ * resolve, is `closed_without_evidence` — "we talked about it" is not a close.
+ * Anything that is neither `Open` nor `Closed`-stemmed is `bad_enum`.
+ */
+function validateStatus(cwd, artifact, id, cell) {
+    const value = cell.trim();
+    if (value === ITEM_STATUS.OPEN)
+        return [];
+    if (!value.startsWith(ITEM_STATUS.CLOSED)) {
+        return [{ artifact, id, reason: 'bad_enum', field: 'status', cell: value }];
+    }
+    const match = CLOSED_EVIDENCE_RE.exec(value);
+    const evidence = match ? match[1].trim() : '';
+    if (evidence === '')
+        return [{ artifact, id, reason: 'closed_without_evidence', evidence: '' }];
+    if (EVIDENCE_DECISION_RE.test(evidence))
+        return [];
+    if (evidenceResolves(cwd, evidence))
+        return [];
+    return [{ artifact, id, reason: 'closed_without_evidence', evidence }];
+}
+/**
+ * D-36 existence check for an ID-bearing join cell (`Gates what?` / `Blocks`).
+ * `—` gates nothing and is handled by the caller. Every comma-separated token
+ * must both look like a requirement ID and be present in `_requirements.md`;
+ * a token that fails either test is reported with the token itself, never the
+ * surrounding cell prose.
+ */
+function validateRequirementRefs(artifact, id, cell, knownIds) {
+    const violations = [];
+    for (const token of cell.split(',').map(t => t.trim()).filter(Boolean)) {
+        if (!REQUIREMENT_ID_RE.test(token) || !knownIds.has(token)) {
+            violations.push({ artifact, id, reason: 'unknown_requirement_id', cell: token });
+        }
+    }
+    return violations;
+}
+/** Comma-separated `S\d+` list, or the em dash (D-40). */
+function feedsAreValid(cell) {
+    if (cell === NOT_APPLICABLE || cell === '')
+        return true;
+    return cell.split(',').map(t => t.trim()).filter(Boolean).every(t => FEEDS_RE.test(t));
+}
+// ─── Register parsers ─────────────────────────────────────────────────────────
+/**
+ * Parse `_research.md` into typed rows. Column order is positional
+ * (`ID | Item | Priority | Gates what? | Source | Owner | Status`) — header
+ * text is never matched, so a header respelling cannot silently change what
+ * is parsed. Only the shape/enum faults live here; the cross-artifact checks
+ * (status evidence, requirement existence) need `cwd` and the requirement ID
+ * set, so they run in `checkResearchTrack`.
+ */
+function parseResearchBacklog(content) {
+    const rows = [];
+    const violations = [];
+    if (typeof content !== 'string' || content === '')
+        return { rows, violations };
+    const seen = new Set();
+    for (const { line, num } of registerRows(content)) {
+        const cells = splitTableCells(line);
+        const id = cells[0] ?? '';
+        // A row is a register row when its first cell claims the family prefix.
+        // Rows belonging to some other table in the document are not this
+        // register's business; a claimed-but-malformed ID is (never warn-and-skip)
+        // — and it is reported by its position in the file, never by its content.
+        if (!id.startsWith('RS-'))
+            continue;
+        if (!RS_ID_RE.test(id)) {
+            // Reported by POSITION, never by content: the first cell has not passed
+            // any validation at this point, so it is arbitrary author prose that the
+            // report must not repeat (T-03-04). The row number the loop already
+            // holds locates it exactly as well.
+            violations.push({ artifact: RESEARCH_FILE, reason: 'bad_id', line: num });
+            continue;
+        }
+        if (seen.has(id)) {
+            violations.push({ artifact: RESEARCH_FILE, id, reason: 'duplicate_id' });
+            continue;
+        }
+        seen.add(id);
+        const priorityCell = cells[2] ?? '';
+        const gates = cells[3] ?? '';
+        const sourceCell = cells[4] ?? '';
+        const owner = cells[5] ?? '';
+        const status = cells[6] ?? '';
+        const priority = PRIORITY_LOOKUP.get(priorityCell.toLowerCase()) ?? '';
+        if (priority === '') {
+            violations.push({ artifact: RESEARCH_FILE, id, reason: 'bad_enum', field: 'priority', cell: priorityCell });
+        }
+        if (sourceCell !== NOT_APPLICABLE && sourceCell !== '' && !SOURCE_RE.test(sourceCell)) {
+            violations.push({ artifact: RESEARCH_FILE, id, reason: 'bad_enum', field: 'source', cell: sourceCell });
+        }
+        if (owner === '' && status.trim() === ITEM_STATUS.OPEN) {
+            violations.push({ artifact: RESEARCH_FILE, id, reason: 'missing_owner' });
+        }
+        // D-36: an item declared to gate the MVP that gates nothing is a
+        // contradiction, and it is a contradiction whether or not
+        // `_requirements.md` exists — so this check never depends on the ID set.
+        if (priority === PRIORITY.GATES_MVP && (gates === NOT_APPLICABLE || gates === '')) {
+            violations.push({ artifact: RESEARCH_FILE, id, reason: 'gates_nothing' });
+        }
+        rows.push({
+            id,
+            seq: parseInt(id.slice(3), 10),
+            item: cells[1] ?? '',
+            priority,
+            gates,
+            source: sourceCell,
+            owner,
+            status,
+            line: num,
+        });
+    }
+    violations.push(...validateSequence(RESEARCH_FILE, 'RS', rows.map(r => r.seq)));
+    return { rows, violations };
+}
+/**
+ * Parse `_risks.md` — the data-gathering register, NOT a risk log. Positional
+ * order `ID | Data to obtain | Affects | Blocks | Owner | Feeds | Status`.
+ */
+function parseRiskRegister(content) {
+    const rows = [];
+    const violations = [];
+    if (typeof content !== 'string' || content === '')
+        return { rows, violations };
+    const seen = new Set();
+    for (const { line, num } of registerRows(content)) {
+        const cells = splitTableCells(line);
+        const id = cells[0] ?? '';
+        if (!id.startsWith('DG-'))
+            continue;
+        if (!DG_ID_RE.test(id)) {
+            // As in `parseResearchBacklog`: a claimed-but-malformed ID is this
+            // register's business (never warn-and-skip), but the row is reported by
+            // position, never by content.
+            violations.push({ artifact: RISKS_FILE, reason: 'bad_id', line: num });
+            continue;
+        }
+        if (seen.has(id)) {
+            violations.push({ artifact: RISKS_FILE, id, reason: 'duplicate_id' });
+            continue;
+        }
+        seen.add(id);
+        const affectsCell = cells[2] ?? '';
+        const owner = cells[4] ?? '';
+        const feeds = cells[5] ?? '';
+        const status = cells[6] ?? '';
+        const affects = AFFECTS_LOOKUP.get(affectsCell.toLowerCase()) ?? '';
+        if (affects === '') {
+            violations.push({ artifact: RISKS_FILE, id, reason: 'bad_enum', field: 'affects', cell: affectsCell });
+        }
+        if (!feedsAreValid(feeds)) {
+            violations.push({ artifact: RISKS_FILE, id, reason: 'bad_enum', field: 'feeds', cell: feeds });
+        }
+        if (owner === '' && status.trim() === ITEM_STATUS.OPEN) {
+            violations.push({ artifact: RISKS_FILE, id, reason: 'missing_owner' });
+        }
+        rows.push({
+            id,
+            seq: parseInt(id.slice(3), 10),
+            data: cells[1] ?? '',
+            affects,
+            blocks: cells[3] ?? '',
+            owner,
+            feeds,
+            status,
+            line: num,
+        });
+    }
+    violations.push(...validateSequence(RISKS_FILE, 'DG', rows.map(r => r.seq)));
+    return { rows, violations };
+}
+/**
+ * Parse `_sparring.md` — a BLOCK parser, not a table parser (D5). A position
+ * evolves in place, including reversals, so its fields are multi-sentence prose
+ * that a pipe table cannot hold; the H3 block form also removes `|`-in-prose as
+ * a parser-fragility class entirely. `SPARRING_HEAD_RE` proposes a position,
+ * `SPARRING_FIELD_RE` fills it, and the next `### ` or EOF closes it.
+ *
+ * Every `### ` line is handled by ONE branch, which decides in this order: the
+ * head regex is permissive, so the candidate token is taken from its capture or
+ * — when the heading is too malformed to match at all — from the first word
+ * after the prefix. A token that does not claim the `SP-` family is not this
+ * register's business and is silently ignored (an appendix H3 must never become
+ * a false fault). A token that DOES claim the family and then fails either the
+ * full heading shape or `SP_ID_RE` is a `bad_id` — never warn-and-skip (D-08).
+ * Only a token passing both opens a position.
+ *
+ * The violation reports the row position ONLY: at that point the token has
+ * passed no validation, so there is nothing about it safe to quote (T-03-04),
+ * which is the same content-free shape the two table registers emit.
+ */
+function parseSparringTracker(content) {
+    const rows = [];
+    const violations = [];
+    if (typeof content !== 'string' || content === '')
+        return { rows, violations };
+    const seen = new Set();
+    const lines = content.split(/\r?\n/);
+    let current = null;
+    let currentValid = false;
+    const flush = () => {
+        if (current && currentValid)
+            rows.push(current);
+        current = null;
+        currentValid = false;
+    };
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (line.startsWith('### ')) {
+            const head = SPARRING_HEAD_RE.exec(line);
+            // When the heading is too malformed for the head regex, the candidate is
+            // still recoverable as the first word after the prefix — which is what
+            // lets `### SP-01 Retention window` be caught rather than dropped.
+            const token = head !== null ? head[1] : (line.slice(4).trim().split(/\s+/)[0] ?? '');
+            // Any `### ` closes the open block, whoever it belongs to.
+            flush();
+            if (!token.startsWith('SP-'))
+                continue;
+            if (head === null || !SP_ID_RE.test(token)) {
+                violations.push({ artifact: SPARRING_FILE, reason: 'bad_id', line: i + 1 });
+                continue;
+            }
+            const id = token;
+            if (seen.has(id)) {
+                violations.push({ artifact: SPARRING_FILE, id, reason: 'duplicate_id' });
+                continue;
+            }
+            seen.add(id);
+            current = {
+                id,
+                seq: parseInt(id.slice(3), 10),
+                question: head[2],
+                position: '',
+                decision: '',
+                feeds: '',
+                status: '',
+                line: i + 1,
+            };
+            currentValid = true;
+            continue;
+        }
+        if (!current)
+            continue;
+        const field = SPARRING_FIELD_RE.exec(line);
+        if (!field)
+            continue;
+        const value = field[2].trim();
+        if (field[1] === 'Position')
+            current.position = value;
+        else if (field[1] === 'DECISION')
+            current.decision = value;
+        else if (field[1] === 'Feeds')
+            current.feeds = value;
+        else if (field[1] === 'Status')
+            current.status = value;
+    }
+    flush();
+    for (const row of rows) {
+        if (!feedsAreValid(row.feeds)) {
+            violations.push({ artifact: SPARRING_FILE, id: row.id, reason: 'bad_enum', field: 'feeds', cell: row.feeds });
+        }
+    }
+    violations.push(...validateSequence(SPARRING_FILE, 'SP', rows.map(r => r.seq)));
+    return { rows, violations };
+}
+// ─── Conditional markers (TRACE-05) ───────────────────────────────────────────
+/**
+ * Find every well-formed `⚠️ CONDITIONAL —` marker. Split by line FIRST, then
+ * apply the anchored regex to each single line (T-03-02). D-45 requires the
+ * marker to own its whole line, so a marker mentioned mid-sentence in prose is
+ * not a marker and is deliberately not returned.
+ */
+function findConditionalMarkers(content) {
+    const markers = [];
+    if (typeof content !== 'string' || content === '')
+        return markers;
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+        const trimmed = lines[i].trim();
+        if (!trimmed.startsWith(CONDITIONAL_MARKER))
+            continue;
+        const match = CONDITIONAL_RE.exec(trimmed);
+        if (!match)
+            continue;
+        markers.push({ id: match[1], line: i + 1, description: match[2] ? match[2].slice(3) : '' });
+    }
+    return markers;
+}
+/**
+ * Lines that CLAIM to be markers but fail the anchored grammar — an
+ * unrecognised ID family, a typo'd ID, a stray suffix. Returned as sanitized
+ * literals (`<marker> <bounded first token>`) so a malformed marker can never
+ * hide behind its own malformedness, while its trailing prose still cannot
+ * leak into the report (T-03-04).
+ *
+ * First-token-only is NOT sufficient on its own: the first whitespace-
+ * delimited token is itself unbounded author text, and a hyphen-joined client
+ * phrase is a single token (reproduced in `03-REVIEW.md` § CR-01). So the
+ * token is length-bounded here as well, and the assembled literal passes
+ * through `sanitizeEcho` again at the `formatViolation` chokepoint.
+ */
+function findMalformedMarkers(content) {
+    const malformed = [];
+    if (typeof content !== 'string' || content === '')
+        return malformed;
+    for (const line of content.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith(CONDITIONAL_MARKER))
+            continue;
+        if (CONDITIONAL_RE.test(trimmed))
+            continue;
+        const token = trimmed.slice(CONDITIONAL_MARKER.length).trim().split(/\s+/)[0] ?? '';
+        malformed.push(`${CONDITIONAL_MARKER} ${sanitizeEcho(token)}`.trim());
+    }
+    return malformed;
+}
+/**
+ * The `conditional:` frontmatter value, normalized to a string array — read as
+ * an OWN property or not at all.
+ *
+ * D-12 inverted: frontmatter is parsed from an untrusted session file, so
+ * `conditional:` is derived state to be validated, never trusted. The concrete
+ * attack (`03-REVIEW.md` § CR-03, reproduced): `extractFrontmatter`'s key regex
+ * `[a-zA-Z0-9_-]+` admits `__proto__`, and assigning that key onto a plain
+ * object literal SETS THE PROTOTYPE rather than creating an own property — so a
+ * `__proto__:` block nesting `conditional:` satisfies an unguarded lookup,
+ * silently passing the drift gate AND writing its own value into the report's
+ * `extra` array. An inherited `conditional` must therefore never satisfy this
+ * read. This is the standing project rule in `.claude/CLAUDE.md`
+ * ("Prototype pollution guards in config access"), and the same
+ * parsed-content-never-touches-an-object-literal discipline the sibling parser
+ * documents at `src/discovery-rollup.cts:189-191`.
+ */
+function conditionalFrontmatter(front) {
+    if (!Object.prototype.hasOwnProperty.call(front, 'conditional'))
+        return [];
+    const value = front.conditional;
+    if (Array.isArray(value))
+        return value.map(v => String(v).trim()).filter(Boolean);
+    if (typeof value === 'string' && value.trim() !== '')
+        return [value.trim()];
+    return [];
+}
+// ─── Aggregation ──────────────────────────────────────────────────────────────
+/**
+ * Aggregate the full research-track 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 — an
+ * unreadable file degrades to "not present" rather than crashing the gate.
+ *
+ * Never-blocks (D-43): an `Open` item — including an `Open` `Gates-MVP` item —
+ * is NOT a violation. It is counted into `open_by_priority` so Session 13 can
+ * render "N sections conditional on M open research items" and sign off anyway.
+ */
+function checkResearchTrack(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 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 (WR-05).
+    // 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;
+        }
+    };
+    // Each register is read independently, so `_risks.md` present while
+    // `_research.md` is absent checks the one it has (graceful arm, per file).
+    const artifactsChecked = [];
+    const researchContent = readArtifact(RESEARCH_FILE);
+    const risksContent = readArtifact(RISKS_FILE);
+    const sparringContent = readArtifact(SPARRING_FILE);
+    if (researchContent !== null)
+        artifactsChecked.push(RESEARCH_FILE);
+    if (risksContent !== null)
+        artifactsChecked.push(RISKS_FILE);
+    if (sparringContent !== null)
+        artifactsChecked.push(SPARRING_FILE);
+    const research = parseResearchBacklog(researchContent ?? '');
+    const risks = parseRiskRegister(risksContent ?? '');
+    const sparring = parseSparringTracker(sparringContent ?? '');
+    violations.push(...research.violations, ...risks.violations, ...sparring.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) {
+        const parsed = rollup.parseRequirementsArtifact(requirementsContent);
+        if (parsed.ok) {
+            knownIds = new Set(parsed.rows.map(r => r.id));
+            requirements = 'ok';
+        }
+        else {
+            requirements = 'unparseable';
+            violations.push({ artifact: REQUIREMENTS_FILE, reason: 'requirements_unparseable' });
+        }
+    }
+    // Status is a cross-artifact check (evidence paths resolve against cwd), and
+    // D-36 existence needs the requirement ID set — both run here, not in the
+    // pure parsers.
+    for (const row of research.rows) {
+        violations.push(...validateStatus(cwd, RESEARCH_FILE, row.id, row.status));
+        if (knownIds !== null && row.gates !== NOT_APPLICABLE && row.gates !== '') {
+            violations.push(...validateRequirementRefs(RESEARCH_FILE, row.id, row.gates, knownIds));
+        }
+    }
+    for (const row of risks.rows) {
+        violations.push(...validateStatus(cwd, RISKS_FILE, row.id, row.status));
+        if (knownIds !== null && row.blocks !== NOT_APPLICABLE && row.blocks !== '') {
+            violations.push(...validateRequirementRefs(RISKS_FILE, row.id, row.blocks, knownIds));
+        }
+    }
+    for (const row of sparring.rows) {
+        violations.push(...validateStatus(cwd, SPARRING_FILE, row.id, row.status));
+    }
+    // Marker targets resolve against the RS/DG registers — the only two families
+    // the marker grammar admits. A Map, never an object literal keyed on parsed
+    // content (T-03-03).
+    const statuses = new Map();
+    for (const row of research.rows)
+        statuses.set(row.id, row.status.trim());
+    for (const row of risks.rows)
+        statuses.set(row.id, row.status.trim());
+    const scanned = [
+        ...names.filter(n => SESSION_FILE_RE.test(n)).sort(),
+        ...(present.has(CONTEXT_FILE) ? [CONTEXT_FILE] : []),
+    ];
+    let conditionalSections = 0;
+    for (const file of scanned) {
+        const content = readArtifact(file);
+        if (content === null)
+            continue;
+        for (const marker of findMalformedMarkers(content)) {
+            violations.push({ file, reason: 'unknown_marker_target', marker });
+        }
+        const markers = findConditionalMarkers(content);
+        conditionalSections += markers.length;
+        const bodyIds = [];
+        for (const marker of markers) {
+            if (!bodyIds.includes(marker.id))
+                bodyIds.push(marker.id);
+            const status = statuses.get(marker.id);
+            const literal = `${CONDITIONAL_MARKER} ${marker.id}`;
+            if (status === undefined) {
+                violations.push({ file, reason: 'unknown_marker_target', marker: literal });
+            }
+            else if (status.startsWith(ITEM_STATUS.CLOSED)) {
+                violations.push({ file, reason: 'stale_marker', marker: literal });
+            }
+        }
+        // D-12 inversion: the `conditional:` frontmatter is derived state, so it is
+        // validated rather than trusted. A file with no frontmatter block at all is
+        // not drift-checked (graceful arm — it has no derived state to disagree).
+        //
+        // OWN properties only, for the same reason `conditionalFrontmatter` guards
+        // its read: a file whose only frontmatter content is a prototype-shaped key
+        // declares nothing, so it has no own derived state and takes the same
+        // graceful arm as a file with no frontmatter block at all. That is the
+        // honest outcome — the alternative is to treat an injected prototype as a
+        // declaration.
+        const front = fm.extractFrontmatter(content);
+        if (Object.getOwnPropertyNames(front).length === 0)
+            continue;
+        const declared = conditionalFrontmatter(front);
+        const missing = bodyIds.filter(id => !declared.includes(id));
+        const extra = declared.filter(id => !bodyIds.includes(id));
+        if (missing.length > 0 || extra.length > 0) {
+            violations.push({ file, reason: 'conditional_frontmatter_drift', missing, extra });
+        }
+    }
+    const openByPriority = {};
+    for (const value of Object.values(PRIORITY))
+        openByPriority[value] = 0;
+    const open = { RS: 0, DG: 0, SP: 0 };
+    const closed = { RS: 0, DG: 0, SP: 0 };
+    const tally = (family, status) => {
+        const value = status.trim();
+        if (value === ITEM_STATUS.OPEN)
+            open[family] += 1;
+        else if (value.startsWith(ITEM_STATUS.CLOSED))
+            closed[family] += 1;
+    };
+    for (const row of research.rows) {
+        tally('RS', row.status);
+        if (row.status.trim() === ITEM_STATUS.OPEN && row.priority !== '') {
+            openByPriority[row.priority] += 1;
+        }
+    }
+    for (const row of risks.rows)
+        tally('DG', row.status);
+    for (const row of sparring.rows)
+        tally('SP', row.status);
+    const summary = {
+        artifacts_checked: artifactsChecked,
+        open_by_priority: openByPriority,
+        open,
+        closed,
+        conditional_sections: conditionalSections,
+        requirements,
+    };
+    if (violations.length > 0)
+        return { ok: false, violations, ...summary };
+    return { ok: true, ...summary };
+}
+// ─── CLI adapter ──────────────────────────────────────────────────────────────
+/**
+ * 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 this 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, which is 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 cell. Register prose is derived from client documents:
+ * treating it as untrusted for LENGTH while treating it as trusted for BYTES
+ * was the gap. Identical to the screens engine's constant, deliberately — the
+ * two 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 chokepoint through which every author-supplied detail reaches
+ * output. Strip the control planes, collapse whitespace, trim, and cap at
+ * `ECHO_MAX_CHARS`, appending an ellipsis when the value was longer.
+ *
+ * Both the strip and the collapse are load-bearing and must run BEFORE the
+ * slice: 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.
+ */
+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.
+    const raw = typeof value === 'string' ? value : '';
+    const collapsed = raw.replace(CONTROL_CHARS_RE, '').replace(/\s+/g, ' ').trim();
+    if (collapsed.length <= ECHO_MAX_CHARS)
+        return collapsed;
+    return `${collapsed.slice(0, ECHO_MAX_CHARS)}…`;
+}
+/**
+ * One content-free line per violation, two-space indented (T-03-04).
+ *
+ * This is the SINGLE chokepoint for echoed detail: every author-supplied value
+ * below routes through `sanitizeEcho`, so a new reason code added to the union
+ * 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.
+ *
+ * `bad_id` renders as locator-plus-reason only. Its cell has passed no
+ * validation at all, so there is nothing about it that is safe to quote; the
+ * `<artifact>:<row>` locator finds the row instead.
+ */
+function formatViolation(v) {
+    const where = v.artifact ?? v.file ?? '';
+    const locator = v.line === undefined ? where : `${where}:${v.line}`;
+    let detail = '';
+    switch (v.reason) {
+        case 'unknown_requirement_id':
+            detail = `${sanitizeEcho(v.id)} → ${sanitizeEcho(v.cell)}`;
+            break;
+        case 'bad_enum':
+            detail = `${sanitizeEcho(v.id)} ${v.field}: ${sanitizeEcho(v.cell)}`;
+            break;
+        case 'bad_id':
+            detail = '';
+            break;
+        case 'unknown_marker_target':
+        case 'stale_marker':
+            detail = sanitizeEcho(v.marker);
+            break;
+        case 'requirements_unparseable':
+            detail = 'run: discovery rollup --check';
+            break;
+        case 'conditional_frontmatter_drift': {
+            // Each ELEMENT is bounded, not just the joined array: an injected or
+            // mistyped `conditional:` entry is author data of arbitrary length.
+            const missing = (v.missing ?? []).map(sanitizeEcho).join(', ');
+            const extra = (v.extra ?? []).map(sanitizeEcho).join(', ');
+            detail = `missing: [${missing}], extra: [${extra}]`;
+            break;
+        }
+        default:
+            detail = sanitizeEcho(v.id ?? '');
+    }
+    return detail === '' ? `  ${locator}: ${v.reason}` : `  ${locator}: ${v.reason} (${detail})`;
+}
+/**
+ * CLI adapter for `pp-tools discovery research-check` (dotted form
+ * `pp-tools query discovery.research-check`).
+ *
+ * Exit semantics (D-42/D-43): any structural violation exits non-zero via
+ * ERROR_REASON.DISCOVERY_RESEARCH_CHECK_FAILED, naming each violation by
+ * artifact and reason. Unfinished research is NOT a violation — an `Open`
+ * `Gates-MVP` item exits 0 and is reported under `open_by_priority`. 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-03-01).
+ */
+function cmdDiscoveryResearchCheck(cwd, args, raw) {
+    // args arrive shaped ['discovery', 'research-check', ...]; global output
+    // flags are consumed by the dispatcher, 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 research-check', ERROR_REASON.USAGE);
+        return; // unreachable — error() exits
+    }
+    const result = checkResearchTrack(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`);
+        }
+        // D-43 holds on the failure path too: "the report tells you exactly what is
+        // still outstanding" (workflows/discovery-sprint/session-13-gates.md). A
+        // register with one malformed cell must not lose its outstanding-work
+        // report — that is exactly the state where an operator needs both halves.
+        // Emitted on stdout BEFORE the envelope goes to stderr, so the ordering is
+        // deterministic: `output` writes fd 1 synchronously and `error` exits.
+        //
+        // This payload is a second output surface and inherits the content-free
+        // contract (T-03-04) by construction: counts, closed-vocabulary enum keys
+        // and artifact filenames only, never a register cell.
+        output({
+            ok: false,
+            violations: total,
+            artifacts_checked: result.artifacts_checked,
+            open_by_priority: result.open_by_priority,
+            open: result.open,
+            closed: result.closed,
+            conditional_sections: result.conditional_sections,
+            requirements: result.requirements,
+        }, raw);
+        error(`discovery research-check: ${total} violation(s):\n${rendered.join('\n')}`, ERROR_REASON.DISCOVERY_RESEARCH_CHECK_FAILED);
+        return; // unreachable — error() exits
+    }
+    output({
+        ok: true,
+        artifacts_checked: result.artifacts_checked,
+        open_by_priority: result.open_by_priority,
+        open: result.open,
+        closed: result.closed,
+        conditional_sections: result.conditional_sections,
+        requirements: result.requirements,
+    }, raw);
+}
+module.exports = {
+    PRIORITY,
+    ITEM_STATUS,
+    AFFECTS,
+    CONDITIONAL_MARKER,
+    ECHO_MAX_CHARS,
+    VIOLATION_REASONS,
+    parseResearchBacklog,
+    parseRiskRegister,
+    parseSparringTracker,
+    // Exported so the bounded-span floor can be falsified through THIS engine
+    // rather than only through the shared leaf. All three family grammars are 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 (AR-04-02).
+    validateSequence,
+    findConditionalMarkers,
+    checkResearchTrack,
+    cmdDiscoveryResearchCheck,
+};