@pareto4/pp-core 1.11.0 → 1.12.0

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

@@ -0,0 +1,1995 @@
+"use strict";
+/**
+ * Discovery screen-inventory enforcement engine (discovery-v2 Phase 4,
+ * TRACE-02 / TRACE-03 / TRACE-04 + GUARD-01, D-49..D-59).
+ *
+ * Read-only structural validator over the per-engagement requirement-to-screen
+ * inventory `.planning/discovery/_screens.md` (D-49), the feedback-round log
+ * `.planning/discovery/_feedback.md` (D-56/D-57/D-58), the engine-computed MVP
+ * coverage assertion (D-51) and the build-tree instrumentation scan (D-54),
+ * aggregated by `checkScreenInventory` behind `pp-tools discovery screen-check`.
+ *
+ * The aggregator is PURE COMPOSITION: every rule it enforces is a NAMED,
+ * EXPORTED function declared below, so no fault class ever waited on the
+ * aggregator to become emittable or testable, and the aggregator adds no
+ * violation code, grammar rule or resolution of its own.
+ *
+ * Never-blocks contract (D-43): unprocessed feedback is not a fault — a round
+ * whose every Processing cell is `Open` exits 0 and reports those rows under
+ * `open_feedback`, so a still-running feedback loop can never block Session 13
+ * sign-off. Only STRUCTURAL faults set `ok` false, and the outstanding-work
+ * report is emitted on the failure path too.
+ *
+ * Why the contract lives in code (D-52): `/pp-discovery-to-build` and
+ * `/pp-ui-phase` each add a CALL plus a checklist row, not a second copy of the
+ * rule. Prose in two workflows drifts; a parser does not.
+ *
+ * Why the reason codes are a runtime VALUE (D-60): the reference
+ * `pp-core/references/discovery-traceability.md` and the sketch emitter are both
+ * pinned against `VIOLATION_REASONS` / `INSTRUMENTATION_LITERALS` by test rather
+ * than by manual diff. That is what makes the single-home claim mechanical
+ * instead of aspirational — the same repair Phase 3 made for the research track.
+ *
+ * Fail-loud (D-53), one bullet per fault class this plan emits:
+ *   - missing_section — `## Screens` or `## No screen (still MVP)` absent
+ *   - bad_id — a screens row whose first cell is not `SCR-\d{2}`, or a no-screen
+ *     row whose first cell is not a requirement ID. Reported by artifact plus
+ *     row number ONLY; the cell has passed no validation, so nothing about it is
+ *     safe to quote (T-04-04)
+ *   - duplicate_id — a second screens row claiming an ID already seen, or a
+ *     second no-screen bucket row claiming a requirement the bucket already
+ *     holds. The first row keeps the slot and the later one is REPORTED rather
+ *     than dropped: its cell may contradict the one already recorded. Also a
+ *     REPEATED `## Screens` / `## No screen (still MVP)` heading, which costs
+ *     the gate a whole table; the heading named is this module's own literal
+ *   - sequence_gap — the observed screen numbers are not exactly `01..max`; the
+ *     reported id is the MISSING one, so a deleted row cannot lapse (D-41)
+ *   - bad_surface_status — a surface cell that is neither the required keyword
+ *     nor the deferred keyword with a parenthesised reason. A BARE deferred
+ *     keyword lands here, per D-55: the reason is structured, not prose to be
+ *     regexed out later
+ *   - deferred_without_reason — the deferred shape with an empty or
+ *     whitespace-only reason
+ *   - no_screen_without_reason — a no-screen bucket row with an empty reason
+ *   - unknown_requirement_id — a requirement-ID token on a screen that either
+ *     does not match the family regex (the parser's arm) or matches it and
+ *     names no row of `_requirements.md` (`resolveRequirementRefs`, guarded on
+ *     a parseable requirements table). BOTH arms exist: for a long while only
+ *     the first did, and a code named for resolution that only ever meant
+ *     "malformed shape" is a trap for the next reader
+ *   - 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 graceful absent
+ *     arm: "could not read it, so it's fine" is a fail-open on a gate whose
+ *     whole purpose is structural verification
+ *   - bad_anchor — a feedback Anchor cell that is not `SCR-<nn> · <element>`
+ *     (D-58). The separator is the one D-27/D-37/D-45 established; there is no
+ *     second spelling
+ *   - bad_verdict — a Verdict cell outside the closed four-word D-58 vocabulary
+ *   - bad_processing — a Processing cell that is neither `Open`, nor
+ *     `No change`, nor a closed citation of an existing decision / `DG-` / `RS-`
+ *     ID (D-57). A BARE or prose-only cell lands here rather than in a code of
+ *     its own: D-57 calls it one structural error, not two
+ *   - unknown_screen_id — a feedback anchor naming a screen the inventory does
+ *     not contain. An ABSENT `_screens.md` yields an empty map, so every anchor
+ *     fails rather than passing vacuously — a feedback log without an inventory
+ *     is exactly the silent-omission failure GUARD-01 exists to catch
+ *   - unknown_processing_id — a `DG-`/`RS-` citation that does not resolve
+ *     against a PRESENT `_risks.md` / `_research.md`
+ *   - uncovered_mvp_requirement — an `MVP`-disposition requirement that appears
+ *     on no screen and in no no-screen bucket row (D-51)
+ *   - screens_markers — the computed-coverage marker pair is missing, doubled or
+ *     out of order. A structural property of `_screens.md` alone, so it is
+ *     checked even when `_requirements.md` is not there to compute against
+ *   - screens_mismatch — the text between the markers differs from the machine
+ *     render. Hand-writing a coverage claim is the 105-vs-106 drift D-05..D-08
+ *     exist to kill, and this phase does not reintroduce it
+ *   - instrumentation_leaked — a build-tree file carrying one of the pinned
+ *     `INSTRUMENTATION_LITERALS`. GUARD-01 asks for the absence of discovery
+ *     instrumentation to be ASSERTED, not assumed, so the fault names the
+ *     repo-relative path, the 1-based line number and the matched literal — and
+ *     NEVER the surrounding source line. D-54 asks for what was found and where,
+ *     not for the code (T-04-15). Suppressible per exact path through
+ *     `_scan-allow.txt`, so a known false positive is a recorded decision
+ *     rather than a reason to disable the whole gate
+ *   - scan_budget_exceeded — the walk hit its file-count or byte cap. Reported
+ *     as a loud fault rather than returned as a partial pass: a bounded scan
+ *     that truncates quietly is a fail-open, which is the defect class this
+ *     engine exists to close
+ *
+ * Deliberately NOT validated — the non-rules, stated here because a parser
+ * contract is only honest when it says what it does NOT check:
+ *   - the Role and Purpose cells of `_screens.md`. Role is a grouping column
+ *     (D-50) and Purpose is free text; neither has a closed grammar, so neither
+ *     is checked and neither is ever echoed
+ *   - the round heading's DATE and LABEL. `ROUND_HEADING_RE` validates the round
+ *     NUMBER and nothing else; the ISO date and the free-text label are matched
+ *     for shape only and their content is never inspected
+ *   - the feedback log's `Feedback` cell. It is verbatim client comment on a
+ *     prototype — free text by definition, so it is never validated and never
+ *     echoed
+ *   - a DUPLICATE Anchor inside one round. This is a deliberate NON-rule, not an
+ *     oversight: the same element legitimately attracts two comments in a round,
+ *     and D-57 makes row identity Anchor + round precisely so no ID family has
+ *     to be minted for feedback rows (D-32). A negative test pins it, so a later
+ *     change that tightens it fails loudly rather than quietly
+ *   - a decision-ID citation in a Processing cell, which resolves by SHAPE ONLY
+ *     and is never looked up — the same posture as the research track's
+ *     `Closed (D-<ss>-<n>)` evidence rule
+ *   - the NO-SCREEN BUCKET's requirement cell, which resolves by SHAPE only and
+ *     is never looked up in `_requirements.md`, unlike a screen's join cell.
+ *     Stated rather than left implicit, and it is a decision with a reason: a
+ *     bucket key can only ever make a REAL requirement look covered, and
+ *     `computeCoverage` walks the requirements table asking `bucketSet.has(id)`,
+ *     so a key naming no requirement matches no row, reaches no count, and
+ *     cannot produce a false pass. There is no fail-open here to close
+ *
+ * Graceful arms (D-42 posture, applied to every artifact this engine reads): no
+ * `.planning/discovery/` directory at all, and `_screens.md` simply absent, both
+ * check clean. A `DG-`/`RS-` citation whose register artifact is ABSENT passes
+ * on shape alone rather than failing for the register's absence. An ABSENT or
+ * unparseable `_requirements.md` skips coverage computation entirely — no
+ * `uncovered_mvp_requirement`, no `screens_mismatch` — AND skips requirement-ID
+ * resolution, so a screen's citations still pass on shape alone: resolving
+ * against a table that could not be read would fail every citation on every
+ * screen and turn a missing artifact into an inventory full of faults. The
+ * `screens_markers` structural check still runs. An artifact that EXISTS but
+ * cannot be read is a fault, not an absence, in every one of those arms.
+ *
+ * The build-tree scan takes that same graceful arm and it is GATED, not merely
+ * quiet: `scanBuildTree` runs only when at least one of `DISCOVERY_ARTIFACTS`
+ * was actually found under `.planning/discovery/`. A project with no discovery
+ * package never walks its own tree at all, so a codebase that uses the
+ * `data-req` attribute for its own unrelated purposes is untouched by this gate.
+ * That gate is the bound on the one cost D-54 accepted explicitly (T-04-18), and
+ * it is a property of the aggregator, so the scan itself stays unconditional and
+ * drivable on its own.
+ *
+ * The gate reads ARTIFACT NAMES, never `present.size`. `present` is every entry
+ * the directory listing returned — subdirectories, editor scratch files and the
+ * `.DS_Store` macOS writes on mere Finder access — so a size test made the
+ * bound "the folder has something in it" rather than "a discovery package
+ * exists", and opening a folder was enough to promote an empty one into a
+ * whole-repo walk.
+ *
+ * The one cost D-54 accepted also has a way to DISCHARGE it, which is not the
+ * same thing as a bound on it: an optional `_scan-allow.txt` in the discovery
+ * package records repo-relative paths whose `instrumentation_leaked` hit is a
+ * known false positive. With a hard block at the handoff and no allowlist, a
+ * single unavoidable hit made the gate unpassable with no remedy but deleting
+ * the file — and an operator with no way to record "this one is fine" does not
+ * leave the gate red, they turn the gate off.
+ *
+ * Content-free contract (T-04-04): output names artifact paths, `<file>:<row>`
+ * locators, IDs that have already passed their family regex, field names and
+ * snake_case reason codes — and nothing else. Every remaining author-supplied
+ * 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: screen names, purposes
+ * and deferral reasons are derived from client documents (D-24).
+ *
+ * COLUMN CONTRACT — decided here, in the first plan that parses each artifact,
+ * so it is not emergent. `_screens.md` carries two tables plus a computed block:
+ *   `## Screens`                 → | ID | Role | Purpose | Surface | Requirements |
+ *   `## No screen (still MVP)`   → | Requirement | Reason |
+ *   `## Coverage`                → the marker pair, machine-owned
+ * `_feedback.md` carries one table per round:
+ *   `## Round <n> — <date> — <label>` → | Anchor | Verdict | Feedback | Processing |
+ * The bootstrap template in `references/discovery-traceability.md` and Session
+ * 4's instruction block must both match these positions; the positions are
+ * exported as named indices below rather than being spelled as bare integers at
+ * their use sites.
+ */
+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");
+// 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");
+// The `DG-`/`RS-` register grammar is owned by the research-track gate (D-42).
+// This engine RESOLVES citations against those registers and re-implements none
+// of their validation — a parse fault there is that gate's to report, not this
+// one's to launder into a screens fault.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const researchTrack = require("./discovery-research-track.cjs");
+const { splitTableCells, SEPARATOR_ROW_RE, boundedSequenceMax } = table;
+const { output, error, ERROR_REASON } = io;
+// Exported under its own name as well as through `ERROR_REASON`: the gate's
+// identity is cited by the workflow steps that run it and by the reference, so
+// it lives in one place rather than being re-spelled as a string literal.
+const SCREEN_CHECK_FAILED = io.ERROR_REASON.DISCOVERY_SCREEN_CHECK_FAILED;
+// ─── Types ────────────────────────────────────────────────────────────────────
+/**
+ * The closed set of reason codes this engine can emit, in declaration order.
+ *
+ * Declared IN FULL here even though this plan only emits ten of them. Later
+ * plans in this phase add the emission paths and their tests; the coverage audit
+ * asserts every code is emitted by at least one fixture. Declaration ORDER is
+ * part of the contract — the tuple is pinned with a `deepEqual`, so a code moved
+ * is a code the reference table has to move too.
+ *
+ * Exported as a runtime VALUE, not merely as a type, for the D-60 reason given
+ * in the module comment: `ViolationReason` is derived from the tuple, so a code
+ * added to one is a code added to both.
+ */
+const VIOLATION_REASONS = Object.freeze([
+    'bad_id',
+    'duplicate_id',
+    'sequence_gap',
+    'missing_section',
+    'bad_surface_status',
+    'deferred_without_reason',
+    'no_screen_without_reason',
+    'unknown_requirement_id',
+    'uncovered_mvp_requirement',
+    'screens_markers',
+    'screens_mismatch',
+    'bad_anchor',
+    'unknown_screen_id',
+    'bad_verdict',
+    'bad_processing',
+    'unknown_processing_id',
+    'instrumentation_leaked',
+    'scan_budget_exceeded',
+    'requirements_unparseable',
+    'artifact_unreadable',
+]);
+/**
+ * The two literals D-54's build-tree scan looks for, and the two the `/pp-sketch`
+ * emitter must produce.
+ *
+ * Declaring them HERE — in the engine that both consumes and enforces them — is
+ * what makes D-60's single-home claim mechanical: the sketch surface and the
+ * reference are compared against this tuple by test, so a renamed attribute or
+ * toggle id cannot drift into a scan that quietly finds nothing.
+ */
+const INSTRUMENTATION_LITERALS = Object.freeze([
+    'data-req=',
+    'sketch-req-overlay',
+]);
+// ─── Constants ────────────────────────────────────────────────────────────────
+const PLANNING_DIR = '.planning';
+const DISCOVERY_SUBDIR = 'discovery';
+const SCREENS_FILE = '_screens.md';
+const FEEDBACK_FILE = '_feedback.md';
+const REQUIREMENTS_FILE = '_requirements.md';
+// Read-only, for citation resolution only. Their grammar belongs to
+// `discovery research-check` (D-42) and is not re-implemented here.
+const RISKS_FILE = '_risks.md';
+const RESEARCH_FILE = '_research.md';
+/**
+ * The optional, auditable suppression list for `instrumentation_leaked`
+ * (T-04-18). Repo-relative POSIX paths, one per line; `#` comments and blank
+ * lines are ignored, and there are no globs — an exact path is a decision a
+ * reviewer can read, a pattern is a hole nobody can size.
+ *
+ * NOT a discovery artifact this gate validates, and deliberately not a member of
+ * `DISCOVERY_ARTIFACTS` below: an allowlist alone must never be what promotes a
+ * project into a whole-repo walk. It lives under `.planning/discovery/` because
+ * that directory is committed, which is what makes the suppression a recorded
+ * decision rather than a local workaround — and because `.planning` is in
+ * `SCAN_SKIP_DIRS`, so the list can never allowlist itself into invisibility.
+ */
+const SCAN_ALLOW_FILE = '_scan-allow.txt';
+/**
+ * The artifacts whose presence means "this project has a discovery package".
+ *
+ * The build-tree scan gates on THIS, not on `present.size > 0`. `present` is
+ * `new Set(fs.readdirSync(dir))` — every name in the directory, including
+ * subdirectories, editor scratch files and `.DS_Store`, which macOS creates on
+ * mere Finder access. The documented bound (see the module comment) is "a
+ * project with no discovery package never walks its own tree"; the bound as
+ * implemented was "a project whose `.planning/discovery/` directory is empty or
+ * absent", and a single metadata file silently promoted the one into the other.
+ * A gate whose reach depends on whether someone opened a folder is not a bound.
+ */
+const DISCOVERY_ARTIFACTS = Object.freeze([
+    SCREENS_FILE, FEEDBACK_FILE, REQUIREMENTS_FILE, RISKS_FILE, RESEARCH_FILE,
+]);
+const SCREENS_HEADING = '## Screens';
+const NO_SCREEN_HEADING = '## No screen (still MVP)';
+const COVERAGE_HEADING = '## Coverage';
+/** D-51/D-06: the computed coverage block is replaced verbatim from command output. */
+const COVERAGE_OPEN = '<!-- screens:auto -->';
+const COVERAGE_CLOSE = '<!-- /screens:auto -->';
+/**
+ * The plan for the coverage mechanism names this pair `SCREENS_OPEN` /
+ * `SCREENS_CLOSE`, by analogy with rollup's `ROLLUP_OPEN` / `ROLLUP_CLOSE`. The
+ * constants already existed under the `COVERAGE_*` spelling, so these are
+ * ALIASES of the same two strings rather than a second pair — one marker
+ * spelling, two names, and the equality is pinned by test.
+ */
+const SCREENS_OPEN = COVERAGE_OPEN;
+const SCREENS_CLOSE = COVERAGE_CLOSE;
+// Column positions of the three tables (see the COLUMN CONTRACT note in the
+// module comment). Named rather than spelled inline so the reference and the
+// bootstrap template have something concrete to agree with.
+const SCREEN_COL = Object.freeze({ ID: 0, ROLE: 1, PURPOSE: 2, SURFACE: 3, REQUIREMENTS: 4 });
+const NO_SCREEN_COL = Object.freeze({ ID: 0, REASON: 1 });
+const FEEDBACK_COL = Object.freeze({ ANCHOR: 0, VERDICT: 1, FEEDBACK: 2, PROCESSING: 3 });
+// Anchored, quantifier-free, applied to a SINGLE already-split cell — never
+// unanchored across whole-file untrusted content (T-03-02 discipline carried
+// forward as T-04-05). A backtracking pattern here would be a denial-of-service
+// surface, and the cells are client-derived.
+/** D-50: screen IDs are a flat, global, zero-padded 2-digit sequence. */
+const SCR_ID_RE = /^SCR-\d{2}$/;
+/** D-51: the join cell names requirement IDs, whose family shape is fixed by D-01. */
+const REQ_ID_RE = /^[A-Z][A-Z0-9]*-\d+$/;
+/**
+ * D-55 surface-status grammar. The cell is EXACTLY the required keyword, or the
+ * deferred keyword with a parenthesised reason. Same trick as `Closed
+ * (<evidence>)` (D-35) and `Dropped (D-<ss>-<n>)`: the reason is structured, not
+ * prose to be regexed out later.
+ */
+const SURFACE_STATUS = Object.freeze({ REQUIRED: 'REQUIRED', DEFERRED: 'DEFERRED' });
+/**
+ * The capture is `(.*)` rather than `(.+)` on purpose: an EMPTY parenthesised
+ * reason must reach `deferred_without_reason`, which says what is wrong, rather
+ * than falling through to `bad_surface_status`, which does not. A bare
+ * `DEFERRED` with no parentheses fails this pattern and IS a
+ * `bad_surface_status`, per D-55.
+ */
+const DEFERRED_REASON_RE = /^DEFERRED \((.*)\)$/;
+/** The em dash alone is a permitted "no requirements on this row" marker. */
+const EM_DASH = '—';
+/**
+ * D-58 verdict vocabulary: four lowercase English WORDS, not emoji — the same
+ * posture D-03 and D-34 took for the sibling registers. Declaration order is the
+ * contract and is pinned by test.
+ */
+const VERDICTS = Object.freeze(['change', 'keep', 'drop', 'question']);
+/**
+ * D-57 Processing grammar. The cell is EXACTLY one of these two literals, or a
+ * closed citation of an existing ID. Same trick as `Closed (<evidence>)` (D-35):
+ * "nothing came of this" is an explicit closed value, because many rows
+ * legitimately produce no decision — a `keep` verdict changes nothing, and a
+ * `question` may seed a `DG-`/`RS-` item instead. That is why an EMPTY cell is
+ * a fault rather than a shorthand for `No change`.
+ */
+const PROCESSING = Object.freeze({ OPEN: 'Open', NO_CHANGE: 'No change' });
+// D-57: the three citation shapes a Processing cell may take. Anchored,
+// quantifier-free, applied to a SINGLE already-split cell (T-04-13).
+const DECISION_CITE_RE = /^D-\d{2}-\d+$/;
+// D-57: a data-gathering item in `_risks.md`.
+const DG_CITE_RE = /^DG-\d{2}$/;
+// D-57: a research-backlog item in `_research.md`.
+const RS_CITE_RE = /^RS-\d{2}$/;
+/**
+ * D-56 round heading. 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.
+ *
+ * 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 (`SCR-\d{2}`, `DG-\d{2}`, `RS-\d{2}`). 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 the CLI's try/catch can turn into `{ ok, reason }`.
+ */
+const ROUND_HEADING_RE = /^## Round (\d{1,2}) — [^—]+ — .+$/;
+/** A heading that CLAIMS the round family. A claimed-but-malformed one is a fault. */
+const ROUND_CLAIM_RE = /^## Round\b/;
+/**
+ * D-58 anchor grammar: screen ID, the ` · ` separator D-27/D-37/D-45
+ * established, then a non-empty element anchor. One spelling of the separator
+ * across the whole discovery surface — a second would be a join that silently
+ * matches nothing.
+ */
+const ANCHOR_SEP = ' · ';
+const ANCHOR_RE = /^(SCR-\d{2}) · (.+)$/;
+/**
+ * The confidentiality bound on every echoed detail. Not a formatting preference:
+ * inventory prose is derived from client documents (D-24), so an unbounded echo
+ * is a disclosure. Same value as the research-track sibling, deliberately.
+ */
+const ECHO_MAX_CHARS = 24;
+/** A pathological artifact must not produce an unbounded report. */
+const MAX_REPORTED_VIOLATIONS = 50;
+// ─── Parsing ──────────────────────────────────────────────────────────────────
+/**
+ * Collect the pipe-table row lines belonging to the section opening at `start`.
+ *
+ * Modelled on the rollup parser's `sectionRows` but LOCAL to this module and
+ * deliberately not shared with it: rollup's stop condition names the rollup
+ * marker and is specific to the `_requirements.md` template, and the research
+ * track's whole-file `registerRows` treats `## ` as a section START (D-32).
+ * Neither is interchangeable with this one, which stops at the next second-level
+ * heading or at the coverage open marker. Only the SPLITTER is shared (D-60).
+ *
+ * The header row is identified POSITIONALLY — it is the row immediately before
+ * the table's FIRST separator — not by header text and not by "any row followed
+ * by a separator-shaped line". Those last two are not the same rule, and the
+ * difference was a silent-omission hole: `SEPARATOR_ROW_RE` matches the
+ * extremely common `| --- | --- | --- |` idiom ANYWHERE in the document, so a
+ * stray separator (an author appending a second table under one heading, a
+ * pasted separator, a `| --- |` placeholder row) deleted the data row above it
+ * from the entire gate — its faults were never reported, its ID never
+ * registered, and its sequence number never counted, so not even
+ * `sequence_gap` noticed. A gate whose stated purpose is that nothing is
+ * silently omitted must not have a one-line trick that omits a row.
+ *
+ * A SECOND separator therefore STOPS the collection rather than swallowing the
+ * row above it. Stopping is the conservative reading: the rows that were
+ * collected are still validated, and a second table under one heading is
+ * outside the template this parser is written against.
+ *
+ * Split from `screenSectionRows` (which resolves a heading by TEXT) because the
+ * feedback log's sections are found by PATTERN — every `## Round …` heading, in
+ * order — and two headings can carry the same text. One collector, two ways of
+ * locating the section it starts from; the alternative was a second copy of the
+ * stop condition, and a stop condition that exists twice drifts.
+ */
+function sectionRowsFrom(lines, start) {
+    const rows = [];
+    let seenSeparator = false;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (trimmed.startsWith('## ') || trimmed === COVERAGE_OPEN)
+            break;
+        if (!trimmed.includes('|'))
+            continue;
+        if (SEPARATOR_ROW_RE.test(line)) {
+            // The FIRST separator ends the header, so the row before it — and only
+            // that row — is the header. A LATER separator starts a new table in the
+            // same section: stop, rather than silently swallowing the data row above
+            // it as the previous lookahead did.
+            if (seenSeparator)
+                break;
+            seenSeparator = true;
+            if (rows.length > 0)
+                rows.pop();
+            continue;
+        }
+        rows.push({ line, num: i + 1 });
+    }
+    return rows;
+}
+/**
+ * Locate a section by its exact heading TEXT and collect its rows. Returns null
+ * when the heading itself is absent, which the caller turns into
+ * `missing_section`.
+ *
+ * EVERY matching heading is counted, not just the first, and that is the whole
+ * reason this returns a record rather than a bare row list. `findIndex` took the
+ * first match and `sectionRowsFrom` stops at the next `## ` — which, when the
+ * document carries the heading twice, is the SECOND copy of the same heading. So
+ * the second table's rows were never collected and never validated: no `bad_id`,
+ * no `duplicate_id`, no `bad_surface_status`, no sequence number, and no
+ * violation of any kind saying a table had been skipped. One duplicated heading
+ * deleted a whole table from a gate whose entire purpose is that nothing is
+ * silently omitted — the same silent-omission class as the stray separator that
+ * `sectionRowsFrom` above was repaired for, and not one of the module's declared
+ * non-rules.
+ *
+ * The extra headings are REPORTED and their tables are still not read. Stopping
+ * at the first section is the conservative reading, exactly as it is for a
+ * second separator: a second table under one heading is outside the template
+ * this parser is written against, and guessing at a merge would invent sequence
+ * and duplicate semantics nobody specified. What changed is that the omission
+ * now has a name.
+ */
+function screenSectionRows(lines, heading) {
+    const starts = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        if (lines[i].trim() === heading)
+            starts.push(i);
+    }
+    if (starts.length === 0)
+        return null;
+    return {
+        rows: sectionRowsFrom(lines, starts[0]),
+        duplicateHeadings: starts.slice(1).map(i => i + 1),
+    };
+}
+// `boundedSequenceMax` and its `MAX_SEQUENCE_SPAN` ceiling used to live here,
+// private to this module. They now live in the `discovery-table.cjs` leaf and
+// are shared with `discovery-research-track.cts`, which had been left with a
+// bare `Math.max(...seqs)` when this engine was hardened (04-SECURITY AR-04-02).
+// Being private was also why neutering the ceiling or restoring the spread left
+// the suite green (M4/M5): no test could reach the fold. It is exported and
+// pinned there now.
+/**
+ * D-41 sequence integrity. `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. An inventory with zero rows has no gaps.
+ */
+function validateScreenSequence(seqs) {
+    const violations = [];
+    if (seqs.length === 0)
+        return violations;
+    const seen = new Set(seqs);
+    const max = boundedSequenceMax(seqs);
+    if (max === null) {
+        // Unreachable through `SCR_ID_RE` (two digits, so max is 99) 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: SCREENS_FILE, reason: 'bad_id' }];
+    }
+    for (let n = 1; n <= max; n += 1) {
+        if (!seen.has(n)) {
+            violations.push({
+                artifact: SCREENS_FILE,
+                id: `SCR-${String(n).padStart(2, '0')}`,
+                reason: 'sequence_gap',
+            });
+        }
+    }
+    return violations;
+}
+/**
+ * D-55 surface-status validation for one already-split cell.
+ *
+ * The three arms are exhaustive and ordered so the most specific fault wins:
+ * exactly the required keyword is clean; the deferred shape with an empty or
+ * whitespace-only reason is `deferred_without_reason`; anything else — including
+ * a BARE deferred keyword — is `bad_surface_status`, and only that arm echoes,
+ * through the sanitiser.
+ */
+function validateSurfaceStatus(cell, num) {
+    const value = cell.trim();
+    if (value === SURFACE_STATUS.REQUIRED)
+        return [];
+    const match = DEFERRED_REASON_RE.exec(value);
+    if (match === null) {
+        return [{
+                artifact: SCREENS_FILE,
+                line: num,
+                reason: 'bad_surface_status',
+                field: 'surface_status',
+                cell: value,
+            }];
+    }
+    if (match[1].trim() === '') {
+        return [{ artifact: SCREENS_FILE, line: num, reason: 'deferred_without_reason' }];
+    }
+    return [];
+}
+/**
+ * D-51 join cell: the requirement IDs a screen serves. An em dash alone is
+ * permitted and contributes nothing. Every other cell is split on commas and
+ * each token must match the family regex.
+ *
+ * A token that does not is `unknown_requirement_id` with the TOKEN echoed
+ * through the sanitiser — the token, not the surrounding cell, because the
+ * bounded echo is what lets an author find the typo without the report carrying
+ * the row's prose.
+ *
+ * RESOLUTION against `_requirements.md` (does this ID exist?) is NOT done here —
+ * that needs the other artifact, so the parser stays pure and the rule lives in
+ * `resolveRequirementRefs`, which the aggregator calls. It emits the SAME code:
+ * a token of the right shape naming nothing and a token of the wrong shape are
+ * both "this is not a requirement I can find", and splitting them would only
+ * split the fixture set that proves the rule.
+ */
+function parseRequirementCell(cell, num) {
+    const ids = [];
+    const violations = [];
+    const value = cell.trim();
+    if (value === '' || value === EM_DASH)
+        return { ids, violations };
+    for (const raw of value.split(',')) {
+        const token = raw.trim();
+        if (token === '')
+            continue;
+        if (!REQ_ID_RE.test(token)) {
+            violations.push({
+                artifact: SCREENS_FILE,
+                line: num,
+                reason: 'unknown_requirement_id',
+                cell: token,
+            });
+            continue;
+        }
+        ids.push(token);
+    }
+    return { ids, violations };
+}
+/**
+ * Parse `_screens.md` into the screen inventory and the no-screen bucket.
+ *
+ * Fail-loud (D-53), never warn-and-skip: every fault class runs before the
+ * return, so an author sees the whole picture in one pass rather than peeling
+ * one fault at a time.
+ *
+ * Both collections are `Map`s, never plain object literals: the keys are parsed
+ * from untrusted content, and a `__proto__`-shaped key must not be able to write
+ * into derived state (T-03-03 discipline carried forward as T-04-06). The screen
+ * key has passed `SCR_ID_RE` and the bucket key has passed `REQ_ID_RE`, so
+ * neither can actually be `__proto__` today — the `Map` is the structural
+ * guarantee that stays true if a regex is ever loosened.
+ */
+function parseScreenInventory(content) {
+    const screens = new Map();
+    const noScreen = new Map();
+    const violations = [];
+    if (typeof content !== 'string' || content === '') {
+        return { screens, noScreen, violations };
+    }
+    const lines = content.split(/\r?\n/);
+    const screenSection = screenSectionRows(lines, SCREENS_HEADING);
+    const bucketSection = screenSectionRows(lines, NO_SCREEN_HEADING);
+    // An absent heading is one violation naming the heading's own artifact, and
+    // that section contributes no rows. The sibling section is still parsed —
+    // reporting only the first missing heading would be warn-and-skip by another
+    // name.
+    if (screenSection === null) {
+        violations.push({ artifact: SCREENS_FILE, reason: 'missing_section', cell: SCREENS_HEADING });
+    }
+    if (bucketSection === null) {
+        violations.push({ artifact: SCREENS_FILE, reason: 'missing_section', cell: NO_SCREEN_HEADING });
+    }
+    // A REPEATED heading is the mirror of an absent one and is reported for the
+    // same reason: it costs the gate a whole table. One violation per extra
+    // heading, located by its own source row so the author can find the copy.
+    //
+    // The heading is carried in `id` rather than in `cell`, and that is safe
+    // BECAUSE it is not author data at all: both values are closed literals
+    // declared in this module — `SCREENS_HEADING` and `NO_SCREEN_HEADING`, never
+    // the text as it was written in the document — so naming one discloses
+    // nothing and cannot smuggle prose past the echo bound. It still routes
+    // through `sanitizeEcho` at the chokepoint, because the invariant that every
+    // rendered detail passes it stays literally true or it is not an invariant.
+    for (const [section, heading] of [
+        [screenSection, SCREENS_HEADING],
+        [bucketSection, NO_SCREEN_HEADING],
+    ]) {
+        for (const num of section?.duplicateHeadings ?? []) {
+            violations.push({ artifact: SCREENS_FILE, id: heading, reason: 'duplicate_id', line: num });
+        }
+    }
+    const seqs = [];
+    for (const { line, num } of screenSection?.rows ?? []) {
+        const cells = splitTableCells(line);
+        const id = cells[SCREEN_COL.ID] ?? '';
+        const idOk = SCR_ID_RE.test(id);
+        const duplicate = idOk && screens.has(id);
+        if (!idOk) {
+            // Reported by POSITION, never by content: the first cell has passed no
+            // validation at all, so there is nothing about it that is safe to quote.
+            violations.push({ artifact: SCREENS_FILE, line: num, reason: 'bad_id' });
+        }
+        else if (duplicate) {
+            // The ID is validated, so naming it is safe — and naming it is the only
+            // way an author can find the second row.
+            violations.push({ artifact: SCREENS_FILE, id, reason: 'duplicate_id', line: num });
+        }
+        // The cell validators run REGARDLESS of the ID's fate, and that is the
+        // whole point. Both ID arms used to `continue` past this block, so a row
+        // with a typo'd ID and a malformed Surface cell reported one fault; the
+        // author fixed the ID, re-ran, and only then met the second. That is
+        // exactly the peeling-one-fault-at-a-time this parser says it does not do
+        // (D-53). Surface status and the requirements join are properties of their
+        // OWN cells — neither is derived from the ID, and neither becomes
+        // meaningless because the ID is wrong — so there is nothing to defer.
+        violations.push(...validateSurfaceStatus(cells[SCREEN_COL.SURFACE] ?? '', num));
+        const requirements = parseRequirementCell(cells[SCREEN_COL.REQUIREMENTS] ?? '', num);
+        violations.push(...requirements.violations);
+        // Only a row with a valid, unseen ID joins the inventory and the sequence.
+        // That much is genuinely ID-dependent: a malformed ID has no sequence
+        // number to contribute, and a duplicate must not overwrite the row that
+        // claimed the slot first. Reporting more is not the same as recording more.
+        if (!idOk || duplicate)
+            continue;
+        seqs.push(Number(id.slice('SCR-'.length)));
+        screens.set(id, {
+            id,
+            seq: Number(id.slice('SCR-'.length)),
+            role: cells[SCREEN_COL.ROLE] ?? '',
+            purpose: cells[SCREEN_COL.PURPOSE] ?? '',
+            surface: (cells[SCREEN_COL.SURFACE] ?? '').trim(),
+            requirementIds: requirements.ids,
+            line: num,
+        });
+    }
+    violations.push(...validateScreenSequence(seqs));
+    for (const { line, num } of bucketSection?.rows ?? []) {
+        const cells = splitTableCells(line);
+        const id = cells[NO_SCREEN_COL.ID] ?? '';
+        if (!REQ_ID_RE.test(id)) {
+            violations.push({ artifact: SCREENS_FILE, line: num, reason: 'bad_id' });
+            continue;
+        }
+        // Ordered BEFORE the empty-reason check so the MORE SPECIFIC fault is the
+        // first thing an author reads. A second row claiming a requirement the
+        // bucket already holds used to be dropped in silence — first row kept,
+        // second row's reason (potentially contradicting it) discarded with no
+        // violation at all. That was an oversight rather than a decision: the
+        // screens table above and the feedback log's rounds both raise
+        // `duplicate_id`, and the non-rules block never claimed this one as open.
+        const duplicate = noScreen.has(id);
+        if (duplicate) {
+            // The ID has passed its family regex, so naming it is safe — and naming
+            // it is the only way an author can find the second row.
+            violations.push({ artifact: SCREENS_FILE, id, reason: 'duplicate_id', line: num });
+        }
+        const reason = (cells[NO_SCREEN_COL.REASON] ?? '').trim();
+        if (reason === '') {
+            // The ID has passed its family regex, so naming it is safe; the empty
+            // cell is what is being reported, and there is nothing in it to echo.
+            // Still checked on a DUPLICATE row, for the same D-53 reason the screens
+            // table validates the cells of a duplicate row: the two faults are
+            // independent, and reporting only one makes the author run the gate twice.
+            violations.push({ artifact: SCREENS_FILE, id, reason: 'no_screen_without_reason', line: num });
+        }
+        if (!duplicate)
+            noScreen.set(id, { id, reason, line: num });
+    }
+    return { screens, noScreen, violations };
+}
+// ─── Feedback log (TRACE-02, D-56 / D-57 / D-58) ──────────────────────────────
+/**
+ * D-41 sequence integrity for feedback rounds. Rows are never deleted (D-56), so
+ * a dropped round leaves a hole the parser names. Round numbers are NEVER
+ * renumbered: renumbering is what turns a deleted round into a round that never
+ * existed, and the round history is the audit trail.
+ */
+function validateRoundSequence(seqs) {
+    const violations = [];
+    if (seqs.length === 0)
+        return violations;
+    const seen = new Set(seqs);
+    const max = boundedSequenceMax(seqs);
+    if (max === null) {
+        // Unreachable through `ROUND_HEADING_RE` (two digits, so max is 99). Kept
+        // because the grammar is one edit away from being widened again, and the
+        // failure mode this floor prevents is a process abort rather than a report.
+        return [{ artifact: FEEDBACK_FILE, reason: 'bad_id' }];
+    }
+    for (let n = 1; n <= max; n += 1) {
+        if (!seen.has(n)) {
+            violations.push({ artifact: FEEDBACK_FILE, id: `Round ${n}`, reason: 'sequence_gap' });
+        }
+    }
+    return violations;
+}
+/**
+ * D-57 Processing-cell grammar for one already-split cell.
+ *
+ * Clean when the cell is exactly `Open`, exactly `No change`, or a single
+ * citation matching one of the three closed shapes. Everything else — including
+ * an EMPTY or whitespace-only cell — is one `bad_processing`. D-57 calls a bare
+ * or prose-only Processing cell a structural error, singular, so there is no
+ * separate empty-cell code: an author who left the cell blank and an author who
+ * wrote a sentence in it have made the same mistake, and inventing a second code
+ * would only split the fixture set that proves the rule.
+ *
+ * RESOLUTION of a `DG-`/`RS-` citation against its register is NOT done here —
+ * that needs the other artifacts, so it lives in `resolveCrossArtifact` and the
+ * parser stays pure.
+ */
+function validateProcessing(cell, num) {
+    const value = cell.trim();
+    if (value === PROCESSING.OPEN || value === PROCESSING.NO_CHANGE)
+        return [];
+    if (DECISION_CITE_RE.test(value) || DG_CITE_RE.test(value) || RS_CITE_RE.test(value))
+        return [];
+    return [{
+            artifact: FEEDBACK_FILE,
+            line: num,
+            reason: 'bad_processing',
+            field: 'processing',
+            cell: value,
+        }];
+}
+/**
+ * Parse `_feedback.md` into its rounds and rows.
+ *
+ * Fail-loud (D-53) and never warn-and-skip, including at the HEADING level: a
+ * heading that claims the round family but does not match the grammar is
+ * reported and its section skipped, rather than silently ignored. That widening
+ * is the same repair 03-08 made to the `_sparring.md` heading grammar — a
+ * malformed heading that a parser passes over is a whole section of the audit
+ * trail the gate never looked at.
+ *
+ * The heading fault is `bad_id` located by artifact plus row number ONLY. The
+ * heading text has passed no validation, so there is nothing about it that is
+ * safe to quote (T-04-10).
+ *
+ * A heading that never claims the Round family is ignored outright: other
+ * second-level sections in the document are not this parser's business.
+ *
+ * `rounds` is a `Map` keyed by the validated integer round number (T-04-06
+ * discipline: derived state is never keyed into a plain object literal).
+ */
+function parseFeedbackLog(content) {
+    const rounds = new Map();
+    const rows = [];
+    const violations = [];
+    if (typeof content !== 'string' || content === '')
+        return { rounds, rows, violations };
+    const lines = content.split(/\r?\n/);
+    const seqs = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const heading = lines[i].trim();
+        if (!ROUND_CLAIM_RE.test(heading))
+            continue;
+        const num = i + 1;
+        const match = ROUND_HEADING_RE.exec(heading);
+        if (match === null) {
+            violations.push({ artifact: FEEDBACK_FILE, line: num, reason: 'bad_id' });
+            continue;
+        }
+        const round = Number(match[1]);
+        if (rounds.has(round)) {
+            // 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: FEEDBACK_FILE, id: `Round ${round}`, reason: 'duplicate_id', line: num });
+            continue;
+        }
+        rounds.set(round, { round, line: num });
+        seqs.push(round);
+        for (const row of sectionRowsFrom(lines, i)) {
+            const cells = splitTableCells(row.line);
+            const anchor = (cells[FEEDBACK_COL.ANCHOR] ?? '').trim();
+            const anchorMatch = ANCHOR_RE.exec(anchor);
+            if (anchorMatch === null) {
+                violations.push({
+                    artifact: FEEDBACK_FILE,
+                    line: row.num,
+                    reason: 'bad_anchor',
+                    field: 'anchor',
+                    cell: anchor,
+                });
+            }
+            const verdict = (cells[FEEDBACK_COL.VERDICT] ?? '').trim();
+            if (!VERDICTS.includes(verdict)) {
+                violations.push({
+                    artifact: FEEDBACK_FILE,
+                    line: row.num,
+                    reason: 'bad_verdict',
+                    field: 'verdict',
+                    cell: verdict,
+                });
+            }
+            const processing = (cells[FEEDBACK_COL.PROCESSING] ?? '').trim();
+            violations.push(...validateProcessing(processing, row.num));
+            // Every row is kept, including one whose anchor failed: the cross-artifact
+            // resolver skips rows with no validated screen ID, and dropping the row
+            // here would make a second fault on the same row invisible.
+            rows.push({
+                screenId: anchorMatch === null ? '' : anchorMatch[1],
+                elementAnchor: anchorMatch === null ? '' : anchorMatch[2],
+                verdict,
+                feedback: cells[FEEDBACK_COL.FEEDBACK] ?? '',
+                processing,
+                round,
+                line: row.num,
+            });
+        }
+    }
+    violations.push(...validateRoundSequence(seqs));
+    return { rounds, rows, violations };
+}
+// ─── Artifact loading ─────────────────────────────────────────────────────────
+/**
+ * Resolve the discovery package for a project root and hand back a reader.
+ *
+ * The `present.has(file)` early return is what discriminates the two conditions,
+ * and it must stay that way: ABSENT is the 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, and the failure mode GUARD-01 exists to
+ * close. An unreadable artifact must not be counted as checked either: saying it
+ * was checked would be a second, quieter overstatement.
+ *
+ * This is a NAMED, EXPORTED function rather than a closure buried inside an
+ * aggregator because later plans in this phase compose it — they need a name to
+ * call and a test needs a name to drive.
+ */
+function loadDiscoveryArtifacts(cwd) {
+    const violations = [];
+    const dir = node_path_1.default.join(cwd, PLANNING_DIR, DISCOVERY_SUBDIR);
+    let names = [];
+    try {
+        names = node_fs_1.default.readdirSync(dir);
+    }
+    catch {
+        names = []; // no discovery package at all — graceful arm
+    }
+    const present = new Set(names);
+    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;
+        }
+    };
+    return { dir, present, readArtifact, violations };
+}
+/**
+ * Read `_requirements.md` through the loaded package and hand back its rows.
+ *
+ * `_requirements.md` is owned by `discovery rollup`; this gate consumes that
+ * single exported reader and NOTHING else. A grammar fault there is reported
+ * ONCE, by name, pointing at the owning gate — the underlying errors are NOT
+ * re-enumerated here, because two gates reporting the same fault in two
+ * vocabularies is how an author learns to ignore both.
+ *
+ * An ABSENT `_requirements.md` is silent, yields no rows, and leaves `status`
+ * absent; the requirement-resolution checks that need it are skipped by the
+ * aggregator rather than failing. Not having the artifact is not a fault of this
+ * gate.
+ */
+function resolveRequirements(loaded) {
+    const violations = [];
+    const content = loaded.readArtifact(REQUIREMENTS_FILE);
+    if (content === null)
+        return { rows: [], status: 'absent', violations };
+    const parsed = rollup.parseRequirementsArtifact(content);
+    if (!parsed.ok) {
+        violations.push({ artifact: REQUIREMENTS_FILE, reason: 'requirements_unparseable' });
+        return { rows: [], status: 'unparseable', violations };
+    }
+    const rows = parsed.rows.map((r) => ({
+        id: r.id,
+        disposition: r.disposition,
+    }));
+    return { rows, status: 'ok', violations };
+}
+// ─── Cross-artifact resolution (D-58 anchors, D-57 citations) ─────────────────
+/**
+ * Collect the register IDs of a citation register, or null when the artifact is
+ * absent.
+ *
+ * The read goes through `loaded.readArtifact`, so the absent-versus-unreadable
+ * discrimination is INHERITED rather than re-derived — an unreadable register
+ * pushes `artifact_unreadable` onto the loader's own violation list and returns
+ * null here, which is the correct outcome: this gate must not resolve citations
+ * against a register it could not read, and it must not pretend it did.
+ *
+ * Parsing goes through the research track's exported register parsers. Their
+ * violations are DISCARDED on purpose: a grammar fault in `_risks.md` belongs to
+ * `discovery research-check` (D-42), and laundering it into a screens fault is
+ * the two-gates-two-vocabularies failure `requirements_unparseable` already
+ * avoids for `_requirements.md`.
+ */
+function registerIds(loaded, file, parse) {
+    const content = loaded.readArtifact(file);
+    if (content === null)
+        return null;
+    return new Set(parse(content).rows.map(r => r.id));
+}
+/**
+ * Resolve a parsed feedback log against the screen inventory and the citation
+ * registers. Returns a violation array and nothing else.
+ *
+ * A NAMED, EXPORTED function rather than a step inside `parseFeedbackLog`, for
+ * two reasons that pull the same way: the parser stays pure (it is handed a
+ * string and reads no filesystem), and both cross-artifact fault classes are
+ * emittable and testable in the wave that introduces them rather than waiting on
+ * the aggregator. The aggregator CALLS this; it adds no resolution rule of its
+ * own.
+ *
+ * `unknown_screen_id` (D-58, T-04-11): the screen ID left of the ` · ` separator
+ * must be a key of the inventory map. When `_feedback.md` is present while
+ * `_screens.md` is ABSENT the map is empty and EVERY anchor fails — that is the
+ * correct fail-loud reading, not an over-report: a feedback log without an
+ * inventory is precisely the silent-omission failure GUARD-01 exists to catch,
+ * and a gate that passed it would be verifying nothing.
+ *
+ * `unknown_processing_id` (D-57): a `DG-`/`RS-` citation resolves against
+ * `_risks.md` / `_research.md`. When the register artifact is ABSENT, resolution
+ * is SKIPPED and the citation passes on shape alone — the D-42 graceful arm. A
+ * decision-ID citation is NEVER looked up and always passes on shape, matching
+ * the research track's `Closed (D-<ss>-<n>)` evidence rule. Both of those are
+ * "not mechanically checked beyond shape", and the reference says so.
+ *
+ * Each register is read at most once, whatever the row count.
+ */
+function resolveCrossArtifact(screens, rows, loaded) {
+    const violations = [];
+    let risks;
+    let research;
+    for (const row of rows) {
+        // A row whose anchor failed the grammar already carries `bad_anchor`; it has
+        // no validated screen ID, so there is nothing here to resolve.
+        if (row.screenId !== '' && !screens.has(row.screenId)) {
+            violations.push({
+                artifact: FEEDBACK_FILE,
+                line: row.line,
+                reason: 'unknown_screen_id',
+                id: row.screenId,
+            });
+        }
+        if (DG_CITE_RE.test(row.processing)) {
+            if (risks === undefined)
+                risks = registerIds(loaded, RISKS_FILE, researchTrack.parseRiskRegister);
+            if (risks !== null && !risks.has(row.processing)) {
+                violations.push({
+                    artifact: FEEDBACK_FILE,
+                    line: row.line,
+                    reason: 'unknown_processing_id',
+                    id: row.processing,
+                });
+            }
+        }
+        else if (RS_CITE_RE.test(row.processing)) {
+            if (research === undefined) {
+                research = registerIds(loaded, RESEARCH_FILE, researchTrack.parseResearchBacklog);
+            }
+            if (research !== null && !research.has(row.processing)) {
+                violations.push({
+                    artifact: FEEDBACK_FILE,
+                    line: row.line,
+                    reason: 'unknown_processing_id',
+                    id: row.processing,
+                });
+            }
+        }
+    }
+    return violations;
+}
+/**
+ * Resolve every requirement ID a screen cites against `_requirements.md` (D-51).
+ *
+ * This is the OTHER half of `unknown_requirement_id`, and until it existed the
+ * code did not do what its name said. `parseRequirementCell` checks a token's
+ * SHAPE and nothing else, and two comments in this module used to promise that
+ * resolution was "the aggregator's job (a later plan)". No later plan did it:
+ * `requirementIds` was read in exactly one place — `computeCoverage`, to build
+ * the placed set — and was never compared against the requirements table at all.
+ * A screen citing `REQ-999` where no such requirement existed checked clean, so
+ * a reason code named `unknown_requirement_id` only ever meant "malformed
+ * shape". Coverage compensated partly, and only for MVP rows, by resurfacing the
+ * real requirement as `uncovered_mvp_requirement`; a `Later` or `Dropped`
+ * requirement mistyped on a screen was invisible in every arm. A reason code
+ * that does not do what its name says is a trap for the next reader.
+ *
+ * A NAMED, EXPORTED function rather than a block inside `checkScreenInventory`,
+ * for the reason `resolveCrossArtifact` is one: the aggregator stays pure
+ * composition and adds no resolution of its own, and this rule is drivable and
+ * testable without going through it.
+ *
+ * GUARDED on `status === 'ok'`, which preserves the documented graceful arm
+ * exactly: an ABSENT or UNPARSEABLE `_requirements.md` yields no known set, and
+ * resolving against an empty one would fail every citation on every screen and
+ * turn a missing artifact into an inventory full of faults. `absent` is silent
+ * by design and `unparseable` is already reported once, by name, against the
+ * gate that owns it.
+ *
+ * The NO-SCREEN BUCKET's requirement cell is deliberately NOT resolved here, and
+ * that is a stated non-rule rather than an omission. A bucket key can only ever
+ * make a REAL requirement look covered, and `computeCoverage` iterates the
+ * requirements table and asks `bucketSet.has(row.id)` — so an ID that is in no
+ * requirements table matches no row, contributes to no count, and cannot produce
+ * a false pass of the coverage assertion. There is no fail-open to close.
+ */
+function resolveRequirementRefs(screens, requirements) {
+    const violations = [];
+    if (requirements.status !== 'ok')
+        return violations;
+    const known = new Set(requirements.rows.map(r => r.id));
+    for (const row of screens.values()) {
+        for (const id of row.requirementIds) {
+            if (known.has(id))
+                continue;
+            violations.push({
+                artifact: SCREENS_FILE,
+                line: row.line,
+                reason: 'unknown_requirement_id',
+                // The token has already passed `REQ_ID_RE`, so naming it is safe — and
+                // naming it is the only way an author finds which citation is wrong.
+                cell: id,
+            });
+        }
+    }
+    return violations;
+}
+// ─── MVP coverage (TRACE-03, D-51) ────────────────────────────────────────────
+/** The fixed metric labels of the computed block. A closed vocabulary, like the reason codes. */
+const COVERAGE_LABELS = Object.freeze({
+    MVP: 'MVP requirements',
+    PLACED: 'Placed on a screen',
+    BUCKETED: 'In the no-screen bucket',
+    UNCOVERED: 'Uncovered',
+    UNCOVERED_IDS: 'Uncovered IDs',
+});
+/**
+ * Compute "no requirement without a place" (D-51).
+ *
+ * COMPUTED, never sampled. The motivating failure for this whole phase is a
+ * percentage visual gate that passed over a CURATED baseline list while an
+ * entire prototype surface had been silently dropped: a percentage over a
+ * curated list cannot detect an omission, because the omitted thing is missing
+ * from the denominator too. So the denominator here is `_requirements.md` — the
+ * artifact the author does not get to curate for this check — and the union is
+ * taken FROM the screens inventory INTO it (D-46's join direction; the
+ * requirements grammar is not widened and no Screen column is added to it).
+ *
+ * Only `MVP`-disposition rows participate. `Later` and `Dropped` requirements
+ * need no place, so they appear in no count — a negative test pins that, because
+ * quietly widening the denominator is how this check would start reporting
+ * uncoverable work.
+ *
+ * The placed and bucket sets are `Set`s, never plain objects: the members come
+ * from parsed content (T-04-06).
+ */
+function computeCoverage(screens, noScreen, requirementRows) {
+    const placedSet = new Set();
+    for (const row of screens.values()) {
+        for (const id of row.requirementIds)
+            placedSet.add(id);
+    }
+    const bucketSet = new Set(noScreen.keys());
+    const uncovered = [];
+    let mvp = 0;
+    let placed = 0;
+    let bucketed = 0;
+    for (const row of requirementRows) {
+        if (row.disposition !== rollup.DISPOSITIONS.MVP)
+            continue;
+        mvp += 1;
+        const onScreen = placedSet.has(row.id);
+        const inBucket = bucketSet.has(row.id);
+        if (onScreen)
+            placed += 1;
+        if (inBucket)
+            bucketed += 1;
+        if (!onScreen && !inBucket)
+            uncovered.push(row.id);
+    }
+    uncovered.sort();
+    return { mvp, placed, bucketed, uncovered };
+}
+/**
+ * Render the machine-owned coverage block (D-51/D-06) — the exact text that
+ * belongs between the markers. The workflow replaces the block with this
+ * VERBATIM, exactly as it does with the rollup totals.
+ *
+ * CONTENT-FREE BY CONSTRUCTION (T-04-09): the output is integers, requirement
+ * IDs that have already passed `REQ_ID_RE`, the fixed labels above, table pipes
+ * and an em dash — and nothing else. No Requirement text cell, no screen name,
+ * no purpose ever reaches it, which is what lets the whole block be carried in a
+ * `screens_mismatch` violation's `expected` field without breaching the
+ * content-free contract. A test asserts the property against a whitelist rather
+ * than trusting this comment.
+ */
+function renderCoverageBlock(summary) {
+    return [
+        '| Metric | Count |',
+        '|--------|-------|',
+        `| ${COVERAGE_LABELS.MVP} | ${summary.mvp} |`,
+        `| ${COVERAGE_LABELS.PLACED} | ${summary.placed} |`,
+        `| ${COVERAGE_LABELS.BUCKETED} | ${summary.bucketed} |`,
+        `| ${COVERAGE_LABELS.UNCOVERED} | ${summary.uncovered.length} |`,
+        '',
+        `${COVERAGE_LABELS.UNCOVERED_IDS}: ${summary.uncovered.length > 0 ? summary.uncovered.join(', ') : EM_DASH}`,
+    ].join('\n');
+}
+/** Whitespace-normalize for block comparison: trim lines, collapse runs, drop blanks. */
+function normalizeBlock(text) {
+    return text
+        .split(/\r?\n/)
+        .map(l => l.trim().replace(/\s+/g, ' '))
+        .filter(l => l.length > 0)
+        .join('\n');
+}
+function countOccurrences(haystack, needle) {
+    return haystack.split(needle).length - 1;
+}
+/**
+ * Enforce the coverage assertion against what is actually written in
+ * `_screens.md`. Returns a violation array and nothing else.
+ *
+ * A NAMED, EXPORTED function for the same reason `resolveCrossArtifact` is: all
+ * three of its fault classes are emittable and testable in the wave that
+ * introduces them, and the aggregator CALLS this rather than reimplementing it.
+ *
+ * `requirementsStatus` is passed EXPLICITLY rather than inferred, so the
+ * graceful arm is a decision this function makes rather than one every caller
+ * has to remember to make. Order of the three rules is load-bearing:
+ *
+ *  1. MARKER STRUCTURE, first and unconditionally. Exactly one open marker,
+ *     exactly one close marker, close after open. This is a structural property
+ *     of `_screens.md` ALONE, so it is checked even when `_requirements.md` is
+ *     absent — a document with no computed block is a document whose coverage
+ *     claim was never verified, whatever the other artifacts say. (The `## Coverage`
+ *     heading itself is deliberately not separately reported: `parseScreenInventory`
+ *     does not check it, so there is no second report to collide with.)
+ *  2. UNCOVERED MVP REQUIREMENTS, one violation per ID. The ID has passed
+ *     `REQ_ID_RE`, so naming it is safe — and naming it is the whole point.
+ *  3. NORMALIZED DRIFT COMPARISON. A hand-edited block is `screens_mismatch`,
+ *     exactly as a hand-edited rollup total is `rollup_mismatch`. This is the
+ *     105-vs-106 drift class D-05..D-08 exist to kill, closed for coverage.
+ *
+ * D-42 GRACEFUL ARM: when `_requirements.md` is ABSENT or `unparseable`, rules 2
+ * and 3 are skipped entirely — there is nothing to compute against, and a gate
+ * that reported drift against an empty computation would be dressing up a
+ * missing sibling artifact to look like a coverage fault. Rule 1 still runs.
+ */
+function enforceCoverage(screensContent, summary, requirementsStatus) {
+    const violations = [];
+    const content = typeof screensContent === 'string' ? screensContent : '';
+    const openCount = countOccurrences(content, SCREENS_OPEN);
+    const closeCount = countOccurrences(content, SCREENS_CLOSE);
+    if (openCount !== 1 || closeCount !== 1) {
+        violations.push({
+            artifact: SCREENS_FILE,
+            reason: 'screens_markers',
+            detail: `expected exactly one ${SCREENS_OPEN} and one ${SCREENS_CLOSE} (found ${openCount}/${closeCount})`,
+        });
+        // Without exactly one of each there is no block to compare; a drift report
+        // on top of a marker report would be the same fault in two vocabularies.
+        return violations;
+    }
+    const openIdx = content.indexOf(SCREENS_OPEN);
+    const closeIdx = content.indexOf(SCREENS_CLOSE);
+    if (closeIdx < openIdx) {
+        violations.push({
+            artifact: SCREENS_FILE,
+            reason: 'screens_markers',
+            detail: 'close marker precedes open marker',
+        });
+        return violations;
+    }
+    if (requirementsStatus !== 'ok')
+        return violations;
+    for (const id of summary.uncovered) {
+        violations.push({ artifact: SCREENS_FILE, id, reason: 'uncovered_mvp_requirement' });
+    }
+    const expected = normalizeBlock(renderCoverageBlock(summary));
+    const actual = normalizeBlock(content.slice(openIdx + SCREENS_OPEN.length, closeIdx));
+    if (expected !== actual) {
+        violations.push({
+            artifact: SCREENS_FILE,
+            reason: 'screens_mismatch',
+            expected,
+            // Arbitrary author text between two markers. Bounded HERE, at
+            // construction, so an inspector of the violation object cannot reach an
+            // unbounded echo either (T-04-09).
+            actual: sanitizeEcho(actual),
+        });
+    }
+    return violations;
+}
+// ─── Build-tree instrumentation scan (GUARD-01, D-54) ─────────────────────────
+/**
+ * Directory basenames the walk never enters.
+ *
+ * The OMISSIONS carry as much weight as the entries. A build output directory is
+ * deliberately NOT skipped — a build tree is precisely the thing GUARD-01
+ * asserts about, so skipping `dist`/`build`/`out` would make the whole scan a
+ * ceremony. What is skipped is the three trees whose contents this project did
+ * not author for this engagement: the dependency tree, the git object store, and
+ * `.planning` itself, whose discovery artifacts and templates legitimately spell
+ * the literals out — walking those would report the specification as a leak.
+ *
+ * `Object.freeze` seals the object's own properties; a `Set`'s membership lives
+ * in an internal slot, so this is a declaration of intent backed by the ordinary
+ * no-mutation convention, with the membership pinned by test rather than by the
+ * freeze.
+ */
+const SCAN_SKIP_DIRS = Object.freeze(new Set([
+    'node_modules', '.git', PLANNING_DIR,
+    // Caches and vendored trees. NOT build output: these inflate the file count
+    // without ever shipping, and every visited file counts against
+    // `SCAN_MAX_FILES` regardless of extension (the count precedes the
+    // extension filter). A locally-built Next.js tree alone puts thousands of
+    // files into `.next/cache`, none of which a browser will ever honour a
+    // `data-req` attribute from. `.gitignore` is deliberately NOT consulted —
+    // that would make the scan's reach depend on a file the engagement edits.
+    '.next', '.nuxt', '.turbo', '.cache', 'coverage',
+    '.venv', 'venv', '__pycache__', 'vendor', 'target',
+]));
+/**
+ * The file extensions the scan actually READS. An allowlist rather than a
+ * denylist, because the bound has to hold for file types nobody has thought of
+ * yet: a lockfile, a source map or a binary asset cannot carry a discovery
+ * annotation that a browser would honour, and reading them is pure cost.
+ *
+ * A file outside this list still counts against the file cap — it was visited,
+ * and pretending otherwise would let a tree of a million images walk forever.
+ */
+const SCAN_EXTENSIONS = Object.freeze(new Set([
+    '.html', '.htm',
+    '.js', '.jsx', '.mjs', '.cjs',
+    '.ts', '.tsx',
+    '.vue', '.svelte', '.astro',
+    '.css',
+]));
+/**
+ * The two axes of the walk's budget (T-04-14).
+ *
+ * No analog exists in this codebase — no other discovery engine walks outside
+ * `.planning/discovery/` — so both numbers are invented here and are deliberately
+ * explicit rather than emergent. They are generous enough that a real front-end
+ * build tree passes, and finite enough that a pathological or hostile tree
+ * cannot turn a structural gate into an unbounded read.
+ *
+ * SIZED AGAINST A REAL REPOSITORY, not against a fixture. The first numbers
+ * (5,000 files / 20 MB) were guesses, and measured against THIS repository —
+ * counting exactly as `scanBuildTree` counts, with `SCAN_SKIP_DIRS` applied —
+ * they came to 3,022 files and 18,487,659 bytes: 60% of the file cap and 92%
+ * of the byte cap. The repository that ships this engine was within 1.5 MB of
+ * tripping its own gate, and `scan_budget_exceeded` sets `ok` false at the
+ * handoff, which is the workstream's single deliberate HARD BLOCK. An operator
+ * who hit it had no remedy but to delete files. A cap an operator cannot raise
+ * turns an honest truncation into an unpassable gate, so `SCAN_FLOOR` below
+ * pins these against a stated realistic floor and the CLI accepts a bounded
+ * override.
+ */
+const SCAN_MAX_FILES = 50000;
+const SCAN_MAX_BYTES = 200000000;
+/**
+ * The realistic floor the shipped caps must clear, exported so a test can pin
+ * it. Stated as its own constant rather than as a magic number in an assertion:
+ * the point is that a future edit cannot quietly re-lower the caps back under
+ * what an ordinary repository needs, and a floor nobody can read is a floor
+ * nobody will respect.
+ */
+const SCAN_FLOOR = Object.freeze({ files: 20000, bytes: 100000000 });
+/**
+ * The locator a whole-tree fault is reported against. The repo root has no
+ * filename, and an empty locator would render as a bare `: scan_budget_exceeded`.
+ */
+const SCAN_ROOT_LABEL = '.';
+/**
+ * The ceiling an operator-supplied bound may not exceed, per axis. The override
+ * exists to RAISE a cap that was set too low, never to remove the bound: a walk
+ * with no finite ceiling on either axis is the unbounded read T-04-14 exists to
+ * prevent, and `--max-files 1e21` would be exactly that wearing a number. Both
+ * ceilings sit two orders of magnitude above the shipped defaults, which is
+ * headroom for a repository nobody has built yet and still a hard stop.
+ */
+const SCAN_ABSOLUTE_MAX = Object.freeze({ files: 5000000, bytes: 20000000000 });
+/**
+ * One operator-supplied budget bound, or `null` when it is not a plain positive
+ * integer at or below `ceiling`.
+ *
+ * Deliberately stricter than `Number()`: `parseInt` would accept `50000abc`,
+ * and `Number` accepts `0x10`, `1e9`, `Infinity` and whitespace-padded forms.
+ * An anchored digit run is the whole grammar, so there is nothing to reason
+ * about. Zero is rejected too — a zero cap makes the very first file trip the
+ * budget, which reads as a misunderstanding rather than as an intent.
+ */
+function parseScanBound(value, ceiling) {
+    if (typeof value !== 'string' || !/^\d{1,11}$/.test(value))
+        return null;
+    const parsed = Number(value);
+    if (parsed < 1 || parsed > ceiling)
+        return null;
+    return parsed;
+}
+/**
+ * The single spelling of the usage line. Declared once because it is emitted
+ * from two arms below and the cross-surface literal audit compares the command
+ * name against the workflows — two copies would be two things to drift.
+ */
+const SCREEN_CHECK_USAGE = 'Usage: pp-tools discovery screen-check [--max-files <n>] [--max-bytes <n>] [--require-processed]';
+/**
+ * The truncation fault. Names WHICH axis was crossed, the count reached and the
+ * cap, because "the scan gave up" without saying where is not actionable.
+ *
+ * `detail` is machine-rendered from this module's own integers and fixed
+ * phrases, never from author content, which is what makes it emittable verbatim.
+ */
+function scanBudgetViolation(axis, reached, cap) {
+    return {
+        artifact: SCAN_ROOT_LABEL,
+        reason: 'scan_budget_exceeded',
+        detail: `${axis} cap ${cap} crossed at ${reached}; the scan stopped and nothing beyond that point was checked`,
+    };
+}
+/**
+ * The FIRST pinned literal in a file, or null.
+ *
+ * First, not all: one generated bundle can carry thousands of annotations, and a
+ * report that listed every one would bury the other files under a single build
+ * artifact. The per-file cap is one hit; the report's total stays the number of
+ * FILES with hits, which is the number an operator acts on.
+ *
+ * The matched literal is returned so the caller can name it. It is a
+ * closed-vocabulary token from the frozen `INSTRUMENTATION_LITERALS` tuple, so
+ * naming it is safe — unlike the line it was found on, which is application
+ * source and is never carried anywhere (T-04-15).
+ */
+function firstInstrumentationHit(content) {
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+        for (const literal of INSTRUMENTATION_LITERALS) {
+            if (lines[i].includes(literal))
+                return { line: i + 1, literal };
+        }
+    }
+    return null;
+}
+/** Repo-relative, POSIX-separated, so a report reads the same on every platform. */
+function relativePosix(root, full) {
+    return node_path_1.default.relative(root, full).split(node_path_1.default.sep).join('/');
+}
+/**
+ * Read the optional `_scan-allow.txt` and hand back the repo-relative paths a
+ * known `instrumentation_leaked` false positive has been recorded against.
+ *
+ * WHY THIS EXISTS. D-54 accepted a false-positive cost explicitly, but accepting
+ * a cost is not the same as providing a way to discharge it. With no suppression
+ * mechanism and a hard block at the handoff, ONE unavoidable hit made the gate
+ * unpassable with no remedy but deleting the file — and the hits are not
+ * hypothetical: the repository that ships this engine matches `data-req=` in its
+ * own compiled output and in its own test fixtures, and in a consumer repo the
+ * equivalents are documentation, a config file or a test that merely mentions
+ * the attribute. An operator with no way to record "this one is fine" does not
+ * leave the gate red; they turn the gate off, which costs every other finding.
+ *
+ * WHY IT IS SHAPED THIS WAY. Exact repo-relative paths only, no globs: an exact
+ * path is a decision a reviewer can read and a pattern is a hole nobody can
+ * size. `#` comments are supported precisely so the WHY can sit next to the
+ * path. Split on `/\r?\n/` rather than on `'\n'`, so a list edited on Windows
+ * does not leave a trailing carriage return welded to every path and silently
+ * match nothing.
+ *
+ * The read goes through `loaded.readArtifact`, so the absent-versus-unreadable
+ * discrimination is INHERITED: an absent list is the ordinary case and is
+ * silent, while a list that exists and cannot be read is `artifact_unreadable`
+ * and suppresses nothing. Failing loud with everything reported is the correct
+ * direction for an unreadable SUPPRESSION file.
+ *
+ * A STALE entry — a path that is allowlisted but no longer matches anything — is
+ * a deliberate non-rule. Reporting it would need a reason code of its own, and
+ * an unused allowlist entry cannot cause the gate to miss a leak; it is untidy,
+ * not unsound.
+ */
+function loadScanAllowlist(loaded) {
+    const content = loaded.readArtifact(SCAN_ALLOW_FILE);
+    if (content === null)
+        return new Set();
+    const allowed = new Set();
+    for (const raw of content.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line === '' || line.startsWith('#'))
+            continue;
+        allowed.add(line);
+    }
+    return allowed;
+}
+/**
+ * Assert that no discovery instrumentation survives into the build tree (D-54,
+ * GUARD-01). Returns a violation array and nothing else.
+ *
+ * GUARD-01 asks for the absence to be ASSERTED rather than assumed, and D-54
+ * makes that a deterministic scan for two pinned literals — no Playwright, no
+ * generated per-project code, consistent with the ROADMAP fence.
+ *
+ * Every bound is explicit:
+ *   - the walk is ITERATIVE over a stack, never recursive, so tree depth cannot
+ *     exhaust the call stack;
+ *   - entries are read with `lstatSync` and a SYMLINK is skipped whatever it
+ *     points at, which bounds the walk and removes the directory-cycle class
+ *     outright rather than defending against it with a visited-set;
+ *   - every entry is resolved and confirmed strictly beneath the resolved
+ *     project root before any stat or read, the same posture the roll-up
+ *     traversal guard takes (T-04-16);
+ *   - `SCAN_SKIP_DIRS` keeps the walk out of the dependency tree;
+ *   - `SCAN_EXTENSIONS` bounds what is read;
+ *   - the file and byte caps stop the walk.
+ *
+ * ON CROSSING A CAP the return is the budget violation ALONE. Whatever hits had
+ * accumulated are dropped, deliberately: a truncated scan has not established
+ * anything about the tree, and a result that mixed real findings into a partial
+ * pass would invite exactly the reading "it found two, so it looked" — which is
+ * the silent fail-open this phase exists to close. One loud fault that says the
+ * scan did not complete is the honest report, and the gate exits non-zero on it
+ * either way.
+ *
+ * GATING is the CALLER's job and is documented in the module comment: this
+ * function is unconditional so it stays drivable on its own, and the aggregator
+ * runs it only when a discovery artifact was found.
+ */
+function scanBuildTree(cwd, options = {}) {
+    const maxFiles = options.maxFiles ?? SCAN_MAX_FILES;
+    const maxBytes = options.maxBytes ?? SCAN_MAX_BYTES;
+    const allow = options.allow ?? new Set();
+    const violations = [];
+    const root = node_path_1.default.resolve(cwd);
+    const stack = [root];
+    let files = 0;
+    let bytes = 0;
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (dir === undefined)
+            break;
+        let names;
+        try {
+            names = node_fs_1.default.readdirSync(dir);
+        }
+        catch {
+            // A directory that cannot be listed bounds the walk here. It is not a
+            // discovery artifact, so it is not `artifact_unreadable`: that code names
+            // a file the gate was asked to validate and could not, and inventing a
+            // structural fault out of an unreadable build directory would report the
+            // operator's filesystem permissions as a traceability failure.
+            continue;
+        }
+        // Sorted so the walk is deterministic. Which file a CAPPED scan stops at
+        // must not depend on filesystem enumeration order, or the same tree would
+        // produce different reports on different machines.
+        names.sort();
+        for (const name of names) {
+            const full = node_path_1.default.resolve(dir, name);
+            // Containment guard (T-04-16): refuse anything that does not resolve
+            // strictly beneath the project root, BEFORE any stat or read.
+            if (!full.startsWith(root + node_path_1.default.sep))
+                continue;
+            let stat;
+            try {
+                stat = node_fs_1.default.lstatSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isSymbolicLink())
+                continue;
+            if (stat.isDirectory()) {
+                if (!SCAN_SKIP_DIRS.has(name))
+                    stack.push(full);
+                continue;
+            }
+            // Sockets, FIFOs and devices are neither walked nor counted: they are not
+            // files a build emits, and reading one can block.
+            if (!stat.isFile())
+                continue;
+            files += 1;
+            if (files > maxFiles)
+                return [scanBudgetViolation('file', files, maxFiles)];
+            if (!SCAN_EXTENSIONS.has(node_path_1.default.extname(name).toLowerCase()))
+                continue;
+            // An allowlisted path is still VISITED and still counted against the file
+            // cap — suppressing a finding must not also shrink the walk, or the
+            // budget an operator raised would silently mean something else. Only the
+            // read and the report are skipped.
+            if (allow.has(relativePosix(root, full)))
+                continue;
+            // Checked BEFORE the read, so a single enormous file cannot cross the cap
+            // by being read first and counted afterwards.
+            if (bytes + stat.size > maxBytes) {
+                return [scanBudgetViolation('byte', bytes + stat.size, maxBytes)];
+            }
+            bytes += stat.size;
+            let content;
+            try {
+                content = node_fs_1.default.readFileSync(full, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const hit = firstInstrumentationHit(content);
+            if (hit === null)
+                continue;
+            violations.push({
+                // The repo-relative path IS the report. D-54 accepted the
+                // false-positive cost on the explicit condition that the fault says
+                // plainly what was found and where, so the path is carried in full — a
+                // path truncated to the echo bound would locate nothing. It is a
+                // locator, in the same class as the `<artifact>:<row>` locators the
+                // content-free contract already emits, not client prose.
+                artifact: relativePosix(root, full),
+                line: hit.line,
+                reason: 'instrumentation_leaked',
+                // The matched literal, from this module's own frozen tuple. The SOURCE
+                // LINE it sat on is never carried (T-04-15).
+                detail: hit.literal,
+            });
+        }
+    }
+    return violations;
+}
+// ─── Output ───────────────────────────────────────────────────────────────────
+/**
+ * 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. `_screens.md` and `_feedback.md` are derived from
+ * client documents (D-24): treating them as untrusted for LENGTH while
+ * treating them as trusted for BYTES was the gap.
+ */
+const CONTROL_CHARS_RE = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g;
+/**
+ * Bound and flatten an author-supplied value before it reaches violation 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-04-04).
+ *
+ * This is the SINGLE chokepoint for echoed detail: every author-supplied value
+ * below routes through `sanitizeEcho`, so a reason code added to the union by a
+ * later plan inherits the confidentiality bound by construction rather than by
+ * the author of that code remembering it. Reason codes, field names and IDs that
+ * have already passed their family regex are deliberately NOT sanitised — all
+ * three are closed sets declared in this module, 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 ?? '';
+    const locator = v.line === undefined ? where : `${where}:${v.line}`;
+    let detail = '';
+    switch (v.reason) {
+        case 'bad_id':
+            detail = '';
+            break;
+        case 'missing_section':
+            detail = sanitizeEcho(v.cell);
+            break;
+        case 'bad_surface_status':
+        case 'bad_anchor':
+        case 'bad_verdict':
+        case 'bad_processing':
+            // One arm for every closed-enum fault: the value IS echoed, because a
+            // closed-vocabulary fault an author cannot see the value of is not
+            // actionable — but it is echoed BOUNDED, through the chokepoint.
+            detail = `${v.field}: ${sanitizeEcho(v.cell)}`;
+            break;
+        case 'unknown_requirement_id':
+            detail = sanitizeEcho(v.cell);
+            break;
+        case 'screens_markers':
+        case 'instrumentation_leaked':
+        case 'scan_budget_exceeded':
+            // `detail` is machine-rendered from this module's own marker literals, the
+            // frozen instrumentation tuple and integers — never author content — so it
+            // is emitted verbatim. For `instrumentation_leaked` that is the matched
+            // literal and nothing else: the file and line are already in the locator,
+            // and the source line they name is never carried at all (T-04-15).
+            detail = v.detail ?? '';
+            break;
+        case 'screens_mismatch':
+            // `actual` was already bounded at construction; routing it through the
+            // chokepoint again is idempotent and keeps the invariant "every
+            // author-supplied value in this function passes sanitizeEcho" literally
+            // true, so a later reader cannot mistake the pre-sanitised field for an
+            // exemption. `expected` is deliberately NOT rendered here: it is a
+            // multi-line block, and this format is one line per violation.
+            detail = `block drift; actual: ${sanitizeEcho(v.actual)}`;
+            break;
+        case 'requirements_unparseable':
+            detail = 'run: discovery rollup --check';
+            break;
+        default:
+            detail = sanitizeEcho(v.id ?? '');
+    }
+    return detail === '' ? `  ${locator}: ${v.reason}` : `  ${locator}: ${v.reason} (${detail})`;
+}
+/**
+ * Render a violation list, capped, with the TRUE total.
+ *
+ * A pathological artifact must not produce an unbounded report, but a capped
+ * report that also capped the COUNT would understate the problem — and
+ * understating is the failure mode this whole phase exists to close. So the cap
+ * applies to the rendered lines only; the tail line carries how many were
+ * suppressed and the caller keeps `violations.length` as the true total.
+ *
+ * The research track applies this same idiom inline in its CLI adapter. It is a
+ * named function here because the screens CLI adapter arrives in a later plan
+ * and the cap is a contract that has to be testable before its only caller
+ * exists — the same reason `formatViolation` is exported.
+ */
+function renderViolations(violations) {
+    const total = violations.length;
+    const rendered = violations.slice(0, MAX_REPORTED_VIOLATIONS).map(formatViolation);
+    if (total > MAX_REPORTED_VIOLATIONS) {
+        rendered.push(`  … and ${total - MAX_REPORTED_VIOLATIONS} more`);
+    }
+    return rendered;
+}
+/**
+ * Run every fault class this engine owns, in one pass, for a project root
+ * (D-52). Collect-all-then-fail: every check runs, violations accumulate, the
+ * result returns once. There is no warn-and-skip anywhere in this function.
+ *
+ * PURE COMPOSITION. Every fault class reported here is emitted by a function
+ * declared and tested above; this aggregator introduces no violation code, no
+ * grammar rule and no resolution of its own. That is deliberate and it is the
+ * single-home doctrine applied to itself — a second copy of a resolution is
+ * exactly the drift this phase exists to prevent, and the earlier waves' tests
+ * pin the first copy.
+ *
+ * NEVER-BLOCKS (D-43), carried forward from the research track: unprocessed
+ * feedback is not a fault — a round whose every Processing cell is `Open` exits
+ * 0 and reports those rows under `open_feedback`, so a still-running feedback
+ * loop can never block sign-off. Only STRUCTURAL faults set `ok` false.
+ *
+ * The `_screens.md` ABSENT arm skips coverage enforcement entirely. A document
+ * that does not exist has no markers that could be missing, and reporting
+ * `screens_markers` against it would collapse the absent arm into a fault — the
+ * conflation `loadDiscoveryArtifacts` exists to keep apart. The anchor join is
+ * NOT skipped in that arm, because an empty inventory map failing every anchor
+ * is the correct GUARD-01 reading rather than an over-report.
+ *
+ * `artifacts_checked` names the three artifacts this gate VALIDATES, and only
+ * those. `_risks.md` and `_research.md` are consulted for citation resolution,
+ * never checked — their grammar belongs to `discovery research-check` (D-42) —
+ * so listing them here would be the same overstatement that keeping an
+ * unreadable artifact out of the list avoids.
+ */
+function checkScreenInventory(cwd, budget = {}) {
+    const violations = [];
+    const loaded = loadDiscoveryArtifacts(cwd);
+    const artifactsChecked = [];
+    // 1–2. The screen inventory.
+    const screensContent = loaded.readArtifact(SCREENS_FILE);
+    if (screensContent !== null)
+        artifactsChecked.push(SCREENS_FILE);
+    const inventory = parseScreenInventory(screensContent);
+    violations.push(...inventory.violations);
+    // 3. The requirements spine, through rollup's single exported reader.
+    const requirements = resolveRequirements(loaded);
+    if (requirements.status !== 'absent')
+        artifactsChecked.push(REQUIREMENTS_FILE);
+    violations.push(...requirements.violations);
+    // 4. The feedback log.
+    const feedbackContent = loaded.readArtifact(FEEDBACK_FILE);
+    if (feedbackContent !== null)
+        artifactsChecked.push(FEEDBACK_FILE);
+    const feedback = parseFeedbackLog(feedbackContent);
+    violations.push(...feedback.violations);
+    // 5. The cross-artifact resolutions: anchors and Processing citations against
+    //    the inventory and the registers, and every screen's requirement
+    //    citations against the requirements spine. Each is a named function this
+    //    aggregator CALLS, never a rule it declares.
+    violations.push(...resolveCrossArtifact(inventory.screens, feedback.rows, loaded));
+    violations.push(...resolveRequirementRefs(inventory.screens, requirements));
+    // 6. The computed coverage assertion. Computed unconditionally so the payload
+    //    can report it, ENFORCED only against a `_screens.md` that exists.
+    const coverage = computeCoverage(inventory.screens, inventory.noScreen, requirements.rows);
+    let expectedBlock;
+    if (screensContent !== null) {
+        const coverageViolations = enforceCoverage(screensContent, coverage, requirements.status);
+        violations.push(...coverageViolations);
+        if (coverageViolations.some(v => v.reason === 'screens_mismatch')) {
+            // The VERBATIM render, not the violation's normalised `expected`: the
+            // operator is going to paste this between the markers, and the normalised
+            // form has had its blank line collapsed out of it.
+            expectedBlock = renderCoverageBlock(coverage);
+        }
+    }
+    // 7. The anti-leak scan, GATED ON ARTIFACTS. A project with no discovery
+    //    package never walks its own tree, so a codebase that uses `data-req` for
+    //    its own unrelated purposes is untouched (D-52 graceful arm applied to
+    //    D-54's false-positive surface, T-04-18).
+    //
+    //    The gate reads DISCOVERY_ARTIFACTS rather than `present.size > 0`: the
+    //    latter is every directory entry, so a `.DS_Store` that macOS writes on
+    //    mere Finder access — or a subdirectory, or an editor scratch file —
+    //    promoted an empty discovery folder into a whole-repo walk. The bound has
+    //    to be "a discovery package exists", not "the folder has something in it".
+    //
+    //    The allowlist is loaded here, in the layer that owns the discovery
+    //    package, and handed to the walk. Loading it unconditionally rather than
+    //    inside the gate keeps `artifact_unreadable` reachable for an unreadable
+    //    list even in a project that never gets scanned; the read is a no-op when
+    //    the file is absent, which is the ordinary case.
+    const scanAllow = loadScanAllowlist(loaded);
+    if (DISCOVERY_ARTIFACTS.some(file => loaded.present.has(file))) {
+        violations.push(...scanBuildTree(cwd, { ...budget, allow: scanAllow }));
+    }
+    // LAST, not first: `readArtifact` pushes onto this list as reads happen, and
+    // the citation registers are read lazily inside `resolveCrossArtifact`. Taking
+    // a copy any earlier would silently drop an `artifact_unreadable` fault.
+    violations.push(...loaded.violations);
+    const byVerdict = {};
+    for (const verdict of VERDICTS)
+        byVerdict[verdict] = 0;
+    let openTotal = 0;
+    for (const row of feedback.rows) {
+        if (row.processing !== PROCESSING.OPEN)
+            continue;
+        openTotal += 1;
+        // Guarded membership: a malformed verdict is already a `bad_verdict` fault
+        // and must not be able to mint a key on a derived object.
+        if (VERDICTS.includes(row.verdict))
+            byVerdict[row.verdict] += 1;
+    }
+    const result = {
+        ok: violations.length === 0,
+        artifacts_checked: artifactsChecked,
+        screens: inventory.screens.size,
+        rounds: feedback.rounds.size,
+        open_feedback: { total: openTotal, by_verdict: byVerdict },
+        coverage: {
+            mvp: coverage.mvp,
+            placed: coverage.placed,
+            bucketed: coverage.bucketed,
+            uncovered: coverage.uncovered.length,
+        },
+        violations,
+    };
+    if (expectedBlock !== undefined)
+        result.expected_coverage_block = expectedBlock;
+    return result;
+}
+// ─── CLI adapter ──────────────────────────────────────────────────────────────
+/**
+ * CLI adapter for `pp-tools discovery screen-check` (dotted form
+ * `pp-tools query discovery.screen-check`).
+ *
+ * Exit semantics: any structural violation exits non-zero via
+ * `ERROR_REASON.DISCOVERY_SCREEN_CHECK_FAILED`, naming each violation by
+ * locator and reason. Unprocessed feedback is NOT a violation (D-43) — a round
+ * whose every Processing cell is `Open` exits 0 and is reported under
+ * `open_feedback`.
+ *
+ * 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-04-17, the T-03-01 precedent).
+ * `--max-files <n>` and `--max-bytes <n>` are the ONLY arguments, and they
+ * adjust the build-tree scan's caps and nothing else. The traversal surface
+ * stays eliminated; only the CAP is operator-adjustable, because
+ * `scan_budget_exceeded` sets `ok` false and the handoff arm is a hard block
+ * with no option to proceed — a cap an operator cannot raise turns an honest
+ * truncation into an unpassable gate whose only remedy is deleting files.
+ *
+ * Each value must be a plain positive integer within `SCAN_ABSOLUTE_MAX`. The
+ * override RAISES or lowers a bound; it can never remove one, so the walk stays
+ * finite on both axes exactly as T-04-14 requires.
+ *
+ * The outstanding-work payload is emitted on the FAILURE path too, and first.
+ * An inventory with one malformed cell must not lose the report that makes an
+ * honest partial sign-off possible — that is precisely the state in which an
+ * operator needs both halves. The payload inherits the content-free contract by
+ * construction: counts, closed-vocabulary enum keys, artifact filenames and the
+ * machine-rendered coverage block, never a screen name or a feedback comment.
+ */
+function cmdDiscoveryScreenCheck(cwd, args, raw) {
+    // args arrive shaped ['discovery', 'screen-check', ...]; global output flags
+    // are consumed by the dispatcher, so anything left that is not one of the two
+    // budget flags or `--require-processed` — a positional path or an unknown flag
+    // alike — is a usage error. Parsed by hand so the accepted set stays visibly closed.
+    const rest = args.slice(2);
+    const budget = {};
+    let requireProcessed = false;
+    for (let i = 0; i < rest.length; i += 1) {
+        const flag = rest[i];
+        if (flag === '--require-processed') {
+            requireProcessed = true;
+            continue;
+        }
+        if (flag !== '--max-files' && flag !== '--max-bytes') {
+            error(SCREEN_CHECK_USAGE, ERROR_REASON.USAGE);
+            return; // unreachable — error() exits
+        }
+        const ceiling = flag === '--max-files' ? SCAN_ABSOLUTE_MAX.files : SCAN_ABSOLUTE_MAX.bytes;
+        const parsed = parseScanBound(rest[i + 1], ceiling);
+        if (parsed === null) {
+            error(SCREEN_CHECK_USAGE, ERROR_REASON.USAGE);
+            return; // unreachable — error() exits
+        }
+        if (flag === '--max-files')
+            budget.maxFiles = parsed;
+        else
+            budget.maxBytes = parsed;
+        i += 1; // the consumed value
+    }
+    const result = checkScreenInventory(cwd, budget);
+    const payload = {
+        ok: result.ok,
+        artifacts_checked: result.artifacts_checked,
+        screens: result.screens,
+        rounds: result.rounds,
+        open_feedback: result.open_feedback,
+        coverage: result.coverage,
+    };
+    // Present when and only when the block actually drifted, so its presence is
+    // itself the signal that there is something to paste back (D-06). There is no
+    // compute-and-write mode and no second command: this is how the
+    // replace-verbatim workflow is served by a pure validator.
+    if (result.expected_coverage_block !== undefined) {
+        payload.expected_coverage_block = result.expected_coverage_block;
+    }
+    if (!result.ok) {
+        const total = result.violations.length;
+        payload.violations = total;
+        // Emitted on stdout BEFORE the envelope goes to stderr, so the ordering is
+        // deterministic: `output` writes fd 1 synchronously and `error` exits.
+        output(payload, raw);
+        error(`discovery screen-check: ${total} violation(s):\n${renderViolations(result.violations).join('\n')}`, ERROR_REASON.DISCOVERY_SCREEN_CHECK_FAILED);
+        return; // unreachable — error() exits
+    }
+    // Session close and the build handoff: an Open row is feedback nobody has processed yet.
+    if (requireProcessed && result.open_feedback.total > 0) {
+        const open = result.open_feedback;
+        const split = VERDICTS.map((v) => `${v}: ${open.by_verdict[v] ?? 0}`).join(', ');
+        output(payload, raw);
+        error(`discovery screen-check: ${open.total} feedback row(s) still Open (${split}) in ${FEEDBACK_FILE} — process each before continuing`, ERROR_REASON.DISCOVERY_FEEDBACK_OPEN);
+        return; // unreachable — error() exits
+    }
+    output(payload, raw);
+}
+module.exports = {
+    SURFACE_STATUS,
+    VIOLATION_REASONS,
+    INSTRUMENTATION_LITERALS,
+    ECHO_MAX_CHARS,
+    MAX_REPORTED_VIOLATIONS,
+    SCREENS_FILE,
+    FEEDBACK_FILE,
+    REQUIREMENTS_FILE,
+    SCREENS_HEADING,
+    NO_SCREEN_HEADING,
+    COVERAGE_HEADING,
+    COVERAGE_OPEN,
+    COVERAGE_CLOSE,
+    SCREENS_OPEN,
+    SCREENS_CLOSE,
+    COVERAGE_LABELS,
+    RISKS_FILE,
+    RESEARCH_FILE,
+    VERDICTS,
+    PROCESSING,
+    ANCHOR_SEP,
+    SCREEN_COL,
+    NO_SCREEN_COL,
+    FEEDBACK_COL,
+    SCREEN_CHECK_FAILED,
+    SCAN_ALLOW_FILE,
+    DISCOVERY_ARTIFACTS,
+    loadScanAllowlist,
+    SCAN_SKIP_DIRS,
+    SCAN_EXTENSIONS,
+    SCAN_MAX_FILES,
+    SCAN_MAX_BYTES,
+    SCAN_FLOOR,
+    SCAN_ABSOLUTE_MAX,
+    SCREEN_CHECK_USAGE,
+    scanBuildTree,
+    loadDiscoveryArtifacts,
+    resolveRequirements,
+    parseScreenInventory,
+    parseFeedbackLog,
+    // Exported so the bounded-span floor can be falsified through THIS engine
+    // rather than only through the shared leaf. Both 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 (04-SECURITY AR-04-01).
+    validateScreenSequence,
+    validateRoundSequence,
+    resolveCrossArtifact,
+    resolveRequirementRefs,
+    computeCoverage,
+    renderCoverageBlock,
+    enforceCoverage,
+    formatViolation,
+    renderViolations,
+    checkScreenInventory,
+    cmdDiscoveryScreenCheck,
+};