@pareto4/pp-core 1.12.1 → 1.13.0

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

@@ -0,0 +1,2070 @@
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+/**
+ * src/vault-audit.cts — the pure `vault audit` evaluator: the ONE engine both
+ * surfaces call (`vault audit <phase-dir>` for an operator, `check vault.audit`
+ * for the blocking gate at verify:post and ship:pre).
+ *
+ * Responsibility. Given the practices the cached vault holds and the files a
+ * phase actually changed, decide — per practice — one of exactly four verdicts
+ * and return them all. It owns the diff scoping, the fail-closed exhaustion
+ * arms, and the human rendering. It owns NO parsing and NO matching of its own.
+ *
+ * Reuses (no new runtime dependency):
+ *   - `./vault-practices.cjs` — `globMatch` (the matching path), `isSupportedGlob`
+ *     (the pattern GATE, by reference), `boundedToken` (every client-authored
+ *     value that may reach a rendered string), `discoverPracticeFiles` (the
+ *     practice denominator), and the two cost bounds `MATCH_PAIR_CAP` /
+ *     `MATCH_BUDGET_MS` plus `MATCHED_FILES_CAP`.
+ *
+ *     Nothing on the matching path is re-implemented here and no grammar is
+ *     restated in prose: a second matcher would be a copy free to drift. The
+ *     declarative-check rule (docs/practices-format.md) — no client-authored
+ *     byte is ever compiled into a regular expression — is why content tokens
+ *     below are tested by `String.prototype.includes` and nothing else, and
+ *     why `globMatch` runs the polynomial matcher rather than a pattern
+ *     compiler. The verdict half is mechanised, not merely stated:
+ *     `eslint-rules/practices-boundary-inputs.cjs` is wired at this file in
+ *     `eslint.config.mjs`.
+ *   - `./phase-manifest.cjs` (`readPhaseManifestEntry`) — the phase's recorded
+ *     start commit, read from the file `phase manifest start|record` writes.
+ *   - `./vault-trace.cjs` — the ledger API: SUMMARY `gitCommit` digests for the
+ *     trace-digest rung, and the `check:` census the ledgers recorded.
+ *   - `./git-base-branch.cjs` (`resolveBaseBranchResult`) — the 5-tier ladder is
+ *     never re-derived; issue #1146 records what the naive form cost. The RESULT
+ *     form, so a REFUSED `git.base_branch` becomes a stated note rather than a
+ *     silent change of range (W16).
+ *   - `./shell-command-projection.cjs` (`execGit`) — the mandated, timeout-bounded
+ *     git seam. `execFileSync` is not used anywhere in this module.
+ *
+ * WHAT `require` MEANS HERE, stated because a recorded number depends on it.
+ * A `require` token is satisfied when EVERY matched file contains it. This is
+ * the per-file reading. It is chosen because it is the only reading under which a FAIL can name a SPECIFIC
+ * offending file — and a verdict that cannot name what offended it is a verdict
+ * an auditor cannot act on, which is the failure D-05-03's vocabulary exists to
+ * prevent. Changing this to "some matched file contains the token" is a
+ * decision with a paper trail, not an implementation detail.
+ *
+ * TWO KNOWN LIMITS OF THE DIFF, recorded here rather than rediscovered later.
+ * Both are inherited deliberately from `cmdShipPractices`' scoping mechanism,
+ * which this module lifts verbatim except for the range:
+ *
+ *   1. A RENAME contributes only its NEW path. `git diff --name-only` reports
+ *      the destination, so a check that asserts a file MOVED cannot see where it
+ *      came from.
+ *   2. DELETIONS are excluded (`--diff-filter=d`), and that is correct for both
+ *      assertion kinds. For a `forbid`/`forbidMatch` check a deleted violation
+ *      is the fix, so reporting it would FAIL a repair. For a `require` check a
+ *      deleted file has no content left to satisfy anything, so requiring a
+ *      token of it would FAIL a legitimate removal.
+ */
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+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 practicesMod = require("./vault-practices.cjs");
+// The trace leaf (the ledger API), for the SUMMARY trace-digest rung of
+// `resolvePhaseRange` and for the recorded `check:` census. `vault-trace.cts`
+// imports `vault.cjs` and the practices leaf only, and neither imports this
+// module, so this adds no cycle.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const traceMod = require("./vault-trace.cjs");
+// The phase manifest's reader — the same module owns its writer.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseManifestMod = require("./phase-manifest.cjs");
+// The one remote/credential redactor, applied to vault-authored text before it
+// reaches the gate message.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const vaultMod = require("./vault.cjs");
+const { parseVaultTraceBlock, readRecordedCensus } = traceMod;
+const { readPhaseManifestEntry, PHASE_MANIFEST_READ_MISS, COMMIT_SHA_SHAPE } = phaseManifestMod;
+const { redactRemoteText } = vaultMod;
+const { globMatch, isSupportedGlob, boundedToken, discoverPracticeFiles, MATCH_PAIR_CAP, MATCH_BUDGET_MS, MATCHED_FILES_CAP, 
+// 05-REVIEW CR-02/CR-03: the shared fencing idiom and the errno redactor —
+// reused, never re-authored, so the two modules cannot disagree about how a
+// client-authored byte reaches an agent-read channel.
+defangFenceMarkers, EXTERNAL_CONTENT_FENCE_START, EXTERNAL_CONTENT_FENCE_END, FENCE_NOTICE, errnoOf, } = practicesMod;
+// ─── The frozen vocabulary ────────────────────────────────────────────────────
+// These constants ARE the contract. They are module constants and are NEVER
+// re-derived at run time from configuration or from the vault — the
+// `src/vault-trace.cts` rule, for the same reason: a verdict vocabulary a
+// client repository could move is not a verdict vocabulary.
+/**
+ * D-05-03's four verdicts, verbatim. `NO_CHECK` and `NOT_MATCHED` are two
+ * distinct governance facts and must never collapse into one N-A: `NO_CHECK` is
+ * a gap in the VAULT's coverage (a candidate for CHECK-05 authoring work);
+ * `NOT_MATCHED` is a check that was live and simply had nothing to look at.
+ */
+const AUDIT_VERDICT = Object.freeze({
+    PASS: 'PASS',
+    FAIL: 'FAIL',
+    NO_CHECK: 'NO_CHECK',
+    NOT_MATCHED: 'NOT_MATCHED',
+});
+/**
+ * Why a FAIL is a FAIL. Every one of these is fail-CLOSED: an exhausted budget,
+ * a refused pair count, an unreadable file, an unreadable diff, an unreadable
+ * VAULT and an invalid check block all land here rather than on PASS or on a
+ * skip (CHECK-03g). "Proved nothing" reading as "passed" is the silence this
+ * workstream exists to end.
+ *
+ * 05-10 added `VAULT_UNREADABLE`. Until then that sentence was true of the
+ * diff side only: an absent or unreadable vault fell through to `status: 'ok',
+ * block: false, message: ''` from a gate declared `blocking: true` at both
+ * ship:pre and verify:post (G-1a). The member is what makes the sentence above
+ * true of the vault side too.
+ *
+ * 05-10 also added `PRACTICE_UNLOADABLE` — a file `discoverPracticeFiles`
+ * could not parse at all. It is a FAIL and not a NO_CHECK because a rejected
+ * file's check-bearing-ness is UNKNOWN: folding it into the vault-coverage-gap
+ * verdict would let a one-character typo buy a non-blocking outcome, which is
+ * the same trade `CHECK_INVALID` already refuses.
+ *
+ * EIGHT members, and all eight block.
+ */
+const AUDIT_FAIL_REASON = Object.freeze({
+    UNSATISFIED: 'unsatisfied',
+    PAIR_CAP_EXCEEDED: 'pair_cap_exceeded',
+    BUDGET_EXHAUSTED: 'budget_exhausted',
+    CHECK_INVALID: 'check_invalid',
+    FILE_UNREADABLE: 'file_unreadable',
+    DIFF_UNREADABLE: 'diff_unreadable',
+    VAULT_UNREADABLE: 'vault_unreadable',
+    PRACTICE_UNLOADABLE: 'practice_unloadable',
+});
+/**
+ * Where the compared range came from — recorded beside the range itself.
+ *
+ * In ladder order: the phase's recorded start commit,
+ * the parent of its first recorded commit, the parent of the ancestry-earliest
+ * SUMMARY trace digest, and only then the base-branch fallback. Every source
+ * but the last is resolved FROM THE PHASE, which is what WR-04's block predicate
+ * keys on.
+ *
+ * `OPERATOR_RANGE` (08-04) sits OUTSIDE the ladder entirely — see its own
+ * comment below.
+ */
+const AUDIT_RANGE_SOURCE = Object.freeze({
+    PHASE_START_COMMIT: 'phase-start-commit',
+    PHASE_FIRST_COMMIT: 'phase-first-commit',
+    TRACE_DIGEST: 'trace-digest',
+    BASE_BRANCH: 'base-branch',
+    /**
+     * The range came from an operator flag, not from the ladder (08-04, D-08-19).
+     * The ladder is not consulted at all when this fires, so no `fallbackReason`
+     * can exist and none is set.
+     *
+     * WHY IT EXISTS. UAT test 7a could not be re-run by hand: `vault audit`
+     * exposed no `--range` / `--base` / `--from`, so an operator who watched the
+     * gate block vacuously had no way to ask it about a range they knew was the
+     * phase's. This is the diagnostic channel that answer needs.
+     *
+     * A review tier that maps audit sources should leave this one unmapped, for
+     * the same reason as `base-branch`: a review that accepts no range flag can
+     * never be handed an operator range. Kebab-cased like its four siblings — it IS a source, unlike
+     * `AUDIT_RANGE_OUTCOME`'s members.
+     */
+    OPERATOR_RANGE: 'operator-range',
+});
+/**
+ * The longest operator-supplied range this module will hand to git (08-04).
+ *
+ * Two refs, each allowed a full `refs/...` spelling plus `^`/`~` suffixes, fit
+ * inside 200 characters with room to spare; nothing legitimate needs more, and
+ * a cap keeps an absurd value out of an argv and out of an error path long
+ * before git sees it.
+ */
+const AUDIT_OPERATOR_RANGE_MAX_LENGTH = 200;
+/**
+ * The shape an operator-supplied range must match before it may become an argv
+ * element (08-04, threat T-08-22).
+ *
+ * `diffFilesFor` passes the range as ONE element of
+ * `['-c', 'core.quotepath=off', 'diff', '--name-only', '--diff-filter=d', range]`.
+ * There is no shell here, so quoting is not the exposure — OPTION SHAPE is: a
+ * value beginning with `-` is read by git as a flag, not as a revision range,
+ * and `--output=/tmp/x..HEAD` would have git write a file. Hence the
+ * LEADING-ALPHANUMERIC requirement on both sides, which no `-` or `--` prefix
+ * can satisfy.
+ *
+ * T-6-49 is the precedent class this closes in advance: a configured
+ * `git.base_branch` reached argv unvalidated. The charset is an allow-list, so
+ * whitespace, control characters, `$`, backticks and quotes are excluded by
+ * omission rather than by enumeration — the direction that stays safe when
+ * something new is invented. Two dots or three, and nothing else.
+ */
+const AUDIT_OPERATOR_RANGE_SHAPE = /^[A-Za-z0-9][A-Za-z0-9._/^~-]*\.\.\.?[A-Za-z0-9][A-Za-z0-9._/^~-]*$/;
+/**
+ * Fail-closed: is this value one this module will compare over? (08-04.)
+ *
+ * Takes `unknown` on purpose — the value arrives from a CLI flag two layers up
+ * (plan 08-06), where its type is whatever an argv parser produced. Exported so
+ * the router HARVESTS this predicate rather than restating it; a second copy of
+ * a security check is a second copy that can be relaxed alone.
+ */
+function isValidOperatorRange(value) {
+    if (typeof value !== 'string')
+        return false;
+    if (value.length === 0 || value.length > AUDIT_OPERATOR_RANGE_MAX_LENGTH)
+        return false;
+    return AUDIT_OPERATOR_RANGE_SHAPE.test(value);
+}
+/**
+ * WHY a phase-scoped range could not be resolved (05-10, G-1c).
+ *
+ * `phaseCommitsFor` returned `[]` for five structurally different grounds and
+ * `resolvePhaseRange` distinguished none of them, so `rangeSource:
+ * 'base-branch'` was the whole story an operator got. The executing checkout
+ * writes the manifest itself, but a checkout that never ran
+ * `/pp-execute-phase` — a fresh clone or a CI runner where `.planning/` is
+ * gitignored — has no manifest to read, and there the fallback fires whenever
+ * no SUMMARY trace digest verifies either. That is precisely the case where
+ * knowing WHICH ground fired is the difference between a repairable
+ * configuration and a permanent one, and what makes D-05-08's range record
+ * auditable there.
+ */
+const AUDIT_FALLBACK_REASON = Object.freeze({
+    /** The phase directory's name does not begin with an `NN` or `NN.M` token. */
+    PHASE_SLUG_UNRECOGNISED: PHASE_MANIFEST_READ_MISS.PHASE_SLUG_UNRECOGNISED,
+    /** No `.phase-manifest.json` at the location `phase manifest start` writes for this phase. */
+    MANIFEST_NOT_FOUND: PHASE_MANIFEST_READ_MISS.MANIFEST_NOT_FOUND,
+    /** A manifest was found but is not parseable JSON of the expected shape. */
+    MANIFEST_MALFORMED: PHASE_MANIFEST_READ_MISS.MANIFEST_MALFORMED,
+    /** A manifest parsed, but holds no usable entry for this phase under either key spelling. */
+    PHASE_ENTRY_MISSING: PHASE_MANIFEST_READ_MISS.PHASE_ENTRY_MISSING,
+    /** The phase's entry exists and records neither a start commit nor any commit. */
+    NO_COMMITS_RECORDED: PHASE_MANIFEST_READ_MISS.NO_COMMITS_RECORDED,
+    /** Commits were recorded, and git verified none of them. */
+    COMMIT_UNVERIFIABLE: 'commit-unverifiable',
+});
+/**
+ * WHAT the compared range ESTABLISHES — the outcome, not the source (08-04,
+ * D-08-17).
+ *
+ * `AUDIT_RANGE_SOURCE` answers WHERE the range came from. This answers what an
+ * operator may conclude from what was compared over it, and the two are
+ * genuinely different questions: `base-branch` is a source that sometimes
+ * establishes something (files were compared) and sometimes establishes
+ * nothing at all (zero files over a range nobody tied to this phase). Until
+ * 08-04 the second case had no name — it produced `status: 'warn'`,
+ * `block: true` and a prose sentence, and `range_unresolvable` occurred
+ * nowhere in `src/`, so no consumer could tell "this gate blocked because a
+ * practice failed" from "this gate blocked because it proved nothing".
+ *
+ * `range_unresolvable` is deliberately NOT a fifth `AUDIT_RANGE_SOURCE` member
+ * (RESEARCH R7, Open Question 2): nothing was resolved, so there is no source
+ * to name, and a consumer's source map would then owe it a mapping it
+ * has no meaning for.
+ *
+ * CASING. These three values are underscore-cased while the kebab-cased
+ * `AUDIT_RANGE_SOURCE` / `AUDIT_FALLBACK_REASON` sit beside them. That is a
+ * conscious deviation, not drift: `range_unresolvable` is quoted VERBATIM as
+ * contract text by REQUIREMENTS.md HGATE-04, by ROADMAP.md's third criterion
+ * and by the `vault-phase-range-unresolvable-on-main` todo, all of which
+ * predate this table. Re-spelling it kebab here would make the shipped token
+ * disagree with the three documents that specify it; re-spelling THEM would
+ * rewrite a requirement to suit an implementation. The older tables are not
+ * renamed either — a vocabulary a consumer already serializes is not churned
+ * for symmetry.
+ */
+const AUDIT_RANGE_OUTCOME = Object.freeze({
+    /**
+     * The range came from the phase itself — one of the three phase-derived
+     * rungs (`phase-start-commit`, `phase-first-commit`, `trace-digest`), or an
+     * operator who named the range and thereby asserted its scope. An EMPTY diff
+     * here is a fact ABOUT THE PHASE and is stated, never blocked: D-05-02's
+     * reasoning, preserved by D-08-18 — a legitimately empty phase diff is
+     * common (docs-only phases, re-runs, a re-audit after a merge) and blocking
+     * on it would teach operators to ignore the gate.
+     */
+    PHASE_SCOPED: 'phase_scoped',
+    /**
+     * The base-branch rung with at least one file. Something WAS compared, and
+     * the verdicts speak for it — but nothing established that the range is this
+     * phase's, so a FAIL may name a file belonging to a different phase (D-05-08).
+     * Audited, and not phase-scoped: the two facts an operator needs held apart.
+     */
+    FALLBACK_AUDITED: 'fallback_audited',
+    /**
+     * The base-branch rung with ZERO files: nothing was verified. This is the
+     * predicate WR-04 already wrote and 08-04 merely NAMES (D-08-17). With
+     * `git.branching_strategy: none` — pp-core's default — `main...HEAD` is
+     * empty whenever HEAD sits at or behind the base, so this is the steady
+     * state of a default-config project, not an edge case.
+     */
+    RANGE_UNRESOLVABLE: 'range_unresolvable',
+});
+/**
+ * The ONE predicate that decides which `AUDIT_RANGE_OUTCOME` a comparison
+ * earned (08-04, D-08-17 / D-08-18). Pure: same inputs, same answer, no git.
+ *
+ * EXPORTED on purpose. The review tier (plan 08-05) consults THIS function
+ * rather than re-deriving the cell from `rangeSource` and a file count of its
+ * own — two predicates for one claim are two claims, and they diverge on the
+ * day one of them is edited (the 04-18 lesson, and exactly how the audit and
+ * the review each came to own a range resolver that failed the same way).
+ *
+ * FAIL-CLOSED on a malformed count: anything that is not a non-negative
+ * integer is normalised to 0, which on a non-phase-scoped range lands on
+ * `range_unresolvable` — the outcome that blocks. A count we cannot trust must
+ * never buy the audited reading.
+ */
+function classifyRangeOutcome(input) {
+    const raw = input.filesConsidered;
+    const files = typeof raw === 'number' && Number.isInteger(raw) && raw > 0 ? raw : 0;
+    if (input.phaseScoped)
+        return AUDIT_RANGE_OUTCOME.PHASE_SCOPED;
+    return files > 0 ? AUDIT_RANGE_OUTCOME.FALLBACK_AUDITED : AUDIT_RANGE_OUTCOME.RANGE_UNRESOLVABLE;
+}
+/**
+ * Is this range source one that ties the range to the phase? (08-04.)
+ *
+ * Stated as "everything but the base-branch fallback", in that direction and
+ * not as an allow-list, because that is exactly the shape of WR-04's own
+ * predicate — `rangeSource === AUDIT_RANGE_SOURCE.BASE_BRANCH` — and 08-04
+ * must not change its truth table (D-08-18). Written once so the three
+ * `runVaultAudit` arms cannot answer the question differently.
+ */
+function isPhaseScopedSource(rangeSource) {
+    return rangeSource !== AUDIT_RANGE_SOURCE.BASE_BRANCH;
+}
+/**
+ * The bounded WHOLE-file read for a content check (1 MiB).
+ *
+ * Over-size is a FAIL, never a partial scan, and the direction matters in both
+ * assertion kinds (T-5-14): a truncated read can miss a `forbid` token that
+ * sits past the cut and false-PASS the check, and can miss a `require` token
+ * that sits past the cut and false-FAIL it. Reading changed-file CONTENT is a
+ * new I/O axis that none of the six pre-existing caps governed, so it gets its
+ * own bound rather than borrowing one that means something else.
+ */
+const AUDIT_FILE_READ_MAX = 1048576;
+/** How many FAILing practices the gate message itemizes before it counts the rest. */
+const AUDIT_MESSAGE_PROBLEM_CAP = 20;
+/**
+ * The changed-file cap. A leaf-local constant that MIRRORS `SHIP_DIFF_FILE_CAP`
+ * in `src/check-command-router.cts` — the precedent it copies — deliberately
+ * rather than importing it: that constant is not exported, and importing an
+ * adapter from a leaf is the cycle D-12 forbids. Over the cap the list is
+ * truncated with a COUNTED note, never silently.
+ */
+const AUDIT_DIFF_FILE_CAP = 2000;
+/**
+ * Git's well-known empty-tree object id. Diffing against it includes a root
+ * commit's own files, which is the degenerate case a phase whose first commit
+ * IS the repository root would otherwise crash on.
+ */
+const GIT_EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+/**
+ * The gate message's closing REPAIR sentence.
+ *
+ * Gate details are agent-EXECUTABLE — an orchestrator reading this may perform
+ * what it names — and `.planning/` is gitignored in projects like this one, so
+ * a deletion instruction is unrecoverable (T-4-75). Every sentence this module
+ * emits names a repair and never a removal, and the repair is the CLOSING
+ * sentence so no truncation above it can ever cut the remedy off.
+ */
+const AUDIT_REPAIR_SENTENCE = 'Repair: change the named files so they satisfy the practice, or correct that practice’s check: block in the client vault and re-fetch the vault.';
+/** The diff arm's repair. Also a repair: nothing anywhere is removed. */
+const AUDIT_DIFF_REPAIR_SENTENCE = 'Repair: run this audit from inside the repository’s checkout and confirm `git status` succeeds there, then run it again.';
+/**
+ * The refused-operator-range arm's repair (08-04, D-08-19).
+ *
+ * It names the SHAPE rather than quoting what was supplied: the value failed
+ * validation, so echoing it would put an unvalidated string into a gate message
+ * an orchestrating agent reads verbatim — the one channel this module's own
+ * header calls agent-EXECUTABLE. A repair, never a removal, like its three
+ * siblings.
+ */
+const AUDIT_OPERATOR_RANGE_REPAIR_SENTENCE = 'Repair: re-run the audit with a well-formed two-dot or three-dot range such as `main..HEAD` or `<sha>^..HEAD`, or omit the range entirely and let the phase-range ladder resolve it.';
+/**
+ * The vault arm's repair (05-10). Also a repair, and for a sharper reason than
+ * the other two: the thing that is missing here is the CLIENT VAULT, and the
+ * cache it would be restored into lives under `.planning/`, which is gitignored
+ * in projects like this one. An instruction to remove anything on this path is
+ * therefore unrecoverable, so this sentence names re-fetching and re-running
+ * and nothing else (T-4-75).
+ */
+const AUDIT_VAULT_REPAIR_SENTENCE = 'Repair: re-fetch the client vault with `pp-tools vault fetch`, confirm `.planning/vault` is readable, then run this audit again.';
+// ─── Shape predicates ─────────────────────────────────────────────────────────
+//
+// SHAPE-PREDICATES-BEGIN
+//
+// Every predicate in this region compares its argument against one of this
+// module's own frozen verdict constants and nothing else. No regular
+// expression, no text-search primitive, no character-code probe, no inline
+// literal may appear here or reach a boundary decision anywhere in this file —
+// The declarative-check rule states the prohibition and `eslint-rules/practices-boundary-inputs.cjs`,
+// wired at this file in `eslint.config.mjs`, is what keeps it: a future edit
+// reintroducing one fails `npm run lint`, not a review.
+//
+// The matching and token-testing functions sit deliberately OUTSIDE this region
+// and outside the configured boundary-function set. `globMatch` reaches
+// `.replace()` and `.test()` and a content token is tested with `.includes()` —
+// all three are banned in here, which is exactly why the verdict decision and
+// the text search are kept as separate, separately-audited surfaces.
+/** Is this verdict the satisfied one? */
+function isPassVerdict(verdict) {
+    return verdict === AUDIT_VERDICT.PASS;
+}
+/** Is this verdict a failure — the only verdict that blocks? */
+function isFailVerdict(verdict) {
+    return verdict === AUDIT_VERDICT.FAIL;
+}
+/** Is this the vault-coverage gap — a practice that carries no check block at all? */
+function isNoCheckVerdict(verdict) {
+    return verdict === AUDIT_VERDICT.NO_CHECK;
+}
+/** Is this a live check whose globs matched nothing in this diff? */
+function isNotMatchedVerdict(verdict) {
+    return verdict === AUDIT_VERDICT.NOT_MATCHED;
+}
+//
+// SHAPE-PREDICATES-END
+/**
+ * The frozen registry of every predicate declared in the region above, in
+ * declaration order. Its consumer is the lint rule's registry-drift check,
+ * which compares this array against the region's own declarations in BOTH
+ * directions: a predicate declared there and not registered here, or registered
+ * here and not declared there, fails lint rather than review.
+ */
+const SHAPE_PREDICATE_NAMES = Object.freeze([
+    'isPassVerdict',
+    'isFailVerdict',
+    'isNoCheckVerdict',
+    'isNotMatchedVerdict',
+]);
+/**
+ * The verdict ladder itself — the one place a verdict is chosen.
+ *
+ * ORDER IS LOAD-BEARING. `hasInvalidCheck` is tested FIRST and independently of
+ * every cost bound, because an invalid check block is a fact about the practice
+ * rather than about the comparison: it needs no matching, so neither the pair
+ * cap nor the wall-clock budget can change it, and folding it into `NO_CHECK`
+ * would let a typo in the vault buy a green verdict (05-01's stated contract).
+ */
+function verdictForPractice(state) {
+    if (state.hasInvalidCheck)
+        return AUDIT_VERDICT.FAIL;
+    if (!state.hasCheck)
+        return AUDIT_VERDICT.NO_CHECK;
+    if (state.failed)
+        return AUDIT_VERDICT.FAIL;
+    if (state.matchedNothing)
+        return AUDIT_VERDICT.NOT_MATCHED;
+    return AUDIT_VERDICT.PASS;
+}
+/**
+ * Count the four verdicts through the registered predicates and nothing else,
+ * and derive the run-level coverage facts from those counts.
+ *
+ * THE DERIVATION LIVES HERE ON PURPOSE (D-10-09, settled by planting and
+ * running rather than by argument). `countVerdicts` is already one of the three
+ * `boundaryFunctions` reviewed in `eslint.config.mjs`, so the derivation is
+ * AUDITED where it sits. A new helper called by name from a boundary function
+ * fails `local/practices-boundary-inputs`; a new decider called only from
+ * `runVaultAudit` passes the rule and is entirely UNAUDITED by it, which is the
+ * shape not to take. The rule flags string and template operands of a
+ * comparison but not numeric ones, which is why counting arithmetic is
+ * admissible in an audited body.
+ */
+function countVerdicts(entries) {
+    const counts = {
+        pass: 0,
+        fail: 0,
+        noCheck: 0,
+        notMatched: 0,
+        mechanicallyChecked: 0,
+        applicablePractices: 0,
+        evaluatedNothing: true,
+    };
+    for (const entry of entries) {
+        if (isPassVerdict(entry.verdict))
+            counts.pass += 1;
+        else if (isFailVerdict(entry.verdict))
+            counts.fail += 1;
+        else if (isNoCheckVerdict(entry.verdict))
+            counts.noCheck += 1;
+        else if (isNotMatchedVerdict(entry.verdict))
+            counts.notMatched += 1;
+    }
+    counts.mechanicallyChecked = counts.pass + counts.fail;
+    counts.applicablePractices = counts.pass + counts.fail + counts.noCheck;
+    counts.evaluatedNothing = counts.mechanicallyChecked === 0;
+    return counts;
+}
+/**
+ * The run-level outcome token for an audit that mechanically checked nothing
+ * (MECH-02, D-10-01), in the frozen style of this file's other vocabularies.
+ *
+ * ONE member, and it is NOT an `AUDIT_VERDICT` member and NOT an entry in the
+ * lint rule's `allowedConstants`: it is a run-level fact, never a per-practice
+ * verdict, and it is only ever interpolated into a note — never compared inside
+ * a boundary function. `AUDIT_RANGE_OUTCOME` is the precedent, on this same
+ * envelope, for exactly that placement.
+ *
+ * EXPORTED so tests and the review tier HARVEST the token rather than copying
+ * the literal — a copied token stops guarding the day the shipped one moves.
+ */
+const AUDIT_COVERAGE_OUTCOME = Object.freeze({
+    /**
+     * Not one applicable practice reached a PASS or a FAIL. The vault was read,
+     * the diff was read, and no `check:` block was compared against any file —
+     * so nothing was verified mechanically and no passing claim can be drawn
+     * from the run. Stated, never blocked (D-10-02).
+     */
+    EVALUATED_NOTHING: 'evaluated_nothing',
+});
+/**
+ * The counts-only coverage line (D-10-03, D-10-18), modelled on
+ * the practice review's rate line and inheriting its two rules
+ * verbatim:
+ *
+ *  - the figures are DERIVED from the four verdict counts and a supplied `n`
+ *    or `m` is deliberately ignored, so a caller cannot narrate a denominator
+ *    the rows do not support;
+ *  - counts only. No ratio, no percentage, no letter grade, no single roll-up
+ *    — one number invites being quoted as a measured-sounding compliance claim,
+ *    which is the over-claim this milestone exists to prevent.
+ *
+ * EXPORTED so every surface harvests ONE renderer. A second renderer is a
+ * second place the surfaces can come to disagree about the same fact.
+ */
+function renderMechanicalCoverageLine(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 noCheck = n(counts?.noCheck);
+    const notMatched = n(counts?.notMatched);
+    const checked = pass + fail;
+    const applicable = pass + fail + noCheck;
+    return (`${checked} of ${applicable} practices mechanically checked · ` +
+        `${pass} PASS · ${fail} FAIL · ${notMatched} NOT_MATCHED · ${noCheck} NO_CHECK`);
+}
+/**
+ * The one sentence every surface states about the recorded `check:` census.
+ *
+ * The census is the vault's, taken when the ledger was written; this audit's
+ * counts are the run's. The sentence keeps the two apart: it says what the
+ * LEDGER records, and never that the audit found it. Engine-composed apart
+ * from the artifact name, which is a file name in the phase directory and is
+ * bounded.
+ */
+function renderRecordedCensusLine(census) {
+    if (census === null)
+        return "No check: census is recorded in this phase's trace ledgers.";
+    const sha = census.resolvedSha ? census.resolvedSha.slice(0, 12) : 'an unrecorded sha';
+    const moved = census.distinct > 1
+        ? ` The phase's ledgers record ${census.distinct} different censuses, so the vault changed during the phase.`
+        : '';
+    return (`The phase's trace ledger (${boundedToken(census.artifact)}) records ${census.checkBearingPractices} of ` +
+        `${census.practiceUniverse} practices carrying a check: block, at vault ${sha}.${moved}`);
+}
+/**
+ * Does this verdict set halt the gate? A blocking decision made on client data,
+ * so it is audited: only a FAIL blocks, and it is emitted as a strict boolean
+ * because the enforcer tests `.block === true`.
+ */
+function blocksOnVerdicts(entries) {
+    for (const entry of entries) {
+        if (isFailVerdict(entry.verdict))
+            return true;
+    }
+    return false;
+}
+// ─── Matching and token testing (deliberately NOT boundary functions) ─────────
+/**
+ * Which of `files` sit inside this practice's `applies-to` ∩ `check.files`
+ * intersection (MECH-01, D-10-12).
+ *
+ * A file is matched when it matches at least one `check.files` glob AND the
+ * practice applies to it. Before 10-01 only the first half existed, so a
+ * practice whose `applies-to` named only Vue files reported a FAIL against a
+ * `.cs` file — governance the practice never claimed.
+ *
+ * `isSupportedGlob` gates each pattern BY REFERENCE — a pattern the shipped
+ * gate rejects matches nothing here rather than being interpreted by some
+ * second, more permissive reading of the same string. `globMatch` does the
+ * matching; this module never writes one. That holds for the applies-to side
+ * exactly as it already held for the check side (the declarative-check rule).
+ */
+function matchCheckFiles(check, files, appliesTo) {
+    const scope = Array.isArray(appliesTo) ? appliesTo : [];
+    // THE FAIL-OPEN THIS BRANCH EXISTS TO AVOID. An ABSENT or EMPTY applies-to
+    // means APPLIES EVERYWHERE, so the scope test is skipped rather than run
+    // against nothing. A `scope: global` practice carries an EMPTY `appliesTo`
+    // by construction (`src/vault-practices.cts:1034` refuses a global practice
+    // that declares globs), so reading empty as *matches nothing* would silently
+    // un-govern every global practice in the fleet — a fail-open on the exact
+    // axis this milestone exists to close. The shipped `matchPractices`
+    // (`src/vault-practices.cts:1474`) already answers this question the same
+    // way in its `scope === 'scoped'` else-branch; this agrees with it rather
+    // than inventing a second answer.
+    const scoped = scope.length > 0;
+    const matched = [];
+    for (const file of files) {
+        if (scoped) {
+            let inScope = false;
+            for (const glob of scope) {
+                if (!isSupportedGlob(glob))
+                    continue;
+                if (globMatch(file, glob)) {
+                    inScope = true;
+                    break;
+                }
+            }
+            if (!inScope)
+                continue;
+        }
+        for (const glob of check.files) {
+            if (!isSupportedGlob(glob))
+                continue;
+            if (globMatch(file, glob)) {
+                matched.push(file);
+                break;
+            }
+        }
+    }
+    return matched;
+}
+/**
+ * Does `content` contain the literal token?
+ *
+ * Plain substring containment, and nothing else, ever. The token is a
+ * client-authored byte sequence from the vault repository; the declarative-check rule bars it
+ * from every pattern compiler, so a token that LOOKS like a pattern is tested
+ * as the literal text it is.
+ */
+function contentHasToken(content, token) {
+    return content.includes(token);
+}
+// ─── The evaluator ────────────────────────────────────────────────────────────
+function boundedList(values) {
+    return values.slice(0, MATCHED_FILES_CAP).map((v) => boundedToken(v));
+}
+// ─── The analyzer-provenance clause (MECH-03, D-10-05) ───────────────────────
+/**
+ * The lead of the `enforced-by:` clause, and the ONLY wording this module
+ * composes for it.
+ *
+ * "also enforced by" and NOT "verified by". pp-core runs no analyzer and
+ * confirms no analyzer's result, so the sentence surfaced is a claim about
+ * what the PRACTICE SAYS, attributable to the vault that wrote it — never a
+ * claim about a run that happened here. A confirmation-shaped wording would be
+ * a record asserting more governance than was granted, which is the exact
+ * over-claim this milestone exists to end.
+ *
+ * EXPORTED on the same harvest rule as `AUDIT_REPAIR_SENTENCE` below: a test
+ * that copies the wording it asserts stops guarding the day the wording is
+ * reworded.
+ */
+const AUDIT_ENFORCED_BY_LEAD = 'also enforced by';
+/**
+ * Compose the clause for one practice's `enforced-by:` list, or `''` when
+ * there is nothing to say.
+ *
+ * DELIBERATELY NOT A BOUNDARY FUNCTION and deliberately not named in
+ * `eslint.config.mjs`'s `boundaryFunctions` (D-10-09): composing a display
+ * string is not deciding on client data. Nothing here reads a verdict, and no
+ * caller's verdict changes because of what it returns.
+ *
+ * Each rule name is client-authored. `boundedList` re-applies `boundedToken`
+ * AND the list cap at this interpolation site even though plan 10-03's parser
+ * already bounded the value — `boundedToken` at every interpolation is the
+ * shipped discipline (T-24-07), and a bound that exists once is a bound that
+ * can be removed once.
+ */
+function enforcedByClause(enforcedBy) {
+    if (!Array.isArray(enforcedBy))
+        return '';
+    const named = enforcedBy.filter((r) => typeof r === 'string' && r.length > 0);
+    if (named.length === 0)
+        return '';
+    return `${AUDIT_ENFORCED_BY_LEAD} ${boundedList(named).join(', ')}`;
+}
+/**
+ * The entry, with the vault's analyzer claim APPENDED to whatever detail the
+ * verdict already carries — never replacing it.
+ *
+ * The separator is the one the coverage line already uses, and the order is
+ * load-bearing: an operator reading a FAIL line is reading it for the reason
+ * the gate blocked, and a provenance clause that displaced that reason would
+ * bury the only actionable half of the line behind a claim nobody ran.
+ *
+ * Never reaches `notes`. `noteLine`'s length bound was removed on the stated
+ * property that no client byte reaches a note (see its comment); putting one
+ * there would break that property rather than merely stretch it.
+ */
+function withEnforcedBy(entry, enforcedBy) {
+    const clause = enforcedByClause(enforcedBy);
+    if (clause === '')
+        return entry;
+    return { ...entry, detail: entry.detail ? `${entry.detail} · ${clause}` : clause };
+}
+/** A reader that delivers nothing — the fail-closed default (never a silent read). */
+const NO_READER = () => ({ ok: false, reason: 'no file reader was provided' });
+/**
+ * Run one check's content assertions over its matched files.
+ *
+ * Returns `{ reason: null }` when satisfied. A file that cannot be delivered
+ * WHOLE (missing, unreadable, or longer than `AUDIT_FILE_READ_MAX`) is
+ * `file_unreadable` — never a partial scan, never a silent pass.
+ */
+function evaluateContent(check, matched, readFile) {
+    const requireTokens = check.require ?? [];
+    const forbidTokens = check.forbid ?? [];
+    for (const file of matched) {
+        let read;
+        try {
+            read = readFile(file);
+        }
+        catch (e) {
+            read = { ok: false, reason: e?.message };
+        }
+        if (!read || read.ok !== true || typeof read.content !== 'string') {
+            const why = read && read.ok === false && read.reason ? boundedToken(read.reason) : 'could not be read';
+            return {
+                reason: AUDIT_FAIL_REASON.FILE_UNREADABLE,
+                detail: `${boundedToken(file)} ${why}`,
+            };
+        }
+        if (read.content.length > AUDIT_FILE_READ_MAX) {
+            return {
+                reason: AUDIT_FAIL_REASON.FILE_UNREADABLE,
+                detail: `${boundedToken(file)} is larger than the ${AUDIT_FILE_READ_MAX}-byte whole-file read bound, so it was not scanned`,
+            };
+        }
+        for (const token of requireTokens) {
+            if (!contentHasToken(read.content, token)) {
+                return {
+                    reason: AUDIT_FAIL_REASON.UNSATISFIED,
+                    detail: `${boundedToken(file)} does not contain the required token "${boundedToken(token)}"`,
+                };
+            }
+        }
+        for (const token of forbidTokens) {
+            if (contentHasToken(read.content, token)) {
+                return {
+                    reason: AUDIT_FAIL_REASON.UNSATISFIED,
+                    detail: `${boundedToken(file)} contains the forbidden token "${boundedToken(token)}"`,
+                };
+            }
+        }
+    }
+    return { reason: null, detail: '' };
+}
+/**
+ * Evaluate every discovered practice against the changed-file list.
+ *
+ * PURE, with both side-effecting inputs injected: `readFile` is the whole-file
+ * reader and `now` is a monotonic clock. `now` is called exactly ONCE at entry
+ * and ONCE per practice, which is what lets the budget arm be driven
+ * deterministically by a counting clock instead of by a sleep.
+ *
+ * THE DENOMINATOR IS EVERY DISCOVERED PRACTICE AND EVERY FILE DISCOVERY COULD
+ * NOT LOAD. A practice never disappears from the result; a coverage gap shows
+ * up as `NO_CHECK` rather than as an absence, because an absence is
+ * indistinguishable from a practice the evaluator quietly dropped.
+ *
+ * The second clause is 05-10's (G-1b). This function only ever sees practices
+ * that PARSED, so the rejected files are joined on by `runVaultAudit` as
+ * `FAIL(practice_unloadable)` records — see `unloadableEntries`. Until then the
+ * sentence above was written as though it held and did not: a one-character
+ * `severity:` typo left the file out of the envelope entirely, which is the
+ * exact absence this contract forbids.
+ */
+function evaluatePractices(opts) {
+    const practices = Array.isArray(opts.practices) ? opts.practices : [];
+    const files = Array.isArray(opts.files) ? opts.files : [];
+    const readFile = typeof opts.readFile === 'function' ? opts.readFile : NO_READER;
+    const now = typeof opts.now === 'function' ? opts.now : () => Date.now();
+    // The DETERMINISTIC guard, decided before any matching runs (D-05-06,
+    // pattern 2). `pairs` is arithmetic on counts, so a refusal is reproducible
+    // on any machine — unlike a wall-clock threshold, which would make the
+    // verdict a property of the laptop and is exactly the non-determinism
+    // VERIFY-03 bars from a deterministic gate. The cap itself is IMPORTED from
+    // the shared matcher: one pair of constants, all call sites.
+    let checkGlobCount = 0;
+    for (const practice of practices) {
+        if (practice.check)
+            checkGlobCount += practice.check.files.length;
+    }
+    const pairs = checkGlobCount * files.length;
+    const pairCapExceeded = pairs > MATCH_PAIR_CAP;
+    const start = now();
+    let budgetExhausted = false;
+    let pairsEvaluated = 0;
+    const entries = [];
+    // ONE composition point for the analyzer claim (MECH-03, D-10-05). Every arm
+    // below pushes through here rather than appending the clause itself, so no
+    // arm can be the one that quietly drops it — the same reason `countVerdicts`
+    // is called once per return arm rather than restated per arm.
+    const pushEntry = (practice, entry) => {
+        entries.push(withEnforcedBy(entry, practice.enforcedBy));
+    };
+    for (const practice of practices) {
+        const elapsed = now() - start;
+        if (!pairCapExceeded && elapsed >= MATCH_BUDGET_MS)
+            budgetExhausted = true;
+        const id = boundedToken(practice.id);
+        const hasInvalidCheck = typeof practice.checkInvalid === 'string' && practice.checkInvalid.length > 0;
+        const check = practice.check;
+        const hasCheck = Boolean(check);
+        if (hasInvalidCheck) {
+            pushEntry(practice, {
+                id,
+                verdict: verdictForPractice({ hasInvalidCheck: true, hasCheck, failed: true, matchedNothing: false }),
+                reason: AUDIT_FAIL_REASON.CHECK_INVALID,
+                detail: boundedToken(practice.checkInvalid),
+                matchedFiles: [],
+                matchedCount: 0,
+            });
+            continue;
+        }
+        if (!check) {
+            pushEntry(practice, {
+                id,
+                verdict: verdictForPractice({ hasInvalidCheck: false, hasCheck: false, failed: false, matchedNothing: false }),
+                reason: null,
+                detail: '',
+                matchedFiles: [],
+                matchedCount: 0,
+            });
+            continue;
+        }
+        if (pairCapExceeded) {
+            pushEntry(practice, {
+                id,
+                verdict: verdictForPractice({ hasInvalidCheck: false, hasCheck: true, failed: true, matchedNothing: false }),
+                reason: AUDIT_FAIL_REASON.PAIR_CAP_EXCEEDED,
+                detail: `this vault and change set produce ${pairs} (glob, file) pair(s), over the ${MATCH_PAIR_CAP}-pair cap — this practice was never compared against the diff`,
+                matchedFiles: [],
+                matchedCount: 0,
+            });
+            continue;
+        }
+        if (budgetExhausted) {
+            pushEntry(practice, {
+                id,
+                verdict: verdictForPractice({ hasInvalidCheck: false, hasCheck: true, failed: true, matchedNothing: false }),
+                reason: AUDIT_FAIL_REASON.BUDGET_EXHAUSTED,
+                detail: `the ${MATCH_BUDGET_MS}ms evaluation budget was exhausted before this practice was reached, so it was never compared against the diff`,
+                matchedFiles: [],
+                matchedCount: 0,
+            });
+            continue;
+        }
+        // MECH-01 (D-10-12): the practice's own applies-to bounds the comparison,
+        // beside `check.files`.
+        const matched = matchCheckFiles(check, files, practice.appliesTo);
+        // DELIBERATELY NOT NARROWED BY applies-to. `pairs`, `MATCH_PAIR_CAP` and
+        // this counter are arithmetic on counts decided before any matching runs,
+        // and that is what makes a cap refusal reproducible on any machine
+        // (D-05-06). Narrowing it by applies-to would make the refusal a property
+        // of the practice set rather than of the work — a different decision, and
+        // not one 10-01 takes.
+        pairsEvaluated += check.files.length * files.length;
+        // `forbidMatch` asserts the matched set must be EMPTY, so a match IS the
+        // violation and no content is inspected. The asymmetry below is deliberate:
+        // an empty match set is a PASS here, not NOT_MATCHED, because the assertion
+        // was evaluated over the whole diff and HELD. NOT_MATCHED means "this check
+        // had nothing to look at", which is a different fact from "this check
+        // looked at everything and found nothing forbidden".
+        if (check.forbidMatch === true) {
+            const violated = matched.length > 0;
+            pushEntry(practice, {
+                id,
+                verdict: verdictForPractice({
+                    hasInvalidCheck: false,
+                    hasCheck: true,
+                    failed: violated,
+                    matchedNothing: false,
+                }),
+                reason: violated ? AUDIT_FAIL_REASON.UNSATISFIED : null,
+                detail: violated
+                    ? `${matched.length} file(s) match a forbidden path pattern: ${boundedList(matched).join(', ')}`
+                    : '',
+                matchedFiles: boundedList(matched),
+                matchedCount: matched.length,
+            });
+            continue;
+        }
+        if (matched.length === 0) {
+            pushEntry(practice, {
+                id,
+                verdict: verdictForPractice({
+                    hasInvalidCheck: false,
+                    hasCheck: true,
+                    failed: false,
+                    matchedNothing: true,
+                }),
+                reason: null,
+                detail: '',
+                matchedFiles: [],
+                matchedCount: 0,
+            });
+            continue;
+        }
+        const outcome = evaluateContent(check, matched, readFile);
+        pushEntry(practice, {
+            id,
+            verdict: verdictForPractice({
+                hasInvalidCheck: false,
+                hasCheck: true,
+                failed: outcome.reason !== null,
+                matchedNothing: false,
+            }),
+            reason: outcome.reason,
+            detail: outcome.detail,
+            matchedFiles: boundedList(matched),
+            matchedCount: matched.length,
+        });
+    }
+    return {
+        practices: entries,
+        pairsEvaluated,
+        pairCap: MATCH_PAIR_CAP,
+        budgetMs: MATCH_BUDGET_MS,
+        pairCapExceeded,
+        budgetExhausted,
+    };
+}
+/**
+ * The commit list and start commit this phase's manifest entry records, plus
+ * the NAMED ground on which there was none.
+ *
+ * The manifest is written by `pp-tools phase manifest start|record`
+ * (src/phase-manifest.cts): `start` at execute:pre anchors the phase at HEAD,
+ * `record` after every wave lists the commits since. This reads it through the
+ * same module, from the same file. The shas it returns are engine-written but
+ * sit in editable planning data, so the resolver re-checks their shape before
+ * any reaches a git argv. Never throws: every failure is a fallback to the next
+ * rung, which is a WIDER comparison, never a narrower one.
+ */
+function phaseCommitsFor(root, phaseDir) {
+    const read = readPhaseManifestEntry({ root, phaseDir });
+    return { commits: read.commits, miss: read.miss, startCommit: read.startCommit, notes: read.notes };
+}
+/**
+ * Resolve the git range this audit compares, and record WHERE it came from.
+ *
+ * WHY A PHASE-SCOPED RANGE. This project runs `git.branching_strategy: none`,
+ * so `base...HEAD` spans every phase since the base — under which
+ * `NOT_MATCHED` becomes rare and a FAIL can name a file belonging to a
+ * DIFFERENT phase, which is the misleading verdict D-05-03's vocabulary exists
+ * to prevent (D-05-08). And when work is committed straight onto the base
+ * branch, `base...HEAD` is EMPTY — the UAT-6-F1 halt.
+ *
+ * A FOUR-RUNG LADDER, in this order and no other:
+ *
+ *   1. `phase-start-commit` — the manifest entry's `startCommit`, the commit
+ *      HEAD sat at when `/pp-execute-phase` began the phase (written at
+ *      execute:pre by `recordPhaseStart`). The range is `<sha>..HEAD` with NO
+ *      caret: the anchor's own tree is the baseline the phase started from.
+ *      OLDER-OF (R2, defence in depth behind the writer's refusal): when the
+ *      phase's SUMMARY digests also yield an anchor, and the ancestry-earliest
+ *      digest is an ancestor of (or is) the start commit, the start commit was
+ *      recorded AFTER the phase's own traced work — a late anchor that would
+ *      put that work outside the range. The older, digest-derived range is
+ *      returned instead, with source `trace-digest` (the source always names
+ *      where the range STRING came from) and a note saying the recorded start
+ *      commit postdates the phase's traced commits. A digest that is not an
+ *      ancestor leaves the start commit in place, which is the normal flow. A
+ *      comparison git cannot decide keeps the start commit — the ladder's
+ *      stated precedence — and says the two could not be compared.
+ *   2. `phase-first-commit` — the entry's `commits` list, anchored on the
+ *      parent of the first verifiable one. `recordPhaseCommits` records the
+ *      list OLDEST-FIRST (`git rev-list --reverse`), so the first verifiable
+ *      commit in recorded order is the earliest by construction. When that
+ *      commit IS the repository root there is no parent, so the range anchors
+ *      at git's empty-tree object — still `phase-first-commit`, because a
+ *      phase-scoped range is exactly what was resolved.
+ *   3. `trace-digest` — for a phase built before the manifest writer existed:
+ *      the parent of the ancestry-earliest verified `gitCommit` digest in the
+ *      phase's SUMMARY `vault:` blocks (`traceDigestRange`). A digest records
+ *      only a file's LAST commit at plan end, so this range may under-scope
+ *      the phase, and it always says so in `notes`.
+ *   4. `base-branch` — `resolveBaseBranchResult(root)...HEAD`, exactly as
+ *      before. It now fires only for a phase with no usable manifest entry AND
+ *      no verifiable SUMMARY digest. The 5-tier ladder is never re-derived here
+ *      (issue #1146 records what the naive `origin/HEAD` + `:-main` form
+ *      cost), the RESULT form carries a refused `git.base_branch` out as
+ *      `baseBranchRefused` (W16), and the trace-digest rung's notes travel
+ *      with it so an operator can see the third rung was tried.
+ */
+function resolvePhaseRange(opts) {
+    const exec = typeof opts.exec === 'function' ? opts.exec : shell_command_projection_cjs_1.execGit;
+    const found = (() => {
+        try {
+            return phaseCommitsFor(opts.root, opts.phaseDir);
+        }
+        catch {
+            return { commits: [], miss: AUDIT_FALLBACK_REASON.MANIFEST_NOT_FOUND, startCommit: null, notes: [] };
+        }
+    })();
+    // A stale entry's disclosure (R1) leads every rung's notes: whichever range
+    // is returned, the operator learns that a recorded entry was set aside.
+    const withLead = (tail) => {
+        const all = [...found.notes, ...tail];
+        return all.length === 0 ? {} : { notes: all };
+    };
+    // The digest rung is consulted by rung 1 (older-of) and by rung 3; it is
+    // computed at most once, and only when one of them needs it.
+    let digestMemo = null;
+    const digestOutcome = () => (digestMemo ??= traceDigestRange({ root: opts.root, phaseDir: opts.phaseDir, exec }));
+    // Rung 1 — the phase's recorded start commit.
+    let startVerified = null;
+    try {
+        const start = found.startCommit;
+        if (start !== null && COMMIT_SHA_SHAPE.test(start)) {
+            const verified = exec(['rev-parse', '--verify', `${start}^{commit}`], { cwd: opts.root });
+            if (verified.exitCode === 0 && !verified.error)
+                startVerified = start;
+        }
+    }
+    catch {
+        // Fall through: an unverifiable anchor is not an anchor.
+    }
+    if (startVerified !== null) {
+        const start = startVerified;
+        const fromStart = { range: `${start}..HEAD`, rangeSource: AUDIT_RANGE_SOURCE.PHASE_START_COMMIT };
+        const digest = digestOutcome();
+        if (digest.range === null || digest.earliest === null)
+            return { ...fromStart, ...withLead([]) };
+        const earliest = digest.earliest;
+        // Exit 0: the digest is an ancestor of (or is) the start commit, so the
+        // start commit postdates it. Exit 1: it is not, the normal flow. Anything
+        // else — a git error, a throw — is undecided.
+        let digestIsOlder = null;
+        try {
+            const probe = exec(['merge-base', '--is-ancestor', earliest, start], { cwd: opts.root });
+            if (!probe.error && probe.exitCode === 0)
+                digestIsOlder = true;
+            else if (!probe.error && probe.exitCode === 1)
+                digestIsOlder = false;
+        }
+        catch {
+            digestIsOlder = null;
+        }
+        if (digestIsOlder === true) {
+            return {
+                range: digest.range,
+                rangeSource: AUDIT_RANGE_SOURCE.TRACE_DIGEST,
+                ...withLead([
+                    `the recorded start commit ${start.slice(0, 12)} postdates the phase's own traced commits: SUMMARY digest ` +
+                        `${earliest.slice(0, 12)} is ${earliest === start ? 'the start commit itself' : 'an ancestor of it'}, so ` +
+                        `${start.slice(0, 12)}..HEAD would leave that work outside the range. The older, digest-derived range is ` +
+                        'used instead',
+                    ...digest.notes,
+                ]),
+            };
+        }
+        if (digestIsOlder === null) {
+            return {
+                ...fromStart,
+                ...withLead([
+                    `the recorded start commit ${start.slice(0, 12)} and SUMMARY digest ${earliest.slice(0, 12)} could not be ` +
+                        'compared by ancestry, so the start commit is used as recorded; if it was recorded after the phase\'s own ' +
+                        'commits, this range may under-scope the phase',
+                ]),
+            };
+        }
+        return { ...fromStart, ...withLead([]) };
+    }
+    // Rung 2 — the recorded commit list.
+    try {
+        for (const sha of found.commits) {
+            if (!COMMIT_SHA_SHAPE.test(sha))
+                continue;
+            const verified = exec(['rev-parse', '--verify', `${sha}^{commit}`], { cwd: opts.root });
+            if (verified.exitCode !== 0 || verified.error)
+                continue;
+            const parent = exec(['rev-parse', '--verify', `${sha}^`], { cwd: opts.root });
+            const anchor = parent.exitCode === 0 && !parent.error ? `${sha}^` : GIT_EMPTY_TREE;
+            // A resolved phase-scoped range carries NO fallbackReason: nothing fell
+            // back, so nothing claims to have.
+            return { range: `${anchor}..HEAD`, rangeSource: AUDIT_RANGE_SOURCE.PHASE_FIRST_COMMIT, ...withLead([]) };
+        }
+    }
+    catch {
+        // Fall through: an unresolvable phase range degrades to the next rung.
+    }
+    // Rung 3 — the SUMMARY trace digests.
+    const digest = digestOutcome();
+    if (digest.range !== null) {
+        return { range: digest.range, rangeSource: AUDIT_RANGE_SOURCE.TRACE_DIGEST, ...withLead(digest.notes) };
+    }
+    // Rung 4 — the base-branch fallback, unchanged.
+    let base = 'main';
+    let baseBranchRefused;
+    try {
+        // The RESULT form, not the bare string (W16). This is the only value on the
+        // audit's command line that comes from a file a cloned repository can carry,
+        // and a refusal that fell back to "main" in silence would leave the BLOCKING
+        // tier reporting a verdict computed over a range nobody configured.
+        const resolved = (0, git_base_branch_cjs_1.resolveBaseBranchResult)(opts.root, { execGit: exec });
+        base = resolved.branch;
+        if (resolved.configRejected !== null)
+            baseBranchRefused = resolved.configRejected.reason;
+    }
+    catch {
+        base = 'main';
+    }
+    return {
+        range: `${base}...HEAD`,
+        rangeSource: AUDIT_RANGE_SOURCE.BASE_BRANCH,
+        // Commits WERE recorded and git verified none of them — a distinct ground
+        // from anything the manifest walk itself could observe.
+        fallbackReason: found.miss ?? AUDIT_FALLBACK_REASON.COMMIT_UNVERIFIABLE,
+        ...(baseBranchRefused === undefined ? {} : { baseBranchRefused }),
+        ...withLead(digest.notes),
+    };
+}
+// ─── The trace-digest rung ────────────────────────────
+/** The `gitCommit` shape the trace builder records — 40- or 64-hex, lowercase. */
+const TRACE_DIGEST_SHAPE = /^[0-9a-f]{40}$|^[0-9a-f]{64}$/;
+/** At most this many distinct digests are verified and ranked, with a note when it bites. */
+const TRACE_DIGEST_CANDIDATE_CAP = 64;
+/**
+ * The phase range derived from the `gitCommit` digests in the phase's SUMMARY
+ * `vault:` blocks — the rung for phases built before the manifest writer.
+ *
+ * Every `*-SUMMARY.md` directly in the phase directory is read (sorted, each
+ * bounded by `AUDIT_FILE_READ_MAX`), parsed with the SHIPPED trace parser, and
+ * its subjects' digests collected when they have the builder's own shape; the
+ * wider `COMMIT_SHA_SHAPE` guard is applied again before any sha reaches argv
+ * (the argv-shape guard). The distinct set is capped, then each is verified with
+ * `rev-parse --verify <sha>^{commit}`: an unverifiable digest is never an
+ * anchor.
+ *
+ * RANKING is `git rev-list --count <sha>` ascending, tie-broken by the sha
+ * string ascending — on a linear history the fewest ancestors is the oldest,
+ * and the tie-break keeps the answer deterministic. A VERIFIED digest whose
+ * count git cannot report is KEPT and ranked after every counted one: it is a
+ * real commit, so it may still anchor when nothing better exists, but an
+ * unknown position must never outrank a known one. That makes the `^{commit}`
+ * verification the sole trust gate on which shas may anchor — the count only
+ * orders shas that already passed it.
+ *
+ * The anchor is the earliest digest's parent, or git's empty-tree object when
+ * it has none. Never throws: every failure becomes a note, and when no digest
+ * survives the note states that no SUMMARY carried a verifiable gitCommit
+ * digest.
+ */
+function traceDigestRange(opts) {
+    const notes = [];
+    const none = (why) => ({
+        range: null,
+        earliest: null,
+        notes: [
+            ...notes,
+            `no SUMMARY in the phase directory carried a verifiable gitCommit digest (${why}), so no trace-digest ` +
+                'range could be derived',
+        ],
+    });
+    try {
+        const rootAbs = node_path_1.default.resolve(opts.root);
+        const phaseDirAbs = node_path_1.default.resolve(opts.phaseDir);
+        let names;
+        try {
+            names = node_fs_1.default
+                .readdirSync(phaseDirAbs)
+                .filter((name) => name.endsWith('-SUMMARY.md'))
+                .sort();
+        }
+        catch {
+            return none('the phase directory could not be listed');
+        }
+        if (names.length === 0)
+            return none('no *-SUMMARY.md file was found');
+        const candidates = [];
+        let capBit = false;
+        for (const name of names) {
+            const abs = node_path_1.default.join(phaseDirAbs, name);
+            try {
+                const stat = node_fs_1.default.statSync(abs);
+                if (!stat.isFile())
+                    continue;
+                if (stat.size > AUDIT_FILE_READ_MAX) {
+                    notes.push(`${boundedToken(name)} is over the ${AUDIT_FILE_READ_MAX}-byte read bound, so its trace digests were not read`);
+                    continue;
+                }
+                const content = node_fs_1.default.readFileSync(abs, 'utf8');
+                const rel = node_path_1.default.relative(rootAbs, abs).split(node_path_1.default.sep).join('/');
+                const parsed = parseVaultTraceBlock(content, rel);
+                if (!parsed.present || !parsed.statement)
+                    continue;
+                for (const subject of parsed.statement.subject ?? []) {
+                    const sha = subject?.digest?.gitCommit;
+                    if (typeof sha !== 'string' || !TRACE_DIGEST_SHAPE.test(sha) || !COMMIT_SHA_SHAPE.test(sha))
+                        continue;
+                    if (candidates.includes(sha))
+                        continue;
+                    if (candidates.length >= TRACE_DIGEST_CANDIDATE_CAP) {
+                        capBit = true;
+                        continue;
+                    }
+                    candidates.push(sha);
+                }
+            }
+            catch (err) {
+                notes.push(`${boundedToken(name)} could not be read (${errnoOf(err)}), so its trace digests were not read`);
+            }
+        }
+        if (capBit) {
+            notes.push(`more than ${TRACE_DIGEST_CANDIDATE_CAP} distinct gitCommit digests were recorded, so only the first ` +
+                `${TRACE_DIGEST_CANDIDATE_CAP} were considered`);
+        }
+        if (candidates.length === 0)
+            return none(`${names.length} SUMMARY file(s) read, no gitCommit digest recorded`);
+        const verified = candidates.filter((sha) => {
+            const probe = opts.exec(['rev-parse', '--verify', `${sha}^{commit}`], { cwd: opts.root });
+            return probe.exitCode === 0 && !probe.error;
+        });
+        if (verified.length === 0)
+            return none(`${candidates.length} digest(s) recorded, git verified none`);
+        const ranked = verified
+            .map((sha) => {
+            const counted = opts.exec(['rev-list', '--count', sha], { cwd: opts.root });
+            const n = counted.exitCode === 0 && !counted.error ? Number.parseInt(String(counted.stdout).trim(), 10) : NaN;
+            return { sha, count: Number.isFinite(n) ? n : Number.POSITIVE_INFINITY };
+        })
+            .sort((a, b) => {
+            if (a.count !== b.count)
+                return a.count < b.count ? -1 : 1;
+            return a.sha < b.sha ? -1 : a.sha > b.sha ? 1 : 0;
+        });
+        const earliest = ranked[0].sha;
+        const parent = opts.exec(['rev-parse', '--verify', `${earliest}^`], { cwd: opts.root });
+        const anchor = parent.exitCode === 0 && !parent.error ? `${earliest}^` : GIT_EMPTY_TREE;
+        notes.push(`phase range derived from SUMMARY trace digests: anchored on ${anchor === GIT_EMPTY_TREE ? "git's empty tree" : `the parent of ${earliest}`}, ` +
+            `the ancestry-earliest of ${verified.length} verified gitCommit digest(s). Each digest records only a file's ` +
+            'LAST commit at plan end, so this range may under-scope the phase: an earlier phase commit whose files were ' +
+            'committed again later sits outside it');
+        return { range: `${anchor}..HEAD`, earliest, notes };
+    }
+    catch (err) {
+        return none(`the SUMMARY trace digests could not be read: ${errnoOf(err)}`);
+    }
+}
+// ─── The audit envelope ───────────────────────────────────────────────────────
+/** Is this resolved absolute path the root itself, or somewhere beneath it? */
+function isContainedIn(abs, rootAbs) {
+    return abs === rootAbs || abs.startsWith(rootAbs + node_path_1.default.sep);
+}
+/**
+ * The root with every symlinked component resolved away.
+ *
+ * The post-lstat re-containment below compares two paths, and both sides have
+ * to live in the SAME namespace or the comparison is meaningless. A macOS
+ * temporary root handed in as `/var/folders/...` really lives at
+ * `/private/var/folders/...`, so re-containing a fully-resolved file path
+ * against the UNRESOLVED root would refuse every legitimate read there. A root
+ * that cannot be resolved falls back to itself: the lexical check still ran,
+ * and a reader that refuses everything is worse than one that refuses the
+ * things this contract names.
+ */
+function resolvedRootOf(rootAbs) {
+    try {
+        return node_fs_1.default.realpathSync(rootAbs);
+    }
+    catch {
+        return rootAbs;
+    }
+}
+/**
+ * The default whole-file reader: bounded, contained, and never partial.
+ *
+ * REFUSES, each refusal a `file_unreadable` FAIL upstream and each one pinned
+ * by its own case in `tests/vault-audit.test.cjs`:
+ *
+ *   1. a path that resolves outside the repository root;
+ *   2. a SYMBOLIC LINK at the leaf, categorically — including one pointing at
+ *      another in-root file;
+ *   3. a path whose resolved form escapes the root through an INTERMEDIATE
+ *      symlinked directory, which neither of the two checks above can see;
+ *   4. anything that is not a regular file;
+ *   5. anything over `AUDIT_FILE_READ_MAX` — never a truncated read that could
+ *      false-PASS a `forbid` token sitting past the cut.
+ *
+ * WHY THE LEAF REFUSAL IS CATEGORICAL. A diff path names what git tracked, and
+ * a tracked symlink is a link blob; reading THROUGH one was never this
+ * reader's contract. Admitting in-root links while refusing out-of-root ones
+ * would mean trusting a resolution step on input a `check:` block steers, where
+ * the flat rule is strictly safer. Practice content is vault-authored data
+ * under this phase's trust model, so a `forbid` list that could reach a file
+ * outside the repository is a one-token-per-run content oracle, surfaced in a
+ * message the enforcer prints verbatim. If a later phase needs in-root symlink
+ * reads, that is a widening to argue for then, with its own case.
+ *
+ * No refusal phrase carries a filesystem path. The generic catch reports by
+ * errno only (05-REVIEW CR-03 — it previously repeated the raw Node message,
+ * absolute path included, into a message the enforcer prints verbatim).
+ */
+function createBoundedFileReader(root) {
+    const rootAbs = node_path_1.default.resolve(root);
+    const rootReal = resolvedRootOf(rootAbs);
+    return (rel) => {
+        try {
+            const abs = node_path_1.default.resolve(rootAbs, rel);
+            if (!isContainedIn(abs, rootAbs)) {
+                return { ok: false, reason: 'resolves outside the repository root' };
+            }
+            // LINK-PRESERVING, and that is the whole point: the previous stat call
+            // followed symlinks, so a tracked link out of the root satisfied both
+            // the lexical check above (which does not resolve links either) and the
+            // stat, and was then read end to end.
+            const lst = node_fs_1.default.lstatSync(abs);
+            if (lst.isSymbolicLink()) {
+                return { ok: false, reason: 'is a symbolic link, which is never read through' };
+            }
+            if (!lst.isFile())
+                return { ok: false, reason: 'is not a regular file' };
+            if (lst.size > AUDIT_FILE_READ_MAX) {
+                return { ok: false, reason: `is larger than the ${AUDIT_FILE_READ_MAX}-byte whole-file read bound` };
+            }
+            // Belt and braces for INTERMEDIATE components. A symlinked parent
+            // directory is invisible to the lexical check and to a leaf-level lstat
+            // alike; `realpathSync` on a regular file resolves every component, so
+            // re-running containment on its result closes that arm too.
+            if (!isContainedIn(node_fs_1.default.realpathSync(abs), rootReal)) {
+                return { ok: false, reason: 'resolves outside the repository root' };
+            }
+            return { ok: true, content: node_fs_1.default.readFileSync(abs, 'utf8') };
+        }
+        catch (e) {
+            // 05-REVIEW CR-03: the raw Node message interpolates the absolute path
+            // it failed on, and this reason flows into `detail` → `message`, printed
+            // verbatim into an agent's context. The errno is the whole diagnostic
+            // value; the relative path is already carried beside it by the caller.
+            return { ok: false, reason: `could not be read (${errnoOf(e)})` };
+        }
+    };
+}
+/**
+ * The changed-file list for `range`.
+ *
+ * The MECHANISM is lifted verbatim from `cmdShipPractices` — `core.quotepath=off`
+ * at the seam (with git's default quoting a non-ASCII path arrives C-quoted,
+ * which both bypasses the `.planning/` exclusion and matches no glob),
+ * `--name-only`, `--diff-filter=d`, then the filter chain and the file cap. The
+ * `${base}...HEAD` literal is the ONE part that became an input (D-05-08).
+ */
+function diffFilesFor(root, range, exec) {
+    const result = exec(['-c', 'core.quotepath=off', 'diff', '--name-only', '--diff-filter=d', range], {
+        cwd: root,
+    });
+    if (result.exitCode !== 0 || result.error)
+        return { ok: false };
+    const all = result.stdout
+        .split('\n')
+        .map((f) => f.trim())
+        .filter((f) => f.length > 0)
+        .map((f) => f.replace(/\\/g, '/'))
+        // Load-bearing: a practice glob like `**/*.md` would otherwise match the
+        // phase's own planning artifacts and FAIL a practice about product code.
+        .filter((f) => !f.startsWith('.planning/'));
+    const capped = all.length > AUDIT_DIFF_FILE_CAP;
+    return { ok: true, files: capped ? all.slice(0, AUDIT_DIFF_FILE_CAP) : all, capped, total: all.length };
+}
+/** Every FAILing entry, in envelope order. */
+function failingEntries(entries) {
+    const fails = [];
+    for (const entry of entries) {
+        if (isFailVerdict(entry.verdict))
+            fails.push(entry);
+    }
+    return fails;
+}
+/**
+ * The capped, counted itemization of the FAILing entries — `[]` when none
+ * failed.
+ *
+ * Extracted from `composeAuditMessage` (05-10) so the fail-closed ARMS can use
+ * it too. Before that, a `practice_unloadable` record on the diff-unreadable
+ * or vault-unreadable path reached the envelope and the render but never the
+ * gate message, and `message` is one of the two fields the enforcer reads.
+ */
+function failItemLines(entries) {
+    const fails = failingEntries(entries);
+    if (fails.length === 0)
+        return [];
+    // 05-REVIEW CR-02: `id` and `detail` carry vault-authored bytes (the parser
+    // pins `id` to the vault filename; `detail` quotes require/forbid tokens),
+    // and the gate runner (`loop run-gates`) prints `message` verbatim into an orchestrating
+    // agent's context on every run — the channel this module's own header calls
+    // agent-EXECUTABLE. So the itemized region is defanged and fenced with the
+    // idiom `renderPracticeEntry` already uses: a planted fence marker cannot
+    // close the fence early, and the notice tells the reader these lines are
+    // reference data. The omitted-count line is engine-authored end to end and
+    // stays OUTSIDE the fence — the notice's claim about what is inside must
+    // stay true. The repair sentence is appended by the callers, after this
+    // return, so it remains the closing line a prepend can never cut off.
+    //
+    // REDACTED before defanged: a `require`/`forbid` token the vault wrote can
+    // carry a credential-bearing remote, and this message is printed verbatim.
+    // `redactRemoteText` is the one redactor (src/vault.cts); the fence is the
+    // one fence. Both are applied, neither is re-authored here.
+    const items = [];
+    for (const fail of fails.slice(0, AUDIT_MESSAGE_PROBLEM_CAP)) {
+        const detail = fail.detail ? ` — ${defangFenceMarkers(redactRemoteText(fail.detail))}` : '';
+        items.push(`- ${defangFenceMarkers(redactRemoteText(fail.id))}: ${String(fail.reason)}${detail}`);
+    }
+    const lines = [EXTERNAL_CONTENT_FENCE_START, ...FENCE_NOTICE, '', ...items, EXTERNAL_CONTENT_FENCE_END];
+    const omitted = fails.length - Math.min(fails.length, AUDIT_MESSAGE_PROBLEM_CAP);
+    if (omitted > 0) {
+        lines.push(`- ${omitted} further FAILing practice(s) are not listed here.`);
+    }
+    return lines;
+}
+/** The line that opens the notes block. Engine-authored, like every note. */
+const AUDIT_NOTES_LEAD = 'Vault audit recorded the following limits on what was compared:';
+/**
+ * One note, rendered as one line — collapsed, and deliberately NOT truncated.
+ *
+ * CR/LF collapse to a space so a note can never forge an extra line in a
+ * rendered block (the `boundedToken` discipline, for the same reason).
+ *
+ * The LENGTH bound is deliberately absent, and 05-10 removed it from the
+ * renderer too. Every note this module emits is ENGINE-COMPOSED: the four in
+ * `runVaultAudit` interpolate integers and the engine-derived git range, and
+ * discovery's three interpolate an integer and an already-bounded errno. No
+ * client-authored byte reaches a note. Truncating one at 80 characters
+ * therefore protected nothing and cost the fact — the counted omissions and
+ * the fallback GROUND both sit at the tail of their sentence, so an 80-column
+ * cut turned "N file(s) were not audited" into a sentence that names a cap and
+ * no consequence. A counted omission reported with its count cut off is the
+ * same false-record class this workstream keeps closing.
+ */
+function noteLine(note) {
+    return String(note).split('\r').join(' ').split('\n').join(' ');
+}
+/**
+ * Prepend the counted omissions to whatever body a return path composed.
+ *
+ * THE ONE COMPOSITION POINT, used by every return path of `runVaultAudit`
+ * (05-10, G-1c). Before it, `notes[]` reached neither `block` nor `message` and
+ * the gate runner (`loop run-gates`) reads nothing else — so a truncated diff, a refused
+ * pair count, an unreadable practices directory and a base-branch fallback were
+ * all invisible at the gate. The notes go FIRST because they are the limits
+ * that may explain the findings below them, and because putting them first is
+ * what keeps every path's repair sentence the LAST line: a prepend can never
+ * cut a remedy off, which is the 04-08 / 04-11 discipline.
+ *
+ * When the body is empty (nothing FAILed) the message is the notes block alone
+ * and carries NO repair sentence — nothing is broken to repair, and naming a
+ * remedy for a healthy run would be a false record.
+ *
+ * Every byte of the lead is engine-authored, and each note is already bounded
+ * at its push site. That claim is scoped to the NOTES BLOCK and does not extend
+ * to `message` as a whole — `failItemLines` emits vault-authored ids and
+ * details by a different door (T-5-37).
+ */
+function composeWithNotes(notes, body) {
+    if (notes.length === 0)
+        return body;
+    const lines = [AUDIT_NOTES_LEAD];
+    for (const note of notes)
+        lines.push(`- ${noteLine(note)}`);
+    if (body.length > 0)
+        lines.push(body);
+    return lines.join('\n');
+}
+/**
+ * The gate message: a counted lead, capped items, a counted omission, and the
+ * repair as the closing sentence. `''` when nothing FAILed.
+ *
+ * NOT the whole message any more (05-10): `runVaultAudit` wraps every return
+ * in `composeWithNotes`, so the envelope's `message` is empty only when nothing
+ * failed AND nothing was omitted.
+ */
+function composeAuditMessage(range, rangeSource, entries) {
+    const items = failItemLines(entries);
+    if (items.length === 0)
+        return '';
+    const fails = failingEntries(entries);
+    return [
+        `Vault audit: ${fails.length} practice check(s) FAILED over ${range} (source: ${rangeSource}).`,
+        ...items,
+        AUDIT_REPAIR_SENTENCE,
+    ].join('\n');
+}
+/** Every practice, verdicted without any comparison having happened. */
+function verdictsWithoutComparison(practices, reason, detail) {
+    const entries = [];
+    // The same ONE composition point the evaluator uses (MECH-03, D-10-05). The
+    // degraded arms render through the same report, and a claim that appeared on
+    // one arm and not the other would be the envelope varying by arm — which is
+    // how a consumer learns to read an absence as a fact.
+    const pushEntry = (practice, entry) => {
+        entries.push(withEnforcedBy(entry, practice.enforcedBy));
+    };
+    for (const practice of practices) {
+        const id = boundedToken(practice.id);
+        const hasInvalidCheck = typeof practice.checkInvalid === 'string' && practice.checkInvalid.length > 0;
+        if (hasInvalidCheck) {
+            pushEntry(practice, {
+                id,
+                verdict: verdictForPractice({ hasInvalidCheck: true, hasCheck: false, failed: true, matchedNothing: false }),
+                reason: AUDIT_FAIL_REASON.CHECK_INVALID,
+                detail: boundedToken(practice.checkInvalid),
+                matchedFiles: [],
+                matchedCount: 0,
+            });
+            continue;
+        }
+        const hasCheck = Boolean(practice.check);
+        pushEntry(practice, {
+            id,
+            verdict: verdictForPractice({ hasInvalidCheck: false, hasCheck, failed: hasCheck, matchedNothing: false }),
+            reason: hasCheck ? reason : null,
+            detail: hasCheck ? detail : '',
+            matchedFiles: [],
+            matchedCount: 0,
+        });
+    }
+    return entries;
+}
+/**
+ * Call the discovery seam and reduce its answer to what the audit decides on.
+ *
+ * `vaultUnreadable` is computed from TYPED FIELDS and from the catch, never
+ * from note prose. That is the whole point: before 05-10 the only vault-side
+ * signal was a string in `notes[]`, `notes[]` reached neither `block` nor
+ * `message`, and the gate runner reads nothing else — so
+ * every vault-side miss rendered as a clean pass (G-1a). A `startsWith()` over
+ * the note would have re-created the prose-matching this codebase already
+ * rejected once (`matchBudgetNotes`).
+ */
+function runDiscovery(discover, root) {
+    try {
+        const discovery = discover(root);
+        return {
+            practices: Array.isArray(discovery?.practices) ? discovery.practices : [],
+            notes: [...(discovery?.notes ?? [])],
+            skipped: Array.isArray(discovery?.skipped) ? discovery.skipped : [],
+            vaultUnreadable: discovery?.readFailed === true || discovery?.vaultPresent === false,
+        };
+    }
+    catch {
+        // Discovery already never throws; this is belt-and-braces so an unreadable
+        // vault cannot take the whole gate down with a stack trace. A seam that
+        // threw told this audit nothing, which is the governance equivalent of a
+        // vault that could not be read.
+        return {
+            practices: [],
+            notes: ['the vault could not be read; no practice was evaluated'],
+            skipped: [],
+            vaultUnreadable: true,
+        };
+    }
+}
+/**
+ * One FAIL record per file discovery could not load (05-10, G-1b).
+ *
+ * The verdict is produced through `verdictForPractice`'s FIRST rung, the one
+ * that is decided independently of every cost bound. That rung already encodes
+ * the exact governance fact needed here: this is a statement about the
+ * PRACTICE, not about the comparison, so neither the pair cap nor the budget
+ * can change it. It deliberately does NOT reuse `verdictsWithoutComparison`'s
+ * `failed: hasCheck` trick — a skipped file's check-bearing-ness is unknown,
+ * and it must FAIL unconditionally rather than conditionally.
+ *
+ * Both fields are CLIENT-AUTHORED (the filename the vault chose and the
+ * parser's warning about it) and both are bounded here, at the one place they
+ * enter the envelope. See T-5-37: bounding is length-only, and the trust model
+ * for vault-authored text reaching `message` is the open WR-03 question, not
+ * something this helper settles.
+ */
+function unloadableEntries(skipped) {
+    const entries = [];
+    for (const item of skipped) {
+        const rel = typeof item?.path === 'string' ? item.path : '';
+        const segments = rel.split('\\').join('/').split('/');
+        const leaf = segments[segments.length - 1] || rel;
+        entries.push({
+            id: boundedToken(leaf),
+            verdict: verdictForPractice({ hasInvalidCheck: true, hasCheck: false, failed: true, matchedNothing: false }),
+            reason: AUDIT_FAIL_REASON.PRACTICE_UNLOADABLE,
+            detail: boundedToken(item?.warning),
+            matchedFiles: [],
+            matchedCount: 0,
+        });
+    }
+    return entries;
+}
+/**
+ * The `range` field on a refused operator range (08-04).
+ *
+ * A placeholder rather than the supplied value, and that IS the point: the
+ * value failed validation, so it is never echoed into an envelope whose
+ * `message` an orchestrating agent reads verbatim (T-08-22). The field still
+ * has to say something, and "(refused)" says the true thing.
+ */
+const AUDIT_REFUSED_RANGE = '(refused)';
+/**
+ * The fail-closed envelope for an operator range this module will not compare
+ * over (08-04, D-08-19, threat T-08-22).
+ *
+ * BEFORE DISCOVERY AND BEFORE THE LADDER. Nothing is read — not the vault, not
+ * the manifest, not git — because the input was refused, and work performed on
+ * behalf of a refused input is work an attacker chose. The shape follows the
+ * diff-unreadable arm: `status: 'warn'`, `block: true`, zero files, a repair
+ * sentence closing the message.
+ *
+ * `block: true` is EXPLICIT, not `blocksOnVerdicts([])` — which is false. This
+ * is the same trap 05-10 measured as G-1a: emptiness here means nothing was
+ * verified, and nothing-verified must never read as passed.
+ */
+function refusedOperatorRangeResult() {
+    // The coverage pair on this arm, from the SAME derivation every other arm
+    // uses. No practice was compared, so the counts are zero by construction and
+    // `evaluatedNothing` is true — which is the honest reading and the loud one.
+    const counts = countVerdicts([]);
+    const notes = [
+        `${AUDIT_RANGE_OUTCOME.RANGE_UNRESOLVABLE}: the supplied range is not a well-formed git range, so it was ` +
+            `refused before any comparison and no practice was compared against anything`,
+    ];
+    const lead = 'Vault audit: the range supplied to this audit is not a well-formed `<a>..<b>` or `<a>...<b>` git range ' +
+        'and was refused, so no practice was compared and nothing was verified. The supplied value is not ' +
+        'reproduced here because it failed validation.';
+    return {
+        status: 'warn',
+        block: true,
+        message: composeWithNotes(notes, [lead, AUDIT_OPERATOR_RANGE_REPAIR_SENTENCE].join('\n')),
+        range: AUDIT_REFUSED_RANGE,
+        rangeSource: AUDIT_RANGE_SOURCE.OPERATOR_RANGE,
+        rangeOutcome: AUDIT_RANGE_OUTCOME.RANGE_UNRESOLVABLE,
+        mechanicallyChecked: counts.mechanicallyChecked,
+        applicablePractices: counts.applicablePractices,
+        evaluatedNothing: counts.evaluatedNothing,
+        // Nothing is read for a refused input, the ledgers included.
+        recordedCensus: null,
+        practices: [],
+        pairsEvaluated: 0,
+        pairCap: MATCH_PAIR_CAP,
+        budgetMs: MATCH_BUDGET_MS,
+        filesConsidered: 0,
+        filesCapped: false,
+        notes,
+    };
+}
+/**
+ * Run the whole audit: resolve the range, read the diff, discover the vault's
+ * practices, evaluate them, and compose the envelope both 05-06 surfaces
+ * serialize.
+ *
+ * THE UNREADABLE-DIFF ARM FAILS CLOSED, and that is a DELIBERATE divergence
+ * from `cmdShipPractices`, which warns and passes on the same condition. The
+ * difference is what the verdict feeds: that handler's arm is advisory, and
+ * this one's is a BLOCKING gate (D-05-02). A comparison that never ran, read as
+ * "passed", is precisely the silence this workstream exists to end — so do not
+ * harmonise the two arms later without reversing D-05-02 first.
+ *
+ * THE UNREADABLE-VAULT ARM FAILS CLOSED FOR THE SAME REASON (05-10, G-1a), and
+ * diverges from the sibling matcher channels' tolerate-and-render posture on
+ * exactly the same grounds: those channels advise, this envelope feeds the
+ * blocking gate.
+ */
+function runVaultAudit(opts) {
+    const exec = typeof opts.exec === 'function' ? opts.exec : shell_command_projection_cjs_1.execGit;
+    // The default reads the cache through `resolveVaultCacheDir` — the same
+    // worktree-aware answer the practice trace pins against — so the audit and
+    // the ledger it is read beside describe one vault.
+    const discover = typeof opts.discover === 'function'
+        ? opts.discover
+        : (root) => discoverPracticeFiles(root, vaultMod.resolveVaultCacheDir(root).dir);
+    const readFile = typeof opts.readFile === 'function' ? opts.readFile : createBoundedFileReader(opts.root);
+    // D-08-19. An operator range REPLACES the ladder rather than joining it: the
+    // operator is answering the question the ladder failed to answer, so
+    // consulting it first would be asking a question whose answer is being
+    // overridden. Refusal comes BEFORE the resolver, and long before
+    // `diffFilesFor` builds an argv (T-08-22).
+    const operatorRange = typeof opts.range === 'string' ? opts.range : null;
+    if (operatorRange !== null && !isValidOperatorRange(operatorRange)) {
+        return refusedOperatorRangeResult();
+    }
+    const resolved = operatorRange !== null
+        ? { range: operatorRange, rangeSource: AUDIT_RANGE_SOURCE.OPERATOR_RANGE }
+        : resolvePhaseRange({ root: opts.root, phaseDir: opts.phaseDir, exec });
+    const { range, rangeSource, fallbackReason, baseBranchRefused, notes: rangeNotes } = resolved;
+    const discovery = runDiscovery(discover, opts.root);
+    const practices = discovery.practices;
+    // Read once, from the ledgers, and carried on every arm below.
+    const recordedCensus = (() => {
+        try {
+            return readRecordedCensus(opts.phaseDir);
+        }
+        catch {
+            return null;
+        }
+    })();
+    const notes = [...discovery.notes];
+    if (operatorRange !== null) {
+        // THE DISCLOSURE (D-08-19, threat T-08-25 — accepted, on this sentence).
+        //
+        // An operator range is treated as phase-scoped by the WR-04 predicate: the
+        // operator named the range, so an empty diff over it is a fact about that
+        // range and is STATED rather than blocked, which is D-05-02's reasoning
+        // applied to an assertion instead of to a manifest. But `phase_scoped`
+        // earned that way is the OPERATOR'S claim, not the ladder's, and
+        // HGATE-04's own hazard is an audit that established nothing about the
+        // phase reading as if it had. So the difference travels in two places that
+        // cannot be lost independently: this note, and `rangeSource:
+        // operator-range` on the envelope.
+        notes.push(`range supplied by the operator (--range); the phase-start ladder was not consulted, so this range is ` +
+            `scoped by the operator's assertion, not by the phase manifest — a ${AUDIT_RANGE_OUTCOME.PHASE_SCOPED} ` +
+            `outcome over this range records that assertion and is not a phase-derived scope; ` +
+            `rangeSource: ${AUDIT_RANGE_SOURCE.OPERATOR_RANGE} is what tells the two apart`);
+    }
+    if (baseBranchRefused) {
+        // FIRST, ahead of the fallback ground: an operator reading this list needs
+        // to know the range is not the one they configured before they read
+        // anything computed over it. The sentence is the resolver's own export,
+        // stated verbatim by all three consumers, so this gate and the review
+        // cannot describe the same refusal differently (W16).
+        notes.push(`${baseBranchRefused} This audit is computed over "${range}" instead.`);
+    }
+    if (fallbackReason) {
+        // The phase-scoped range D-05-08 exists to deliver did not resolve, and
+        // the ground is a repairable fact rather than an unavoidable one. Stating
+        // it is what makes the range record auditable on a checkout that has no
+        // manifest to read — a fresh clone or CI runner where `.planning/` is
+        // gitignored, since only the executing checkout writes one.
+        notes.push(`phase range fell back to the base-branch form (${range}) because the phase-scoped range could not be ` +
+            `resolved: ${fallbackReason}`);
+    }
+    // The ladder's own notes: a trace-digest range's under-scope
+    // disclosure, or the statement that the digest rung was tried and found
+    // nothing verifiable. Either is a limit on what the range establishes.
+    for (const note of rangeNotes ?? [])
+        notes.push(note);
+    // Computed ONCE and appended on every arm below. Both arms consume the same
+    // discovery, so a record that survived only one of them would be a record an
+    // operator loses exactly when things are worst (05-10, G-1b).
+    const unloadable = unloadableEntries(discovery.skipped);
+    if (discovery.vaultUnreadable) {
+        const entries = [
+            ...verdictsWithoutComparison(practices, AUDIT_FAIL_REASON.VAULT_UNREADABLE, `the client vault could not be read, so this practice was never compared against ${range}`),
+            ...unloadable,
+        ];
+        const vaultArmCounts = countVerdicts(entries);
+        const lead = `Vault audit: the client vault at .planning/vault was absent or could not be read, ` +
+            `so no practice was compared against ${range} (source: ${rangeSource}) and nothing was verified. ` +
+            `${failingEntries(entries).length} practice check(s) are recorded as FAILED.`;
+        return {
+            status: 'warn',
+            // EXPLICITLY true, not `blocksOnVerdicts(entries)`. On this arm `entries`
+            // is usually EMPTY — the vault yielded nothing to verdict — and
+            // `blocksOnVerdicts([])` is false, which is precisely how G-1a shipped: a
+            // gate that was handed no vault reported a clean pass. Emptiness HERE
+            // means nothing was verified, and nothing-verified must never read as
+            // passed. The diff arm's header comment argues this for the diff side and
+            // the reasoning applies verbatim.
+            block: true,
+            message: composeWithNotes(notes, [lead, ...failItemLines(entries), AUDIT_VAULT_REPAIR_SENTENCE].join('\n')),
+            range,
+            rangeSource,
+            // Nothing was compared on this arm, so the count is 0 by construction and
+            // the outcome is whatever the RANGE alone establishes (08-04).
+            rangeOutcome: classifyRangeOutcome({ phaseScoped: isPhaseScopedSource(rangeSource), filesConsidered: 0 }),
+            // The SAME derivation as every other arm (D-10-18) — `countVerdicts` and
+            // nothing else, so no arm can answer the coverage question differently.
+            mechanicallyChecked: vaultArmCounts.mechanicallyChecked,
+            applicablePractices: vaultArmCounts.applicablePractices,
+            evaluatedNothing: vaultArmCounts.evaluatedNothing,
+            recordedCensus,
+            practices: entries,
+            pairsEvaluated: 0,
+            pairCap: MATCH_PAIR_CAP,
+            budgetMs: MATCH_BUDGET_MS,
+            filesConsidered: 0,
+            filesCapped: false,
+            notes,
+        };
+    }
+    const diff = diffFilesFor(opts.root, range, exec);
+    if (!diff.ok) {
+        const entries = [
+            ...verdictsWithoutComparison(practices, AUDIT_FAIL_REASON.DIFF_UNREADABLE, `the phase diff over ${range} could not be read, so this practice was never compared against it`),
+            ...unloadable,
+        ];
+        const diffArmCounts = countVerdicts(entries);
+        const lead = `Vault audit: the phase diff over ${range} (source: ${rangeSource}) could not be read, ` +
+            `so no practice was compared against it. ${failingEntries(entries).length} ` +
+            `practice check(s) are recorded as FAILED because nothing was verified.`;
+        return {
+            status: 'warn',
+            block: blocksOnVerdicts(entries),
+            message: composeWithNotes(notes, [lead, ...failItemLines(entries), AUDIT_DIFF_REPAIR_SENTENCE].join('\n')),
+            range,
+            rangeSource,
+            // The diff could not be read at all, so nothing was considered (08-04).
+            rangeOutcome: classifyRangeOutcome({ phaseScoped: isPhaseScopedSource(rangeSource), filesConsidered: 0 }),
+            // The SAME derivation as every other arm (D-10-18).
+            mechanicallyChecked: diffArmCounts.mechanicallyChecked,
+            applicablePractices: diffArmCounts.applicablePractices,
+            evaluatedNothing: diffArmCounts.evaluatedNothing,
+            recordedCensus,
+            practices: entries,
+            pairsEvaluated: 0,
+            pairCap: MATCH_PAIR_CAP,
+            budgetMs: MATCH_BUDGET_MS,
+            filesConsidered: 0,
+            filesCapped: false,
+            notes,
+        };
+    }
+    if (diff.capped) {
+        notes.push(`changed-file list truncated: ${diff.total} file(s) in the diff, capped at ${AUDIT_DIFF_FILE_CAP} — ` +
+            `${diff.total - AUDIT_DIFF_FILE_CAP} file(s) were not audited`);
+    }
+    // WR-04: a zero-file comparison means two different things depending on
+    // where the range came from, and only one of them is a pass.
+    //
+    // D-05-02 (05-10) is PRESERVED for a range resolved from the phase: a
+    // legitimately empty phase diff is common — docs-only phases, re-runs, a
+    // re-audit after a merge — so blocking on it would teach operators to ignore
+    // the gate, which costs more than the silence does. It is stated, not blocked.
+    //
+    // On the FALLBACK range that reasoning does not hold, because nothing
+    // established that the range corresponds to this phase. The fallback is the
+    // FOURTH rung of `resolvePhaseRange`'s ladder: it is reached
+    // only when the phase has no usable manifest entry (no verifiable startCommit
+    // or commit) AND no verifiable SUMMARY trace digest. With
+    // `git.branching_strategy: none` — this project's own setting — `main...HEAD`
+    // is empty whenever HEAD sits at or behind the base. The measured consequence,
+    // before the ladder existed, was a live `forbid` practice, a file violating
+    // it, every check NOT_MATCHED and `block: false`: a gate declared
+    // `blocking: true` returning precisely what a clean pass returns, over a range
+    // nobody established was the phase's. An empty diff there is a fact about
+    // nothing, and a gate with no verdict to report must not report the passing
+    // one. The three phase-derived sources (`phase-start-commit`,
+    // `phase-first-commit`, `trace-digest`) sit outside this predicate by
+    // construction, which is the narrowing UAT-6-F1 required.
+    //
+    // 08-04 (D-08-17) gave this predicate a NAME and did not change its truth
+    // table (D-08-18). `unverifiableEmptyRange` is now read off
+    // `classifyRangeOutcome`, which computes the same comparison — zero files on
+    // a range no phase-derived rung produced — and returns the machine-readable
+    // `range_unresolvable` instead of only a boolean. The block expression below
+    // is byte-for-byte the one `d00e0f0` shipped: a resolved range with zero
+    // files is still stated and still not blocked, and the fallback range with
+    // zero files still blocks.
+    const rangeOutcome = classifyRangeOutcome({
+        phaseScoped: isPhaseScopedSource(rangeSource),
+        filesConsidered: diff.files.length,
+    });
+    const unverifiableEmptyRange = rangeOutcome === AUDIT_RANGE_OUTCOME.RANGE_UNRESOLVABLE;
+    if (diff.files.length === 0) {
+        notes.push(`the diff over ${range} (source: ${rangeSource}) contained no auditable file, so no practice was ` +
+            `compared against any file`);
+    }
+    if (unverifiableEmptyRange) {
+        // PREFIXED with the outcome code (08-04, D-08-17). `message` is composed
+        // from `notes`, and the gate runner (`loop run-gates`) prints `message` verbatim — so
+        // putting the code at the head of this sentence is what makes
+        // `range_unresolvable` greppable in BOTH of the two fields the enforcer
+        // reads, not only in the envelope field a workflow would have to parse.
+        notes.push(`${AUDIT_RANGE_OUTCOME.RANGE_UNRESOLVABLE}: nothing was verified — the range was not resolved from the ` +
+            `phase, so an empty diff over it establishes nothing about this phase and no passing verdict can be ` +
+            `drawn from it`);
+    }
+    const evaluated = evaluatePractices({ practices, files: diff.files, readFile, now: opts.now });
+    if (evaluated.pairCapExceeded) {
+        notes.push(`practice evaluation refused: this vault and change set produce more than the ${MATCH_PAIR_CAP}-pair cap, ` +
+            `so no check was compared against the diff`);
+    }
+    if (evaluated.budgetExhausted) {
+        notes.push(`practice evaluation was cut short: the ${MATCH_BUDGET_MS}ms budget was exhausted, so the practices ` +
+            `reported after that point were never compared against the diff`);
+    }
+    // The denominator, assembled: every practice the evaluator saw PLUS every
+    // file discovery could not load. A rejection surfaces as a FAIL, never as an
+    // absence (05-10, G-1b).
+    const audited = [...evaluated.practices, ...unloadable];
+    // ONE `countVerdicts(audited)` call, feeding both the status and the
+    // envelope. Two calls would be two places the report can come to disagree
+    // with the gate that blocks on it.
+    const counts = countVerdicts(audited);
+    if (counts.evaluatedNothing) {
+        // PREFIXED with the outcome token, following the `range_unresolvable`
+        // precedent above: `message` is composed from `notes` and
+        // the gate runner (`loop run-gates`) prints `message` verbatim, so putting the token at
+        // the head of this sentence is what makes the fact greppable in BOTH of the
+        // fields the enforcer reads, not only in an envelope field a workflow would
+        // have to parse. Composed entirely from engine strings and integers — no
+        // client-authored byte reaches it, which is the property `noteLine` relies
+        // on.
+        notes.push(`${AUDIT_COVERAGE_OUTCOME.EVALUATED_NOTHING}: ${counts.mechanicallyChecked} of ` +
+            `${counts.applicablePractices} applicable practice(s) were mechanically checked over ${range} ` +
+            `(source: ${rangeSource}) — no check block was compared against any file, so this run verified ` +
+            `nothing mechanically and no passing claim can be drawn from it. ${renderRecordedCensusLine(recordedCensus)}`);
+    }
+    return {
+        // D-10-11: a run in which nothing was mechanically checked is `warn`, never
+        // the literal `ok` SC2 forbids. `warn` is not invented for this — it is
+        // already the shipped "we could not verify" arm that `unverifiableEmptyRange`
+        // uses, and this is the same species of fact. The union stays two-valued on
+        // purpose: a third value would break every consumer coding against two, for
+        // no gain.
+        status: unverifiableEmptyRange || counts.evaluatedNothing ? 'warn' : 'ok',
+        // WR-04: `blocksOnVerdicts` speaks for the practices that WERE compared.
+        // On an unverifiable empty range none were, so there is no verdict for it
+        // to speak from and the absence itself is the blocking fact.
+        //
+        // D-10-02: `evaluatedNothing` is DELIBERATELY absent from this expression,
+        // and the line is byte-identical to the one 08-04 shipped. Blocking on "we
+        // checked nothing" cannot distinguish an unchecked vault from a failing
+        // one, and on the day a client enables the capability against a vault that
+        // carries zero check blocks every phase would halt at `verify:post` until a
+        // different repository was edited. The fact is loud on three channels
+        // instead — `status: 'warn'`, a prefixed note, and the composed message —
+        // so no surface says `ok` about a run that checked nothing.
+        block: blocksOnVerdicts(audited) || unverifiableEmptyRange,
+        message: composeWithNotes(notes, composeAuditMessage(range, rangeSource, audited)),
+        range,
+        rangeSource,
+        rangeOutcome,
+        // From the SAME `counts` the status above was drawn from (D-10-18).
+        mechanicallyChecked: counts.mechanicallyChecked,
+        applicablePractices: counts.applicablePractices,
+        evaluatedNothing: counts.evaluatedNothing,
+        recordedCensus,
+        practices: audited,
+        pairsEvaluated: evaluated.pairsEvaluated,
+        pairCap: evaluated.pairCap,
+        budgetMs: evaluated.budgetMs,
+        filesConsidered: diff.files.length,
+        filesCapped: diff.capped,
+        notes,
+    };
+}
+// ─── The human rendering ──────────────────────────────────────────────────────
+const AUDIT_SECTIONS = [
+    { verdict: AUDIT_VERDICT.FAIL, gloss: 'a check ran and was not satisfied, or could not be run at all' },
+    { verdict: AUDIT_VERDICT.PASS, gloss: 'a check ran and was satisfied' },
+    {
+        verdict: AUDIT_VERDICT.NOT_MATCHED,
+        gloss: 'a check was live and its globs matched nothing in this diff',
+    },
+    {
+        verdict: AUDIT_VERDICT.NO_CHECK,
+        gloss: 'this practice carries no check: block — a gap in the vault’s own coverage',
+    },
+];
+/**
+ * The human rendering: four labelled sections, one line per practice, every
+ * line carrying its own verdict token.
+ *
+ * The verdict token is repeated on each LINE and not left to the section
+ * heading alone, deliberately. SC1 asks for `NO_CHECK` and `NOT_MATCHED` to be
+ * structurally distinct from `PASS` at every rendered channel; a distinction
+ * that lives only in a heading disappears the moment a line is quoted, grepped
+ * or copied out of its section.
+ */
+function renderAuditReport(result) {
+    const counts = countVerdicts(result.practices);
+    const countFor = {
+        [AUDIT_VERDICT.PASS]: counts.pass,
+        [AUDIT_VERDICT.FAIL]: counts.fail,
+        [AUDIT_VERDICT.NO_CHECK]: counts.noCheck,
+        [AUDIT_VERDICT.NOT_MATCHED]: counts.notMatched,
+    };
+    const lines = [
+        // 08-04: the OUTCOME travels beside the source on the operator's own line,
+        // so the rendered report and the gate envelope state the same fact. An
+        // operator reading `outcome: range_unresolvable` learns in one line what
+        // previously took reading a note at the bottom of the render.
+        `Vault audit — range ${result.range} (source: ${result.rangeSource}, outcome: ${result.rangeOutcome})`,
+        `${result.practices.length} practice(s) audited over ${result.filesConsidered} changed file(s).`,
+        // D-10-03: how much of that was actually CHECKED, immediately below how
+        // much was audited. The two sentences answer the same question and an
+        // operator reads them together; counts only, never a percentage or a score.
+        renderMechanicalCoverageLine(counts),
+        renderRecordedCensusLine(result.recordedCensus ?? null),
+    ];
+    for (const section of AUDIT_SECTIONS) {
+        lines.push('');
+        lines.push(`${section.verdict} (${countFor[section.verdict]}) — ${section.gloss}`);
+        for (const entry of result.practices) {
+            if (entry.verdict !== section.verdict)
+                continue;
+            const reason = entry.reason ? ` ${entry.reason}` : '';
+            const detail = entry.detail ? ` — ${entry.detail}` : '';
+            lines.push(`- ${entry.id} [${entry.verdict}]${reason}${detail}`);
+        }
+    }
+    for (const note of result.notes)
+        lines.push(`\nnote: ${noteLine(note)}`);
+    return lines.join('\n');
+}
+module.exports = {
+    // The frozen vocabulary — the contract 05-06's two surfaces serialize.
+    AUDIT_VERDICT,
+    AUDIT_FAIL_REASON,
+    AUDIT_RANGE_SOURCE,
+    AUDIT_FALLBACK_REASON,
+    // 08-04 (D-08-17): WHAT the compared range established, and the ONE predicate
+    // that decides it. Exported so the review tier (08-05) and the two thin
+    // surfaces (08-06) HARVEST this cell rather than restating the comparison —
+    // a second predicate for one claim is a second claim.
+    AUDIT_RANGE_OUTCOME,
+    classifyRangeOutcome,
+    // 10-01 (MECH-02, D-10-01/D-10-03): the run-level coverage outcome and the
+    // ONE renderer for the coverage line. Exported on the same harvest rule as
+    // the vocabularies above — a test that copies the token, and a second surface
+    // that composes its own line, are each a second claim that drifts from this
+    // one the day either is reworded.
+    AUDIT_COVERAGE_OUTCOME,
+    renderMechanicalCoverageLine,
+    // The recorded census's one sentence (read through the ledger API).
+    renderRecordedCensusLine,
+    // 10-06 (MECH-03, D-10-05): the ONE lead this module composes for an
+    // `enforced-by:` claim. Exported so the tests — and any surface that must
+    // prove it never says "verified by" — assert against the SHIPPED string.
+    AUDIT_ENFORCED_BY_LEAD,
+    // 08-04 (D-08-19): the operator-range channel's shape contract. Exported so
+    // the CLI surface (08-06) validates with THIS predicate — a security check
+    // that exists twice is a security check that can be relaxed in one place.
+    AUDIT_OPERATOR_RANGE_SHAPE,
+    AUDIT_OPERATOR_RANGE_MAX_LENGTH,
+    isValidOperatorRange,
+    AUDIT_FILE_READ_MAX,
+    AUDIT_MESSAGE_PROBLEM_CAP,
+    AUDIT_DIFF_FILE_CAP,
+    GIT_EMPTY_TREE,
+    // The three repair sentences. Exported so a test HARVESTS the wording it
+    // asserts on rather than copying it — a copied remedy sentence rots the day
+    // the shipped one is reworded, and the pin that guards it stops guarding.
+    AUDIT_REPAIR_SENTENCE,
+    AUDIT_DIFF_REPAIR_SENTENCE,
+    AUDIT_VAULT_REPAIR_SENTENCE,
+    // 08-04: the refused-operator-range arm's repair, exported on the same
+    // harvest rule as the three above.
+    AUDIT_OPERATOR_RANGE_REPAIR_SENTENCE,
+    // The pure evaluator. Exported as the ONE engine; 05-06's surfaces choose a
+    // serializer and compute nothing, so they cannot disagree.
+    evaluatePractices,
+    // The diff scoping, exported separately from the envelope so a surface that
+    // only needs to STATE the range never has to run an audit to learn it.
+    resolvePhaseRange,
+    createBoundedFileReader,
+    // The whole audit, and its human rendering.
+    runVaultAudit,
+    renderAuditReport,
+    // The four registered predicates. Exported so a channel-distinctness test can
+    // ask each one directly rather than re-deriving the comparison it makes.
+    isPassVerdict,
+    isFailVerdict,
+    isNoCheckVerdict,
+    isNotMatchedVerdict,
+    SHAPE_PREDICATE_NAMES,
+    // The verdict counters, exported for the renderer's own headings and for a
+    // consumer that needs a summary without walking the list itself.
+    countVerdicts,
+    blocksOnVerdicts,
+};