@pareto4/pp-core 1.12.1 → 1.13.0

package/pp-core/bin/lib/vault-review.cjs

@@ -0,0 +1,2359 @@
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+/**
+ * src/vault-review.cts — the DETERMINISTIC half of the agent practice review
+ * (`/pp-vault-review`, vault assurance R5).
+ *
+ * ## What this module is
+ *
+ * The agent review judges vault practices no `check:` block can settle. A
+ * judgement is not reproducible, so everything the agent must NOT invent lives
+ * here instead: the input set, both derived-N-A populations, the counts, the
+ * rate line, the git range the review was computed over, the artifact the agent
+ * fills in, and the lines that artifact must state. Every one of them is an
+ * exported, unit-tested function, so the agent's discretionary surface shrinks
+ * to the genuinely ambiguous remainder and nothing else.
+ *
+ * Purely a LEAF. It imports leaves (`./vault-audit.cjs`, `./vault-practices.cjs`,
+ * `./vault-trace.cjs`, `./practices-review-check.cjs`, `./git-base-branch.cjs`,
+ * `./shell-command-projection.cjs`) and no adapter. The two functions that touch
+ * the world — the oracle run and the range resolver — take INJECTED seams
+ * (`_audit`, `exec`), so a test drives them without a repo. The I/O composition
+ * (reading the trace, the vault cache and the verdict owner) is the CLI arm's,
+ * in `src/check-command-router.cts`.
+ *
+ * The sibling modules are imported at the top rather than required at call
+ * time: under `recommendedTypeChecked` a bare `require()` returns `any`, while
+ * `import x = require('./y.cjs')` resolves to the sibling's `.cts` source and is
+ * fully typed. None of them performs I/O at load.
+ *
+ * ## The verdict vocabulary is LOCKED
+ *
+ * `REVIEW_VERDICT` holds exactly PASS / FAIL / N-A / INCONCLUSIVE. It is a module
+ * constant and is never re-derived from configuration or from the vault — the
+ * rule `src/vault-trace.cts` and `src/vault-audit.cts` state for the same
+ * reason: a verdict vocabulary a client repository could move is not one.
+ *
+ * It shares no token with the mechanical audit's `AUDIT_VERDICT`. `NO_CHECK` and
+ * `NOT_MATCHED` are facts about a machine-checkable rule; `N-A` and
+ * `INCONCLUSIVE` are facts about a judgement.
+ *
+ * A DELIBERATE DIVERGENCE from code review's practices findings ("likely
+ * violates, never certainty", capped at Warning): this review asserts a FLAT
+ * `FAIL`. It can, because it gates nothing — a FAIL here moves no score and
+ * blocks no ship. Uncertainty has its own honest home, `INCONCLUSIVE`.
+ *
+ * ## Arm A widens the judged boundary, and says so in every row
+ *
+ * `deriveNaAUniverse` (Arm A) reports on practices that were NEVER traced — the
+ * vault practice universe recorded at the pinned ref minus the ledger. That is
+ * wider than "traced practices with no usable `check:` block", and every Arm A
+ * row's reason names the universe as its source, so a reader meets the widening
+ * at the row that caused it. It is needed because `buildTraceStatement` fills
+ * the ledger from `matchPractices(...).matched ++ .global` only: every ledger
+ * entry already matched, so "never matched" can only come from the universe.
+ * Arm B re-derives applicability at review time from the phase's real diff.
+ *
+ * ## `check:`-presence is read LIVE, with an advisory — no trace-schema change
+ *
+ * The trace records no `check:`-presence field, so "traced ∩ NO_CHECK" needs the
+ * vault cache at review time. This module reads it through the shipped
+ * evaluator (`evaluatePractices` + `isNoCheckVerdict`); when the trace's pin and
+ * the cache's `resolvedSha` disagree it emits one advisory shaped like the trace
+ * gate's `PIN_DIVERGED` note — it reports, never blocks. A `checkPresent` field
+ * on the trace would be a schema change under `docs/vault-trace-format.md`'s
+ * freeze discipline for a consumer that does not need it, and this review is not
+ * a gate, so environment-dependence is acceptable here.
+ *
+ * ## The oracle is HARVESTED, never re-derived
+ *
+ * `deriveCandidateSet` learns `check:`-presence by running the shipped
+ * `evaluatePractices` and filtering with `isNoCheckVerdict`. It never scans for a
+ * `check:` key, because the audit tests `hasInvalidCheck` FIRST: an INVALID check
+ * is the mechanical audit's `FAIL`, not a `NO_CHECK`. The oracle runs over an
+ * EMPTY file set on purpose: `NO_CHECK` is decided before any file is consulted,
+ * so the answer is file- and machine-independent.
+ *
+ * ## Findings this module is built around
+ *
+ * - `matchPractices` returns `practicesProcessed: 0` for a never-fetched vault
+ *   and an empty one alike, so Arm B consumes a `discoverPracticeFiles` result
+ *   (whose `vaultPresent` and `readFailed` stay DISTINCT) plus the verdict
+ *   owner's view of the cache (`computeVaultVerdict`), never the match count.
+ * - A parser-rejected practice is reported as a NAMED exclusion, and a degraded
+ *   one as a note — never a silent narrowing.
+ * - The review range SHARES the audit's phase-scoped resolution first
+ *   (`resolvePhaseRange`: the manifest's `startCommit`, its recorded commits,
+ *   then SUMMARY trace digests). Only when that falls back does this module run
+ *   its own `(NN-` commit-token scan over `base..HEAD`, and only then the whole
+ *   base-branch span. `REVIEW_RANGE_SOURCE` mirrors the phase-scoped values
+ *   rather than referencing `AUDIT_RANGE_SOURCE`, which belongs to the blocking
+ *   gate.
+ * - An invalid `check:` is the mechanical audit's FAIL: it is excluded from the
+ *   candidate set and reported as a named exclusion (the practices README states
+ *   the audit blocks on it). Every judgement here binds to the audit's verdicts,
+ *   never to prose.
+ *
+ * ## Nothing measured must never render as clean
+ *
+ * Every degenerate path returns a record that SAYS what did not happen —
+ * `oracleSource: 'unavailable'` with a note, a `notDerived` record per arm, and
+ * `reviewRefusesCleanRender`, the single predicate that forbids a clean review
+ * when no file was considered or an input was not measured.
+ *
+ * ## Trust boundary
+ *
+ * Practice ids, `applies-to` globs and practice prose are CLIENT-AUTHORED DATA.
+ * They are bounded with the shipped `boundedToken` before they reach any string
+ * this module returns, and applicability is decided by the shipped `globMatch`
+ * alone. No client-authored byte is ever compiled into a regular expression and
+ * no second glob grammar is written here (the declarative-check rule,
+ * docs/practices-format.md). Reason texts name practice ids and mechanisms,
+ * never absolute filesystem paths.
+ */
+const node_path_1 = __importDefault(require("node:path"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const git_base_branch_cjs_1 = require("./git-base-branch.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const auditMod = require("./vault-audit.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const practicesMod = require("./vault-practices.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const traceMod = require("./vault-trace.cjs");
+// The artifact validator's fence markers and its parse cap are HARVESTED from
+// the shipped review checker that already exports them (plan 27-28's module),
+// never re-spelled here. A second spelling of a fence marker is a second
+// definition of where untrusted content ends, and this repository has already
+// paid for a decision taken by matching text rather than by reading a value.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const reviewCheckMod = require("./practices-review-check.cjs");
+const { AUDIT_VERDICT, AUDIT_FAIL_REASON, GIT_EMPTY_TREE } = auditMod;
+const { boundedToken } = practicesMod;
+const { TRACE_PROBLEM_KIND } = traceMod;
+const { FENCE_START_MARKER, FENCE_END_MARKER, MAX_PARSED_UNITS } = reviewCheckMod;
+// ─── The frozen vocabulary ───────────────────────────────────────────────────
+/**
+ * D-06-10's four verdicts, verbatim, and LOCKED.
+ *
+ * `INCONCLUSIVE` is a distinct fourth verdict and never folds into `N-A`:
+ * "not applicable here" and "I could not determine this" are completely
+ * different facts, and collapsing them hides the verifier's blind spots inside
+ * a count that looks like coverage. That is the same split D-05-03 already made
+ * one tier down between `NO_CHECK` and `NOT_MATCHED`.
+ */
+const REVIEW_VERDICT = Object.freeze({
+    PASS: 'PASS',
+    FAIL: 'FAIL',
+    NA: 'N-A',
+    INCONCLUSIVE: 'INCONCLUSIVE',
+});
+/**
+ * The TWO derived-N-A arms, as two distinct machine labels (F-2, resolved by
+ * the operator 2026-09-03). They reach the rendered artifact as two distinct
+ * derived reasons and MUST NOT be blurred into one "derived" flag: one says the
+ * practice was never in this phase's conversation at all, the other says it was
+ * and no changed file fell under it. Those are different findings — the first
+ * about the vault's reach, the second about this phase's diff — and a reader who
+ * cannot tell them apart cannot act on either.
+ */
+const NA_DERIVED_REASON = Object.freeze({
+    /** Arm A — in the vault practice universe at the pinned ref, absent from the ledger. */
+    UNIVERSE_MINUS_LEDGER: 'universe-minus-ledger',
+    /** Arm B — a scoped practice whose `applies-to` globs matched no file in the review diff. */
+    NO_FILE_IN_DIFF: 'no-file-in-diff',
+});
+/**
+ * Machine labels for a `notDerived` ground. Values, not prose: `matchBudgetNotes`
+ * is this codebase's standing proof that a decision is never taken by matching
+ * text, and a consumer distinguishing "never fetched" from "unreadable" must not
+ * have to read a sentence to do it.
+ */
+const NOT_DERIVED_GROUND = Object.freeze({
+    UNIVERSE_ABSENT: 'universe-absent',
+    // 06-12 Task 5 follow-up. A universe the trace DID record, withheld because
+    // the trace is degraded, is a different finding from one the trace never
+    // recorded — and the caller is the only party that can tell them apart, so it
+    // says which. Kept out of NOT_MEASURED_GROUNDS for exactly the reason
+    // UNIVERSE_ABSENT is: every degraded-trace review takes the reconstruct arm,
+    // and refusing on it would refuse the primary path.
+    UNIVERSE_WITHHELD: 'universe-withheld-degraded',
+    VAULT_STATE_UNKNOWN: 'vault-state-unknown',
+    VAULT_NEVER_FETCHED: 'vault-never-fetched',
+    VAULT_UNREADABLE: 'vault-unreadable',
+    /**
+     * The cache the vault verdict owner reads records a fetch MISS, or holds no
+     * file: a vault directory may exist, but no client vault was loaded into it.
+     * Without this ground a miss rendered as an empty, clean review.
+     */
+    VAULT_FETCH_MISS: 'vault-fetch-miss',
+    NO_FILES_CONSIDERED: 'no-files-considered',
+    MATCHER_UNAVAILABLE: 'matcher-unavailable',
+});
+/** The ground recorded when no NO_CHECK oracle reached the derivation at all. */
+const ORACLE_UNAVAILABLE_GROUND = 'no-check-oracle-unavailable';
+/**
+ * The grounds that mean the candidate derivation was NOT MEASURED (D3, plan
+ * 06-11) — the half of the distinction `reviewRefusesCleanRender` consumes.
+ *
+ * EMPTY BECAUSE NOTHING WAS MEASURED and EMPTY BECAUSE THE DERIVATION RAN AND
+ * NOTHING QUALIFIED are two different findings, and only one of them is a
+ * rubber stamp. Every ground below names an input the derivation NEEDED and did
+ * not get, so an empty result computed under one of them says nothing about the
+ * phase and must not render as a clean review. A ground absent from this set
+ * describes a measurement that happened, whose empty result IS a finding and
+ * renders with its stated N-A.
+ *
+ * `UNIVERSE_ABSENT` is deliberately NOT here, and the omission is the whole
+ * difference between fixing D3 and shouting it. That ground says the TRACE
+ * records no practice universe — which is true of every reconstruct review by
+ * definition, because a phase with no trace has no universe key. Refusing on it
+ * would refuse the entire reconstruct arm, which is the primary path (every
+ * phase of a project that never traced takes it), not a degraded one. A review that refuses
+ * everything judges exactly as much as one that judges nothing; it is only
+ * louder about it.
+ */
+const UNMEASURED_GROUND = new Set([
+    NOT_DERIVED_GROUND.VAULT_STATE_UNKNOWN,
+    NOT_DERIVED_GROUND.VAULT_NEVER_FETCHED,
+    NOT_DERIVED_GROUND.VAULT_UNREADABLE,
+    NOT_DERIVED_GROUND.VAULT_FETCH_MISS,
+    NOT_DERIVED_GROUND.NO_FILES_CONSIDERED,
+    NOT_DERIVED_GROUND.MATCHER_UNAVAILABLE,
+    ORACLE_UNAVAILABLE_GROUND,
+]);
+/**
+ * Where THIS tier's range came from — recorded beside the range itself.
+ *
+ * Deliberately NOT an extension of `AUDIT_RANGE_SOURCE` in
+ * `src/vault-audit.cts`: that vocabulary belongs to the BLOCKING tier, and one
+ * shared vocabulary would couple the two sides of the wall D-06-01 exists to
+ * keep apart — and would shift the producer-audit citations for no gain.
+ *
+ * * UAT-6-F1 added three members whose VALUES mirror the
+ * phase-scoped sources of the shared resolution. They are this object's own
+ * strings, reached from the audit's through `REVIEW_SOURCE_FOR_AUDIT_SOURCE`,
+ * never a reference to the audit's object.
+ */
+const REVIEW_RANGE_SOURCE = Object.freeze({
+    PHASE_START_COMMIT: 'phase-start-commit',
+    PHASE_FIRST_COMMIT: 'phase-first-commit',
+    TRACE_DIGEST: 'trace-digest',
+    PHASE_COMMIT_SCAN: 'phase-commit-scan',
+    BASE_BRANCH: 'base-branch',
+});
+/**
+ * The audit's phase-scoped range sources, keyed by the audit's OWN member
+ * values (read from the module, never re-spelled), mapped to this tier's.
+ * `base-branch` is deliberately UNMAPPED: a shared resolution that fell back
+ * hands over to this tier's own token scan rather than being adopted. Not
+ * exported — the export surface is a pinned contract.
+ */
+const REVIEW_SOURCE_FOR_AUDIT_SOURCE = Object.freeze({
+    [auditMod.AUDIT_RANGE_SOURCE.PHASE_START_COMMIT]: REVIEW_RANGE_SOURCE.PHASE_START_COMMIT,
+    [auditMod.AUDIT_RANGE_SOURCE.PHASE_FIRST_COMMIT]: REVIEW_RANGE_SOURCE.PHASE_FIRST_COMMIT,
+    [auditMod.AUDIT_RANGE_SOURCE.TRACE_DIGEST]: REVIEW_RANGE_SOURCE.TRACE_DIGEST,
+});
+/**
+ * How to get a phase whose range nobody could resolve back on a resolvable
+ * footing (08-05, D-08-17). Exported so the agent tier, a test and the artifact
+ * all quote THE SAME sentence: a remedy copied into a test rots the day the
+ * shipped one is reworded, and the pin that guards it stops guarding.
+ *
+ * Both remedies, deliberately. The first prevents the recurrence, the second
+ * rescues the phase that already happened — an operator handed only the first
+ * still has no way to review the phase in front of them.
+ */
+const REVIEW_RANGE_UNRESOLVABLE_REMEDY = 'Anchor the phase by running it through /pp-execute-phase (execute:pre records the start commit ' +
+    'via phase manifest start), or audit it by hand over a range you name: ' +
+    'pp-tools vault audit <phase-dir> --range <from>..<to>.';
+/**
+ * The opening of the note `resolveReviewRange` pushes when the SHARED
+ * phase-scoped resolution did not answer. One constant, two writers and one
+ * reader: the `range_unresolvable` statement finds that note by this prefix to
+ * quote the ground it recorded, and a prefix spelled twice is a prefix that
+ * stops matching the day one copy is reworded.
+ */
+const SHARED_RESOLUTION_NOTE_PREFIX = 'the shared phase-scoped resolution';
+/** The id charset a practice id must satisfy before it is echoed into a reason. */
+const REVIEW_ID_SHAPE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** A phase token: `6`, `06` or `06.1`. Anything else never reaches `git log`. */
+const PHASE_TOKEN_SHAPE = /^\d{1,3}(?:\.\d{1,3})?$/;
+/** A resolved commit object name, as `git log --format=%H` emits it. */
+const COMMIT_SHA_SHAPE = /^[0-9a-f]{7,64}$/;
+// ─── Small shared helpers ────────────────────────────────────────────────────
+function asStringList(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const entry of v) {
+        if (typeof entry === 'string' && entry !== '')
+            out.push(entry);
+    }
+    return out;
+}
+/** Order-stable dedup. The ledger's own order is the reported order. */
+function uniqueInOrder(ids) {
+    const seen = new Set();
+    const out = [];
+    for (const id of ids) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        out.push(id);
+    }
+    return out;
+}
+/** Bound a client-authored value before it reaches any returned string. */
+function safe(v) {
+    return boundedToken(v);
+}
+/** A practice id fit to quote back. Out-of-charset ids are bounded, never trusted. */
+function quotableId(id) {
+    return REVIEW_ID_SHAPE.test(id) ? id : safe(id);
+}
+/** Is this token one of the two verdicts that carry a judgement (D-06-10)? */
+function isJudgedVerdict(verdict) {
+    return verdict === REVIEW_VERDICT.PASS || verdict === REVIEW_VERDICT.FAIL;
+}
+/** Is this token one of the two NON-verdicts, which D-06-11 requires a reason of? */
+function isNonVerdict(verdict) {
+    return verdict === REVIEW_VERDICT.NA || verdict === REVIEW_VERDICT.INCONCLUSIVE;
+}
+// ─── The input set (traced ∩ NO_CHECK) ───────────────────────────────────────
+/**
+ * Derive the candidate set the agent tier may judge: the ids of THIS ARM's
+ * practice universe, intersected with the ids the SHIPPED evaluator calls
+ * `NO_CHECK`. Order-stable, deduplicated.
+ *
+ * ## The two universes (D3, plan 06-11)
+ *
+ * - TRACED (`reconstruct` absent or false) — the universe is the phase's trace
+ *   ledger. Unchanged, byte for byte, from the shipped behaviour: a traced
+ *   phase is judged against what it recorded.
+ * - RECONSTRUCT (`reconstruct: true`) — there is no ledger, so the universe is
+ *   the VAULT'S OWN practice list, in the order discovery returned it. This is
+ *   the half of D3 that made an untraced phase derive nothing at all: iterating
+ *   an empty ledger produced an empty candidate set, an empty remainder and no
+ *   fenced prose, no matter how large the diff or the vault, while the arm's
+ *   own statement said the set had been rebuilt from both.
+ *
+ * APPLICABILITY IS NOT DECIDED HERE, and deliberately so. This function answers
+ * "which practices could the agent tier own at all" (the mechanical tier owns
+ * every check-bearing one); crossing that universe with the review's real diff
+ * is `deriveNaANoFile`'s job and reaches the SHIPPED `globMatch` through the
+ * same `_practices` seam. No second matcher is written for the reconstruct arm,
+ * because a second matcher is a second answer to one question (the
+ * declarative-check rule). The practices that fall outside the range therefore leave
+ * this set as STATED derived N-A rows rather than as silent absences.
+ *
+ * Three oracle paths, and the third one SAYS so:
+ *   - `practices` supplied → `oracleSource: 'evaluated'`. The shipped
+ *     `evaluatePractices` runs over an empty file set (the ladder answers
+ *     `NO_CHECK` before consulting a file, so no diff is needed and none is
+ *     used) and `isNoCheckVerdict` selects. Every excluded id carries the
+ *     shipped verdict and fail-reason that excluded it.
+ *   - `noCheckIds` supplied → `oracleSource: 'provided'`. The pure path: a
+ *     caller that already holds the set.
+ *   - neither → `oracleSource: 'unavailable'`, an EMPTY candidate list and a
+ *     note stating that nothing was measured. An empty set with no note is
+ *     indistinguishable from "nothing qualifies", which is the silence this
+ *     workstream exists to end.
+ */
+function deriveCandidateSet(opts) {
+    const audit = opts._audit ?? auditMod;
+    const ledgerIds = uniqueInOrder(asStringList(opts.ledgerIds));
+    const reconstruct = opts.reconstruct === true;
+    const notes = [];
+    const exclusions = [];
+    // ── the oracle ──
+    let oracleSource = 'unavailable';
+    const noCheck = new Set();
+    const verdictById = new Map();
+    // Every id the oracle SAW, in the order it saw it. On the reconstruct arm this
+    // is the vault's practice list and becomes the universe; on the traced arm it
+    // is collected and unused, so the two arms share one traversal and cannot
+    // disagree about which ids the oracle covered.
+    const oracleIds = [];
+    if (Array.isArray(opts.practices)) {
+        oracleSource = 'evaluated';
+        const inputs = [];
+        for (const p of opts.practices) {
+            inputs.push({
+                id: typeof p?.id === 'string' ? p.id : '',
+                check: (p?.check ?? undefined),
+                checkInvalid: typeof p?.checkInvalid === 'string' ? p.checkInvalid : undefined,
+            });
+        }
+        const evaluated = audit.evaluatePractices({
+            practices: inputs,
+            // EMPTY on purpose — see the module header. The ladder returns NO_CHECK
+            // before any file is consulted, so the oracle is both file-independent
+            // and machine-independent.
+            files: [],
+        });
+        for (const entry of evaluated.practices) {
+            verdictById.set(entry.id, { verdict: entry.verdict, reason: entry.reason, detail: entry.detail });
+            oracleIds.push(entry.id);
+            if (audit.isNoCheckVerdict(entry.verdict))
+                noCheck.add(entry.id);
+        }
+    }
+    else if (opts.noCheckIds !== undefined && Array.isArray(opts.noCheckIds)) {
+        oracleSource = 'provided';
+        for (const id of asStringList(opts.noCheckIds)) {
+            noCheck.add(id);
+            oracleIds.push(id);
+        }
+    }
+    else {
+        notes.push('no NO_CHECK oracle was supplied: neither a live practice list nor a precomputed id set reached ' +
+            'this derivation, so the candidate set is EMPTY because nothing was measured — not because no ' +
+            'practice qualifies.');
+    }
+    // ── this arm's universe ∩ NO_CHECK, with every exclusion NAMED ──
+    //
+    // D3: the reconstruct arm's universe is the vault's practice list, because it
+    // has no ledger to intersect and iterating one produced an empty set that then
+    // rendered as a clean review. The traced arm is untouched.
+    const universeIds = reconstruct ? uniqueInOrder(oracleIds) : ledgerIds;
+    if (reconstruct) {
+        notes.push(
+        // NOT "no trace ledger exists": since 06-12 this arm is also taken by a
+        // phase whose trace parses but records a DEGRADED vault, and that phase
+        // does have a ledger — one this review declines to trust. Claiming it does
+        // not exist would be false on exactly the input G1 was about.
+        `no trusted trace ledger is available for this phase, so the candidate universe is the ${universeIds.length} practice ` +
+            "id(s) the vault's own practice list supplied. Which of them the phase's diff actually falls under is " +
+            'measured separately, by the shipped applicability matcher, and every one that does not is reported as ' +
+            'a derived N-A rather than dropped.');
+    }
+    const candidates = [];
+    for (const id of universeIds) {
+        if (noCheck.has(id)) {
+            candidates.push(id);
+            continue;
+        }
+        const known = verdictById.get(id);
+        if (known && known.reason === AUDIT_FAIL_REASON.CHECK_INVALID) {
+            exclusions.push({
+                id,
+                mechanicalVerdict: known.verdict,
+                reason: known.reason,
+                detail: `the \`check:\` block on "${quotableId(id)}" is not usable (${safe(known.detail)}). The shipped ` +
+                    'ladder tests an invalid check FIRST and returns FAIL, so this practice is the mechanical ' +
+                    "tier's and never reaches the agent tier.",
+            });
+            continue;
+        }
+        if (known) {
+            exclusions.push({
+                id,
+                mechanicalVerdict: known.verdict,
+                reason: known.reason,
+                detail: `"${quotableId(id)}" carries a usable \`check:\` block, so the shipped mechanical tier owns it ` +
+                    'and the agent tier never judges it. The verdict shown was computed over an EMPTY file set — ' +
+                    'the ladder decides NO_CHECK before any file is consulted, so no diff was needed and none was used.',
+            });
+            continue;
+        }
+        exclusions.push({
+            id,
+            mechanicalVerdict: null,
+            reason: null,
+            detail: `"${quotableId(id)}" is recorded in ${reconstruct ? "this vault's practice list" : "this phase's trace ledger"}` +
+                ' but is not in the NO_CHECK set the oracle produced, so it is not a candidate for agent judgement.',
+        });
+    }
+    // ── WR-02: a parser-rejected practice never leaves the set in silence ──
+    for (const entry of opts.skipped ?? []) {
+        const where = typeof entry?.path === 'string' ? entry.path : '';
+        exclusions.push({
+            id: safe(node_path_1.default.basename(where) || where),
+            mechanicalVerdict: AUDIT_VERDICT.FAIL,
+            reason: AUDIT_FAIL_REASON.PRACTICE_UNLOADABLE,
+            detail: 'a practice file was REJECTED by the parser and therefore never entered the practice set: ' +
+                `${safe(entry?.warning)}. Its check-bearing-ness is unknown, so it can be neither a candidate ` +
+                'nor a silent absence.',
+        });
+    }
+    // ── degraded practices are RETAINED (their prose still applies) but named ──
+    for (const entry of opts.degraded ?? []) {
+        notes.push(`practice "${quotableId(typeof entry?.id === 'string' ? entry.id : '')}" was retained but DEGRADED: ` +
+            `${safe(asStringList(entry?.warnings).join('; '))}. Its prose still applies and it stays in the population.`);
+    }
+    return {
+        candidates,
+        exclusions,
+        advisories: derivePinAdvisories(opts.tracePinSha, opts.cacheSha),
+        notes,
+        oracleSource,
+    };
+}
+/**
+ * The pin advisory (recorded decision above; no trace-schema change).
+ *
+ * Mirrors the wording discipline of the trace gate's `PIN_DIVERGED` note
+ * (`cmdVaultTrace`) and harvests its KIND from
+ * `TRACE_PROBLEM_KIND` so the two cannot drift. It reports; it never blocks;
+ * it states that no reader action is required. An ABSENT cache emits NOTHING —
+ * an absent cache is not a divergence, and a check that fired on absence would
+ * penalise every machine that never fetched.
+ */
+function derivePinAdvisories(tracePinSha, cacheSha) {
+    const pinned = typeof tracePinSha === 'string' ? tracePinSha.trim() : '';
+    const local = typeof cacheSha === 'string' ? cacheSha.trim() : '';
+    if (pinned === '' || local === '' || pinned === local)
+        return [];
+    return [
+        {
+            kind: TRACE_PROBLEM_KIND.PIN_DIVERGED,
+            detail: `this phase's trace pins the vault at "${safe(pinned)}" while the local cache records ` +
+                `"${safe(local)}", and the \`check:\`-presence oracle above was read from the LOCAL cache. This ` +
+                'is a NOTE, not a defect: whether the vault has moved since the trace was written is a different ' +
+                'question from whether this review is valid, and this tier gates nothing. No action is required ' +
+                'of anyone reading this.',
+        },
+    ];
+}
+// ─── Counts and the rate line ────────────────────────────────────────────────
+/**
+ * Count the four verdicts, in the shape the audit's `countVerdicts`
+ * established one tier down.
+ *
+ * `judged` is `total - na`. Recorded because it is a choice: an `INCONCLUSIVE`
+ * practice WAS judged — the agent looked at it and could not determine an
+ * answer — while an `N-A` practice was not judged at all, either because the
+ * derivation removed it or because the agent found it inapplicable. So
+ * `INCONCLUSIVE` counts inside `judged` and is ALSO reported on its own, which
+ * is what makes a hollow review visible: a rate line reading `12 of 16 judged ·
+ * 4 N-A · 11 INCONCLUSIVE` says something a count of PASSes never could.
+ *
+ * `total` counts only rows with a RECOGNISED verdict, so `judged + na === total`
+ * holds unconditionally. Rows outside the vocabulary are counted as
+ * `unrecognised` and never absorbed into a real verdict — an unrecognised row
+ * silently folded into N-A would be an invented non-verdict.
+ *
+ * D-06-11 is enforced at the type level by `NonVerdictRow`. It is ALSO checked
+ * here, because rows arrive as parsed YAML from an artifact no compiler saw. A
+ * bare non-verdict is REPORTED in `malformed` and still counted: dropping it
+ * would shrink the denominator, which is the one number this tier must never
+ * quietly improve.
+ */
+function countReviewVerdicts(rows) {
+    const counts = {
+        pass: 0,
+        fail: 0,
+        na: 0,
+        inconclusive: 0,
+        judged: 0,
+        total: 0,
+        unrecognised: 0,
+        malformed: [],
+    };
+    const list = Array.isArray(rows) ? rows : [];
+    for (const raw of list) {
+        if (raw === null || typeof raw !== 'object') {
+            counts.unrecognised += 1;
+            continue;
+        }
+        const row = raw;
+        const verdict = typeof row.verdict === 'string' ? row.verdict : '';
+        const id = typeof row.id === 'string' ? row.id : '';
+        if (!isJudgedVerdict(verdict) && !isNonVerdict(verdict)) {
+            counts.unrecognised += 1;
+            continue;
+        }
+        if (verdict === REVIEW_VERDICT.PASS)
+            counts.pass += 1;
+        else if (verdict === REVIEW_VERDICT.FAIL)
+            counts.fail += 1;
+        else if (verdict === REVIEW_VERDICT.NA)
+            counts.na += 1;
+        else
+            counts.inconclusive += 1;
+        counts.total += 1;
+        if (isNonVerdict(verdict)) {
+            const reason = typeof row.reason === 'string' ? row.reason.trim() : '';
+            if (reason === '') {
+                counts.malformed.push({
+                    id: quotableId(id),
+                    verdict,
+                    problem: 'A non-verdict must carry a stated reason. A bare N-A or INCONCLUSIVE is ' +
+                        'indistinguishable from the agent giving up.',
+                });
+            }
+        }
+    }
+    counts.judged = counts.total - counts.na;
+    return counts;
+}
+/**
+ * D-06-12's non-verdict rate line, computed from the four verdict counts and
+ * NOTHING else — a supplied `judged` or `total` is deliberately ignored, so a
+ * caller cannot narrate a denominator the rows do not support.
+ *
+ * D-06-13 constrains the shape: counts only. No ratio, no percentage, no letter
+ * grade, no single score. A single number invites being quoted as "87 %
+ * compliant" — a measured-sounding claim about an LLM judgement, which is
+ * precisely the over-claim this phase exists to prevent.
+ */
+function renderRateLine(counts) {
+    const n = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0);
+    const pass = n(counts?.pass);
+    const fail = n(counts?.fail);
+    const na = n(counts?.na);
+    const inconclusive = n(counts?.inconclusive);
+    const total = pass + fail + na + inconclusive;
+    const judged = total - na;
+    return `${judged} of ${total} practices judged · ${na} N-A · ${inconclusive} INCONCLUSIVE`;
+}
+/**
+ * The MECHANICAL tier's coverage over THIS review's own resolved file set
+ * (MECH-02, D-10-03), or `null` when there was nothing honest to compute it
+ * from.
+ *
+ * HARVESTED, NEVER REWRITTEN. Three shipped pieces and no fourth: the shipped
+ * `evaluatePractices` through the same audit seam `deriveCandidateSet` reaches,
+ * then the shipped `countVerdicts`, then the ONE renderer `src/vault-audit.cts`
+ * exports. `src/check-command-router.cts` states the rule for its own
+ * pass-through and it holds identically here — a second computation is a second
+ * place the report can disagree with the gate that blocks on it.
+ *
+ * The counter and the renderer are deliberately NOT taken off the seam. The
+ * seam exists so a test can substitute the EVALUATOR; letting a caller
+ * substitute the arithmetic or the wording would hand back exactly the
+ * narrated denominator `renderRateLine` refuses to accept.
+ *
+ * The reader is the shipped BOUNDED one, rooted at the review's own `cwd`, so a
+ * `require:`/`forbid:` assertion is measured rather than collapsed into
+ * `file_unreadable` — and so the containment properties that reader's contract
+ * proves are the ones in force here too. No reader, no read: a run with no cwd
+ * evaluates with the fail-closed default rather than inventing one.
+ */
+function deriveMechanicalCoverageLine(opts) {
+    const audit = opts?._audit ?? auditMod;
+    if (typeof audit?.evaluatePractices !== 'function')
+        return null;
+    const inputs = [];
+    for (const p of opts?.practices ?? []) {
+        if (!p || typeof p.id !== 'string' || p.id === '')
+            continue;
+        inputs.push({
+            id: p.id,
+            check: (p.check ?? undefined),
+            checkInvalid: typeof p.checkInvalid === 'string' ? p.checkInvalid : undefined,
+            // MECH-01 (D-10-12): the practice's own applies-to bounds the comparison
+            // here for the same reason it does in the gate. An ABSENT list is the
+            // same case as an EMPTY one — applies everywhere — which is what the
+            // evaluator's own branch says, so nothing is re-decided here.
+            appliesTo: [...asStringList(p.appliesTo)],
+        });
+    }
+    const root = typeof opts?.cwd === 'string' && opts.cwd !== '' ? opts.cwd : null;
+    const readFile = root === null ? null : auditMod.createBoundedFileReader(root);
+    const evaluated = audit.evaluatePractices({
+        practices: inputs,
+        files: [...asStringList(opts?.files)],
+        ...(readFile === null ? {} : { readFile }),
+    });
+    return auditMod.renderMechanicalCoverageLine(auditMod.countVerdicts(evaluated.practices));
+}
+// ─── Arm A — the vault universe minus the trace ledger ───────────────────────
+/**
+ * Arm A: every practice in the vault universe recorded at the pinned ref that
+ * the trace ledger never mentions. Those practices were never matched at plan
+ * time, so no code in this phase was written against them — a DERIVED N-A, not
+ * a judgement (D-06-09).
+ *
+ * BOUNDARY WIDENING, surfaced in every row (and in the module header): these
+ * ids were never traced, so reporting them widens the judged boundary beyond
+ * the traced input set (see the module header). The reason
+ * text names the vault universe as its source so a reader of the ARTIFACT meets
+ * the widening at the row that caused it, never only in a plan nobody reopens.
+ *
+ * ABSENT and EMPTY are different facts and this function keeps them apart —
+ * `docs/vault-trace-format.md` says so explicitly. `practiceUniverse` is
+ * OMITTED (or null) whenever the pin is null, because a degraded run has no
+ * universe to record: that derives NOTHING and returns a loud not-derived
+ * record. A literal empty array means the manifest was read and held no
+ * practices: that derives zero rows with NO gap record, because nothing is
+ * missing.
+ */
+function deriveNaAUniverse(opts) {
+    const notes = [];
+    const universe = opts?.universe;
+    if (universe === undefined || universe === null || !Array.isArray(universe)) {
+        return {
+            derived: false,
+            rows: [],
+            notDerived: {
+                arm: NA_DERIVED_REASON.UNIVERSE_MINUS_LEDGER,
+                ...(opts?.universeWithheld === true
+                    ? {
+                        ground: NOT_DERIVED_GROUND.UNIVERSE_WITHHELD,
+                        statement: 'Arm A derived NOTHING: this trace DOES record a practice universe, and it was ' +
+                            'deliberately withheld because the trace is DEGRADED — it records that the vault could ' +
+                            'not be loaded when the work was planned, so its universe proves nothing about which ' +
+                            'practices governed that work and may not be subtracted from. This is a ' +
+                            // Same wording constraint as the sibling branch below: the
+                            // prompt-injection scanner's regex carries no leading word
+                            // boundary, so "is a different fact from …" is written in place
+                            // of the natural phrasing.
+                            'WITHHELD universe, which is a different fact from a trace that records no universe at ' +
+                            'all, and a different fact from a vault that was read and held no practices — no ' +
+                            'derived N-A may be reported from it.',
+                    }
+                    : {
+                        ground: NOT_DERIVED_GROUND.UNIVERSE_ABSENT,
+                        statement: 'Arm A derived NOTHING: this trace records no practice universe at all. The universe key is ' +
+                            'omitted whenever the vault pin is null, so a degraded or never-pinned run has no universe to ' +
+                            // WORDING CONSTRAINT, recorded so a future edit does not undo it:
+                            // `tests/prompt-injection-scan.security.test.cjs` scans this module's
+                            // emitted `.cjs` for a role-manipulation pattern whose regex carries
+                            // no leading word boundary, so the last three letters of "fact"
+                            // followed by " as a <noun>" match it. Every sentence here therefore
+                            // says "is a different fact from …" rather than the natural phrasing.
+                            'subtract the ledger from. This is an ABSENT universe, which is a different fact from a vault ' +
+                            'that was read and held no practices — no derived N-A may be reported from it.',
+                    }),
+            },
+            notes,
+        };
+    }
+    const ledger = new Set(asStringList(opts.ledgerIds));
+    const rows = [];
+    for (const id of uniqueInOrder(asStringList(universe))) {
+        if (ledger.has(id))
+            continue;
+        rows.push({
+            id,
+            verdict: REVIEW_VERDICT.NA,
+            naDerivedReason: NA_DERIVED_REASON.UNIVERSE_MINUS_LEDGER,
+            reason: `derived, not judged: "${quotableId(id)}" is in the VAULT PRACTICE UNIVERSE recorded at the ` +
+                "pinned ref and absent from this phase's trace ledger, so it was never matched to any file at " +
+                'plan time and no code here was written against it. Reported under a judged boundary WIDENED ' +
+                'beyond the traced set: the trace ledger is not the whole vault, and this practice was never traced.',
+        });
+    }
+    if (rows.length === 0) {
+        notes.push(`Arm A derived zero rows: the trace ledger accounts for every one of the ${universe.length} ` +
+            'practice id(s) in the recorded universe. The universe was READ — this is an empty result, not a gap.');
+    }
+    return { derived: true, rows, notDerived: null, notes };
+}
+// ─── Arm B — review-time applicability against the real diff ────────────────
+/**
+ * Arm B: a candidate whose `applies-to` globs match no file in the review
+ * range. Re-derived at review time against the phase's REAL diff (D-06-15's
+ * wording), never against a plan's `files_modified` — a plan states intent and
+ * this tier reports what happened. The artifact states which range produced the
+ * file list, and when that range is refused or empty this arm is SKIPPED with a
+ * loud not-derived record rather than fabricating N-A from an unmeasured diff:
+ * "no file matched" and "no file was looked at" are different facts, and only
+ * the first is a finding.
+ *
+ * The vault-state guard is CR-01's workaround and the reason this function
+ * takes a `discoverPracticeFiles` result rather than calling `matchPractices`:
+ * `matchPractices` returns `practicesProcessed: 0` for a never-fetched vault
+ * and for an empty one alike, so it cannot be the vault-state oracle. Discovery
+ * keeps `vaultPresent` and `readFailed` distinct, and the two degraded states
+ * get two DIFFERENT loud statements and two different grounds — never fetched
+ * and unreadable are different repairs, and collapsing them would tell an
+ * operator to do the wrong one.
+ *
+ * A GLOBAL-scope practice never receives an Arm B N-A, by construction: a
+ * global practice applies to the whole change set by definition, so "no file
+ * fell under it" is not a statement that can be true of one.
+ *
+ * Applicability is decided by the SHIPPED `globMatch` alone (the declarative-check
+ * rule: no second grammar, no client-authored byte compiled into a RegExp).
+ */
+function deriveNaANoFile(opts) {
+    const arm = NA_DERIVED_REASON.NO_FILE_IN_DIFF;
+    const notes = [];
+    const refuse = (ground, statement) => ({
+        derived: false,
+        rows: [],
+        notDerived: { arm, ground, statement },
+        notes,
+    });
+    const discovery = opts?.discovery;
+    if (discovery === undefined || discovery === null || typeof discovery !== 'object') {
+        return refuse(NOT_DERIVED_GROUND.VAULT_STATE_UNKNOWN, 'Arm B derived NOTHING: no practice-discovery result was supplied, so whether the client vault is ' +
+            'present and readable is UNKNOWN. Applicability is not derived from an unknown vault state, ' +
+            'because a practice set that may be empty only because nothing was read cannot produce an ' +
+            'honest N-A.');
+    }
+    if (discovery.vaultPresent === false) {
+        return refuse(NOT_DERIVED_GROUND.VAULT_NEVER_FETCHED, 'Arm B derived NOTHING: no fetched client vault cache exists on this machine — the vault was ' +
+            'NEVER FETCHED. This is not an empty vault, and no applicability was derived from it. Repair by ' +
+            'fetching the vault, then re-run the review.');
+    }
+    if (discovery.fetchMiss === true) {
+        return refuse(NOT_DERIVED_GROUND.VAULT_FETCH_MISS, 'Arm B derived NOTHING: the vault cache records a FETCH MISS (or holds no file), so no client vault ' +
+            'was loaded and no applicability was derived from it. An empty practice set read from a miss is ' +
+            'not an empty vault. Repair by fetching the vault, then re-run the review.');
+    }
+    if (discovery.readFailed === true) {
+        return refuse(NOT_DERIVED_GROUND.VAULT_UNREADABLE, 'Arm B derived NOTHING: the client vault is PRESENT but a read of it REFUSED — the vault is ' +
+            'unreadable. This is not an empty vault and not a missing one, and no applicability was derived ' +
+            'from it. Repair by making the cached vault readable, then re-run the review.');
+    }
+    const diffFiles = asStringList(opts.diffFiles).map((f) => f.replace(/\\/g, '/'));
+    if (diffFiles.length === 0) {
+        return refuse(NOT_DERIVED_GROUND.NO_FILES_CONSIDERED, 'Arm B derived NOTHING: the review range yielded zero files, so no applicability was measured. ' +
+            '"No file matched this practice" and "no file was looked at" are different facts and only the ' +
+            'first is a finding — an N-A fabricated from an unmeasured diff would be the second wearing the ' +
+            "first's label.");
+    }
+    const matcher = opts._practices ?? practicesMod;
+    if (typeof matcher.globMatch !== 'function') {
+        return refuse(NOT_DERIVED_GROUND.MATCHER_UNAVAILABLE, 'Arm B derived NOTHING: the shipped glob matcher could not be reached, and no second matcher is ' +
+            'written here (the declarative-check rule). No applicability was measured.');
+    }
+    const byId = new Map();
+    for (const p of opts.practices ?? []) {
+        if (p && typeof p.id === 'string')
+            byId.set(p.id, p);
+    }
+    const rows = [];
+    for (const id of uniqueInOrder(asStringList(opts.candidates))) {
+        const practice = byId.get(id);
+        if (!practice) {
+            notes.push(`Arm B skipped "${quotableId(id)}": it is a candidate but no practice record carrying its ` +
+                '`applies-to` globs was supplied, so its applicability was NOT measured and no N-A is claimed.');
+            continue;
+        }
+        // A global practice applies to everything; "no file fell under it" cannot
+        // be true of one, so it is excluded from this arm by construction.
+        if (practice.scope !== 'scoped')
+            continue;
+        const globs = asStringList(practice.appliesTo);
+        if (globs.length === 0) {
+            notes.push(`Arm B skipped "${quotableId(id)}": it is scoped but carries no \`applies-to\` glob, so there is ` +
+                'nothing to measure applicability against and no N-A is claimed.');
+            continue;
+        }
+        let matchedAny = false;
+        for (const file of diffFiles) {
+            for (const glob of globs) {
+                if (matcher.globMatch(file, glob)) {
+                    matchedAny = true;
+                    break;
+                }
+            }
+            if (matchedAny)
+                break;
+        }
+        if (matchedAny)
+            continue;
+        rows.push({
+            id,
+            verdict: REVIEW_VERDICT.NA,
+            naDerivedReason: NA_DERIVED_REASON.NO_FILE_IN_DIFF,
+            reason: `derived, not judged: "${quotableId(id)}" is a scoped practice and none of its \`applies-to\` ` +
+                `glob(s) matched any of the ${diffFiles.length} file(s) in this review's range, so no changed ` +
+                'file in this phase falls under it.',
+        });
+    }
+    return { derived: true, rows, notDerived: null, notes };
+}
+// ─── The partition that feeds the agent ─────────────────────────────────────
+/**
+ * Split the reported population into the two derived-N-A sets and the
+ * REMAINDER — the only ids that reach the agent (D-06-09).
+ *
+ * The three sets are DISJOINT and their union is exactly `population`. Arm A's
+ * ids come from the universe minus the ledger and Arm B's from the candidates
+ * (a subset of the ledger), so they are structurally disjoint already; the
+ * ordering below makes it true even when a caller hands in overlapping rows,
+ * with Arm A winning, because "never traced at all" is the stronger statement
+ * and the weaker one would say less about the same id.
+ */
+function partitionForJudgement(opts) {
+    const rowsOf = (v) => {
+        if (v === undefined || v === null)
+            return [];
+        if (Array.isArray(v))
+            return [...v];
+        const arm = v;
+        return Array.isArray(arm.rows) ? [...arm.rows] : [];
+    };
+    const armA = [];
+    const armAIds = new Set();
+    for (const row of rowsOf(opts?.naUniverse)) {
+        if (typeof row?.id !== 'string' || armAIds.has(row.id))
+            continue;
+        armAIds.add(row.id);
+        armA.push(row);
+    }
+    const armB = [];
+    const armBIds = new Set();
+    for (const row of rowsOf(opts?.naNoFile)) {
+        if (typeof row?.id !== 'string' || armAIds.has(row.id) || armBIds.has(row.id))
+            continue;
+        armBIds.add(row.id);
+        armB.push(row);
+    }
+    const candidates = uniqueInOrder(asStringList(opts?.candidates));
+    const population = uniqueInOrder([...armA.map((r) => r.id), ...candidates]);
+    const remainder = population.filter((id) => !armAIds.has(id) && !armBIds.has(id));
+    return { naUniverse: armA, naNoFile: armB, remainder, population };
+}
+// ─── The review range, and the refusal that guards it ───────────────────────
+/** Normalise a phase token to the zero-padded form the commit convention uses. */
+function normalisePhaseToken(v) {
+    const raw = typeof v === 'number' && Number.isFinite(v) ? String(v) : typeof v === 'string' ? v.trim() : '';
+    if (!PHASE_TOKEN_SHAPE.test(raw))
+        return null;
+    const parts = raw.split('.');
+    const padded = parts[0].padStart(2, '0');
+    return parts.length === 1 ? padded : `${padded}.${parts[1]}`;
+}
+/**
+ * Resolve the range this review is computed over, and RECORD where it came from
+ * (F-3 / WR-04).
+ *
+ * First — the SHARED phase-scoped resolution (UAT-6-F1). When a
+ * `phaseDir` is given, the mechanical tier's `resolvePhaseRange` is asked
+ * before anything else, and its ladder is the one this tier adopts:
+ * `phase-start-commit` (the manifest anchor written at execute:pre),
+ * `phase-first-commit` (the commits recorded at verify:post), then
+ * `trace-digest` (SUMMARY `gitCommit` digests, for a phase built before that
+ * writer). Its notes travel with the adopted range. When it answers
+ * `base-branch` — its fourth rung — the fallback is NOT adopted: one note names
+ * its ground and this tier continues into its own scan. The vocabulary stays
+ * separate for the reason `REVIEW_RANGE_SOURCE` states.
+ *
+ * Then — `phase-commit-scan`: the EARLIEST commit on `base..HEAD` whose
+ * message carries this repository's `type(NN-MM):` convention token for the
+ * phase, anchored on that commit's parent. This is WR-04's own suggested fix,
+ * and it covers a phase branch that never recorded a manifest. The scan stays
+ * over `base..HEAD` and is never widened to whole history: this repository
+ * carries two workstreams whose `(05-` tokens would both match. A review that
+ * attributes another phase's file to this one is the misleading verdict this
+ * tier exists to avoid.
+ *
+ * When the phase's first commit is the repository root there is no parent to
+ * anchor on, so the anchor becomes git's empty-tree object — HARVESTED from the
+ * mechanical tier's `GIT_EMPTY_TREE` rather than spelled again here. That is
+ * not a fallback: a phase-scoped range was resolved, so the source stays
+ * `phase-commit-scan`.
+ *
+ * Fallback — `base-branch`: `resolveBaseBranchResult(cwd)...HEAD`. The 5-tier
+ * ladder is never re-derived (#1146 records what the naive `origin/HEAD` +
+ * `:-main` form cost) and every git call goes through the timeout-bounded
+ * `execGit` seam, never `execFileSync`. The RESULT form is used rather than the
+ * bare string so a REFUSED `git.base_branch` becomes a stated note instead of a
+ * silent change of range (T-6-49).
+ *
+ * TWO deliberate details in the scan:
+ *   - `-F` (fixed-string). A commit subject is repository data; reading the
+ *     needle as a pattern would let the convention token's own parenthesis be
+ *     a group, and a phase token that failed `PHASE_TOKEN_SHAPE` never reaches
+ *     git at all.
+ *   - `base..HEAD`, not `base...HEAD`. For `git log` the three-dot form is the
+ *     SYMMETRIC difference and would admit commits that live only on the base,
+ *     which are by definition not this phase's.
+ *
+ * Deletions are excluded from the file list (`--diff-filter=d`), the same
+ * scoping the mechanical tier states its own reasons for: a deleted violation
+ * is the fix, and a deleted file has no content left to satisfy anything.
+ *
+ * Every degenerate path pushes a NOTE. A range that resolved nothing and a diff
+ * that could not be read must never look like a phase that changed nothing.
+ */
+function resolveReviewRange(opts) {
+    const exec = typeof opts?.exec === 'function' ? opts.exec : shell_command_projection_cjs_1.execGit;
+    const cwd = typeof opts?.cwd === 'string' && opts.cwd !== '' ? opts.cwd : process.cwd();
+    const notes = [];
+    let base = 'main';
+    try {
+        // The RESULT form, not the bare string: `git.base_branch` is the one value
+        // this function puts on a git command line that comes from a file a cloned
+        // repository can carry, and the ladder now refuses a shape git would read as
+        // an option rather than a revision (T-6-49). A refusal that fell back to
+        // "main" in silence would be exactly the failure mode this whole module
+        // exists to end, so it is stated here — this function already owns the
+        // channel, and every other degenerate path below already uses it.
+        const resolved = (0, git_base_branch_cjs_1.resolveBaseBranchResult)(cwd, { execGit: exec });
+        base = resolved.branch;
+        if (resolved.configRejected !== null) {
+            notes.push(`${resolved.configRejected.reason} The range below is computed over "${safe(base)}" instead.`);
+        }
+    }
+    catch {
+        base = 'main';
+        notes.push('the base-branch ladder threw, so the range fell back to the literal default "main".');
+    }
+    let range = `${base}...HEAD`;
+    let rangeSource = REVIEW_RANGE_SOURCE.BASE_BRANCH;
+    // The shared phase-scoped resolution, ahead of the token scan (UAT-6-F1).
+    let sharedResolved = false;
+    if (typeof opts?.phaseDir === 'string' && opts.phaseDir !== '') {
+        try {
+            const shared = auditMod.resolvePhaseRange({ root: cwd, phaseDir: node_path_1.default.resolve(cwd, opts.phaseDir), exec });
+            const mapped = Object.prototype.hasOwnProperty.call(REVIEW_SOURCE_FOR_AUDIT_SOURCE, shared.rangeSource)
+                ? REVIEW_SOURCE_FOR_AUDIT_SOURCE[shared.rangeSource]
+                : undefined;
+            if (mapped !== undefined) {
+                range = shared.range;
+                rangeSource = mapped;
+                for (const note of shared.notes ?? [])
+                    notes.push(note);
+                sharedResolved = true;
+            }
+            else {
+                notes.push(`${SHARED_RESOLUTION_NOTE_PREFIX} fell back (${safe(shared.fallbackReason ?? 'no ground recorded')}): ` +
+                    'no usable phase manifest entry and no verifiable SUMMARY trace digest, so the phase-commit scan ran next.');
+            }
+        }
+        catch {
+            notes.push(`${SHARED_RESOLUTION_NOTE_PREFIX} threw, so the phase-commit scan ran next.`);
+        }
+    }
+    const token = normalisePhaseToken(opts?.phaseToken);
+    if (sharedResolved) {
+        // The phase-scoped range above is adopted; the token scan is not needed.
+    }
+    else if (token === null) {
+        notes.push('no usable phase token was supplied, so the phase-commit scan never ran and the range is the whole ' +
+            'base-branch span — which, on a repository that uses no phase branching, covers every phase since ' +
+            'the base rather than this one. Files below may belong to another phase.');
+    }
+    else {
+        const needle = `(${token}-`;
+        let anchor = null;
+        try {
+            const log = exec(['log', '--format=%H', '--reverse', '-F', '--grep', needle, `${base}..HEAD`], { cwd });
+            if (log.exitCode === 0 && !log.error) {
+                const first = String(log.stdout || '')
+                    .split('\n')
+                    .map((line) => line.trim())
+                    .find((line) => COMMIT_SHA_SHAPE.test(line));
+                if (first !== undefined) {
+                    const parent = exec(['rev-parse', '--verify', `${first}^`], { cwd });
+                    anchor = parent.exitCode === 0 && !parent.error ? `${first}^` : GIT_EMPTY_TREE;
+                }
+            }
+        }
+        catch {
+            anchor = null;
+        }
+        if (anchor === null) {
+            notes.push(`no commit on ${base}..HEAD carries the "${needle}" convention token, so the phase-commit scan ` +
+                'resolved nothing and the range fell back to the whole base-branch span. Files below may belong ' +
+                'to another phase.');
+        }
+        else {
+            range = `${anchor}..HEAD`;
+            rangeSource = REVIEW_RANGE_SOURCE.PHASE_COMMIT_SCAN;
+        }
+    }
+    let files = [];
+    try {
+        const diff = exec(['diff', '--name-only', '--diff-filter=d', range], { cwd });
+        if (diff.exitCode === 0 && !diff.error) {
+            files = String(diff.stdout || '')
+                .split('\n')
+                .map((line) => line.trim())
+                .filter((line) => line !== '');
+        }
+        else {
+            notes.push(`the diff over ${range} could not be READ, so zero files were considered — this is an unreadable ` +
+                'diff, not a phase that changed nothing.');
+        }
+    }
+    catch {
+        notes.push(`the diff over ${range} threw, so zero files were considered — this is an unreadable diff, not a ` +
+            'phase that changed nothing.');
+    }
+    // ── WHAT the range established, read from the audit leaf's ONE predicate
+    // (08-05, D-08-17). `phase-commit-scan` counts as phase-scoped because the
+    // review's OWN scan anchored on this phase's commits; only the base-branch
+    // span establishes nothing about the phase, which is exactly the direction
+    // WR-04's predicate states and 08-04 preserved (D-08-18).
+    //
+    // The values are read from `AUDIT_RANGE_OUTCOME`, never re-spelled here — the
+    // `REVIEW_SOURCE_FOR_AUDIT_SOURCE` rule, for the same reason: a token this
+    // tier spells for itself is a token that can drift from the one the blocking
+    // tier serializes. FAIL TOWARD THE CAUTIOUS CELL if the predicate throws: zero
+    // files is `range_unresolvable`, anything else `fallback_audited`. Neither
+    // fallback can claim `phase_scoped`, because a call we could not complete is
+    // not a witness that the range belongs to this phase.
+    let outcome;
+    try {
+        outcome = auditMod.classifyRangeOutcome({
+            phaseScoped: rangeSource !== REVIEW_RANGE_SOURCE.BASE_BRANCH,
+            filesConsidered: files.length,
+        });
+    }
+    catch {
+        outcome =
+            files.length === 0
+                ? auditMod.AUDIT_RANGE_OUTCOME.RANGE_UNRESOLVABLE
+                : auditMod.AUDIT_RANGE_OUTCOME.FALLBACK_AUDITED;
+    }
+    return { range, rangeSource, base, files, filesConsidered: files.length, outcome, notes };
+}
+/**
+ * The grounds, in order, on which THIS input records that the candidate
+ * derivation was not measured. Empty when everything it records was measured —
+ * including when it records nothing at all about measurement.
+ *
+ * Extracted rather than inlined into the predicate because two consumers need
+ * one answer: the predicate decides, and the payload's refusal statement NAMES
+ * what was missing. Recomputing the second from the first's prose, or asking the
+ * question twice, would be the 04-18 shape again.
+ */
+function unmeasuredGrounds(input) {
+    if (input === null || typeof input !== 'object')
+        return [];
+    const source = input;
+    const grounds = [];
+    if (source.inputSet !== null && typeof source.inputSet === 'object' && source.inputSet.oracleSource === 'unavailable') {
+        grounds.push(ORACLE_UNAVAILABLE_GROUND);
+    }
+    for (const arm of [source.naUniverse, source.naNoFile]) {
+        if (arm === null || arm === undefined || typeof arm !== 'object')
+            continue;
+        const record = arm.notDerived;
+        if (record === null || record === undefined || typeof record !== 'object')
+            continue;
+        const ground = record.ground;
+        if (typeof ground === 'string' && UNMEASURED_GROUND.has(ground) && !grounds.includes(ground)) {
+            grounds.push(ground);
+        }
+    }
+    return grounds;
+}
+/**
+ * The ONE predicate that forbids a clean review (F-3, D-06-15; widened by D3).
+ *
+ * True on either of two independent grounds:
+ *
+ *  1. THE REVIEW CONSIDERED NO FILES — whatever the range source, and regardless
+ *     of how many rows a caller has assembled. A review that looked at nothing
+ *     and rendered clean is the rubber stamp this phase exists to prevent, and
+ *     `secure-phase` already states the rule in its own words: empty-by-no-
+ *     planning must not rubber-stamp a clean artifact.
+ *  2. THE CANDIDATE DERIVATION WAS NOT MEASURED — the input POSITIVELY records
+ *     an unavailable NO_CHECK oracle, or an arm that did not derive on a ground
+ *     in `UNMEASURED_GROUND`. This is D3's second half: a phase with a hundred
+ *     changed files and an unreachable vault passed condition 1 easily and
+ *     rendered clean having judged nothing.
+ *
+ * The two silences are treated DIFFERENTLY, on purpose. A missing, non-numeric,
+ * non-integer or negative file count is not a witness that files were
+ * considered, so it refuses: the range's own contract is to state that number.
+ * An input that says nothing about measurement is a caller holding only a range
+ * — 06-04's CLI arm and the range tests do exactly that — and inventing a
+ * refusal from its silence would refuse every one of them. Condition 2 fires on
+ * a RECORD, never on an absence.
+ *
+ * Exported so the CLI arm (06-04) and the workflow (06-07) consult THIS
+ * predicate rather than a private restatement: two predicates for one claim are
+ * two claims, and this repository has already paid for that once (04-18).
+ */
+function reviewRefusesCleanRender(input) {
+    const value = typeof input === 'number'
+        ? input
+        : input !== null && typeof input === 'object'
+            ? input.filesConsidered
+            : undefined;
+    if (!(typeof value === 'number' && Number.isInteger(value) && value > 0))
+        return true;
+    return unmeasuredGrounds(input).length > 0;
+}
+// ─── The artifact validator (parse, then judge ONE unit) ─────────────────────
+/**
+ * ## Why this half exists, and why it is shaped like this
+ *
+ * Everything above computes what the agent must NOT invent. This half judges
+ * what the agent DID write. The design is not a new one: it is
+ * `src/practices-review-check.cts`'s, copied deliberately, because that module's
+ * header records a defect class that survived FOUR verification rounds while the
+ * detector lived as inline shell glue built on state shared across findings. Its
+ * answer — parse into nodes FIRST, then judge exactly ONE unit as a pure
+ * function of that unit alone, with the single-parameter signature standing as
+ * the isolation guarantee — is the one this module adopts verbatim.
+ *
+ * So `judgeReviewRow` takes one parameter and reads nothing else. A malformed
+ * row can change its OWN verdict and its own problems, and no sibling's, in
+ * either direction. Everything that is genuinely cross-row — the rate line's
+ * arithmetic, the counts line's arithmetic, the fence balance, the forbidden
+ * score-token scan — is computed by `validateReviewArtifact` from the judged
+ * rows, AFTER every row has been judged in isolation.
+ *
+ * ## Trust boundary
+ *
+ * The text handed here is UNTRUSTED on two counts at once: an LLM wrote the
+ * section, and the fenced excerpts inside it are client-authored vault prose.
+ * Nothing here performs I/O, nothing throws, and every value echoed into a
+ * problem detail passes `boundedToken` first.
+ */
+/**
+ * The problem vocabulary. Frozen and exported for the same reason the three
+ * vocabularies above are: a consumer must branch on a VALUE, and a test must
+ * harvest the token it asserts on rather than copy it.
+ *
+ * The four `FORBIDDEN_*` members are the D-06-13 score FORMS. They live in this
+ * one vocabulary rather than a second one because a token the scan finds becomes
+ * a problem in this list unchanged — one label, one home, no translation step
+ * where the two could drift.
+ */
+const REVIEW_PROBLEM_KIND = Object.freeze({
+    /** No `## Practice Verdicts (agent-judged)` heading anywhere in the supplied text. */
+    SECTION_ABSENT: 'section-absent',
+    /** The heading is present and the section holds no verdict row at all. */
+    NO_ROWS: 'no-rows',
+    ROW_MISSING_ID: 'row-missing-id',
+    ROW_UNKNOWN_VERDICT: 'row-unknown-verdict',
+    /** D-06-11: a non-verdict with no stated reason. */
+    ROW_MISSING_REASON: 'row-missing-reason',
+    /** D-06-09: a row marked derived that does not say WHICH derivation produced it. */
+    ROW_DERIVED_LABEL_MISSING: 'row-derived-label-missing',
+    /** D-06-09: a derived row reclassified into a judged verdict. */
+    ROW_DERIVED_VERDICT_CONFLICT: 'row-derived-verdict-conflict',
+    RATE_LINE_ABSENT: 'rate-line-absent',
+    /** D-06-12: the rate line's numbers are not the ones the rows support. */
+    RATE_LINE_ARITHMETIC: 'rate-line-arithmetic',
+    COUNTS_LINE_ABSENT: 'counts-line-absent',
+    /** D-06-13: the counts line's numbers are not the ones the rows support. */
+    COUNTS_LINE_ARITHMETIC: 'counts-line-arithmetic',
+    // ── MECH-02 / D-10-20: the mechanical coverage line ────────────────────────
+    // An instructed-only line is an unenforced one: an artifact that dropped it
+    // validated clean. These four kinds close it.
+    /** The payload carried a coverage line and the artifact does not. */
+    COVERAGE_LINE_ABSENT: 'coverage-line-absent',
+    /** A coverage line is present but is not the engine's sentence, verbatim. */
+    COVERAGE_LINE_MISMATCH: 'coverage-line-mismatch',
+    /**
+     * The line sits inside the verdicts section, which the agent contract
+     * explicitly forbids: "a second bare shaped line makes the section
+     * contradict itself". It belongs under `## Range`.
+     */
+    COVERAGE_LINE_MISPLACED: 'coverage-line-misplaced',
+    /**
+     * The payload carried NO coverage line and the artifact invented one. Its
+     * absence means the inputs were never measured, so any figure here states a
+     * measurement nobody took.
+     */
+    COVERAGE_LINE_UNEXPECTED: 'coverage-line-unexpected',
+    /** The external-content fence markers do not pair up. */
+    FENCE_UNBALANCED: 'fence-unbalanced',
+    /** The parse cap was reached; rows beyond it were NOT judged. */
+    ROWS_TRUNCATED: 'rows-truncated',
+    // ── The population, checked against the payload by `vault review finalize` ──
+    /** A practice of the review's population has no row: dropped rather than judged. */
+    ROW_POPULATION_MISSING: 'row-population-missing',
+    /** A row names a practice outside the population the payload derived. */
+    ROW_POPULATION_UNEXPECTED: 'row-population-unexpected',
+    /** One practice carries more than one row. */
+    ROW_DUPLICATE: 'row-duplicate',
+    // The four D-06-13 score forms.
+    FORBIDDEN_PERCENTAGE: 'forbidden-percentage',
+    FORBIDDEN_RATIO: 'forbidden-ratio',
+    FORBIDDEN_SCORE_ASSIGNMENT: 'forbidden-score-assignment',
+    FORBIDDEN_LETTER_GRADE: 'forbidden-letter-grade',
+});
+/** The heading D-06-02 locks, verbatim. Never re-derived from configuration. */
+const REVIEW_SECTION_HEADING = '## Practice Verdicts (agent-judged)';
+/** The D-06-12 rate line, as a shape. The renderer above is the only writer. */
+const RATE_LINE_SHAPE = /^(\d+) of (\d+) practices judged · (\d+) N-A · (\d+) INCONCLUSIVE$/;
+/**
+ * The D-10-03 mechanical coverage line, as a shape. The audit's
+ * `renderMechanicalCoverageLine` is the only writer; this recognises its output so a
+ * MISPLACED or UNEXPECTED line can be named even when no expectation was supplied.
+ */
+const COVERAGE_LINE_SHAPE = /^(\d+) of (\d+) practices mechanically checked · (\d+) PASS · (\d+) FAIL · (\d+) NOT_MATCHED · (\d+) NO_CHECK$/;
+/** The D-06-13 counts line, as a shape. */
+const COUNTS_LINE_SHAPE = /^(\d+) PASS · (\d+) FAIL · (\d+) INCONCLUSIVE · (\d+) N-A \(of (\d+) traced\)$/;
+/** A markdown table separator cell: `---`, `:---`, `---:` or `:---:`. */
+const TABLE_SEPARATOR_CELL = /^:?-{3,}:?$/;
+/** A `Source` cell that declares the row DERIVED rather than agent-judged. */
+const DERIVED_SOURCE_SHAPE = /^derived\b/i;
+/** The distinguishing label inside a derived `Source` cell: `derived (…)`. */
+const DERIVED_LABEL_SHAPE = /\(([^)]*)\)/;
+/**
+ * The four forbidden score FORMS, targeted by SHAPE rather than by word.
+ *
+ * That distinction is the whole design. A word-targeted scan would flag the
+ * disclaimer sentence a review is supposed to carry — the one that states no
+ * single score, ratio, percentage or letter grade was computed — and a rule that
+ * forbids saying what the rule forbids is a rule nobody can comply with. Each
+ * pattern below therefore requires the numeric or graded FORM itself, never the
+ * name of it.
+ *
+ * The two sanctioned lines need no exemption entry and deliberately do not get
+ * one: neither carries a percent sign, a slash-separated pair, a score
+ * assignment or a letter grade, so they pass on their own shape. An exemption
+ * list would additionally let a real violation hide inside a line that merely
+ * looked sanctioned.
+ */
+const FORBIDDEN_SCORE_SHAPES = Object.freeze([
+    { kind: REVIEW_PROBLEM_KIND.FORBIDDEN_PERCENTAGE, re: /\d\s*%|\b\d+(?:\.\d+)?\s*(?:percent|pct)\b/gi },
+    { kind: REVIEW_PROBLEM_KIND.FORBIDDEN_RATIO, re: /\b\d+\s*\/\s*\d+\b/g },
+    {
+        kind: REVIEW_PROBLEM_KIND.FORBIDDEN_SCORE_ASSIGNMENT,
+        re: /\b(?:score|rating|compliance|conformance|health)\b[^\S\n]*[:=][^\S\n]*\S/gi,
+    },
+    {
+        kind: REVIEW_PROBLEM_KIND.FORBIDDEN_LETTER_GRADE,
+        re: /\bgrades?\b[^\S\n]*[:=]?[^\S\n]*[A-F][+-]?(?![A-Za-z0-9])/gi,
+    },
+]);
+/** Compose one problem. Every echoed value is bounded before it lands here. */
+function reviewProblem(kind, id, line, detail) {
+    return { kind, id, line, detail };
+}
+/**
+ * The D-06-13 counts line, computed from the four verdict counts and nothing
+ * else — the same discipline `renderRateLine` states for its own line. Internal:
+ * the ONE writer of this shape is this module, and `validateReviewArtifact`
+ * returns the string it computed, so a consumer harvests it rather than
+ * re-spelling it.
+ */
+function renderCountsLine(counts) {
+    return (`${counts.pass} PASS · ${counts.fail} FAIL · ${counts.inconclusive} INCONCLUSIVE · ` +
+        `${counts.na} N-A (of ${counts.total} traced)`);
+}
+/** Split a markdown table line into trimmed cells, dropping the outer pipes. */
+function tableCells(line) {
+    const trimmed = line.trim();
+    const inner = trimmed.slice(1, trimmed.endsWith('|') ? -1 : undefined);
+    return inner.split('|').map((c) => c.trim());
+}
+function isTableLine(line) {
+    return line.trim().startsWith('|');
+}
+function isSeparatorLine(line) {
+    if (!isTableLine(line))
+        return false;
+    const cells = tableCells(line);
+    return cells.length > 0 && cells.every((c) => TABLE_SEPARATOR_CELL.test(c));
+}
+/**
+ * Locate the verdict section's own lines inside the supplied text.
+ *
+ * BOTH CONSUMERS, ONE PARSER. The `## Practice Verdicts (agent-judged)` section
+ * inside a VERIFICATION.md and a whole VAULT-REVIEW.md body reach this function
+ * the same way: the heading is found, and the section runs to the next
+ * top-level `##` heading or to the end of the text. A body that carries the
+ * heading nowhere reports `present: false` — which is a finding, never a silent
+ * empty result.
+ */
+function locateReviewSection(lines) {
+    // A line between a closed pair of fence markers is client prose, never
+    // structure: a heading-shaped client line can neither open the section nor
+    // end it (the same trust boundary `parseReviewRows` draws for rows).
+    const fenced = fencedLineMap(lines);
+    const start = lines.findIndex((l, i) => !fenced[i] && l.trim() === REVIEW_SECTION_HEADING);
+    if (start === -1)
+        return { present: false, start: 0, end: lines.length };
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (fenced[i])
+            continue;
+        if (line.startsWith('## ') || line.trim() === '---') {
+            end = i;
+            break;
+        }
+    }
+    return { present: true, start: start + 1, end };
+}
+/**
+ * WHICH LINES ARE CLIENT-AUTHORED. One computation, for every pass that needs
+ * the answer.
+ *
+ * The fence MARKERS are harvested from the shipped check module rather than
+ * re-spelled here, for the reason stated at the imports: a second spelling of a
+ * marker is a second definition of where untrusted content ends. A second
+ * COMPUTATION of which lines that marker encloses is the same failure with the
+ * same consequence, and it is what shipped — `scanForbiddenScoreTokens` had this
+ * pass inline and `parseReviewRows` had none, so a client-authored markdown
+ * table inside a closed fence was excluded from the score scan and counted as an
+ * agent verdict by the row parser at the same time (T-6-18). The two passes
+ * disagreeing about the trust boundary let the audited party set the audit's own
+ * number.
+ *
+ * Both semantics are the ones the score scan already had, and both are kept
+ * deliberately:
+ *
+ *   - Only a CLOSED pair fences anything. An opener with no closer marks
+ *     nothing, so the unterminated remainder is still scanned and still parsed.
+ *     Failing towards reading is the direction that cannot hide a violation, and
+ *     the unbalanced pair is separately reported as `FENCE_UNBALANCED`.
+ *   - The markers' own lines are inside the region. They are structure, never
+ *     content, and neither pass has anything to say about them.
+ *
+ * Total over any input; `lines` is never mutated.
+ */
+function fencedLineMap(lines) {
+    const fenced = new Array(lines.length).fill(false);
+    for (let i = 0; i < lines.length; i += 1) {
+        if (!lines[i].includes(FENCE_START_MARKER))
+            continue;
+        let close = -1;
+        for (let j = i + 1; j < lines.length; j += 1) {
+            if (lines[j].includes(FENCE_END_MARKER)) {
+                close = j;
+                break;
+            }
+        }
+        if (close === -1)
+            break;
+        for (let k = i; k <= close; k += 1)
+            fenced[k] = true;
+        i = close;
+    }
+    return fenced;
+}
+/**
+ * Parse the section's verdict rows into units. NOTHING is judged here, and no
+ * unit is ever dropped or truncated out of the returned array below the cap:
+ * a row this parser discarded would be a row whose defects nobody could report.
+ *
+ * FENCED LINES ARE NOT ROWS. The exclusion is `fencedLineMap`'s, shared with the
+ * score scan rather than restated, and it is the trust boundary this module's
+ * header draws: a pipe table between the external-content markers is prose from
+ * the client's vault that the agent was instructed to reproduce verbatim, and it
+ * is not a verdict the agent reached. Counting it is tampering in one direction
+ * — the judged population inflates and the arithmetic cross-check then validates
+ * the inflated figures — and denial of service in the other, since any table in
+ * any practice document turns a cell reading `Type` into a `row-unknown-verdict`
+ * charged to the agent.
+ *
+ * A fenced line is not a discarded row and is never counted against
+ * `MAX_PARSED_UNITS`: it was never a unit to begin with.
+ *
+ * The header row is recognised by a ONE-LINE LOOKAHEAD — a table line
+ * immediately followed by a separator line is the header. That lookahead lives
+ * in the parser and never in the judge, so the isolation invariant below is
+ * untouched by it. Recognising the header by its literal column text would
+ * instead make a row whose verdict cell happened to read `Verdict` silently
+ * vanish.
+ */
+function parseReviewRows(lines, start, end) {
+    const units = [];
+    let truncated = 0;
+    // The same window the score scan is handed (`lines.slice(section.start,
+    // section.end)`), so the two passes cannot be looking at different text.
+    const fenced = fencedLineMap(lines.slice(start, end));
+    for (let i = start; i < end; i += 1) {
+        const line = lines[i];
+        if (fenced[i - start])
+            continue;
+        if (!isTableLine(line))
+            continue;
+        if (isSeparatorLine(line))
+            continue;
+        if (i + 1 < end && isSeparatorLine(lines[i + 1]))
+            continue;
+        if (units.length >= MAX_PARSED_UNITS) {
+            truncated += 1;
+            continue;
+        }
+        units.push({ index: units.length, line: i + 1, raw: line, cells: tableCells(line) });
+    }
+    return { units, truncated };
+}
+/**
+ * Judge exactly ONE row, as a pure function of that row alone.
+ *
+ * ITS ARITY IS THE CONTRACT. One parameter means this function cannot consult a
+ * sibling, so a malformed row can only ever change its own verdict and its own
+ * problems. That is the invariant `src/practices-review-check.cts` pins as
+ * `judgeUnit.length === 1`, for a defect class that four verification rounds
+ * failed to close while any state was shared across units; the arity is pinned
+ * here by a test for the same reason.
+ *
+ * Four row-level rules, and no more — everything cross-row belongs to the caller:
+ *   - a practice id is present (an anonymous verdict is not attributable);
+ *   - the verdict is one of the four locked tokens (D-06-10);
+ *   - a non-verdict carries a stated, non-empty reason (D-06-11);
+ *   - a derived row says WHICH derivation produced it and does not carry a
+ *     judged verdict (D-06-09 — the two derived populations are different
+ *     findings, and a derived N-A reclassified into PASS/FAIL is the agent
+ *     overwriting a fact it was handed).
+ */
+function judgeReviewRow(unit) {
+    const u = (unit ?? {});
+    const cells = Array.isArray(u.cells) ? u.cells : [];
+    const cell = (n) => (typeof cells[n] === 'string' ? cells[n].trim() : '');
+    const line = typeof u.line === 'number' && Number.isFinite(u.line) ? u.line : null;
+    const idCell = cell(0).replace(/`/g, '').trim();
+    const verdict = cell(1);
+    const reason = cell(2);
+    const source = cell(3);
+    const id = idCell === '' ? '' : quotableId(idCell);
+    const problems = [];
+    if (idCell === '') {
+        problems.push(reviewProblem(REVIEW_PROBLEM_KIND.ROW_MISSING_ID, null, line, 'this row carries no practice id, so its verdict is attributable to nothing. A verdict ' +
+            'nobody can trace back to a practice is not a finding.'));
+    }
+    const recognised = isJudgedVerdict(verdict) || isNonVerdict(verdict);
+    if (!recognised) {
+        problems.push(reviewProblem(REVIEW_PROBLEM_KIND.ROW_UNKNOWN_VERDICT, id === '' ? null : id, line, `"${safe(verdict)}" is not one of the four locked verdicts. A coined fifth verdict ` +
+            'is counted as unrecognised and is never absorbed into a real one.'));
+    }
+    else if (isNonVerdict(verdict) && reason === '') {
+        problems.push(reviewProblem(REVIEW_PROBLEM_KIND.ROW_MISSING_REASON, id === '' ? null : id, line, 'A non-verdict must carry a stated reason. A bare N-A or INCONCLUSIVE is ' +
+            'indistinguishable from the agent giving up.'));
+    }
+    const derived = DERIVED_SOURCE_SHAPE.test(source);
+    let derivedLabel = null;
+    if (derived) {
+        const matched = DERIVED_LABEL_SHAPE.exec(source);
+        const label = matched && typeof matched[1] === 'string' ? matched[1].trim() : '';
+        derivedLabel = label === '' ? null : safe(label);
+        if (derivedLabel === null) {
+            problems.push(reviewProblem(REVIEW_PROBLEM_KIND.ROW_DERIVED_LABEL_MISSING, id === '' ? null : id, line, 'this row is marked derived but does not say WHICH derivation produced it. The two ' +
+                `derived populations ("${NA_DERIVED_REASON.UNIVERSE_MINUS_LEDGER}" and ` +
+                `"${NA_DERIVED_REASON.NO_FILE_IN_DIFF}") are different findings about different things, ` +
+                'and a reader who cannot tell them apart cannot act on either.'));
+        }
+        if (isJudgedVerdict(verdict)) {
+            problems.push(reviewProblem(REVIEW_PROBLEM_KIND.ROW_DERIVED_VERDICT_CONFLICT, id === '' ? null : id, line, `a derived row carries "${safe(verdict)}", a judged verdict. Derived rows are handed to ` +
+                'the agent to reproduce, not to reclassify: a derived N-A promoted to PASS or FAIL is a ' +
+                'computed fact overwritten by a judgement.'));
+        }
+    }
+    return { id, verdict, reason, source, derived, derivedLabel, problems };
+}
+/**
+ * Find every D-06-13 score form in the supplied text, by SHAPE.
+ *
+ * FENCED REGIONS ARE EXCLUDED, and that is a decision rather than an oversight.
+ * D-06-13 governs what the AGENT writes; text between the external-content fence
+ * markers is client-authored vault prose the agent was instructed to reproduce
+ * verbatim, and a client practice that mentions a ratio of its own is not the
+ * agent scoring a phase. A fence that never closes does NOT swallow the rest of
+ * the document: the unterminated remainder is scanned, because failing towards
+ * scanning is the direction that cannot hide a violation, and the unbalanced
+ * pair is separately reported by `validateReviewArtifact`.
+ *
+ * The exclusion itself is `fencedLineMap`'s and is shared with `parseReviewRows`
+ * rather than computed twice. It used to live inline here, and the row parser
+ * had no equivalent — two passes over one document disagreeing about where
+ * untrusted content ends, which is T-6-18.
+ *
+ * Total over any input. A non-string reports no findings, which is honest: there
+ * was no text to scan, and the caller's own absent-input problem says so.
+ */
+function scanForbiddenScoreTokens(text) {
+    if (typeof text !== 'string' || text === '')
+        return [];
+    const lines = text.split(/\r?\n/);
+    // Computed before any scanning so an unterminated opener cannot silence
+    // everything after it.
+    const fenced = fencedLineMap(lines);
+    const findings = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        if (fenced[i])
+            continue;
+        for (const shape of FORBIDDEN_SCORE_SHAPES) {
+            for (const m of lines[i].matchAll(shape.re)) {
+                findings.push({ kind: shape.kind, line: i + 1, match: safe(m[0]) });
+            }
+        }
+    }
+    return findings;
+}
+function validateReviewArtifact(text, opts) {
+    const problems = [];
+    const src = typeof text === 'string' ? text : '';
+    const lines = src.split(/\r?\n/);
+    const section = locateReviewSection(lines);
+    if (typeof text !== 'string') {
+        problems.push(reviewProblem(REVIEW_PROBLEM_KIND.SECTION_ABSENT, null, null, 'no artifact text was supplied, so nothing was validated. This is an absent input, which is ' +
+            'a different finding from an artifact that was read and held no defect.'));
+    }
+    else if (!section.present) {
+        problems.push(reviewProblem(REVIEW_PROBLEM_KIND.SECTION_ABSENT, null, null, `the artifact carries no "${REVIEW_SECTION_HEADING}" heading, so no verdict row was found ` +
+            'and nothing was judged. The heading is locked; a section under any other heading is ' +
+            'not this section.'));
+    }
+    const { units, truncated } = section.present
+        ? parseReviewRows(lines, section.start, section.end)
+        : { units: [], truncated: 0 };
+    if (truncated > 0) {
+        problems.push(reviewProblem(REVIEW_PROBLEM_KIND.ROWS_TRUNCATED, null, null, `${truncated} row(s) beyond the parse cap of ${MAX_PARSED_UNITS} were NOT judged. A cap ` +
+            'reached in silence would report a partial judgement as a whole one.'));
+    }
+    const rows = [];
+    for (const unit of units) {
+        const judged = judgeReviewRow(unit);
+        rows.push(judged);
+        for (const p of judged.problems)
+            problems.push(p);
+    }
+    if (section.present && units.length === 0) {
+        problems.push(reviewProblem(REVIEW_PROBLEM_KIND.NO_ROWS, null, null, 'the section heading is present and carries no verdict row. An empty section is not a clean ' +
+            'review: a gap is reported loudly, never as an empty register.'));
+    }
+    const counts = countReviewVerdicts(rows);
+    const expectedRateLine = renderRateLine(counts);
+    const expectedCountsLine = renderCountsLine(counts);
+    const body = section.present ? lines.slice(section.start, section.end) : [];
+    const foundRateLine = body.map((l) => l.trim()).find((l) => RATE_LINE_SHAPE.test(l)) ?? null;
+    const foundCountsLine = body.map((l) => l.trim()).find((l) => COUNTS_LINE_SHAPE.test(l)) ?? null;
+    if (section.present) {
+        if (foundRateLine === null) {
+            problems.push(reviewProblem(REVIEW_PROBLEM_KIND.RATE_LINE_ABSENT, null, null, `The section carries no non-verdict rate line. Expected the computed line ` +
+                `"${expectedRateLine}" — the denominator is the point, and a list of green rows without ` +
+                'it cannot tell a reader that a review is hollow.'));
+        }
+        else if (foundRateLine !== expectedRateLine) {
+            problems.push(reviewProblem(REVIEW_PROBLEM_KIND.RATE_LINE_ARITHMETIC, null, null, `The rate line reads "${safe(foundRateLine)}" while the rows support ` +
+                `"${expectedRateLine}". The arithmetic is computed from the rows and never narrated.`));
+        }
+        if (foundCountsLine === null) {
+            problems.push(reviewProblem(REVIEW_PROBLEM_KIND.COUNTS_LINE_ABSENT, null, null, `The section carries no counts line. Expected "${expectedCountsLine}".`));
+        }
+        else if (foundCountsLine !== expectedCountsLine) {
+            problems.push(reviewProblem(REVIEW_PROBLEM_KIND.COUNTS_LINE_ARITHMETIC, null, null, `The counts line reads "${safe(foundCountsLine)}" while the rows support ` +
+                `"${expectedCountsLine}".`));
+        }
+    }
+    // ── MECH-02 / D-10-20: the mechanical coverage line ────────────────────────
+    // Scanned over the WHOLE document, not `body`: the agent contract puts this
+    // line under `## Range` and forbids it inside the verdicts section, so a
+    // scan scoped to that section could never see it. That scoping is exactly
+    // why phase 10 shipped the line unenforced.
+    if (opts && Object.prototype.hasOwnProperty.call(opts, 'expectedCoverageLine')) {
+        const expected = opts.expectedCoverageLine;
+        const inSection = (i) => section.present && i >= section.start && i < section.end;
+        let foundIdx = -1;
+        const fencedLines = fencedLineMap(lines);
+        for (let i = 0; i < lines.length; i += 1) {
+            if (fencedLines[i])
+                continue;
+            if (COVERAGE_LINE_SHAPE.test(lines[i].trim())) {
+                foundIdx = i;
+                break;
+            }
+        }
+        const found = foundIdx >= 0 ? lines[foundIdx].trim() : null;
+        if (typeof expected === 'string' && expected.length > 0) {
+            if (found === null) {
+                problems.push(reviewProblem(REVIEW_PROBLEM_KIND.COVERAGE_LINE_ABSENT, null, null, `The payload carried the mechanical coverage line "${expected}" and the ` +
+                    'artifact reproduces it nowhere. That line is how a reader learns how much of the ' +
+                    'vault was mechanically checked; without it a page of judged rows cannot say ' +
+                    'whether the mechanical tier ran at all.'));
+            }
+            else if (found !== expected) {
+                problems.push(reviewProblem(REVIEW_PROBLEM_KIND.COVERAGE_LINE_MISMATCH, null, null, `The coverage line reads "${safe(found)}" where the engine computed ` +
+                    `"${expected}". It is the engine's sentence, reproduced verbatim and never restated.`));
+            }
+            else if (inSection(foundIdx)) {
+                problems.push(reviewProblem(REVIEW_PROBLEM_KIND.COVERAGE_LINE_MISPLACED, null, null, 'The coverage line sits inside the verdicts section, where a second bare ' +
+                    'shaped line makes the section contradict itself — its figures count a different ' +
+                    'population from the rate line above them. It belongs under "## Range".'));
+            }
+        }
+        else if (expected === null && found !== null) {
+            problems.push(reviewProblem(REVIEW_PROBLEM_KIND.COVERAGE_LINE_UNEXPECTED, null, null, `The artifact carries "${safe(found)}" while the payload carried no coverage ` +
+                'line at all. Its absence means the inputs were never measured, so this figure ' +
+                'states a measurement nobody took.'));
+        }
+    }
+    let fenceStarts = 0;
+    let fenceEnds = 0;
+    let depth = 0;
+    let endBeforeStart = false;
+    for (const line of body) {
+        if (line.includes(FENCE_START_MARKER)) {
+            fenceStarts += 1;
+            depth += 1;
+        }
+        if (line.includes(FENCE_END_MARKER)) {
+            fenceEnds += 1;
+            if (depth === 0)
+                endBeforeStart = true;
+            else
+                depth -= 1;
+        }
+    }
+    if (section.present && (fenceStarts !== fenceEnds || endBeforeStart)) {
+        problems.push(reviewProblem(REVIEW_PROBLEM_KIND.FENCE_UNBALANCED, null, null, `the external-content fence markers do not pair up: ${fenceStarts} opener(s) and ` +
+            `${fenceEnds} closer(s)` +
+            (endBeforeStart ? ', with a closer appearing before any opener' : '') +
+            '. An unbalanced pair means client-authored prose is sitting outside the boundary that ' +
+            'marks it as reference data, which is the escape the fencing exists to prevent.'));
+    }
+    for (const finding of scanForbiddenScoreTokens(body.join('\n'))) {
+        problems.push(reviewProblem(finding.kind, null, section.present ? section.start + finding.line : finding.line, `No single-number roll-up may appear anywhere in this section; "${finding.match}" is one. ` +
+            'Counts by verdict stay sortable and trackable across phases without inviting a ' +
+            'measured-sounding claim about a judgement.'));
+    }
+    return {
+        sectionPresent: section.present,
+        units,
+        rows,
+        counts,
+        foundRateLine,
+        expectedRateLine,
+        foundCountsLine,
+        expectedCountsLine,
+        fenceStarts,
+        fenceEnds,
+        problems,
+    };
+}
+/** The only `predicate.vault.state` value that means the vault was reached. */
+const TRACE_STATE_LOADED = 'loaded';
+/**
+ * Normalise the caller's per-block list.
+ *
+ * FAIL-CLOSED at the edge: an entry that is not an object still becomes a
+ * record — one whose `state` is null and therefore is not `loaded`. Dropping it
+ * instead would let a junk entry beside a loaded one read as a loaded phase,
+ * which is the multi-block fail-open T-6-47 names.
+ */
+function asTraceBlocks(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const entry of v) {
+        const b = (entry !== null && typeof entry === 'object' ? entry : {});
+        const source = typeof b.source === 'string' && b.source !== '' ? b.source : null;
+        out.push({
+            source,
+            state: typeof b.state === 'string' && b.state !== '' ? b.state : null,
+            reason: typeof b.reason === 'string' && b.reason !== '' ? b.reason : null,
+            override: asOverrideRecord(b.override, source),
+        });
+    }
+    return out;
+}
+/**
+ * Normalise ONE block's override record, or answer null (08-05, D-08-11).
+ *
+ * Null unless the value is a plain object: an array, a string or a number is
+ * not a record, and treating one as though it were would put a fabricated
+ * bypass in front of a reader. A record whose fields are ALL missing still
+ * survives as an entry — the artifact recorded an override, and "recorded, and
+ * said nothing about it" is a different finding from "no override", which is
+ * exactly the distinction D-06-14 exists to keep visible.
+ *
+ * EVERY field passes `safe()` here rather than at the point of use, including
+ * `source`, because all six reach both `statements[]` and an agent prompt. That
+ * is the discipline `describeDegradedTrace` already applies to the same
+ * artifact's other fields (T-6-44 / T-6-46, and T-08-26 for this one): a trace
+ * artifact is agent- or hand-editable DATA.
+ */
+function asOverrideRecord(v, source) {
+    if (v === null || typeof v !== 'object' || Array.isArray(v))
+        return null;
+    const o = v;
+    const field = (x) => (typeof x === 'string' && x !== '' ? safe(x) : null);
+    return {
+        source: source === null ? null : safe(source),
+        gate: field(o.gate),
+        reason: field(o.reason),
+        suppressedReason: field(o.suppressedReason),
+        who: field(o.who),
+        when: field(o.when),
+    };
+}
+/**
+ * Name the FIRST block that is not `loaded`, and say what it recorded.
+ *
+ * The value is a labelled fact for the reviewer, never a routing signal: the
+ * routing is `traceLoaded`, computed from the same blocks. Every fragment that
+ * originates in a trace artifact — the source path and the recorded reason
+ * alike — passes through `safe()` before it reaches the returned string, exactly
+ * as `sources` and `pinSha` already do (T-6-44, T-6-46). A trace artifact is
+ * agent- or hand-editable data, and this string crosses into an agent prompt.
+ */
+function describeDegradedTrace(blocks) {
+    const offending = blocks.find((b) => b.state !== TRACE_STATE_LOADED);
+    if (offending === undefined) {
+        return ('no per-block provenance was carried with this trace, so nothing here establishes that the vault ' +
+            'was reached when this phase was planned');
+    }
+    const source = offending.source === null ? 'an unnamed trace artifact' : safe(offending.source);
+    const state = offending.state;
+    const reason = offending.reason === null ? null : safe(offending.reason);
+    if (state === null) {
+        return `${source}: records no \`predicate.vault.state\` at all, so it cannot record that the vault loaded`;
+    }
+    if (state === 'degraded') {
+        return `${source}: ${reason ?? 'no reason recorded'}`;
+    }
+    return (`${source}: records state "${safe(state)}", which is not a state this tier recognises` +
+        (reason === null ? '' : `; its recorded reason is ${reason}`));
+}
+function buildReviewPayload(opts) {
+    const statements = [];
+    const notes = [];
+    const trace = opts?.trace ?? null;
+    const tracePresent = trace?.present === true;
+    // ── The provenance, decided ONCE and here (06-12, G1). `present` answers "did
+    // a block parse"; `traceLoaded` answers the different question the workflow's
+    // §2 actually routes on: "was the vault reached when this phase was planned".
+    // FAIL-CLOSED, deliberately (T-6-43, T-6-47): loaded requires strict equality
+    // with `loaded` on EVERY parsed block, so one degraded block among loaded ones
+    // is not a loaded phase, an unrecognised value is not a loaded one, and a
+    // `present` trace carrying no per-block provenance at all is not one either —
+    // an absence of a record is not a record of success.
+    const traceBlocks = asTraceBlocks(trace?.blocks);
+    const traceLoaded = tracePresent && traceBlocks.length > 0 && traceBlocks.every((b) => b.state === TRACE_STATE_LOADED);
+    const traceState = !tracePresent
+        ? null
+        : traceLoaded
+            ? TRACE_STATE_LOADED
+            : 'degraded';
+    const traceReason = traceState === 'degraded' ? describeDegradedTrace(traceBlocks) : null;
+    const ledgerIds = asStringList(trace?.ledgerIds);
+    const phaseDir = typeof opts?.phaseDir === 'string' && opts.phaseDir !== '' ? safe(opts.phaseDir) : null;
+    // ── The range, first: every derivation below is scoped by it.
+    const range = resolveReviewRange({
+        cwd: opts.cwd,
+        phaseToken: opts?.phaseToken ?? null,
+        // UAT-6-F1: the check router already supplies `phaseDir: phase.rel`, so
+        // forwarding it is all the shared phase-scoped resolution needs.
+        phaseDir: typeof opts?.phaseDir === 'string' && opts.phaseDir !== '' ? opts.phaseDir : null,
+        ...(typeof opts?.exec === 'function' ? { exec: opts.exec } : {}),
+    });
+    statements.push(`This review is computed over the git range "${range.range}" (rangeSource: ${range.rangeSource}, ` +
+        `base: ${safe(range.base)}), which considered ${range.filesConsidered} changed file(s). Every ` +
+        'applicability judgement below is scoped to exactly that set.');
+    for (const note of range.notes)
+        statements.push(`Range note: ${note}`);
+    // ── The vault verdict owner's answer, stated when it is not `loaded`: the
+    // practices below were read from the cache as it stands, and a reader must
+    // know whether the load gate considers that cache the client's loaded vault.
+    const ownerVerdict = opts?.vaultVerdict ?? null;
+    const vault = ownerVerdict !== null && typeof ownerVerdict === 'object' && typeof ownerVerdict.verdict === 'string'
+        ? { verdict: safe(ownerVerdict.verdict), reason: typeof ownerVerdict.reason === 'string' ? safe(ownerVerdict.reason) : '' }
+        : null;
+    if (vault !== null && vault.verdict !== 'loaded') {
+        statements.push(`The vault verdict owner reports this project's vault as ${vault.verdict}` +
+            (vault.reason === '' ? '' : ` (${vault.reason})`) +
+            ': the practices reviewed below were read from the local cache as it stands, which the vault load ' +
+            "gate does not treat as the client's loaded vault.");
+    }
+    // ── D-06-15: an absent trace does not refuse; it says so and RECONSTRUCTS.
+    if (!tracePresent) {
+        statements.push('No practice trace was found for this phase' +
+            (phaseDir === null ? '' : ` in ${phaseDir}`) +
+            '. This review therefore took the RECONSTRUCT arm: the applicable practice set is rebuilt ' +
+            "from this phase's real diff and the vault's own practice list rather than from a ledger. " +
+            'Any completed phase is eligible for review and a missing trace is itself a finding, ' +
+            'so it is recorded here rather than used as a reason to refuse.');
+    }
+    // ── G1: a trace that PARSES but records a failed vault load. This is not the
+    // absent case and must never be reported as one — a found-and-failed trace is
+    // a finding, and calling it an absence loses it entirely.
+    if (tracePresent && !traceLoaded) {
+        statements.push(
+        // The source list is NOT repeated here: `traceReason` already opens with
+        // the artifact path of the block that failed, which is the one a reader
+        // needs. Naming the whole list beside it printed the same path three times
+        // in one sentence.
+        'A practice trace WAS found for this phase' +
+            (phaseDir === null ? '' : ` in ${phaseDir}`) +
+            `, and it records a FAILURE — ${traceReason ?? 'no reason recorded'}. A degraded block is a valid ` +
+            'record of a failure — it says the vault could not be loaded when the work was planned — so it ' +
+            'proves nothing about which practices governed that work and may not stand in for a loaded trace. ' +
+            'This review therefore took the RECONSTRUCT arm: the applicable practice set is rebuilt ' +
+            "from this phase's real diff and the vault's own practice list, and this trace's own ledger and " +
+            'practice universe are deliberately not consulted.');
+    }
+    // ── D-08-09 / D-08-11: every RECORDED gate override, stated. `check
+    // vault.trace` reports the same records under `checked_with_override`, so a
+    // review that stayed silent about one would be the second surface disagreeing
+    // with the first about whether a phase was overridden — and the silent one is
+    // the one a human reads. Collected from EVERY parsed block, not keyed on
+    // `traceLoaded`: an override is recordable whenever a gate blocked, which is
+    // independent of whether the vault itself loaded, and a degraded block's
+    // override is exactly the one a reader must not lose.
+    const overrides = traceBlocks
+        .map((b) => b.override)
+        .filter((o) => o !== null);
+    for (const o of overrides) {
+        const said = (v) => v ?? '(not recorded)';
+        statements.push(`A vault-gate OVERRIDE is recorded in ${said(o.source)}: gate ${said(o.gate)} was overridden by ` +
+            `${said(o.who)} at ${said(o.when)} with the stated reason "${said(o.reason)}", suppressing the ` +
+            `verdict ${said(o.suppressedReason)}. The work this phase records was therefore planned or ` +
+            'executed under a deliberate, attributed bypass of that gate; this review reports the fact ' +
+            'and does not judge it.');
+    }
+    // ── The input set: this arm's universe ∩ NO_CHECK, harvested through the
+    // shipped ladder. On the reconstruct arm the universe is the vault's own
+    // practice list (D3): the ledger is empty there by definition, and deriving
+    // from it is what let an untraced phase render a clean review having judged
+    // nothing. Crossing that universe with this range's real diff is Arm B's job
+    // below, through the shipped matcher — not a second one written here.
+    //
+    // KEYED ON `traceLoaded`, NOT ON `tracePresent` (06-12, G1). A degraded block
+    // carries a ledger and a practice universe of its own, and both are worthless:
+    // docs/vault-trace-format.md §"What a degraded record proves" says an empty
+    // ledger and a complete one are indistinguishable through it. Feeding them to
+    // the derivation while the statement above announces a reconstruction from the
+    // vault's practice list would make that statement false — which is the whole
+    // reason this is more than a label change.
+    const inputSet = deriveCandidateSet({
+        ledgerIds: traceLoaded ? ledgerIds : [],
+        reconstruct: !traceLoaded,
+        practices: [...(opts?.practices ?? [])],
+        skipped: opts?.skipped ?? [],
+        degraded: opts?.degraded ?? [],
+        tracePinSha: trace?.pinSha ?? null,
+        cacheSha: opts?.cacheSha ?? null,
+        ...(opts?._audit ? { _audit: opts._audit } : {}),
+    });
+    for (const note of inputSet.notes)
+        statements.push(`Input set: ${note}`);
+    // ── Both derived-N-A arms, kept as two labels that never blur.
+    // Arm A consumes the BLOCK's own recorded universe, so it is keyed on
+    // `traceLoaded` for the same reason the derivation above is: a degraded
+    // block's universe is not a universe anyone may report against.
+    const naUniverse = deriveNaAUniverse({
+        universe: traceLoaded ? (trace?.universe ?? null) : null,
+        ledgerIds: traceLoaded ? ledgerIds : [],
+        // Only true when a universe EXISTED and this call suppressed it. An absent
+        // trace, and a degraded one that recorded no universe, both stay on the
+        // absent ground — whose sentence is true of them (06-12 Task 5 follow-up).
+        universeWithheld: !traceLoaded && (trace?.universe ?? null) !== null,
+    });
+    const naNoFile = deriveNaANoFile({
+        candidates: inputSet.candidates,
+        practices: opts?.practices ?? [],
+        diffFiles: range.files,
+        discovery: opts?.discovery ?? null,
+        ...(opts?._practices ? { _practices: opts._practices } : {}),
+    });
+    for (const arm of [naUniverse, naNoFile]) {
+        if (arm.notDerived)
+            statements.push(arm.notDerived.statement);
+        for (const note of arm.notes)
+            notes.push(note);
+    }
+    // ── The clean-render refusal, drawn LAST because it is the conclusion of
+    // everything above: the range's file count AND whether the candidate
+    // derivation was measured at all (D3). The predicate is the shipped one and
+    // the grounds it names are the ones the derivation recorded — this function
+    // restates neither.
+    const refusalInput = { filesConsidered: range.filesConsidered, inputSet, naUniverse, naNoFile };
+    const refusesCleanRender = reviewRefusesCleanRender(refusalInput);
+    if (reviewRefusesCleanRender(range)) {
+        statements.push('This review considered ZERO files, so no clean review may be rendered from it. A review that ' +
+            'looked at nothing and reported cleanly is the rubber stamp this tier exists to prevent; the ' +
+            'refusal is the shipped predicate\'s, not a restatement of it.');
+    }
+    // ── D-08-17, the review half: the refusal above says a review looked at
+    // nothing. THIS one says WHY, by the code the blocking tier already reports,
+    // and hands back both remedies. The two sentences stay side by side because
+    // they are different facts — "no clean render may follow" and "the range
+    // resolved nothing about this phase" — and an operator who is told only the
+    // first has been told their review is worthless and nothing else.
+    if (range.outcome === auditMod.AUDIT_RANGE_OUTCOME.RANGE_UNRESOLVABLE) {
+        const sharedGround = range.notes.find((n) => n.startsWith(SHARED_RESOLUTION_NOTE_PREFIX));
+        statements.push(`Range outcome ${range.outcome}: the range fell to the base-branch span (${range.range}) and ` +
+            'considered zero files, so nothing was established about this phase — ' +
+            `${sharedGround ?? 'no phase manifest entry and no SUMMARY trace digest resolved.'} ` +
+            REVIEW_RANGE_UNRESOLVABLE_REMEDY);
+    }
+    const unmeasured = unmeasuredGrounds(refusalInput);
+    if (unmeasured.length > 0) {
+        statements.push(`This review could not MEASURE the inputs its candidate set is derived from (${unmeasured.join(', ')}), ` +
+            'so no clean review may be rendered from it. An empty candidate set nobody measured is a different ' +
+            'finding from one that was measured and held nothing, and rendering the first as though it were the ' +
+            'second is exactly the silence this tier exists to end.');
+    }
+    const partition = partitionForJudgement({
+        candidates: inputSet.candidates,
+        naUniverse,
+        naNoFile,
+    });
+    const derivedCounts = countReviewVerdicts([...naUniverse.rows, ...naNoFile.rows]);
+    const derivedRateLine = renderRateLine(derivedCounts);
+    // ── MECH-02 / D-10-03: the MECHANICAL tier's coverage over THIS review's own
+    // file set, joining the two derived facts above. Gated on the SHIPPED
+    // `unmeasuredGrounds` answer already computed above rather than on a second
+    // reading of the same inputs: where that predicate names a ground, nothing
+    // was measured, and a `0 of 0` line would state a measurement nobody took.
+    const mechanicalCoverageLine = unmeasured.length > 0
+        ? null
+        : deriveMechanicalCoverageLine({
+            practices: opts?.practices ?? [],
+            files: range.files,
+            cwd: opts?.cwd,
+            ...(opts?._audit ? { _audit: opts._audit } : {}),
+        });
+    // ── The remainder's prose, rendered through the SHIPPED per-practice renderer.
+    // Not a renderer of this module's own: a second one is a second place a
+    // client-authored byte can reach an agent context unfenced (CR-02).
+    const practiceEntries = [];
+    const renderEntry = typeof opts?.renderEntry === 'function' ? opts.renderEntry : null;
+    const byId = new Map();
+    const entries = typeof opts?.matchEntries === 'function' ? opts.matchEntries(range.files) : (opts?.entries ?? []);
+    for (const entry of entries) {
+        if (entry && typeof entry.id === 'string')
+            byId.set(entry.id, entry);
+    }
+    for (const id of partition.remainder) {
+        const entry = byId.get(id);
+        if (entry === undefined) {
+            notes.push(`"${quotableId(id)}" reaches the agent as a remainder id with no matcher entry, so no fenced ` +
+                'prose is supplied for it. The id is reported rather than dropped.');
+            continue;
+        }
+        if (renderEntry === null) {
+            notes.push('no practice renderer was supplied, so no fenced practice prose is emitted at all. Vault prose ' +
+                'is never emitted unfenced, so the honest answer is to emit none.');
+            break;
+        }
+        practiceEntries.push(renderEntry(entry));
+    }
+    return {
+        status: 'reviewed',
+        // ONE routing decision, read from ONE field. `arm` is derived from
+        // `traceLoaded` and so is `trace.loaded`, which is why the workflow reads
+        // the latter and never re-derives it from the former (06-12, T-6-48).
+        arm: traceLoaded ? 'traced' : 'reconstruct',
+        phaseDir,
+        vault,
+        statements,
+        trace: {
+            present: tracePresent,
+            sources: asStringList(trace?.sources).map((s) => safe(s)),
+            pinSha: typeof trace?.pinSha === 'string' ? safe(trace.pinSha) : null,
+            state: traceState,
+            reason: traceReason,
+            loaded: traceLoaded,
+            overrides,
+        },
+        range,
+        refusesCleanRender,
+        inputSet,
+        naUniverse,
+        naNoFile,
+        partition,
+        derivedCounts,
+        derivedRateLine,
+        // OMITTED, not zeroed, on the unmeasured path — see the field's comment.
+        ...(mechanicalCoverageLine === null ? {} : { mechanicalCoverageLine }),
+        practiceEntries,
+        notes,
+    };
+}
+// ─── The artifact the agent fills in, and the lines only code writes ─────────
+/**
+ * The verdict cell of a remainder row until the agent judges it. Deliberately
+ * outside the locked vocabulary: a row left unjudged is reported by the
+ * validator as `row-unknown-verdict`, never counted as any verdict.
+ */
+const REVIEW_UNJUDGED_VERDICT = 'TODO';
+/** The `## Range` heading the coverage line is stamped under. */
+const RANGE_SECTION_HEADING = '## Range';
+/** A table cell: one line, no column separator, never empty. */
+function tableCell(v, empty = 'none.') {
+    const s = (typeof v === 'string' ? v : '').replace(/[\r\n]+/g, ' ').replace(/\|/g, '¦').trim();
+    return s === '' ? empty : s;
+}
+/**
+ * The gaps the payload recorded, one row each, in a fixed order. Every row is
+ * written on every run; a row with nothing to report says `none.`, so "nothing
+ * to report" and "not looked at" never look alike.
+ */
+function reviewGapRows(p) {
+    const notDerived = (arm) => (arm.notDerived ? arm.notDerived.statement : '');
+    const vaultGround = p.naNoFile.notDerived?.ground ?? '';
+    const vaultGap = [
+        NOT_DERIVED_GROUND.VAULT_STATE_UNKNOWN,
+        NOT_DERIVED_GROUND.VAULT_NEVER_FETCHED,
+        NOT_DERIVED_GROUND.VAULT_FETCH_MISS,
+        NOT_DERIVED_GROUND.VAULT_UNREADABLE,
+    ].some((g) => g === vaultGround)
+        ? notDerived(p.naNoFile)
+        : '';
+    const traceGap = !p.trace.present
+        ? 'absent — no practice trace was found, so this review took the reconstruct arm'
+        : p.trace.loaded
+            ? ''
+            : `degraded — ${p.trace.reason ?? 'no reason recorded'}`;
+    const said = (v) => v ?? '(not recorded)';
+    const overrides = p.trace.overrides
+        .map((o) => `${said(o.gate)} overridden by ${said(o.who)} at ${said(o.when)} in ${said(o.source)}: "${said(o.reason)}" (suppressed ${said(o.suppressedReason)})`)
+        .join('; ');
+    const rangeGap = p.range.outcome === auditMod.AUDIT_RANGE_OUTCOME.RANGE_UNRESOLVABLE
+        ? `${p.range.outcome}: ${REVIEW_RANGE_UNRESOLVABLE_REMEDY}`
+        : '';
+    const skipped = p.inputSet.exclusions
+        .filter((e) => e.reason === AUDIT_FAIL_REASON.PRACTICE_UNLOADABLE)
+        .map((e) => quotableId(e.id))
+        .join(', ');
+    const unmeasured = unmeasuredGrounds({
+        filesConsidered: p.range.filesConsidered,
+        inputSet: p.inputSet,
+        naUniverse: p.naUniverse,
+        naNoFile: p.naNoFile,
+    });
+    const refused = p.refusesCleanRender
+        ? `no clean review may be rendered: ${p.range.filesConsidered === 0 ? 'zero files were considered' : `inputs not measured (${unmeasured.join(', ')})`}`
+        : '';
+    return [
+        ['Vault absent, never fetched, missed or unreadable', vaultGap],
+        ['Practice universe not recorded at the pin', notDerived(p.naUniverse)],
+        ['Trace absent or degraded', traceGap],
+        ['Gate override recorded (who, when, reason)', overrides],
+        ['Range refused or unresolvable', rangeGap],
+        ['Empty diff — no file considered', p.range.filesConsidered === 0 ? 'zero files were considered' : ''],
+        ['Practices skipped or rejected before matching', skipped],
+        ['Clean review refused', refused],
+    ];
+}
+/**
+ * Render the `NN-VAULT-REVIEW.md` the agent fills in, from the payload alone.
+ *
+ * Everything computed is written here, by code: provenance, the range, every
+ * derived row with its reason and arm label, every gap row, the payload's
+ * statements, the fixed limits, and — through `stampReviewLines` — the rate,
+ * counts and coverage lines. Each remainder practice gets one row whose verdict
+ * reads `TODO` and whose reason is empty: those two cells are the agent's whole
+ * writable surface. The remainder's practice text follows, last, inside the
+ * fences the shipped renderer already put around it.
+ *
+ * Pure: payload and date in, text out.
+ */
+function renderReviewScaffold(payload, meta = {}) {
+    const p = payload;
+    const token = typeof meta.phaseToken === 'string' && meta.phaseToken !== '' ? safe(meta.phaseToken) : '?';
+    const date = typeof meta.date === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(meta.date) ? meta.date : '';
+    const traceCell = !p.trace.present
+        ? 'absent'
+        : p.trace.loaded
+            ? 'present and loaded'
+            : `degraded — ${p.trace.reason ?? 'no reason recorded'}`;
+    const advisories = p.inputSet.advisories.map((a) => a.detail).join(' ');
+    const rows = [];
+    for (const id of p.partition.remainder) {
+        rows.push(`| \`${tableCell(quotableId(id))}\` | ${REVIEW_UNJUDGED_VERDICT} |  | agent-judged |`);
+    }
+    for (const r of [...p.partition.naUniverse, ...p.partition.naNoFile]) {
+        rows.push(`| \`${tableCell(quotableId(r.id))}\` | ${r.verdict} | ${tableCell(r.reason)} | derived (${tableCell(r.naDerivedReason ?? '')}) |`);
+    }
+    const lines = [
+        '---',
+        `phase: "${token}"`,
+        'artifact: vault-review',
+        `reviewed: ${date === '' ? 'unknown' : date}`,
+        `arm: ${p.arm}`,
+        '---',
+        '',
+        `# Phase ${token} — Vault Practice Review`,
+        '',
+        '> This review reports and never gates: no verdict here changes a phase status, a score, a gap or a',
+        '> ship. Verdicts are agent-judged, not measured, and two runs may differ. Counts by verdict only.',
+        '',
+        '## Provenance',
+        '',
+        '| Field | Value |',
+        '| --- | --- |',
+        `| Phase directory | ${tableCell(p.phaseDir ?? '')} |`,
+        `| Arm | ${p.arm} |`,
+        `| Trace | ${tableCell(traceCell)} |`,
+        `| Trace sources | ${tableCell(p.trace.sources.join(', '))} |`,
+        `| Vault verdict | ${tableCell(p.vault ? `${p.vault.verdict}${p.vault.reason ? ` (${p.vault.reason})` : ''}` : '', 'not supplied')} |`,
+        `| Pin advisory | ${tableCell(advisories)} |`,
+        '',
+        RANGE_SECTION_HEADING,
+        '',
+        '| Field | Value |',
+        '| --- | --- |',
+        `| \`range\` | \`${tableCell(p.range.range)}\` |`,
+        `| \`rangeSource\` | \`${tableCell(p.range.rangeSource)}\` |`,
+        `| \`filesConsidered\` | ${p.range.filesConsidered} |`,
+        `| \`outcome\` | \`${tableCell(p.range.outcome)}\` |`,
+        '',
+        REVIEW_SECTION_HEADING,
+        '',
+        '| Practice | Verdict | Reason / evidence | Source |',
+        '| --- | --- | --- | --- |',
+        ...rows,
+        '',
+        '## Not Derived — the gaps',
+        '',
+        '| Gap | Statement |',
+        '| --- | --- |',
+        ...reviewGapRows(p).map(([gap, statement]) => `| ${gap} | ${tableCell(statement)} |`),
+        '',
+        '## Derivation Statements',
+        '',
+        ...(p.statements.length + p.notes.length === 0
+            ? ['none.']
+            : [...p.statements.map((st) => `- ${st}`), ...p.notes.map((n) => `- Note: ${n}`)]),
+        '',
+        '## Limits of This Review',
+        '',
+        '- Nothing in this artifact gates anything. A `FAIL` is a report to a human, not a halt.',
+        '- A verdict is one agent run\'s judgement; reproducibility is not claimed.',
+        '- The non-verdict rate is reported, not judged: there is no threshold at which a review is declared',
+        '  low-confidence.',
+        '- A practice absent from the register was not in the input set; the gaps table says why. Absence',
+        '  is not a statement that it was followed.',
+        '',
+        '## Practice Text (client reference data)',
+        '',
+        ...(p.practiceEntries.length === 0 ? ['none.'] : p.practiceEntries.flatMap((e) => [e, ''])),
+        '',
+    ];
+    return stampReviewLines(lines.join('\n'), { coverageLine: p.mechanicalCoverageLine ?? null }).text;
+}
+/** Index of the first unfenced line equal to `heading`, or -1. */
+function unfencedHeadingIndex(lines, heading) {
+    const fenced = fencedLineMap(lines);
+    return lines.findIndex((l, i) => !fenced[i] && l.trim() === heading);
+}
+/**
+ * Write the three computed lines into an artifact — the ONLY writer of them.
+ *
+ * Every unfenced rate- or counts-shaped line inside the verdicts section, and
+ * every unfenced coverage-shaped line anywhere, is removed; then the rate and
+ * counts lines the validator computes from the section's own rows are written
+ * directly under the section heading, and the payload's coverage line (when it
+ * carries one) at the end of `## Range` — or above the verdicts section when
+ * there is no `## Range`. A narrated figure therefore cannot survive, and the
+ * two count populations (the payload's derived rows and the register's rows)
+ * cannot be confused by anyone: the register's lines are always the register's.
+ *
+ * Fenced client prose is never touched. Without the verdicts heading nothing is
+ * stamped and the validator reports the absent section.
+ */
+function stampReviewLines(text, opts = {}) {
+    if (typeof text !== 'string')
+        return { text: '', stamped: false };
+    const src = text.split(/\r?\n/);
+    const section = locateReviewSection(src);
+    if (!section.present)
+        return { text, stamped: false };
+    const fenced = fencedLineMap(src);
+    const kept = [];
+    for (let i = 0; i < src.length; i += 1) {
+        const t = src[i].trim();
+        if (!fenced[i]) {
+            if (COVERAGE_LINE_SHAPE.test(t))
+                continue;
+            if (i >= section.start && i < section.end && (RATE_LINE_SHAPE.test(t) || COUNTS_LINE_SHAPE.test(t)))
+                continue;
+        }
+        kept.push(src[i]);
+    }
+    const probe = validateReviewArtifact(kept.join('\n'));
+    const head = unfencedHeadingIndex(kept, REVIEW_SECTION_HEADING);
+    let after = head + 1;
+    while (after < kept.length && kept[after].trim() === '')
+        after += 1;
+    kept.splice(head + 1, after - (head + 1), '', probe.expectedRateLine, probe.expectedCountsLine, '');
+    const coverage = typeof opts.coverageLine === 'string' ? opts.coverageLine.trim() : '';
+    if (coverage !== '' && COVERAGE_LINE_SHAPE.test(coverage)) {
+        const fencedNow = fencedLineMap(kept);
+        const range = unfencedHeadingIndex(kept, RANGE_SECTION_HEADING);
+        let at = unfencedHeadingIndex(kept, REVIEW_SECTION_HEADING);
+        if (range !== -1) {
+            at = kept.length;
+            for (let i = range + 1; i < kept.length; i += 1) {
+                if (!fencedNow[i] && (kept[i].startsWith('## ') || kept[i].trim() === '---')) {
+                    at = i;
+                    break;
+                }
+            }
+            while (at > range + 1 && kept[at - 1].trim() === '')
+                at -= 1;
+            kept.splice(at, 0, '', coverage);
+        }
+        else {
+            kept.splice(at, 0, coverage, '');
+        }
+    }
+    // Removing a line leaves its blank neighbours behind; collapse every unfenced
+    // run of blank lines to one, so stamping is idempotent.
+    const fencedOut = fencedLineMap(kept);
+    const out = kept.filter((l, i) => fencedOut[i] || l.trim() !== '' || i === 0 || kept[i - 1].trim() !== '');
+    return { text: out.join('\n'), stamped: true };
+}
+/**
+ * The register's rows against the population the payload derived: every
+ * practice of `partition.population` (remainder plus both derived arms) has
+ * exactly one row, and no row names anything else. Deleting a row is how a
+ * hard practice disappears from a review; this makes that a reported problem.
+ */
+function compareReviewPopulation(rows, partition) {
+    const expected = uniqueInOrder([
+        ...partition.remainder,
+        ...partition.naUniverse.map((r) => r.id),
+        ...partition.naNoFile.map((r) => r.id),
+    ]);
+    const want = new Set(expected.map((id) => quotableId(id)));
+    const seen = new Map();
+    for (const r of rows) {
+        if (typeof r?.id !== 'string' || r.id === '')
+            continue;
+        seen.set(r.id, (seen.get(r.id) ?? 0) + 1);
+    }
+    const problems = [];
+    for (const id of want) {
+        if (!seen.has(id)) {
+            problems.push(reviewProblem(REVIEW_PROBLEM_KIND.ROW_POPULATION_MISSING, id, null, `"${id}" is in the population this review derived and has no row: a practice handed to the review ` +
+                'is judged or reproduced, never dropped.'));
+        }
+    }
+    for (const [id, n] of seen) {
+        if (!want.has(id)) {
+            problems.push(reviewProblem(REVIEW_PROBLEM_KIND.ROW_POPULATION_UNEXPECTED, id, null, `"${safe(id)}" has a row but is not in the population this review derived, so its verdict judges ` +
+                'something the review was not handed.'));
+        }
+        if (n > 1) {
+            problems.push(reviewProblem(REVIEW_PROBLEM_KIND.ROW_DUPLICATE, id, null, `"${safe(id)}" carries ${n} rows; each practice carries exactly one verdict.`));
+        }
+    }
+    return problems;
+}
+module.exports = {
+    // The three frozen vocabularies. These ARE the contract 06-04/06-06/06-08 and
+    // 06-10 serialize; nothing downstream re-derives a token.
+    REVIEW_VERDICT,
+    NA_DERIVED_REASON,
+    REVIEW_RANGE_SOURCE,
+    // The input set, harvested from the shipped mechanical tier.
+    deriveCandidateSet,
+    // The two derived-N-A arms, deliberately two functions and two labels.
+    deriveNaAUniverse,
+    deriveNaANoFile,
+    // The split that decides what may reach the agent at all.
+    partitionForJudgement,
+    // The arithmetic. Computed, never narrated.
+    countReviewVerdicts,
+    renderRateLine,
+    // The range, and the single refusal predicate that guards it.
+    resolveReviewRange,
+    reviewRefusesCleanRender,
+    // 08-05 (D-08-17): the two remedies for a range nobody could resolve, as ONE
+    // sentence. Exported on the same harvest rule the audit's repair sentences
+    // use — a test and an artifact quote this, never a copy of it.
+    REVIEW_RANGE_UNRESOLVABLE_REMEDY,
+    // 06-04 — the deterministic half of what the AGENT writes back. The problem
+    // vocabulary joins the three above for the same stated reason: a consumer
+    // branches on a value, and a test harvests the token it asserts on.
+    REVIEW_PROBLEM_KIND,
+    judgeReviewRow,
+    validateReviewArtifact,
+    scanForbiddenScoreTokens,
+    // 06-04 — the ONE composition of every derivation above into the envelope the
+    // CLI arm emits. Composed here rather than in the handler for the reason
+    // `cmdVaultAudit` states about its own leaf: a second composition is a second
+    // place the report can disagree with the derivation it claims to report.
+    buildReviewPayload,
+    // The artifact the agent fills in, and the three lines only code writes.
+    REVIEW_UNJUDGED_VERDICT,
+    renderReviewScaffold,
+    stampReviewLines,
+    compareReviewPopulation,
+};