@pareto4/pp-core 1.12.0 → 1.13.0

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

@@ -0,0 +1,2831 @@
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+/**
+ * src/vault-trace.cts — the vault practice-trace envelope: the frozen
+ * contract's constants, the statement builder, the frontmatter serializer,
+ * the `## Practices Applied` renderer, the bespoke block parser, and the
+ * pure validators a trace gate composes.
+ *
+ * Responsibility (Phase 03-01 — task 1, the frozen half):
+ *   The five constants below ARE the contract. `docs/vault-trace-format.md`
+ *   states the same values in prose, and `tests/vault-trace.test.cjs` asserts
+ *   the document and this module agree from both ends, so the two cannot
+ *   drift. They are module constants and are NEVER re-derived at runtime from
+ *   configuration or from the vault: a version marker a client repository
+ *   could move is not a version marker.
+ *
+ * Reuses (no new runtime dependency):
+ *   - `./vault.cjs` (`computeVaultVerdict`, `readManifest`) — the pin's state
+ *     is the vault verdict's, and its values are READ through the existing
+ *     manifest reader, never re-parsed here. A second reader would let the
+ *     trace disagree with the load gate about one cache.
+ *   - `./vault-practices.cjs` (`matchPractices`, `boundedToken`) — the practice
+ *     denominator is the matcher's return set, and the id bounding is the
+ *     shared helper.
+ *
+ * DELIBERATELY NOT REUSED — and this omission is load-bearing, not an oversight:
+ *   This module does NOT use the shared frontmatter extractor/serializer pair
+ *   in `./frontmatter.cjs`, even though that is the only sanctioned
+ *   frontmatter parser in this repo and `src/vault-practices.cts` reuses it by
+ *   name. (The mechanical proof is in `tests/vault-trace.test.cjs`: this module
+ *   must not IMPORT `./frontmatter.cjs`, and must not CALL any of its four
+ *   entry points — `extractFrontmatter`, its `parseFrontmatter` alias,
+ *   `reconstructFrontmatter`, or `spliceFrontmatter`. Naming them here is
+ *   deliberate and safe: the guard is keyed on import and call shapes, not on
+ *   the bare strings. It used to be keyed on the strings, which forbade the
+ *   very citation the explanation needs — so this paragraph claimed the names
+ *   appeared nowhere in the file while `spliceFrontmatter` was quoted twenty
+ *   lines below, and the guard covered only two of the four names. 03-SECURITY
+ *   OF-1 / T-03-07.)
+ *
+ *   The reason for the omission: the trace's practice list is a LIST OF MAPS,
+ *   and neither half of that shared pair can represent that shape.
+ *
+ *     - The shared EXTRACTOR's key regex (`^(\s*)([a-zA-Z0-9_-]+):\s*(.*)`)
+ *       cannot match a line beginning with `- ` — the space after the dash
+ *       fails the character class — so its list branch always wins and pushes
+ *       `line.trim().slice(2)` as a RAW STRING. A practices list reads back as
+ *       the string array `["id: x", "status: applied"]`: the structure is
+ *       gone, silently.
+ *     - The shared SERIALIZER is worse, and says so itself. Quoting the
+ *       comment inside `spliceFrontmatter` verbatim: it is "a deliberately
+ *       lossy serializer — it cannot faithfully re-emit nested object-list
+ *       items (e.g. must_haves.artifacts / must_haves.prohibitions, whose
+ *       items are `{ path, provides }` / `{ statement, status, … }` maps)".
+ *
+ *   So the trace gets its own emitter (`serializeTraceBlock`) and its own
+ *   parser (`parseVaultTraceBlock`), the latter modelled on the in-repo
+ *   precedent `parseMustHavesBlock` (`src/frontmatter.cts`) — the technique is
+ *   copied, not the function, because that function is anchored on its own
+ *   literal `must_haves:` key and widening it would dissolve its whole shape.
+ *
+ *   If you are here to "fix" this module by wiring it to the shared parser:
+ *   don't. It will flatten every trace it touches, and the flattening is
+ *   silent — an emptied trace and a genuine coverage failure produce the same
+ *   verdict from different causes.
+ */
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const vaultMod = require("./vault.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const practicesMod = require("./vault-practices.cjs");
+// The count cap is IMPORTED, never re-declared. `derivePracticeUniverse` below
+// must bound the recorded universe by the same number `discoverPracticeFiles`
+// bounds its return set by; a second literal here would be a second cap that
+// drifts, which is the shape of the defect this whole file's universe
+// derivation was found to carry (04-REVIEW WR-05). This widens an EXISTING
+// destructure over an EXISTING import edge — no new edge is created, and the
+// direction (trace leaf -> practices leaf) is the one D-12 settled on.
+// `defangFenceMarkers` joins the destructure in 10-08 on the reason its own
+// export comment gives: "Authoring a second fence or preamble in the audit
+// module is how CR-02's class returns." The same holds here — the analyzer
+// provenance clause is a client-authored byte written into a committed record
+// an agent reads, and it is defanged with the SHIPPED marker pair, never a
+// second one spelled locally.
+const { boundedToken, PRACTICE_COUNT_CAP, defangFenceMarkers } = practicesMod;
+/**
+ * Collapse every run of C0 control characters and DEL to a single space.
+ *
+ * `boundedToken` collapses CR/LF only — it is the LENGTH bound plus a
+ * line-forging guard — so a TAB, a NUL or a DEL in a client-authored value
+ * still reaches a message an enforcer prints verbatim and a reviewer agent
+ * loads unfenced (03-REVIEW CR-03, T-03-31/T-03-36). This is the character
+ * half, applied wherever an untrusted value crosses into generated output.
+ */
+function collapseControlChars(value) {
+    return value.replace(/[\u0000-\u001F\u007F]+/g, ' ');
+}
+// ─── The frozen contract (Phase 03-01, TRACE-05) ──────────────────────────────
+// Changing any value below is a breaking change to a schema that other phases
+// develop against in parallel. See docs/vault-trace-format.md § Versioning
+// discipline: the URI major and TRACE_SCHEMA_VERSION move together, or not at
+// all.
+/**
+ * The in-toto Statement type. The envelope is in-toto SHAPED — it is never fed
+ * to an in-toto verifier and carries no library dependency.
+ */
+const TRACE_STATEMENT_TYPE = 'https://in-toto.io/Statement/v1';
+/**
+ * The custom predicate type, and the MAJOR version carrier. pp-core's own
+ * namespace: every trace this engine WRITES carries exactly this URI. The URI
+ * is an identifier, not an endpoint — nothing fetches it.
+ *
+ * READERS accept this URI plus any URI the project's org profile lists under
+ * `vault.trace.accepted_predicates` (`acceptedPredicateTypes`), so a project
+ * that switches engine mid-engagement keeps reading the traces its earlier
+ * engine wrote. An accepted URI must carry the same major as this one
+ * (`/v<TRACE_SCHEMA_VERSION>`): the URI major and the schema version move
+ * together, or not at all.
+ */
+const TRACE_PREDICATE_TYPE = 'https://pareto.ooo/attestation/vault-practice-trace/v1';
+/**
+ * The schema version, mirroring the `PRACTICE_SCHEMA_VERSION` discipline in
+ * `src/vault-practices.cts`. An integer, not a string. A consumer reading a
+ * value above the highest it knows warns loudly and does not silently pass.
+ */
+const TRACE_SCHEMA_VERSION = 1;
+/**
+ * The three-state disposition vocabulary. These exact strings ALREADY ship in
+ * `agents/pp-executor.md` §<summary_creation> and are read by the code
+ * reviewer's cross-plan reconciliation contract — they are copied here, never
+ * re-coined. Frozen so a caller cannot mutate the shared array in place.
+ */
+const TRACE_STATUS_VALUES = Object.freeze(['applied', 'not-applicable', 'deviated']);
+/**
+ * The permitted charset for a practice `id` — the ONLY client-authored token
+ * that reaches the ledger. An alphanumeric first character, then letters,
+ * digits, dots, underscores and hyphens, to a maximum of 64 characters.
+ *
+ * A practice id derives from a client-authored FILENAME, and POSIX permits
+ * nearly anything in a filename including an embedded newline (a fact
+ * `boundedToken`'s own docstring cites). `boundedToken` bounds length and
+ * collapses newlines; it does NOT restrict the charset. This pattern is the
+ * charset half, and it exists so `docs/vault-trace-format.md` can state
+ * "the only client-authored token is bounded, quoted and charset-validated"
+ * as a property rather than a hope.
+ *
+ * No `g` flag: a global RegExp carries `lastIndex` state across `.test()`
+ * calls and would return alternating results for the same input.
+ */
+const TRACE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const NULL_PIN = Object.freeze({
+    ref: null,
+    resolvedSha: null,
+    tier: null,
+    source: null,
+    repo: null,
+});
+/**
+ * The degraded reason sentences, one per cause. Contract surface: the format
+ * page lists them, and a reader six months later needs to know WHICH failure
+ * a degraded trace records. Every interpolated value is bounded.
+ */
+const PIN_REASON = Object.freeze({
+    noCache: 'no vault cache present at .planning/vault',
+    manifestMissing: 'vault manifest missing at .planning/vault/.manifest.json',
+    manifestMalformed: 'vault manifest unreadable or malformed at .planning/vault/.manifest.json',
+    miss: 'vault manifest records a miss; no vault content was reached',
+    empty: 'vault cache holds no files; no vault content was reached',
+    noBindings: 'no client vault is bound (.platform-bindings.json needs client.vaultRepo and client.vaultRef); '
+        + 'only a client-tier load at the configured ref records loaded',
+    configUnreadable: 'the project config cannot be read, so the vault state is unknown',
+    disabled: 'vault.enabled is not true',
+});
+/**
+ * Read the pin. The STATE is the vault verdict's — `computeVaultVerdict` in
+ * src/vault.cts is the one owner of "is the client vault loaded" (pack 6), so
+ * the trace and the load gate cannot disagree about one cache: `loaded`
+ * exactly when the verdict is `loaded` (the client tier, at the configured
+ * repo and ref, fresh). The pin VALUES (ref, sha, tier, source, repo) are
+ * read from the same cache's manifest through `readManifest`, which already
+ * returns the display-safe repo; this module parses `.manifest.json` nowhere.
+ *
+ * A degraded run is a FIRST-CLASS path, not an error branch — the caller
+ * always gets a pin object, and a statement is always produced. A stale,
+ * fallback-tier or drifted cache keeps its pin: the cached copy really did
+ * come from that SHA, and only the reason says why it does not prove the
+ * configured standards were applied.
+ *
+ * WORKTREES. `vaultDirPath` is the directory `buildTraceStatement` resolved
+ * once through `vaultMod.resolveVaultCacheDir`: the local `.planning/vault`,
+ * or, for the root of a linked git worktree with no local manifest, the
+ * owning main checkout's cache. The verdict is judged against that same
+ * directory.
+ */
+function resolvePin(cwd, vaultDirPath = node_path_1.default.join(cwd, '.planning', 'vault')) {
+    const v = vaultMod.computeVaultVerdict(cwd, { vaultDir: vaultDirPath });
+    const manifest = vaultMod.readManifest(vaultDirPath);
+    const str = (x) => (typeof x === 'string' && x !== '' ? x : null);
+    const pin = manifest
+        ? {
+            ref: str(manifest.ref),
+            resolvedSha: str(manifest.resolvedSha),
+            tier: str(manifest.tier),
+            source: str(manifest.source),
+            repo: vaultMod.redactCloneTarget(str(manifest.repo)),
+        }
+        : { ...NULL_PIN };
+    if (v.verdict === 'loaded') {
+        return {
+            state: 'loaded',
+            reason: null,
+            ...pin,
+            manifestFiles: manifest && Array.isArray(manifest.files)
+                ? manifest.files.filter((f) => typeof f === 'string')
+                : [],
+        };
+    }
+    let reason;
+    switch (v.reason) {
+        case 'never_fetched':
+            if (!node_fs_1.default.existsSync(vaultDirPath))
+                reason = PIN_REASON.noCache;
+            else if (!node_fs_1.default.existsSync(node_path_1.default.join(vaultDirPath, '.manifest.json')))
+                reason = PIN_REASON.manifestMissing;
+            else
+                reason = PIN_REASON.manifestMalformed;
+            break;
+        case 'fetch_miss':
+            reason = vaultMod.manifestRecordsMiss(manifest) ? PIN_REASON.miss : PIN_REASON.empty;
+            break;
+        case 'fallback_tier':
+            reason =
+                `vault loaded on the ${boundedToken(pin.tier ?? 'unknown')} tier `
+                    + `(${boundedToken(pin.repo ?? 'no repo recorded')}); no client standards were applied `
+                    + '— only a client-tier load records loaded';
+            break;
+        case 'ref_drift':
+            // Both refs come FIRST so they survive an 80-character head, and both go
+            // through `boundedToken`: a ref is project-authored text reaching an
+            // agent's context unfenced.
+            reason = pin.ref !== v.configuredRef
+                ? `vault cache was fetched from ref ${boundedToken(pin.ref ?? 'unknown')} `
+                    + `but client.vaultRef is now ${boundedToken(v.configuredRef ?? 'unknown')}; `
+                    + 'the cached standards are not the configured ones — only a client-tier load '
+                    + 'at the configured ref records loaded'
+                : `vault cache was fetched from ${boundedToken(pin.repo ?? 'unknown')} `
+                    + `but client.vaultRepo is now ${boundedToken(v.configuredRepo ?? 'unknown')}; `
+                    + 'the cached standards are not the configured ones — only a client-tier load '
+                    + 'at the configured repo records loaded';
+            break;
+        case 'stale_cache':
+            reason =
+                `vault cache is stale (fetched ${boundedToken(str(manifest?.fetchedAt) ?? 'unknown')}); `
+                    + 'it exceeds vault.cache_ttl_hours';
+            break;
+        case 'no_bindings':
+            reason = PIN_REASON.noBindings;
+            break;
+        case 'config_unreadable':
+            reason = PIN_REASON.configUnreadable;
+            break;
+        default:
+            reason = PIN_REASON.disabled;
+    }
+    return { state: 'degraded', reason, ...pin, manifestFiles: null };
+}
+// ─── The universe ──────────────────────────────────────────────────────────────
+/** The manifest-relative directory prefix under which practice files live. */
+const PRACTICE_PATH_PREFIX = 'practices/';
+/** The extension a practice file carries; stripped to yield the id. */
+const PRACTICE_FILE_EXT = '.md';
+/**
+ * Derive the practice-ID universe from the manifest file list the pin already
+ * carries.
+ *
+ * THE PROPERTY THIS FUNCTION EXISTS TO HOLD: every identifier the practice
+ * MATCHER can put into `predicate.practices` must be present here. The gate
+ * resolves the ledger against this list, so any file the matcher accepts and
+ * this derivation rejects becomes an `practice_id_unresolved` block whose only
+ * remedy — regenerate the trace — reproduces itself, and whose real fix lives
+ * in the client's own vault repository (04-REVIEW CR-02). The two sides are
+ * therefore filtered by the SAME rules, in the SAME order, and a test drives
+ * both over one shared file list so the pair cannot drift again.
+ *
+ * The three filters, mirroring `discoverPracticeFiles` in
+ * `src/vault-practices.cts` exactly:
+ *
+ *   1. the `practices/` prefix — a vault holds more than its practices
+ *      directory, and a README must never become a practice identifier;
+ *   2. the markdown extension tested CASE-INSENSITIVELY — the matcher
+ *      lowercases before testing, so `practices/beta.MD` is a practice file to
+ *      it. Testing case-sensitively here was the CR-02 divergence;
+ *   3. the secret-file exclusion — `vaultMod.isSecretFile` is a pure function
+ *      of the relative path (it opens nothing, so FENCE 1's read discipline is
+ *      untouched) and the matcher applies it BEFORE any read because such
+ *      names must never be surfaced into agent or model context (VSEC-03).
+ *      The universe is written into a durable artifact that agents read, so
+ *      omitting it here re-opened the exact disclosure the matcher closes.
+ *
+ * ORDER IS LOAD-BEARING and is the matcher's order: filter, sort the PATHS,
+ * then cap.
+ *
+ *   - The exclusions run BEFORE the cap so an excluded entry can never displace
+ *     an included one out of the bound.
+ *   - The sort is over the PATHS, not over the derived ids, because that is the
+ *     order the matcher caps in. Sorting ids instead would select a different
+ *     hundred at the boundary (`practices/a-b.md` sorts before
+ *     `practices/a.md`, while the id `a` sorts before `a-b`), and the two sides
+ *     would disagree about exactly the entries nobody looks at.
+ *   - `PRACTICE_COUNT_CAP` is the matcher's own exported constant, not a copy.
+ *     The bound exists so client-vault data cannot dictate artifact size: an
+ *     unbounded universe writes one line per vault file into every PLAN.md and
+ *     SUMMARY.md, and past the gate's artifact byte cap the client's file count
+ *     decides whether the project can ship (04-REVIEW WR-05).
+ *   - An omission is recorded as a COUNT and never as a name. The matcher emits
+ *     counts for precisely this reason, and the universe must not be the place
+ *     an excluded filename leaks back out.
+ *
+ * The id is derived with `path.basename(rel, PRACTICE_FILE_EXT)` — the SAME
+ * call `parsePracticeFile` uses to decide whether a practice's declared id
+ * matches its filename (D-03). That is deliberate and it is not the same thing
+ * as stripping the last three characters: Node strips the suffix only on an
+ * exact match, so `practices/beta.MD` yields the id `beta.MD` on BOTH sides.
+ * A length-based strip would yield `beta` here and `beta.MD` there, which fixes
+ * the case test and relocates CR-02 rather than closing it. Lowercasing the
+ * basename would break it a third way. The derivation must mirror the matcher's
+ * operation, not approximate it.
+ *
+ * No practice file is opened: the basename is the whole input, and
+ * `src/vault-practices.cts` enforces (D-03) that a practice's frontmatter
+ * identifier equals it, SKIPPING any file that disagrees. A file the matcher
+ * skips for that reason leaves the universe a strict superset, which only ever
+ * makes MORE identifiers resolve — never fewer.
+ *
+ * Every derived id is re-validated against `TRACE_ID_PATTERN` here at build
+ * time, copying the defence-in-depth shape the practices list uses: a failing
+ * id is DROPPED and a note names the rejected value. A vault-authored filename
+ * reaches an agent's context through this list; it must not be the first
+ * unvalidated string in the statement.
+ *
+ * Null in, null out: a degraded pin carries no file list and records no
+ * universe (D-04).
+ */
+function derivePracticeUniverse(manifestFiles, notes) {
+    if (manifestFiles === null)
+        return null;
+    const kept = [];
+    for (const rel of manifestFiles) {
+        if (!rel.startsWith(PRACTICE_PATH_PREFIX))
+            continue;
+        if (!rel.toLowerCase().endsWith(PRACTICE_FILE_EXT))
+            continue;
+        if (vaultMod.isSecretFile(rel))
+            continue;
+        kept.push(rel);
+    }
+    kept.sort();
+    const shown = kept.slice(0, PRACTICE_COUNT_CAP);
+    const omitted = kept.length - shown.length;
+    if (omitted > 0) {
+        notes.push(`${omitted} practice universe entries omitted (cap: ${PRACTICE_COUNT_CAP})`);
+    }
+    const ids = new Set();
+    for (const rel of shown) {
+        const id = node_path_1.default.basename(rel, PRACTICE_FILE_EXT);
+        if (!TRACE_ID_PATTERN.test(id)) {
+            notes.push(`practice universe id skipped: "${boundedToken(id)}" does not match the permitted id charset`);
+            continue;
+        }
+        ids.add(id);
+    }
+    return [...ids].sort();
+}
+/**
+ * The lead of the analyzer-provenance clause, and the ONLY wording this module
+ * puts in front of a rule name (MECH-03, D-10-05).
+ *
+ * "also enforced by", never "verified by". pp-core runs no analyzer and
+ * confirms none; the clause is a claim about what the PRACTICE SAYS,
+ * attributable to the vault.
+ *
+ * ONE SENTENCE, TWO MODULES, AND WHY THAT IS NOT A DRIFT WAITING TO HAPPEN.
+ * `src/vault-audit.cts` is the OWNER — 10-06 shipped this wording there as
+ * `AUDIT_ENFORCED_BY_LEAD`, and harvesting rather than restating is this
+ * project's standing rule. It is not harvested HERE because it cannot be:
+ * `src/vault-audit.cts:70-72` requires this module's compiled form and
+ * DESTRUCTURES it at top level, and the comment at `:66-68` records the
+ * invariant that keeps that safe — "neither imports this module, so this adds
+ * no cycle". An edge from here back to the audit leaf, eager or lazy, makes
+ * that sentence false and the destructure load-order-dependent. So the copy
+ * stays and is PINNED against its owner by a test that fails when the two
+ * spellings disagree, which is the remedy this project prescribes for a copy
+ * that has to stay.
+ */
+const TRACE_ENFORCED_BY_LEAD = 'also enforced by';
+/**
+ * Compose one practice's provenance clause, or `''` when it names nothing.
+ *
+ * Every rule name is a CLIENT-AUTHORED BYTE on its way into a committed record
+ * an agent reads, so each is bounded and defanged here even though
+ * `parseEnforcedBy` already bounded it at parse time: this is the boundary that
+ * matters, and a statement can be hand-built or mutated between build and
+ * serialize.
+ */
+function composeEnforcedByClause(rules) {
+    if (!Array.isArray(rules))
+        return '';
+    const named = [];
+    for (const rule of rules) {
+        if (typeof rule !== 'string')
+            continue;
+        const safe = defangFenceMarkers(collapseControlChars(boundedToken(rule))).trim();
+        if (safe !== '')
+            named.push(safe);
+    }
+    if (named.length === 0)
+        return '';
+    return `${TRACE_ENFORCED_BY_LEAD} ${named.join(', ')}`;
+}
+const NO_PINNED_FACTS = Object.freeze({
+    checkBearingIds: new Set(),
+    clauseById: new Map(),
+    read: false,
+});
+/**
+ * Read the pinned practice cache ONCE and derive both facts 10-08 adds
+ * (MECH-02, MECH-03).
+ *
+ * Reads through `discoverPracticeFiles` — the ONE practice reader — against the
+ * SAME resolved cache directory the pin used (the comment above `resolvePin`'s
+ * call site states why one cache directory serves the pin and the matcher; the
+ * census must not reach for a second). A second frontmatter scan here would be
+ * a second answer to one question, and the two would disagree the day either is
+ * edited. This is the widened read profile stated on
+ * `ResolvedPin.manifestFiles`, named rather than left implicit.
+ *
+ * ONE call for both facts, not two: the census and the provenance map are two
+ * projections of the same read, and taking the cache twice would let them
+ * describe two different moments.
+ *
+ * A read that FAILS records `read: false` and says so in `notes`. The census
+ * then lands on `null`, never `0`: zero is a claim about a vault that WAS read,
+ * and collapsing the two is how "we checked nothing" comes to read as "nothing
+ * needed checking".
+ */
+function readPinnedPractices(cwd, vaultDir, notes) {
+    try {
+        const discovery = practicesMod.discoverPracticeFiles(cwd, vaultDir);
+        const checkBearingIds = new Set();
+        const clauseById = new Map();
+        for (const practice of discovery.practices ?? []) {
+            if (typeof practice.id !== 'string')
+                continue;
+            // `check` is present ONLY when a `check:` key was authored AND every rule
+            // in `parseCheckBlock` passed. A practice carrying `checkInvalid` instead
+            // is deliberately NOT counted: that defect is a fail-closed FAIL at the
+            // audit, and counting it as adoption would overstate the vault's
+            // mechanical coverage — the over-claim this milestone exists to prevent
+            // (T-10-33).
+            if (practice.check !== undefined && practice.check !== null) {
+                checkBearingIds.add(practice.id);
+            }
+            const clause = composeEnforcedByClause(practice.enforcedBy);
+            if (clause !== '')
+                clauseById.set(practice.id, clause);
+        }
+        return { checkBearingIds, clauseById, read: true };
+    }
+    catch (e) {
+        notes.push(`the pinned practice cache could not be read for the check-bearing census (${boundedToken(e?.message ?? e)})`);
+        return NO_PINNED_FACTS;
+    }
+}
+/**
+ * Take the check-block CENSUS of the recorded universe (MECH-02, D-10-13).
+ *
+ * `universe === null` in, `null` out: a degraded run has no universe to take a
+ * census of (D-04), and the census carries the rule of the sibling it sits
+ * beside rather than of the per-practice fields further down the statement.
+ *
+ * Counting is confined to ids the universe records, which is what makes
+ * "N of `universe.length`" exactly true of one statement read on its own: a
+ * practice file present on disk but absent from the manifest at the pinned SHA
+ * is not at that ref.
+ */
+function deriveCheckBearingCensus(universe, facts) {
+    if (universe === null || !facts.read)
+        return null;
+    let checkBearing = 0;
+    for (const id of universe) {
+        if (facts.checkBearingIds.has(id))
+            checkBearing += 1;
+    }
+    return checkBearing;
+}
+/** At most this many PLAN/SUMMARY artifacts are read for the census. */
+const CENSUS_ARTIFACT_CAP = 200;
+/** Each artifact is read whole or not at all, up to this many bytes. */
+const CENSUS_ARTIFACT_BYTE_CAP = 1024 * 1024;
+/**
+ * Read the `check:` census this phase's ledgers RECORDED — never re-derive it.
+ *
+ * The census is taken once, by `buildTraceStatement`, against the pinned vault
+ * the plan or summary was written under. A consumer (the mechanical audit)
+ * reads that record back here instead of counting the vault again: a second
+ * count could describe a different vault than the ledger does.
+ *
+ * Execute-stage ledgers (SUMMARY.md) are preferred over plan-stage ones, and
+ * within a stage the last artifact in name order — the latest plan — is the
+ * one reported. `distinct` counts how many different censuses the phase's
+ * ledgers record, so a vault that moved during the phase is visible. A ledger
+ * with no census (a degraded run) is skipped. `null` when no ledger records
+ * one. Pure read; never throws.
+ */
+function readRecordedCensus(phaseDir) {
+    try {
+        const names = node_fs_1.default
+            .readdirSync(phaseDir)
+            .filter((name) => /(^|-)(PLAN|SUMMARY)\.md$/.test(name))
+            .sort()
+            .slice(0, CENSUS_ARTIFACT_CAP);
+        const found = [];
+        for (const name of names) {
+            const abs = node_path_1.default.join(phaseDir, name);
+            let content;
+            try {
+                const stat = node_fs_1.default.lstatSync(abs);
+                if (!stat.isFile() || stat.size > CENSUS_ARTIFACT_BYTE_CAP)
+                    continue;
+                content = node_fs_1.default.readFileSync(abs, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const parsed = parseVaultTraceBlock(content, name);
+            const vault = parsed.present && parsed.statement ? parsed.statement.predicate?.vault : null;
+            if (!vault)
+                continue;
+            const census = vault.checkBearingPractices;
+            if (typeof census !== 'number' || !Number.isInteger(census) || census < 0)
+                continue;
+            if (!Array.isArray(vault.practiceUniverse))
+                continue;
+            found.push({
+                census,
+                universe: vault.practiceUniverse.length,
+                sha: typeof vault.resolvedSha === 'string' ? vault.resolvedSha : null,
+                artifact: name,
+                execute: /(^|-)SUMMARY\.md$/.test(name),
+            });
+        }
+        if (found.length === 0)
+            return null;
+        const pool = found.some((f) => f.execute) ? found.filter((f) => f.execute) : found;
+        const chosen = pool[pool.length - 1];
+        const distinct = new Set(found.map((f) => `${f.census}/${f.universe}/${f.sha ?? ''}`)).size;
+        return {
+            checkBearingPractices: chosen.census,
+            practiceUniverse: chosen.universe,
+            resolvedSha: chosen.sha,
+            artifact: chosen.artifact,
+            distinct,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ─── The builder ───────────────────────────────────────────────────────────────
+/**
+ * The statement note recorded when the cache was read from the owning main git
+ * worktree (worktree executors). A fact, never a path.
+ */
+const TRACE_WORKTREE_CACHE_NOTE = 'vault cache read from the owning main git worktree; this checkout carries no local .planning/vault';
+/**
+ * Build a complete trace statement.
+ *
+ * ALWAYS returns a statement. A vault that cannot be read produces a
+ * `state: degraded` record with a non-null reason, never an omitted artifact —
+ * an absent trace would be indistinguishable from a phase that was never
+ * vault-enabled, and that silence is exactly what this schema exists to end.
+ */
+function buildTraceStatement(opts) {
+    const { cwd, stage, plan } = opts;
+    const files = Array.isArray(opts.files) ? opts.files : [];
+    const notes = [];
+    const generatedAt = new Date().toISOString();
+    // ONE cache directory for the pin AND the matcher (worktree executors), so
+    // the practice set and the ref it is recorded against come from one vault.
+    const cache = vaultMod.resolveVaultCacheDir(cwd);
+    if (cache.source === 'main-worktree') {
+        // The fact, never the path: an absolute path of the owning checkout would
+        // leak a machine layout into a committed record.
+        notes.push(TRACE_WORKTREE_CACHE_NOTE);
+    }
+    const pin = resolvePin(cwd, cache.dir);
+    // The universe comes from the SAME manifest read that produced the pin
+    // (D-01); charset rejects are dropped and noted onto THIS statement's notes.
+    const practiceUniverse = derivePracticeUniverse(pin.manifestFiles, notes);
+    // ONE read of the pinned cache, two facts (10-08): the check-block census of
+    // the universe above, and the per-practice analyzer-provenance clauses the
+    // ledger entries below carry. This is the widened read profile this path now
+    // owns; it is stated on `ResolvedPin.manifestFiles` rather than left implicit.
+    const pinnedFacts = readPinnedPractices(cwd, cache.dir, notes);
+    const checkBearingPractices = deriveCheckBearingCensus(practiceUniverse, pinnedFacts);
+    // ── subject ──
+    const subject = [];
+    const names = [];
+    for (const entry of files) {
+        const rawName = typeof entry === 'string' ? entry : entry?.name;
+        if (typeof rawName !== 'string' || rawName === '')
+            continue;
+        const name = rawName.replace(/\\/g, '/');
+        names.push(name);
+        if (stage === 'execute') {
+            const digest = typeof entry === 'string' ? undefined : entry.gitCommit;
+            if (typeof digest === 'string' && /^[0-9a-f]{40}$|^[0-9a-f]{64}$/.test(digest)) {
+                subject.push({ name, digest: { gitCommit: digest } });
+            }
+            else {
+                // Loud, not silent: an execute-stage entry with no usable digest is a
+                // real coverage gap and the reader must be able to see it.
+                notes.push(`subject "${boundedToken(name)}" has no usable gitCommit digest at execute stage`);
+                subject.push({ name, uri: name });
+            }
+        }
+        else {
+            // Plan stage: no digest key at all. `uri` is set so the entry still
+            // satisfies in-toto's ResourceDescriptor minimum.
+            subject.push({ name, uri: name });
+        }
+    }
+    // ── practices: the matcher's return set, and nothing else ──
+    const dispositionById = new Map();
+    for (const d of opts.dispositions ?? []) {
+        if (d && typeof d.id === 'string')
+            dispositionById.set(d.id, d);
+    }
+    const practices = [];
+    try {
+        const match = practicesMod.matchPractices({ cwd, files: names, vaultDir: cache.dir });
+        // Concatenate matched THEN global, preserving the matcher's own sort. Do
+        // not re-glob, do not read the practices directory, and do not filter by
+        // severity — a `not-applicable` entry is exactly the record TRACE-02
+        // exists to produce.
+        for (const p of [...match.matched, ...match.global]) {
+            const id = boundedToken(p.id);
+            if (!TRACE_ID_PATTERN.test(id)) {
+                notes.push(`practice id skipped: "${id}" does not match the permitted id charset`);
+                continue;
+            }
+            const d = dispositionById.get(id);
+            const entry = {
+                id,
+                scope: p.scope ?? null,
+                severity: p.severity ?? null,
+                status: typeof d?.status === 'string' ? d.status : '',
+                reason: typeof d?.reason === 'string' ? d.reason : '',
+                tasks: Array.isArray(d?.tasks) ? d.tasks.map((t) => String(t)) : [],
+            };
+            // Set ONLY when the practice carries a claim. An `undefined` property
+            // would change every deepEqual in every consumer for no behavioural gain
+            // — the same reasoning the validator's optional `tail` field already
+            // carries — and an entry for a practice with no claim must stay
+            // byte-identical to the one it produced before this phase (MECH-03).
+            const clause = pinnedFacts.clauseById.get(id);
+            if (typeof clause === 'string' && clause !== '')
+                entry.enforcedBy = clause;
+            // THE TEXT DIGEST (D-05-07). Digested from the SAME unwrapped excerpt
+            // `renderPracticeEntry` places under `ask:`/`excerpt:` in the body block
+            // — `unwrapFencedExcerpt` is the practices module's own, exported for
+            // exactly this, so the two readers cannot strip the fence differently.
+            // The scaffold and `vault practices match --block` run the same matcher
+            // on the same cache in the same session, which is what makes a digest
+            // written here comparable to a block embedded there.
+            const fenced = p.scope === 'scoped'
+                ? p.ask
+                : p.excerpt;
+            if (typeof fenced === 'string') {
+                entry.textSha256 = practiceTextDigest(practicesMod.unwrapFencedExcerpt(fenced));
+            }
+            practices.push(entry);
+        }
+    }
+    catch (e) {
+        // The matcher degrades internally rather than throwing, but a trace is
+        // never worth losing to an unexpected read failure.
+        notes.push(`practice matching failed: ${boundedToken(e.message)}`);
+    }
+    return {
+        _type: TRACE_STATEMENT_TYPE,
+        predicateType: TRACE_PREDICATE_TYPE,
+        schemaVersion: TRACE_SCHEMA_VERSION,
+        subject,
+        predicate: {
+            stage,
+            plan,
+            generatedAt,
+            vault: {
+                state: pin.state,
+                reason: pin.reason,
+                ref: pin.ref,
+                resolvedSha: pin.resolvedSha,
+                practiceUniverse,
+                checkBearingPractices,
+                tier: pin.tier,
+                source: pin.source,
+                repo: pin.repo,
+            },
+            practices,
+            notes,
+            override: null,
+        },
+    };
+}
+// ─── The reader allowlist ──────────────────────────────────────────────────────
+/**
+ * The predicate types a trace READER accepts for the project at `cwd`:
+ * `TRACE_PREDICATE_TYPE` first, then each URI the org profile lists under
+ * `vault.trace.accepted_predicates` that carries the same major
+ * (`/v<TRACE_SCHEMA_VERSION>`). A listed URI of another major is ignored —
+ * the URI major and the schema version move together. Never throws; writers
+ * never call it.
+ */
+function acceptedPredicateTypes(cwd) {
+    const out = [TRACE_PREDICATE_TYPE];
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const orgProfile = require('./org-profile.cjs');
+        const majorSuffix = `/v${TRACE_SCHEMA_VERSION}`;
+        for (const uri of orgProfile.resolveAcceptedTracePredicates(cwd)) {
+            if (typeof uri === 'string' && uri.endsWith(majorSuffix) && !out.includes(uri))
+                out.push(uri);
+        }
+    }
+    catch {
+        /* no profile reader: pp-core's own type only */
+    }
+    return out;
+}
+// ─── The serializer ────────────────────────────────────────────────────────────
+const INDENT = '  ';
+/**
+ * Quote a scalar for the emitted block. Every string value is emitted
+ * double-quoted — uniformly, rather than only when it "looks dangerous",
+ * because a conditional quoting rule is one review away from being widened to
+ * the wrong case. Backslashes and quotes are escaped, and any CR/LF is
+ * collapsed to a space so no value can ever add a line to the document.
+ */
+function yamlQuote(value) {
+    const flat = String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/[\r\n]+/g, ' ');
+    return `"${flat}"`;
+}
+/** Emit `key: value` where value is a string, a number, or null. */
+function scalarLine(depth, key, value) {
+    const rendered = value === null ? 'null' : typeof value === 'number' ? String(value) : yamlQuote(value);
+    return `${INDENT.repeat(depth)}${key}: ${rendered}`;
+}
+/** Emit a list of quoted strings, or an explicit `[]`. */
+function stringListLines(depth, key, values) {
+    if (values.length === 0)
+        return [`${INDENT.repeat(depth)}${key}: []`];
+    return [
+        `${INDENT.repeat(depth)}${key}:`,
+        ...values.map((v) => `${INDENT.repeat(depth + 1)}- ${yamlQuote(v)}`),
+    ];
+}
+/** Emit an inline list of quoted strings (`tasks: ["T1", "T3"]`). */
+function inlineList(values) {
+    if (values.length === 0)
+        return '[]';
+    return `[${values.map(yamlQuote).join(', ')}]`;
+}
+/**
+ * Serialize a statement as the `vault:` frontmatter block.
+ *
+ * Hand-written, with no YAML library: `pp-core/bin/lib/*.cjs` takes no external
+ * runtime dependency, and TRACE-01 adopts the in-toto shape without one.
+ *
+ * The practice list is emitted as a LIST OF MAPS so every id sits in a VALUE
+ * position (`- id: "db-naming"`). A map keyed by id would put a
+ * client-authored token in a KEY position, where a `:`, a `#`, a leading `-`
+ * or a newline changes the document's structure instead of a value's content.
+ *
+ * An id that fails the charset is SKIPPED with a note recorded inside the
+ * emitted statement, never dropped silently — a silent drop is
+ * indistinguishable from an agent omission and would break the 1:1 coverage
+ * check a gate performs against this list.
+ */
+function serializeTraceBlock(statement) {
+    const p = statement.predicate;
+    const notes = [...(p.notes ?? [])];
+    const lines = ['vault:'];
+    lines.push(scalarLine(1, '_type', statement._type));
+    lines.push(scalarLine(1, 'predicateType', statement.predicateType));
+    lines.push(`${INDENT}schemaVersion: ${Number(statement.schemaVersion)}`);
+    // ── subject ──
+    const subjects = statement.subject ?? [];
+    if (subjects.length === 0) {
+        lines.push(`${INDENT}subject: []`);
+    }
+    else {
+        lines.push(`${INDENT}subject:`);
+        for (const s of subjects) {
+            lines.push(`${INDENT.repeat(2)}- name: ${yamlQuote(s.name)}`);
+            if (typeof s.uri === 'string')
+                lines.push(scalarLine(3, 'uri', s.uri));
+            if (s.digest && typeof s.digest.gitCommit === 'string') {
+                lines.push(`${INDENT.repeat(3)}digest:`);
+                lines.push(scalarLine(4, 'gitCommit', s.digest.gitCommit));
+            }
+        }
+    }
+    // ── predicate ──
+    lines.push(`${INDENT}predicate:`);
+    lines.push(scalarLine(2, 'stage', p.stage));
+    lines.push(scalarLine(2, 'plan', p.plan));
+    lines.push(scalarLine(2, 'generatedAt', p.generatedAt));
+    lines.push(`${INDENT.repeat(2)}vault:`);
+    lines.push(scalarLine(3, 'state', p.vault.state));
+    lines.push(scalarLine(3, 'reason', p.vault.reason));
+    lines.push(scalarLine(3, 'ref', p.vault.ref));
+    lines.push(scalarLine(3, 'resolvedSha', p.vault.resolvedSha));
+    // practiceUniverse sits immediately after `resolvedSha`: the two facts come
+    // from the same manifest read (D-01). When null or absent, NO line is
+    // emitted — an empty universe (`[]`) and an unrecorded one are different
+    // facts and plan 04-05 must be able to tell them apart. Re-validated at emit
+    // time exactly like the practices list below (defence in depth): the
+    // statement may have been hand-built or mutated between build and serialize.
+    if (Array.isArray(p.vault.practiceUniverse)) {
+        const emittableIds = p.vault.practiceUniverse.filter((id) => {
+            const ok = typeof id === 'string' && TRACE_ID_PATTERN.test(id);
+            if (!ok) {
+                notes.push(`practice universe id skipped at serialize time: "${boundedToken(id)}" does not match the permitted id charset`);
+            }
+            return ok;
+        });
+        lines.push(...stringListLines(3, 'practiceUniverse', emittableIds));
+    }
+    // The census sits with the universe it is a census OF, on the same rule the
+    // universe follows: when the value is not a usable count, NO line is emitted,
+    // because an unrecorded census and a census of ZERO are different facts and a
+    // consumer must be able to tell them apart. Zero IS emitted — "0 of 55" is
+    // the fact MECH-02 exists to make legible, and a fact nobody writes down is
+    // not a record.
+    //
+    // Re-validated at emit time exactly like the practices list below (defence in
+    // depth): the statement may have been hand-built or mutated between build and
+    // serialize, and the YAML boundary is the one that matters. A value that is
+    // not an integer >= 0 is DROPPED WITH A NOTE rather than emitted — a silent
+    // drop would be indistinguishable from a census that was never taken.
+    const census = p.vault.checkBearingPractices;
+    if (typeof census === 'number' && Number.isInteger(census) && census >= 0) {
+        lines.push(scalarLine(3, 'checkBearingPractices', census));
+    }
+    else if (census !== null && census !== undefined) {
+        notes.push(`check-bearing census dropped at serialize time: "${boundedToken(census)}" is not an integer count of zero or more`);
+    }
+    lines.push(scalarLine(3, 'tier', p.vault.tier));
+    lines.push(scalarLine(3, 'source', p.vault.source));
+    lines.push(scalarLine(3, 'repo', p.vault.repo));
+    // ── practices ──
+    // Re-validate at emit time (defence in depth): the statement may have been
+    // hand-built or mutated between build and serialize, and the YAML boundary
+    // is the one that matters.
+    const emittable = (p.practices ?? []).filter((entry) => {
+        const ok = typeof entry.id === 'string' && TRACE_ID_PATTERN.test(entry.id);
+        if (!ok) {
+            notes.push(`practice id skipped at serialize time: "${boundedToken(entry.id)}" does not match the permitted id charset`);
+        }
+        return ok;
+    });
+    if (emittable.length === 0) {
+        lines.push(`${INDENT.repeat(2)}practices: []`);
+    }
+    else {
+        lines.push(`${INDENT.repeat(2)}practices:`);
+        for (const entry of emittable) {
+            lines.push(`${INDENT.repeat(3)}- id: ${yamlQuote(entry.id)}`);
+            lines.push(scalarLine(4, 'scope', entry.scope ?? null));
+            lines.push(scalarLine(4, 'severity', entry.severity ?? null));
+            lines.push(scalarLine(4, 'status', entry.status ?? ''));
+            lines.push(scalarLine(4, 'reason', entry.reason ?? ''));
+            // Analyzer provenance, between `reason` and `tasks` (10-08, MECH-03).
+            // NOTHING is emitted when the practice carries no claim, so an entry with
+            // no new fact keeps the shape it had before this phase.
+            //
+            // Re-bounded and re-defanged HERE even though the builder already did it,
+            // on the emit-time re-validation rule the id filter below states: the
+            // statement may have been hand-built or mutated between build and
+            // serialize, and the YAML boundary is the one that matters. Three
+            // distinct hazards, three shipped guards: `renderSafeField` collapses the
+            // control characters `boundedToken` does not (it handles CR/LF only) and
+            // caps the length so one ledger entry cannot fill an agent's context;
+            // `defangFenceMarkers` neutralises the SHIPPED external-content markers,
+            // which `yamlQuote` does not touch at all; and `yamlQuote` below owns the
+            // CR/LF half, so a newline cannot add a line to the document.
+            const clause = defangFenceMarkers(renderSafeField(entry.enforcedBy));
+            if (clause !== '')
+                lines.push(scalarLine(4, 'enforcedBy', clause));
+            // The text digest (D-05-07), between `enforcedBy` and `tasks`. NOTHING
+            // is emitted when the entry carries none, so a ledger written from a
+            // statement without digests keeps the shape it had. Re-validated at emit
+            // time on the same rule as the id filter: only a 64-character lowercase
+            // hex string is a digest, and anything else is dropped WITH a note rather
+            // than written as a value the gate would then compare against.
+            const digest = entry.textSha256;
+            if (typeof digest === 'string' && TEXT_DIGEST_PATTERN.test(digest)) {
+                lines.push(scalarLine(4, 'textSha256', digest));
+            }
+            else if (digest !== undefined && digest !== null) {
+                notes.push(`text digest dropped at serialize time for "${boundedToken(entry.id)}": not a sha256 hex digest`);
+            }
+            lines.push(`${INDENT.repeat(4)}tasks: ${inlineList(entry.tasks ?? [])}`);
+        }
+    }
+    lines.push(...stringListLines(2, 'notes', notes));
+    // ── override ──
+    if (!p.override) {
+        lines.push(`${INDENT.repeat(2)}override: null`);
+    }
+    else {
+        lines.push(`${INDENT.repeat(2)}override:`);
+        lines.push(scalarLine(3, 'gate', p.override.gate));
+        lines.push(scalarLine(3, 'reason', p.override.reason));
+        lines.push(scalarLine(3, 'suppressedReason', p.override.suppressedReason));
+        lines.push(scalarLine(3, 'who', p.override.who));
+        lines.push(scalarLine(3, 'when', p.override.when));
+    }
+    // TERMINATED, and the trailing newline is load-bearing (04-REVIEW IN-01).
+    // The block's destination is a document's YAML frontmatter, and the agent
+    // that puts it there splices by concatenation. Without a terminator the final
+    // line runs into whatever follows — `override: null---` — and
+    // `collectBlockLines`' frontmatter match then fails against a block that is
+    // physically present. The verdict is `trace_absent`, and its remedy is to
+    // regenerate the block that is already there: an unrecoverable false block of
+    // exactly the shape D-11 exists to prevent. One character removes the failure
+    // mode; a caller that joins with its own newline sees a blank line, which
+    // `collectBlockLines` already skips.
+    return `${lines.join('\n')}\n`;
+}
+// ─── The rendered surface ──────────────────────────────────────────────────────
+const PRACTICES_APPLIED_HEADING = '## Practices Applied';
+/**
+ * The cap applied to every client-influenced field the renderer interpolates
+ * into a generated markdown line (03-REVIEW WR-12, T-03-34). Wider than
+ * `WARNING_TOKEN_MAX` (80) because a one-line reason is not a warning token,
+ * and `boundedToken` is deliberately NOT reused here — widening its bound
+ * would silently change unrelated warning messages across two modules.
+ */
+const TRACE_RENDERED_FIELD_MAX = 300;
+/**
+ * The single line emitted in place of an entry whose id fails the charset. It
+ * has to teach a human reader three things at once, because it is the only
+ * thing they will see: that an id was refused AT THIS POSITION (the section
+ * never silently shrinks), that the reason is the permitted id charset, and
+ * that the record is regenerated rather than hand-repaired.
+ */
+const TRACE_REFUSED_ID_LINE = '- (a practice id was refused here: it does not match the permitted id charset — regenerate the trace block rather than hand-repairing it)';
+/**
+ * Bound and flatten one client-influenced value for a generated markdown line.
+ *
+ * The `## Practices Applied` section is loaded UNFENCED by name — the code
+ * reviewer's cross-plan reconciliation contract reads it — so this is the
+ * shortest injection path in the capability (T-03-34). A non-string coerces to
+ * the empty string rather than to `[object Object]`, control characters cannot
+ * forge a second line, and the length cap keeps one ledger entry from filling a
+ * downstream agent's context.
+ */
+function renderSafeField(value) {
+    if (typeof value !== 'string')
+        return '';
+    const flat = collapseControlChars(value).trim();
+    return flat.length > TRACE_RENDERED_FIELD_MAX
+        ? `${flat.slice(0, TRACE_RENDERED_FIELD_MAX)}…`
+        : flat;
+}
+/**
+ * Render the `## Practices Applied` section from the ledger.
+ *
+ * D-02 retires the hand-authoring of this section; D-03 PRESERVES the surface
+ * by generating it, so the two can never disagree and nothing downstream has
+ * to move. The heading has far more reach than its size suggests — the code
+ * reviewer's cross-plan reconciliation contract reads it by name, a capability
+ * contribution reads it, and four test files pin the literal string. The
+ * output must therefore be substitutable for what the executor writes today,
+ * which is why the line shape and the three-word vocabulary are reproduced
+ * rather than improved.
+ */
+function renderPracticesApplied(statement) {
+    const entries = statement?.predicate?.practices ?? [];
+    const lines = [PRACTICES_APPLIED_HEADING, ''];
+    if (entries.length === 0) {
+        // Never an empty section: D-04 requires a degraded or empty run to be
+        // READABLE as a fact. An omitted section and an unrecorded one look
+        // identical to every downstream reader.
+        lines.push('No client-vault practices were in scope for this plan (the recorded practice ledger is empty).');
+        return lines.join('\n');
+    }
+    for (const entry of entries) {
+        // 03-REVIEW CR-03, render half. The id is the only client-authored token
+        // that reaches this line, and this line is read UNFENCED by another agent.
+        // A refusal keeps the entry's POSITION — pushing nothing would let a
+        // hostile ledger quietly shorten the section, which reads as "fewer
+        // practices were in scope" rather than "something was refused here".
+        if (typeof entry?.id !== 'string' || !TRACE_ID_PATTERN.test(entry.id)) {
+            lines.push(TRACE_REFUSED_ID_LINE);
+            continue;
+        }
+        const statusText = renderSafeField(entry.status);
+        const status = statusText !== '' ? statusText : 'not-applicable';
+        const reason = renderSafeField(entry.reason);
+        lines.push(reason === '' ? `- ${entry.id}: ${status}` : `- ${entry.id}: ${status} — ${reason}`);
+    }
+    return lines.join('\n');
+}
+// ─── The parser ────────────────────────────────────────────────────────────────
+/**
+ * The frontmatter key the trace is anchored on. The parser locates THIS key and
+ * its indent, exactly as `parseMustHavesBlock` anchors on `must_haves:`.
+ */
+const TRACE_BLOCK_KEY = 'vault';
+/** A complete double-quoted scalar, allowing escaped quotes and backslashes. */
+const QUOTED_RE = /^"(?:[^"\\]|\\.)*"$/;
+/**
+ * Key-value recognizer, carrying the whitespace-after-colon guard.
+ *
+ * The `\s+` after the colon is NOT cosmetic. YAML key-value always has at
+ * least one space after the colon, and requiring it is what stops
+ * `Class::Method` and `db:seed` being mis-read as a key-value pair when they
+ * appear as a plain scalar (#2757). Without it, a hand-edited note reading
+ * `db:seed was used` silently becomes the object `{ db: 'seed was used' }` and
+ * the round-trip stops being an identity.
+ */
+const KV_RE = /^([A-Za-z0-9_-]+):(?:\s+(.*))?$/;
+function unquoteScalar(s) {
+    return s.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+}
+function parseScalar(raw) {
+    const s = raw.trim();
+    if (s === '')
+        return '';
+    if (s === 'null')
+        return null;
+    if (s === '[]')
+        return [];
+    if (QUOTED_RE.test(s))
+        return unquoteScalar(s);
+    if (/^\[.*\]$/.test(s)) {
+        const inner = s.slice(1, -1);
+        const quoted = inner.match(/"(?:[^"\\]|\\.)*"/g);
+        if (quoted)
+            return quoted.map(unquoteScalar);
+        return inner
+            .split(',')
+            .map((x) => x.trim())
+            .filter((x) => x !== '');
+    }
+    if (/^-?\d+$/.test(s))
+        return Number(s);
+    return s;
+}
+/**
+ * The three keys that are never assigned from document text (03-REVIEW CR-05).
+ *
+ * `KV_RE`'s character class matches `__proto__`, and a key carrying a nested
+ * block is assigned an OBJECT — which reassigns the prototype of the plain
+ * accumulator the parser is building. A block whose whole body sat under
+ * `__proto__` therefore validated clean while neither frozen literal appeared
+ * anywhere a `grep` would find it (T-03-32/T-03-33). For a capability whose
+ * product is a provable, READABLE audit record, the gate and the document text
+ * disagreeing is the defect itself.
+ *
+ * The guard sits at the key-recognition boundary — this project's stated
+ * convention for prototype guards, and the same three-key shape the phase's own
+ * integration-test helper already implements — so BOTH `parseListItem` and
+ * `parseValueLines` inherit one guard instead of each growing their own.
+ */
+const FORBIDDEN_KEYS = Object.freeze(new Set(['__proto__', 'constructor', 'prototype']));
+function matchKeyValue(text) {
+    const m = text.match(KV_RE);
+    if (!m || FORBIDDEN_KEYS.has(m[1]))
+        return null;
+    return { key: m[1], value: (m[2] ?? '').trim() };
+}
+function parseListItem(head, children) {
+    const trimmed = head.trim();
+    // A fully-quoted item is a STRING, checked before the key-value branch so a
+    // quoted value containing a colon can never be re-read as a mapping.
+    if (QUOTED_RE.test(trimmed) && children.length === 0)
+        return unquoteScalar(trimmed);
+    const kv = matchKeyValue(trimmed);
+    if (!kv) {
+        if (children.length === 0)
+            return parseScalar(trimmed);
+        return parseValueLines(children);
+    }
+    // Null prototype as defence in depth (CR-05): a key that ever slipped past
+    // the recognizer above still cannot reach a prototype from here.
+    const obj = Object.create(null);
+    obj[kv.key] = kv.value === '' ? {} : parseScalar(kv.value);
+    if (children.length > 0) {
+        const rest = parseValueLines(children);
+        if (rest && typeof rest === 'object' && !Array.isArray(rest)) {
+            Object.assign(obj, rest);
+        }
+    }
+    return obj;
+}
+/**
+ * Parse a run of block lines that are all more indented than their parent.
+ *
+ * The technique is copied from `parseMustHavesBlock` and not the function
+ * itself: that one is anchored on its own literal key, and widening it would
+ * dissolve the very shape that makes it work. The five moves reproduced here
+ * are — capture the parent indent; require the nested block be more indented;
+ * detect the list-item indent from the first `- `; treat a deeper indent under
+ * an object item as a continuation key-value; and stop at the first line whose
+ * indent is not greater than the parent's.
+ */
+function parseValueLines(lines) {
+    if (lines.length === 0)
+        return {};
+    const base = lines[0].indent;
+    if (lines[0].text.startsWith('- ')) {
+        const items = [];
+        let i = 0;
+        while (i < lines.length) {
+            if (lines[i].indent !== base || !lines[i].text.startsWith('- ')) {
+                i += 1;
+                continue;
+            }
+            const head = lines[i].text.slice(2);
+            const children = [];
+            let j = i + 1;
+            while (j < lines.length && lines[j].indent > base) {
+                children.push(lines[j]);
+                j += 1;
+            }
+            items.push(parseListItem(head, children));
+            i = j;
+        }
+        return items;
+    }
+    // Null prototype as defence in depth (CR-05) — see `FORBIDDEN_KEYS`.
+    const obj = Object.create(null);
+    let i = 0;
+    while (i < lines.length) {
+        if (lines[i].indent !== base) {
+            i += 1;
+            continue;
+        }
+        const kv = matchKeyValue(lines[i].text);
+        if (!kv) {
+            i += 1;
+            continue;
+        }
+        const children = [];
+        let j = i + 1;
+        while (j < lines.length && lines[j].indent > base) {
+            children.push(lines[j]);
+            j += 1;
+        }
+        obj[kv.key] = kv.value === '' ? parseValueLines(children) : parseScalar(kv.value);
+        i = j;
+    }
+    return obj;
+}
+/** Collect the block's lines, anchored on `vault:` and bounded by its indent. */
+function collectBlockLines(content) {
+    const fm = String(content ?? '').match(/^---\r?\n([\s\S]+?)\r?\n---/);
+    if (!fm)
+        return null;
+    const lines = fm[1].split(/\r?\n/);
+    // 03-REVIEW WR-09: anchor on the TOP-LEVEL key only — no leading-whitespace
+    // capture. The trace is only ever WRITTEN at the top level of the
+    // frontmatter, so a nested `vault:` sub-key is not a trace. Taking the first
+    // match at any indent let an unrelated nested key (a config echo, a tool
+    // block, a hand-added note) shadow the real ledger: the collected lines were
+    // that node's children, the statement normalised to empty, and the gate
+    // reported `trace_unparsable`. Fail-closed, so never a bypass — but an
+    // UNRECOVERABLE false block, because the block's own remedy ("regenerate the
+    // block") re-emits the same second `vault:` key (T-03-35).
+    const anchorRe = new RegExp(`^${TRACE_BLOCK_KEY}:\\s*$`);
+    const anchorIndent = 0;
+    let anchor = -1;
+    for (let i = 0; i < lines.length; i += 1) {
+        if (anchorRe.test(lines[i])) {
+            anchor = i;
+            break;
+        }
+    }
+    if (anchor === -1)
+        return null;
+    const out = [];
+    for (let i = anchor + 1; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (line.trim() === '')
+            continue;
+        const indent = line.match(/^(\s*)/)[1].length;
+        if (indent <= anchorIndent)
+            break;
+        out.push({ indent, text: line.trim() });
+    }
+    return out;
+}
+/** How many content lines sit under a nested `practices:` key (0 if inline). */
+function practicesContentLineCount(lines) {
+    const idx = lines.findIndex((l) => l.text === 'practices:');
+    if (idx === -1)
+        return 0;
+    const base = lines[idx].indent;
+    let n = 0;
+    for (let i = idx + 1; i < lines.length; i += 1) {
+        if (lines[i].indent <= base)
+            break;
+        n += 1;
+    }
+    return n;
+}
+function asObject(v) {
+    return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+}
+function asArray(v) {
+    return Array.isArray(v) ? v : [];
+}
+/**
+ * Render a parsed scalar as a string WITHOUT ever falling through to
+ * `[object Object]`. A string passes through byte-identically, which is what
+ * keeps the round-trip an identity; anything else is a shape the emitter never
+ * produces, so it is rendered defensively rather than trusted.
+ */
+function stringifyScalar(v) {
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    if (v === null || v === undefined)
+        return '';
+    try {
+        return JSON.stringify(v) ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+function asStringOrNull(v) {
+    if (v === null || v === undefined)
+        return null;
+    return stringifyScalar(v);
+}
+function asString(v) {
+    return stringifyScalar(v);
+}
+const ABSENT = Object.freeze({
+    present: false,
+    reason: 'no_vault_block',
+    statement: null,
+});
+/**
+ * Read a `vault:` trace block back out of a document.
+ *
+ * Returns a documented ABSENT result rather than throwing when the document
+ * carries no block: handlers in this repository never throw and adapters
+ * return a structured reason, and the parser sits on the adapter side of that
+ * line.
+ *
+ * @param content      The full document text (frontmatter included).
+ * @param artifactPath Named in the empty-parse diagnostic so an operator knows
+ *                     WHICH file to look at.
+ */
+function parseVaultTraceBlock(content, artifactPath = 'the artifact') {
+    const lines = collectBlockLines(content);
+    if (lines === null || lines.length === 0)
+        return ABSENT;
+    const root = asObject(parseValueLines(lines));
+    const predicate = asObject(root.predicate);
+    const vault = asObject(predicate.vault);
+    const practices = asArray(predicate.practices).map((raw) => {
+        const p = asObject(raw);
+        const entry = {
+            id: asString(p.id),
+            scope: asStringOrNull(p.scope),
+            severity: asStringOrNull(p.severity),
+            status: typeof p.status === 'string' ? p.status : '',
+            reason: typeof p.reason === 'string' ? p.reason : '',
+            tasks: asArray(p.tasks).map((t) => asString(t)),
+        };
+        // Optional (10-08): reconstructed ONLY when the document carried it, so a
+        // trace written before this phase parses back into the exact entry it
+        // parsed into then. An `undefined` property would not be that.
+        if (typeof p.enforcedBy === 'string' && p.enforcedBy !== '')
+            entry.enforcedBy = p.enforcedBy;
+        // Optional (D-05-07): reconstructed ONLY when the document carried it,
+        // on the same reasoning as `enforcedBy` above.
+        if (typeof p.textSha256 === 'string' && p.textSha256 !== '')
+            entry.textSha256 = p.textSha256;
+        return entry;
+    });
+    // A silently empty parse is not merely unhelpful here: a downstream
+    // validator checks that dispositions cover the emitted id set one-to-one, so
+    // an empty parse and a genuine coverage failure would produce the same
+    // verdict from different causes. Say which it was.
+    const contentLines = practicesContentLineCount(lines);
+    if (practices.length === 0 && contentLines > 0) {
+        // 03-REVIEW WR-03: `artifactPath` is built from `fs.readdirSync` output or
+        // straight from argv, and POSIX permits a newline in a filename — the same
+        // fact `boundedToken`'s docstring cites. Sanitized HERE, inside the leaf,
+        // so the guard does not depend on every caller remembering; the check
+        // router sanitizes independently and both defences are wanted (T-03-36).
+        const safeArtifactPath = boundedToken(collapseControlChars(String(artifactPath)));
+        process.stderr.write(`[pp-tools] WARNING: the \`${TRACE_BLOCK_KEY}:\` trace block in ${safeArtifactPath} has ` +
+            `${contentLines} practice content line(s) but parsed 0 entries. The trace is unreadable, ` +
+            `which is NOT the same as an empty practice set — do not treat this as a clean run. ` +
+            `Regenerate the block rather than hand-repairing it.\n`);
+    }
+    const subject = asArray(root.subject).map((raw) => {
+        const s = asObject(raw);
+        const entry = { name: asString(s.name) };
+        if (typeof s.uri === 'string')
+            entry.uri = s.uri;
+        const digest = asObject(s.digest);
+        if (typeof digest.gitCommit === 'string')
+            entry.digest = { gitCommit: digest.gitCommit };
+        return entry;
+    });
+    const rawOverride = predicate.override;
+    let override = null;
+    if (rawOverride && typeof rawOverride === 'object' && !Array.isArray(rawOverride)) {
+        const o = asObject(rawOverride);
+        override = {
+            gate: asString(o.gate),
+            reason: asString(o.reason),
+            suppressedReason: asString(o.suppressedReason),
+            who: asString(o.who),
+            when: asString(o.when),
+        };
+    }
+    const statement = {
+        _type: asString(root._type),
+        predicateType: asString(root.predicateType),
+        schemaVersion: typeof root.schemaVersion === 'number' ? root.schemaVersion : Number(root.schemaVersion),
+        subject,
+        predicate: {
+            stage: asString(predicate.stage),
+            plan: asString(predicate.plan),
+            generatedAt: asString(predicate.generatedAt),
+            vault: {
+                state: asString(vault.state),
+                reason: asStringOrNull(vault.reason),
+                ref: asStringOrNull(vault.ref),
+                resolvedSha: asStringOrNull(vault.resolvedSha),
+                // The `notes` parse partner's shape, with the optional-key absent case
+                // made explicit: a present list (even `[]`) reconstructs element by
+                // element; an absent or non-list value reconstructs as null, which is
+                // how the writer spells "no universe was recorded" (degraded run).
+                practiceUniverse: Array.isArray(vault.practiceUniverse)
+                    ? asArray(vault.practiceUniverse).map((v) => asString(v))
+                    : null,
+                // The universe's absent-case rule, applied to a number: a present
+                // integer count (INCLUDING zero) reconstructs as itself; anything else
+                // — absent, a string, a float, a negative — reconstructs as null, which
+                // is how the writer spells "no census was recorded". It is deliberately
+                // NOT coerced with `Number(...)`: a coercion would turn a hand-edited
+                // `checkBearingPractices: none` into `NaN` and a blank into `0`, and
+                // that `0` would be a claim the document never made.
+                checkBearingPractices: typeof vault.checkBearingPractices === 'number' &&
+                    Number.isInteger(vault.checkBearingPractices) &&
+                    vault.checkBearingPractices >= 0
+                    ? vault.checkBearingPractices
+                    : null,
+                tier: asStringOrNull(vault.tier),
+                source: asStringOrNull(vault.source),
+                // VAULT-EGRESS-1: a trace written before the pin was display-safe carries the raw
+                // coordinate; normalised here, at the one parse site every persisted-trace reader shares.
+                repo: vaultMod.redactCloneTarget(asStringOrNull(vault.repo)),
+            },
+            practices,
+            notes: asArray(predicate.notes).map((n) => asString(n)),
+            override,
+        },
+    };
+    return { present: true, reason: null, statement };
+}
+// ─── The validator (Phase 03-04, TRACE-04 / D-09) ─────────────────────────────
+//
+// SCOPE, AND WHY THE SEAM SITS EXACTLY HERE. This validator implements the
+// checks that need NO vault read: the block is there, it parsed, the required
+// keys are present, the pin is non-null when the state is `loaded`, the
+// dispositions cover the emitted id set one-to-one, every status is in the
+// three-value vocabulary, and every `deviated` entry carries a non-empty
+// reason. Plus the version discipline the frozen document states.
+//
+// Phase 3 named TWO checks as belonging to Phase 4 and deliberately did not
+// build them. BOTH are now closed, and the record of what was deferred is kept
+// rather than deleted — a deleted note loses the fact that the gap existed:
+//
+//   1. resolving each practice id against the vault manifest at the pinned SHA
+//      — CLOSED by plan 04-05 (TGATE-01), and closed WITHOUT crossing the seam.
+//      It never needed a vault read: 04-02 recorded the manifest's practice-ID
+//      universe INTO the statement (D-01), so resolution is set membership over
+//      data already in hand. The seam Phase 3 drew — "does the check have to
+//      read the vault" — is exactly what let it close: the answer was no.
+//   2. proving the executor's disposition list covers the planner's — CLOSED by
+//      plan 04-07 (TGATE-01, D-09), and NOT inside this function. It compares
+//      TWO statements, which a single-statement validator cannot do, so the
+//      closure took the form of a SECOND entry point in this leaf,
+//      `comparePracticeCoverage`, which the gate handler composes into its own
+//      verdict. Nothing below compares two statements, and nothing below should.
+//
+// The seam is a PROPERTY OF THE CHECK — whether it has to read the vault — not
+// a judgement about difficulty. Nothing in this region calls the manifest
+// reader or the practice matcher; an integration fence asserts that
+// mechanically over this function's source, and it is what keeps the verdict a
+// function of the record rather than of the machine it ran on.
+//
+// A NOTE ON THE PARSER AND THE REQUIRED-KEY CHECK. `parseVaultTraceBlock`
+// NORMALISES: it always constructs a full statement, filling an absent scalar
+// with `''` or `null`. So on the handler's path a missing key arrives as a
+// present-but-empty one, and the required-key check is not what catches it —
+// the VALUE checks below are (an empty `_type` fails the literal comparison, a
+// null `ref` at `loaded` fails the pin, an empty `status` at execute fails
+// coverage). The required-key list is nonetheless the load-bearing contract
+// surface: it is what `docs/vault-trace-format.md` states, what plan 03-08
+// compares the document against from both ends, and what a caller building a
+// statement by hand — as Phase 4 and Phase 5 will — is checked against.
+/**
+ * The required-key list, per stage, written in the SAME path vocabulary as the
+ * freeze table in `docs/vault-trace-format.md`: the `vault.` prefix is the
+ * frontmatter key, and `[]` means "for every element of that list".
+ *
+ * The two stages differ in exactly one entry each, which is the document's own
+ * plan/execute split: a plan-stage subject entry carries `uri` and no digest
+ * (the governed files do not exist yet), an execute-stage one carries the
+ * `gitCommit` digest that makes the statement falsifiable.
+ *
+ * Keys the document marks **required key** (present, value may be null) are in
+ * this list; keys it marks optional — `reason`, `scope`, `severity`, `tasks`,
+ * `notes` — are not.
+ */
+const TRACE_REQUIRED_KEYS_COMMON = [
+    'vault._type',
+    'vault.predicateType',
+    'vault.schemaVersion',
+    'vault.subject',
+    'vault.subject[].name',
+    'vault.predicate.stage',
+    'vault.predicate.plan',
+    'vault.predicate.generatedAt',
+    'vault.predicate.vault.state',
+    'vault.predicate.vault.reason',
+    'vault.predicate.vault.ref',
+    'vault.predicate.vault.resolvedSha',
+    'vault.predicate.vault.tier',
+    'vault.predicate.vault.source',
+    'vault.predicate.vault.repo',
+    'vault.predicate.practices',
+    'vault.predicate.practices[].id',
+    'vault.predicate.practices[].status',
+    'vault.predicate.override',
+];
+const TRACE_REQUIRED_KEYS = Object.freeze({
+    plan: Object.freeze([...TRACE_REQUIRED_KEYS_COMMON, 'vault.subject[].uri']),
+    execute: Object.freeze([...TRACE_REQUIRED_KEYS_COMMON, 'vault.subject[].digest.gitCommit']),
+});
+/**
+ * The one required key whose failure the generic message could not resolve
+ * (03-REVIEW WR-10). A governed file with no commit yields no digest, so the
+ * execute-stage trace blocks — and the generic message sent the operator back
+ * to the scaffold, which re-emits the same digest-less entry and the same
+ * block, indefinitely.
+ *
+ * The requirement itself is NOT relaxed: the per-stage table is the frozen,
+ * documented contract, and a digest is what makes an execute-stage statement
+ * falsifiable. Only the message changes, and only for this one path.
+ */
+const EXECUTE_DIGEST_KEY = 'vault.subject[].digest.gitCommit';
+const EXECUTE_DIGEST_REMEDY = ' A governed file in this trace has no git commit, so no digest could be recorded.' +
+    ' Commit the governed file first, then re-run the execute-stage trace scaffold —' +
+    ' re-running the scaffold against an uncommitted file produces the same digest-less' +
+    ' entry and the same block.';
+/**
+ * The command that regenerates a trace block, named in any failure message that
+ * has a regeneration remedy.
+ *
+ * D-12: the execute-side gate runs in the ORCHESTRATOR, after the SUMMARY has
+ * been rescued out of the executor's worktree and before wave cleanup. By then
+ * the worktree that wrote the artifact is gone, so the remedy can never be
+ * phrased as re-running or asking whoever produced it — it has to be something
+ * the orchestrator can do on its own, against the file named in the message.
+ *
+ * ONE constant, so the plan that ships the writer changes it in one place. It
+ * lives in this leaf rather than in the gate handler (04-05) because the
+ * validator now needs it too, and the handler already imports this module —
+ * the reverse edge would be a cycle (the D-12 split's own lesson).
+ *
+ * The remedy names `pp_run`, the launcher every workflow binds in its
+ * preamble and ships as `pp-core/bin/pp_run`, because a bare `pp-tools` can
+ * resolve to a different install than the project's own. INVARIANT 1 derives
+ * its floor from the command's first token, so the floor moved with the rename.
+ * The literal pins live in the two vault-trace suites and vault-status-check.
+ */
+const TRACE_REGENERATE_COMMAND = 'pp_run vault trace scaffold --stage <plan|execute> --plan <plan-id> <files_modified...>';
+/**
+ * Stable, machine-readable problem kinds. A consumer branches on these; the
+ * `detail` string is for a human and is not a contract.
+ *
+ * The two coverage directions carry DIFFERENT kinds on purpose: "an emitted id
+ * has no disposition" and "a disposition names an id nobody emitted" are two
+ * defects with two different fixes, and collapsing them into one message makes
+ * the second unfixable.
+ */
+const TRACE_PROBLEM_KIND = Object.freeze({
+    ABSENT: 'trace_absent',
+    UNPARSABLE: 'trace_unparsable',
+    MALFORMED_INPUT: 'trace_malformed_input',
+    MISSING_REQUIRED_KEY: 'missing_required_key',
+    STAGE_MISMATCH: 'stage_mismatch',
+    STATEMENT_TYPE_MISMATCH: 'statement_type_mismatch',
+    PREDICATE_TYPE_MISMATCH: 'predicate_type_mismatch',
+    SCHEMA_VERSION_INVALID: 'schema_version_invalid',
+    SCHEMA_VERSION_UNSUPPORTED: 'schema_version_unsupported',
+    VAULT_STATE_INVALID: 'vault_state_invalid',
+    PIN_MISSING: 'pin_missing',
+    // 04-05 (TGATE-01, D-01): the statement-shape sibling of PIN_MISSING, and it
+    // sits here beside it rather than with the practice-entry family because the
+    // defect is of the RECORD AS A WHOLE — this trace is incomplete — not of any
+    // one entry. It arises from the same read as the pin: a loaded run that wrote
+    // a pin but no universe recorded half of what it saw. Filing it against an
+    // entry would mean naming an offending id, and there is none to name — every
+    // id is equally unresolvable when the universe is absent.
+    UNIVERSE_MISSING: 'practice_universe_missing',
+    // 04-07 (TGATE-01, D-03): the statement-shape sibling of PIN_MISSING and
+    // UNIVERSE_MISSING, and — uniquely in this table — ADVISORY. The handler
+    // classifies it so, and it must NEVER contribute to a block.
+    //
+    // WHY ADVISORY, ARGUED. Whether the vault has MOVED since this trace was
+    // written is a different question from whether this trace is VALID. The
+    // statement is self-verifying: it carries its own pin and its own universe,
+    // so its verdict is a function of the record rather than of the machine that
+    // happens to hold a cache. A blocking divergence would invert that — every
+    // machine whose cache advanced past the pin would fail its build for a fact
+    // about the cache, not about the artifact. D-03's binding content is "a note,
+    // never a block", and this member is that note's carrier.
+    //
+    // It is a ROUTER-side emission, never a validator one: detecting it requires
+    // reading the local manifest, and FENCE 1 asserts the validator reads no
+    // manifest. The kind lives here because this table owns STATEMENT-LEVEL kinds
+    // — defects of a trace statement, which is what `pin_diverged` names — not
+    // because the validator emits it.
+    //
+    // 04-11 CORRECTS THE CLAIM THAT USED TO SIT HERE. It read: "the table is the
+    // one home for a machine-readable kind". That was never true — the gate
+    // handler emitted nine ENVELOPE kinds as inline string literals with no table
+    // at all, and this comment's confidence was part of why nobody noticed. There
+    // are now two tables and the split is BY CATEGORY:
+    //
+    //   - this one owns kinds that describe a STATEMENT: its shape, its version
+    //     discipline, its pin, its ledger entries, and the comparison of two
+    //     statements against each other;
+    //   - `TRACE_HANDLER_KIND` (src/check-command-router.cts) owns kinds that
+    //     describe the ARGUMENT the gate was invoked with, or the artifact SET it
+    //     found — neither of which a statement validator can see, because it is
+    //     handed one statement at a time and no argv at all.
+    //
+    // Stated as a category, and NO MEMBER of the other table is named here. A
+    // list of the router's kinds inside a leaf comment is a stale claim waiting
+    // to happen, and a stale list of somewhere else's kinds is the exact defect
+    // 04-11 exists to stop repeating.
+    PIN_DIVERGED: 'pin_diverged',
+    COVERAGE_MISSING_DISPOSITION: 'coverage_missing_disposition',
+    COVERAGE_UNKNOWN_DISPOSITION: 'coverage_unknown_disposition',
+    COVERAGE_DUPLICATE_ID: 'coverage_duplicate_id',
+    // 04-07 (TGATE-01, TGATE-03, D-09): the coverage family's THIRD direction,
+    // and the first one that spans TWO artifacts. The two members above compare
+    // an emitted set against a disposition set INSIDE one statement; this one
+    // asks whether the executor's record accounts for the planner's, plan by
+    // plan. One problem PER uncovered identifier, and filed against the SUMMARY —
+    // the plan is not the file an operator has to fix.
+    //
+    // A PHASE AGGREGATE WAS REJECTED, and the reason belongs here beside the
+    // member: an aggregate union passes VACUOUSLY. If one plan dropped every
+    // practice while a sibling happened to carry the same identifiers, the union
+    // still covers, and a gate that cannot fail is not a gate. It also cannot
+    // satisfy TGATE-03, which requires naming the file to fix — an aggregate has
+    // no file to name.
+    COVERAGE_PLAN_UNCOVERED: 'coverage_plan_uncovered',
+    // 04-07 (TGATE-01, D-10): a plan statement with no summary counterpart at
+    // all. Coverage family, because "nothing covered any of it" is the limiting
+    // case of the member above rather than a different defect.
+    //
+    // Emitted only where the CALLER declares the point strict. Mid-phase an
+    // unpaired plan is normal — waves are still running and the execute-side
+    // point fires once per wave — so a gate that always emitted this would have
+    // blocked Phase 3 continuously across all seven of its waves. At `ship:pre`
+    // and `verify:post` every plan must have an executed counterpart, and a phase
+    // shipping with a planned-but-never-executed plan is a real defect this gate
+    // can see cheaply.
+    COVERAGE_PAIR_MISSING: 'coverage_pair_missing',
+    // 04-07 (TGATE-01, D-11): the pair exists but the summary was generated
+    // STRICTLY BEFORE its plan — a re-planned plan whose summary answers an
+    // earlier version of it. Its own defect, not a coverage gap: the identifiers
+    // may all match and the record still prove nothing.
+    //
+    // CR-02's lesson binds this member's DETAIL, not just its existence. Phase 3
+    // shipped a block of exactly this shape whose message named no remedy the
+    // reader could perform, and it had to be fixed. So the detail extends the
+    // single `TRACE_REGENERATE_COMMAND` constant and is phrased for the
+    // ORCHESTRATOR: at the execute-side point the executor's worktree is already
+    // gone, and a remedy addressed to whoever wrote the artifact is a trap.
+    COVERAGE_PAIR_STALE: 'coverage_pair_stale',
+    // 04-13 (TGATE-01, CR-01): the pair family's FOURTH member, and the one that
+    // closes this phase's own fail-open. A pair whose halves are both present and
+    // both well-formed can still prove nothing. If either half records a vault
+    // state other than `loaded`, the ledger answering the plan was written
+    // against a vault that was never read — so an empty ledger and a complete one
+    // are indistinguishable, and the two judgements above are both vacuous.
+    // Until this member the comparison returned early on that state with no
+    // problem of any kind, so the strict `ship:pre` and `verify:post` gates
+    // answered `block: false` with ZERO problems over a record accounting for
+    // nothing, and the phase shipped recorded as governed.
+    //
+    // A DEFECT OF THE PAIR — argued, not asserted, which is why it sits here
+    // beside COVERAGE_PAIR_MISSING and COVERAGE_PAIR_STALE.
+    //
+    //   - NOT the practice-entry family. An unprovable pair names NO offending
+    //     identifier, because when the answering half proved nothing every
+    //     identifier is equally unaccounted for. Filing one problem per promised
+    //     id would hand an operator N things to chase for ONE cause, and point
+    //     each of them at a ledger section where the fix does not live.
+    //   - NOT the statement-shape family. Neither half is malformed: each is a
+    //     CORRECT record of what really happened (D-04), and Phase 3 requires a
+    //     degraded run to write exactly this record. Filing it against a
+    //     statement would say the record is wrong when the record is right.
+    //   - It IS the relation that fails: this summary cannot answer this plan.
+    //     That is the same category as "there is no summary" and "the summary
+    //     answers an earlier plan", and it is one problem per PAIR for the same
+    //     reason those are.
+    //
+    // EMITTED ONLY UNDER THE STRICT MODE, on COVERAGE_PAIR_MISSING's reasoning
+    // exactly (D-10). At the two write points the question is whether the record
+    // is CORRECT, and a degraded record is correct. At `ship:pre` and
+    // `verify:post` the question is whether it PROVES the phase was governed, and
+    // it does not. One artifact, two questions, one flag already parsed for the
+    // sibling member above — see the state gate in `comparePracticeCoverage` for
+    // the whole argument, including the remedy asymmetry that makes the strict
+    // arm a gate rather than a trap.
+    COVERAGE_PAIR_UNPROVABLE: 'coverage_pair_unprovable',
+    // 03-REVIEW CR-03: the READ path's half of the charset the write path has
+    // always applied. Sits with the practice-entry family because it is a defect
+    // of one entry, not of the statement's shape.
+    ID_CHARSET_INVALID: 'practice_id_invalid',
+    // 04-05 (TGATE-01, D-01): the read side's verdict on the universe 04-02 put
+    // into the statement. Sits with the practice-entry family beside the charset
+    // kind — and for the same reason CR-03 put that one here — because it is a
+    // defect of ONE entry: this id, in this ledger, resolves nowhere. That
+    // entry-level placement is what lets the detail name the id at fault, which
+    // is TGATE-03's core clause and is only possible at all because D-02 chose an
+    // id LIST over a digest: a digest could prove disagreement but never say
+    // which id caused it.
+    ID_UNRESOLVED: 'practice_id_unresolved',
+    STATUS_OUT_OF_VOCABULARY: 'status_out_of_vocabulary',
+    DEVIATED_REASON_MISSING: 'deviated_reason_missing',
+    // ── THE BODY-BLOCK FAMILY (D-05-07) ────────────────────
+    //
+    // Seven kinds that compare the `vault:` LEDGER against the `<vault_practices>`
+    // BODY BLOCK of the same plan artifact. Measured on a fresh project: seven
+    // perturbations that removed or
+    // gutted the body block — the only practice text the executor reads — all
+    // answered `block: false`, because nothing read the block back. A plan could
+    // record full governance and deliver none. These kinds end that silence.
+    //
+    // WHY THE LEAF TABLE. They are defects of ONE artifact's record — its two
+    // halves disagree — not of the argument the gate was invoked with nor of the
+    // artifact SET, which is the category split the two tables draw. The body is
+    // read by `validatePracticesBody`, which is handed the artifact text and the
+    // parsed statement and nothing else: no manifest, no matcher, no disk (D-01).
+    //
+    // ONE-PER-ARTIFACT vs ONE-PER-ID, argued. `absent`, `duplicate`,
+    // `state_mismatch` and `empty` are facts about the block as a whole and name
+    // no identifier, so each is
+    // emitted once and the per-id checks are skipped behind it — a block that
+    // renders nothing would otherwise yield one problem per promised id for ONE
+    // cause (the COVERAGE_PAIR_UNPROVABLE argument). The id and text kinds name
+    // the identifier at fault, one problem each (TGATE-03).
+    //
+    // ALL SEVEN BLOCK. None is advisory: each means the executor is handed less
+    // than, or other than, what the ledger records, which is exactly a record
+    // claiming more governance than was delivered.
+    PRACTICES_BLOCK_ABSENT: 'practices_block_absent',
+    PRACTICES_BLOCK_DUPLICATE: 'practices_block_duplicate',
+    // The block states the vault was NOT read (the absent / unreadable /
+    // could-not-be-checked sentence) while the ledger records `state: loaded`.
+    // Its own kind rather than a clause on `empty`, because it fires whatever the
+    // ledger promises — including nothing — and names a different repair target:
+    // the two halves disagree about the RUN, not merely about a count.
+    PRACTICES_BLOCK_STATE_MISMATCH: 'practices_block_state_mismatch',
+    PRACTICES_BLOCK_EMPTY: 'practices_block_empty',
+    PRACTICES_BLOCK_ID_MISSING: 'practices_block_id_missing',
+    PRACTICES_BLOCK_ID_UNEXPECTED: 'practices_block_id_unexpected',
+    PRACTICES_BLOCK_TEXT_MISMATCH: 'practices_block_text_mismatch',
+    VALIDATOR_ERROR: 'validator_error',
+});
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Does `obj` own every segment of a dotted path with no `[]` in it? */
+function hasPlainPath(obj, dotted) {
+    if (dotted === '')
+        return isPlainObject(obj);
+    let cursor = obj;
+    for (const seg of dotted.split('.')) {
+        if (!isPlainObject(cursor))
+            return false;
+        if (!Object.prototype.hasOwnProperty.call(cursor, seg))
+            return false;
+        cursor = cursor[seg];
+    }
+    return true;
+}
+function readPlainPath(obj, dotted) {
+    if (dotted === '')
+        return obj;
+    let cursor = obj;
+    for (const seg of dotted.split('.')) {
+        if (!isPlainObject(cursor))
+            return undefined;
+        cursor = cursor[seg];
+    }
+    return cursor;
+}
+/**
+ * Presence of one required-key path against a statement. The `vault.` prefix is
+ * stripped because it names the frontmatter key, not a key of the statement.
+ *
+ * An EMPTY list satisfies a `[]` path vacuously and deliberately: the document
+ * says `subject: []` is legal for a doc-only plan, and requiring `name` of a
+ * list with no elements would reject that legal shape.
+ */
+function hasRequiredKey(statement, docPath) {
+    const rel = docPath.replace(/^vault\.?/, '');
+    const arrIdx = rel.indexOf('[]');
+    if (arrIdx === -1)
+        return hasPlainPath(statement, rel);
+    const head = rel.slice(0, arrIdx);
+    const tail = rel.slice(arrIdx + 2).replace(/^\./, '');
+    const arr = readPlainPath(statement, head);
+    if (!Array.isArray(arr))
+        return false;
+    if (tail === '')
+        return true;
+    return arr.every((el) => hasPlainPath(el, tail));
+}
+/** A short, bounded rendering of an arbitrary value for a problem detail. */
+function describeValue(v) {
+    if (v === null)
+        return 'null';
+    if (v === undefined)
+        return 'absent';
+    if (typeof v === 'string')
+        return v.length > 120 ? `${v.slice(0, 120)}…` : v;
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    if (Array.isArray(v))
+        return `a list of ${v.length}`;
+    return 'an object';
+}
+/**
+ * A statement that reached the parser but from which nothing was read. The
+ * parser NORMALISES an unreadable block into a full-shaped statement with empty
+ * scalars, so "did not parse" cannot be detected from key presence — it is
+ * detected from every identifying value being empty at once. A genuine
+ * statement always carries `_type`.
+ */
+function statementReadNothing(st) {
+    const predicate = isPlainObject(st['predicate']) ? st['predicate'] : {};
+    const subject = st['subject'];
+    const practices = predicate['practices'];
+    return ((st['_type'] ?? '') === '' &&
+        (st['predicateType'] ?? '') === '' &&
+        (predicate['stage'] ?? '') === '' &&
+        (predicate['plan'] ?? '') === '' &&
+        (!Array.isArray(subject) || subject.length === 0) &&
+        (!Array.isArray(practices) || practices.length === 0));
+}
+/**
+ * Validate a trace statement against the structure-and-pin half of the contract
+ * (D-09). NEVER throws, for any input: this sits on the read path for an
+ * attacker-influenceable document, handlers in this repository never throw, and
+ * a handler is what calls this.
+ *
+ * Returns EVERY defect rather than the first — an operator fixing a trace wants
+ * the whole list at once, and Phase 4's gate output builds on the same list.
+ *
+ * @param input   A statement, a `parseVaultTraceBlock` result, or nothing.
+ * @param options `stage` is the stage being validated; `file` names the
+ *                artifact in every problem; `dispositions` supplies the
+ *                judgment half when the caller holds it separately.
+ */
+function validateTraceStatement(input, options) {
+    const opts = isPlainObject(options) ? options : {};
+    const file = typeof opts.file === 'string' && opts.file !== '' ? opts.file : 'the artifact';
+    const stage = typeof opts.stage === 'string' ? opts.stage : '';
+    const problems = [];
+    // `tail` is optional and is omitted from the pushed object when absent, so a
+    // problem that carries no remedy is byte-identical to what it was before the
+    // field existed — an `undefined` property would change every deepEqual in
+    // every consumer for no behavioural gain.
+    const add = (kind, detail, tail) => {
+        problems.push(tail === undefined ? { file, kind, detail } : { file, kind, detail, tail });
+    };
+    try {
+        // ── the block is there at all (D-11: a hard cut, no grandfather clause) ──
+        let statement = input;
+        if (isPlainObject(input) && typeof input['present'] === 'boolean' && 'statement' in input) {
+            if (input['present'] !== true) {
+                add(TRACE_PROBLEM_KIND.ABSENT, `${file} carries no \`${TRACE_BLOCK_KEY}:\` trace block. A vault-enabled phase records its practice trace in every plan artifact; there is no backfill path and no pre-schema exemption.`);
+                return { block: true, problems };
+            }
+            statement = input['statement'];
+        }
+        if (statement === null || statement === undefined) {
+            add(TRACE_PROBLEM_KIND.ABSENT, `${file} carries no \`${TRACE_BLOCK_KEY}:\` trace block. A vault-enabled phase records its practice trace in every plan artifact; there is no backfill path and no pre-schema exemption.`);
+            return { block: true, problems };
+        }
+        if (!isPlainObject(statement)) {
+            add(TRACE_PROBLEM_KIND.MALFORMED_INPUT, `the \`${TRACE_BLOCK_KEY}:\` block in ${file} is not a mapping (found ${describeValue(statement)}).`);
+            return { block: true, problems };
+        }
+        // ── it parsed ──
+        if (statementReadNothing(statement)) {
+            add(TRACE_PROBLEM_KIND.UNPARSABLE, `the \`${TRACE_BLOCK_KEY}:\` block in ${file} is present but nothing could be read from it — no statement type, no stage and no practice entries parsed. The block is unreadable, which is NOT the same as an empty practice set.`);
+            return { block: true, problems };
+        }
+        // ── required keys present ──
+        const requiredKeys = stage === 'plan' || stage === 'execute'
+            ? TRACE_REQUIRED_KEYS[stage]
+            : TRACE_REQUIRED_KEYS.plan;
+        for (const docPath of requiredKeys) {
+            if (!hasRequiredKey(statement, docPath)) {
+                add(TRACE_PROBLEM_KIND.MISSING_REQUIRED_KEY, `required key ${docPath} is missing from the trace in ${file}.` +
+                    (docPath === EXECUTE_DIGEST_KEY ? EXECUTE_DIGEST_REMEDY : ''));
+            }
+        }
+        // ── version discipline (TRACE-05) ──
+        // An unknown OPTIONAL key is never inspected, and that silence is the point:
+        // it is what makes an additive minor change non-breaking for the Phase 4 and
+        // Phase 5 consumers. An unexpected MAJOR marker, by contrast, fails loudly
+        // and names both values — a consumer silently accepting a future major is
+        // the failure mode the whole freeze exists to prevent.
+        if (statement['_type'] !== TRACE_STATEMENT_TYPE) {
+            add(TRACE_PROBLEM_KIND.STATEMENT_TYPE_MISMATCH, `_type must be exactly "${TRACE_STATEMENT_TYPE}"; found "${describeValue(statement['_type'])}".`);
+        }
+        const acceptedTypes = [
+            TRACE_PREDICATE_TYPE,
+            ...(Array.isArray(opts.acceptedPredicateTypes)
+                ? opts.acceptedPredicateTypes.filter((t) => typeof t === 'string' && t !== '')
+                : []),
+        ];
+        if (!acceptedTypes.includes(statement['predicateType'])) {
+            add(TRACE_PROBLEM_KIND.PREDICATE_TYPE_MISMATCH, `predicateType must be exactly "${TRACE_PREDICATE_TYPE}"` +
+                (acceptedTypes.length > 1 ? ` or one of the ${acceptedTypes.length - 1} the org profile accepts` : '') +
+                `; found "${describeValue(statement['predicateType'])}". The URI carries the MAJOR version — this reader is pinned to it and will not silently accept another.`);
+        }
+        const schemaVersion = statement['schemaVersion'];
+        if (typeof schemaVersion !== 'number' || !Number.isInteger(schemaVersion)) {
+            add(TRACE_PROBLEM_KIND.SCHEMA_VERSION_INVALID, `schemaVersion must be an integer; found "${describeValue(schemaVersion)}".`);
+        }
+        else if (schemaVersion > TRACE_SCHEMA_VERSION) {
+            add(TRACE_PROBLEM_KIND.SCHEMA_VERSION_UNSUPPORTED, `schemaVersion ${schemaVersion} is above the highest version this reader knows (${TRACE_SCHEMA_VERSION}). A newer major is refused loudly rather than read as if it were understood.`);
+        }
+        const predicate = isPlainObject(statement['predicate']) ? statement['predicate'] : {};
+        // The stage is the one field that tells the two traces apart, so a required
+        // key whose value could be anything would not be a required key in any
+        // useful sense. Validated against the stage the caller asked for.
+        if (stage === 'plan' || stage === 'execute') {
+            if (predicate['stage'] !== stage) {
+                add(TRACE_PROBLEM_KIND.STAGE_MISMATCH, `predicate.stage must be "${stage}" for this artifact; found "${describeValue(predicate['stage'])}".`);
+            }
+        }
+        // ── the pin, scoped to a LOADED state ──
+        // A degraded statement legitimately carries a null pin (D-04), and a stale
+        // cache is degraded WITH a live pin. A validator that checked the pin
+        // unconditionally would reject exactly the record D-04 exists to produce.
+        const vaultBlock = isPlainObject(predicate['vault']) ? predicate['vault'] : {};
+        const vaultState = vaultBlock['state'];
+        if (vaultState !== 'loaded' && vaultState !== 'degraded') {
+            add(TRACE_PROBLEM_KIND.VAULT_STATE_INVALID, `predicate.vault.state must be "loaded" or "degraded"; found "${describeValue(vaultState)}".`);
+        }
+        else if (vaultState === 'loaded') {
+            for (const half of ['ref', 'resolvedSha']) {
+                const value = vaultBlock[half];
+                if (typeof value !== 'string' || value.trim() === '') {
+                    add(TRACE_PROBLEM_KIND.PIN_MISSING, `predicate.vault.${half} must be non-null when predicate.vault.state is "loaded"; found "${describeValue(value)}". Without both halves of the pin nothing about this run is provable.`);
+                }
+            }
+        }
+        // ── the practice entries: vocabulary, deviated reasons, coverage ──
+        const practices = Array.isArray(predicate['practices']) ? predicate['practices'] : [];
+        const emittedIds = [];
+        const seenIds = new Set();
+        const duplicateIds = new Set();
+        const decidedIds = new Set();
+        for (const raw of practices) {
+            const entry = isPlainObject(raw) ? raw : {};
+            const id = typeof entry['id'] === 'string' ? entry['id'] : '';
+            // 03-REVIEW CR-03: the charset the write path has always applied, applied
+            // here too. `docs/vault-trace-format.md` states as a FACT that the id is
+            // "bounded, charset-validated, and always emitted quoted"; without this
+            // the claim held only where the engine writes an id, and a ledger whose
+            // id was a whole English sentence validated clean (T-03-31).
+            //
+            // Reads ONLY the module-local pattern — nothing on disk, and nothing from
+            // the vault. Resolving an id against the manifest is Phase 4's.
+            //
+            // Deliberately does NOT `continue`: the entry still joins the duplicate
+            // and coverage sets below, because suppressing it would turn one defect
+            // into a second, quieter one.
+            if (typeof entry['id'] !== 'string' || !TRACE_ID_PATTERN.test(entry['id'])) {
+                add(TRACE_PROBLEM_KIND.ID_CHARSET_INVALID, `practice id "${collapseControlChars(boundedToken(entry['id']))}" is not in the permitted charset (alphanumerics plus . _ -, first character alphanumeric, max 64).`);
+            }
+            emittedIds.push(id);
+            if (seenIds.has(id))
+                duplicateIds.add(id);
+            seenIds.add(id);
+            const status = entry['status'];
+            const statusText = typeof status === 'string' ? status : '';
+            const inVocabulary = TRACE_STATUS_VALUES.includes(statusText);
+            // The empty string is the documented PLAN-stage value — the slot the
+            // executor fills in later — so it is not an out-of-vocabulary word there.
+            const emptyIsLegal = stage !== 'execute';
+            if (!inVocabulary && !(statusText === '' && emptyIsLegal)) {
+                add(TRACE_PROBLEM_KIND.STATUS_OUT_OF_VOCABULARY, `practice "${id}" carries status "${describeValue(status)}", which is not one of ${TRACE_STATUS_VALUES.join(', ')}.`);
+            }
+            if (inVocabulary)
+                decidedIds.add(id);
+            if (statusText === 'deviated') {
+                const reason = entry['reason'];
+                if (typeof reason !== 'string' || reason.trim() === '') {
+                    add(TRACE_PROBLEM_KIND.DEVIATED_REASON_MISSING, `practice "${id}" is recorded as deviated with no reason. A deviation without a stated reason is indistinguishable from a practice that was never considered.`);
+                }
+            }
+        }
+        for (const dup of duplicateIds) {
+            add(TRACE_PROBLEM_KIND.COVERAGE_DUPLICATE_ID, `practice id "${dup}" appears more than once in the emitted set, so its disposition is ambiguous.`);
+        }
+        // ── identifier resolution, scoped to a LOADED state (04-05, TGATE-01) ────
+        //
+        // A PURE SET OPERATION over data already in the statement. The universe is
+        // an INPUT — 04-02 recorded it from the SAME vault read that produced the
+        // pin — and is never re-derived here. A validator that went to disk for it
+        // would make the verdict a function of the machine it ran on rather than of
+        // the record, which is precisely the environment-dependence D-01 was
+        // written to remove: the same trace must yield the same verdict on any
+        // machine, with or without a cache. Nothing below opens a file, spawns a
+        // process, reads an environment variable or consults the practice matcher.
+        //
+        // SUPPRESSED — not failed, and not silently skipped — when the state is not
+        // `loaded`, on the pin check's reasoning verbatim. A degraded run
+        // legitimately carries a null pin and no universe (D-04), and Phase 3
+        // REQUIRES such a run to write a trace recording the degraded state and its
+        // reason. The miss is therefore already a recorded fact in the artifact; a
+        // validator that additionally rejected the record would be rejecting a
+        // correct record of a real failure. What keeps this from being an escape
+        // hatch is the other half 04-02 pinned: the state is derived by the CLI
+        // from the vault fixture and cannot be selected through any
+        // statement-builder option.
+        if (vaultState === 'loaded') {
+            const universe = vaultBlock['practiceUniverse'];
+            if (!Array.isArray(universe)) {
+                // Fail closed, on the posture the handler already holds at its
+                // unresolved-phase branch: a check that proved nothing must not read as
+                // a check that passed. Unreachable from the shipped writer — every
+                // loaded statement it emits carries a universe (04-02) — so this names
+                // a hand-authored statement, and the remedy is one the reader can
+                // perform without the worktree that wrote the artifact.
+                //
+                // 04-11 (CR-05): the remedy is the TAIL, never the head. The head names
+                // the artifact — an untrusted, unbounded-in-practice path — and the
+                // whole of that sentence used to be followed by the command inside a
+                // single 400-character budget. A 138-character artifact path, which is
+                // an ordinary workstream phase path rather than a hostile one, printed
+                // a PARTIAL command an orchestrator agent could run.
+                add(TRACE_PROBLEM_KIND.UNIVERSE_MISSING, `the trace in ${file} records no practice-identifier universe (predicate.vault.practiceUniverse), so no identifier it lists can be resolved and the ledger proves nothing.`, ` Regenerate the trace in place: ${TRACE_REGENERATE_COMMAND}`);
+            }
+            else {
+                // Built ONCE per validation rather than scanned per id: a linear scan
+                // per identifier turns a large universe into a quadratic walk (T-4-22).
+                const universeIds = new Set(universe.filter((v) => typeof v === 'string'));
+                // `seenIds` is the emitted set already de-duplicated, so a duplicated
+                // unresolvable id yields one problem, not one per occurrence — the
+                // duplication is its own defect above and has its own kind.
+                for (const id of seenIds) {
+                    if (universeIds.has(id))
+                        continue;
+                    // ONE problem PER unresolved id, never one aggregate: the detail has
+                    // to name the id at fault (TGATE-03), and a single problem standing
+                    // for three broken ids makes the problem count meaningless.
+                    add(TRACE_PROBLEM_KIND.ID_UNRESOLVED, `practice id "${collapseControlChars(boundedToken(id))}" is not in the practice-identifier universe this trace records for the vault at its pinned SHA, so it resolves to no practice.`);
+                }
+            }
+        }
+        // The 1:1 coverage check runs at EXECUTE stage: at plan stage nothing has
+        // been decided yet by design, so every id would read as uncovered.
+        if (stage === 'execute') {
+            const supplied = Array.isArray(opts.dispositions) ? opts.dispositions : null;
+            const dispositionIds = supplied
+                ? new Set(supplied.map((d) => (isPlainObject(d) && typeof d['id'] === 'string' ? d['id'] : '')))
+                : decidedIds;
+            const emittedSet = new Set(emittedIds);
+            const uncovered = [...emittedSet].filter((id) => !dispositionIds.has(id));
+            if (uncovered.length > 0) {
+                add(TRACE_PROBLEM_KIND.COVERAGE_MISSING_DISPOSITION, `these practice ids are in the emitted set with no recorded disposition: ${uncovered.map((id) => `"${id}"`).join(', ')}.`);
+            }
+            const unknown = [...dispositionIds].filter((id) => !emittedSet.has(id));
+            if (unknown.length > 0) {
+                add(TRACE_PROBLEM_KIND.COVERAGE_UNKNOWN_DISPOSITION, `these dispositions name a practice id the emitted set does not contain: ${unknown.map((id) => `"${id}"`).join(', ')}.`);
+            }
+        }
+        return { block: problems.length > 0, problems };
+    }
+    catch (e) {
+        // Totality is the contract, not a courtesy: a throw here would turn a
+        // halt-on-error gate into a permanently stopped build (T-03-16).
+        return {
+            block: true,
+            problems: [
+                {
+                    file,
+                    kind: TRACE_PROBLEM_KIND.VALIDATOR_ERROR,
+                    detail: `the trace validator could not complete: ${boundedToken(String(e?.message ?? e))}`,
+                },
+            ],
+        };
+    }
+}
+/** The vault state a statement records, or `''` when it records none. */
+function traceVaultStateOf(statement) {
+    if (!isPlainObject(statement))
+        return '';
+    const predicate = isPlainObject(statement['predicate']) ? statement['predicate'] : {};
+    const vault = isPlainObject(predicate['vault']) ? predicate['vault'] : {};
+    return typeof vault['state'] === 'string' ? vault['state'] : '';
+}
+/**
+ * The degraded reason a statement records, or `''` (04-13).
+ *
+ * The fifth sibling of the four accessors around it, in their register and
+ * with their defensive shape: every hop is type-checked, and a statement that
+ * carries none of them yields the empty string rather than throwing. The
+ * comparison never throws, so nothing it calls may either.
+ */
+function traceVaultReasonOf(statement) {
+    if (!isPlainObject(statement))
+        return '';
+    const predicate = isPlainObject(statement['predicate']) ? statement['predicate'] : {};
+    const vault = isPlainObject(predicate['vault']) ? predicate['vault'] : {};
+    return typeof vault['reason'] === 'string' ? vault['reason'] : '';
+}
+/** The non-empty practice identifiers a statement emits, in recorded order. */
+function traceEmittedIdsOf(statement) {
+    if (!isPlainObject(statement))
+        return [];
+    const predicate = isPlainObject(statement['predicate']) ? statement['predicate'] : {};
+    const practices = Array.isArray(predicate['practices']) ? predicate['practices'] : [];
+    const out = [];
+    for (const raw of practices) {
+        const entry = isPlainObject(raw) ? raw : {};
+        const id = entry['id'];
+        if (typeof id === 'string' && id !== '')
+            out.push(id);
+    }
+    return out;
+}
+/** The plan identifier a statement records, or `''`. */
+function tracePlanIdOf(statement) {
+    if (!isPlainObject(statement))
+        return '';
+    const predicate = isPlainObject(statement['predicate']) ? statement['predicate'] : {};
+    return typeof predicate['plan'] === 'string' ? predicate['plan'] : '';
+}
+/** The generation timestamp a statement records, or `''`. */
+function traceGeneratedAtOf(statement) {
+    if (!isPlainObject(statement))
+        return '';
+    const predicate = isPlainObject(statement['predicate']) ? statement['predicate'] : {};
+    return typeof predicate['generatedAt'] === 'string' ? predicate['generatedAt'] : '';
+}
+/**
+ * The performable remedy for an unprovable pair, as a TRUSTED TAIL (04-13).
+ *
+ * TWO ROUTES, ALWAYS BOTH, AND THAT IS THE WHOLE POINT. Phase 3's CR-02
+ * established that a block naming no remedy the reader can perform is a trap,
+ * and this block is emitted on SEVEN distinct degraded causes that do not behave
+ * the same way. Read from the pin resolver above rather than from memory:
+ *
+ *   - no vault cache directory, an absent manifest, an unreadable or malformed
+ *     manifest — and a stale cache whenever the vault is REACHABLE. Three (and
+ *     a half) causes a re-fetch clears: the strict points run on the main
+ *     checkout, so regenerating really does produce a loaded statement.
+ *   - a recorded MISS, and a stale cache whose refresh FAILS. Two causes
+ *     regeneration cannot clear at all: the fetch itself failed on credentials,
+ *     network or an unreachable repository, so re-fetching reproduces the miss
+ *     and regenerating reproduces the identical record. A tail offering only
+ *     "regenerate" would be CR-02's trap reintroduced on exactly these two.
+ *
+ *   - a load at a tier that is not `client` (D-08-25). The sixth cause, and
+ *     the one NEITHER route above clears on its own: the vault was reached,
+ *     freshly and successfully, and it was the wrong vault. Re-fetching
+ *     reproduces the same tier and regenerating reproduces the same record,
+ *     because the project's own `client.vaultRepo` / `client.vaultRef` point
+ *     where they point. Its lead therefore names the configuration edit.
+ *
+ *   - a client-tier cache fetched from a ref other than the configured
+ *     `client.vaultRef` (D-08-34, UAT F5). The seventh cause, and it needs NO
+ *     fourth lead: `vault fetch` reads the CONFIGURED ref, so a successful
+ *     fetch genuinely replaces the drifted cache and the default re-fetch lead
+ *     clears it. It reproduces only when that ref cannot be fetched — the same
+ *     "and a half" the stale cause already carries — and the tail names the
+ *     disable route in every case regardless. So its reason is phrased OUTSIDE
+ *     all three classifier substrings below, deliberately, and lands on the
+ *     re-fetch-first lead (D-08-36).
+ *
+ * So ALL THREE tails name BOTH routes, and the second route — turning the practices
+ * capability off for this project, a local `.planning/config.json` edit — is
+ * performable with the vault down, from the same checkout the gate ran in.
+ * There is no third route: nothing overrides this kind.
+ *
+ * WHAT THE CLASSIFIER DOES, AND WHAT IT DELIBERATELY CANNOT DO. It reads the
+ * recorded reason only to choose which route to state FIRST, so a reader on the
+ * unreachable arm is not sent to re-run a command that will come back
+ * identical. It selects between three FIXED strings; nothing from the artifact is
+ * interpolated, so a hand-edited or hostile reason can change the emphasis and
+ * can never change what is offered. Misclassification therefore costs an
+ * operator one sentence of reading order, never a performable remedy — which is
+ * why a substring probe over our own generated prose is an acceptable
+ * mechanism here and would not be if it gated the routes themselves.
+ */
+function unprovablePairTail(reason) {
+    // THREE leads for SEVEN causes now (D-08-25, then D-08-34). The tier cause is tested FIRST
+    // because it is the only one neither existing lead describes: the vault was
+    // reached, freshly, successfully — at the WRONG TIER. Regenerating alone
+    // reproduces it (the scaffold reads the cache, it does not fetch), and so
+    // does restoring reachability (the shared vault was already reachable; that
+    // is how it loaded). The project is pointed at the wrong vault, and only a
+    // configuration edit moves it — which is why this lead names the key.
+    //
+    // A stale FALLBACK cache lands here rather than on the unreachable lead,
+    // because `resolvePin` returns the tier reason ahead of the stale one: the
+    // tier is the stronger fact and its remedy is the one that clears both.
+    //
+    // THE LEAD IS LENGTH-BUDGETED, NOT PHRASED TO TASTE, AND THE BUDGET WAS
+    // MEASURED RATHER THAN ESTIMATED. `TRACE_DETAIL_CAP` is 400 and the router
+    // gives the head `cap - tail.length - 1`. The tier cause's worst realistic
+    // head is the BOTH-HALVES case — a fallback-tier plan and its summary are
+    // written from the same cache, so both degrade together — which opens "both
+    // halves of this pair record" and carries the reason bounded to
+    // `boundedToken`'s 80 characters: 187 characters, measured. With the command
+    // (87) and the disable sentence (63) fixed, the lead has 62 characters. A
+    // longer one truncates the head that names the plan, which is the
+    // truncated-remedy bug arriving from the other end.
+    //
+    // So the lead states the DIAGNOSIS the other two leads do not give — the
+    // project is pointed at the wrong vault — plus the key to change and the
+    // fact that a fetch must follow it. The fuller remedy (re-point
+    // `client.vaultRepo` / `client.vaultRef`, re-fetch, regenerate) is spelled
+    // out in `docs/vault-trace-format.md`, which has no cap.
+    const lead = /no client standards were applied/.test(reason)
+        ? ' Wrong vault: fix client.vaultRepo, re-fetch, then '
+        // The two reasons the resolver emits when the vault was REACHED FOR and not
+        // reached. Anything else — including an empty reason — falls to the
+        // re-fetch-first tail, which also names the disable route.
+        : /records a miss|is stale/.test(reason)
+            ? ' Regenerating alone reproduces this: restore vault access first, then '
+            : " Re-fetch the vault and regenerate that stage's trace: ";
+    return (lead
+        + TRACE_REGENERATE_COMMAND
+        // The SECOND route, and it is the same sentence in all three tails on
+        // purpose: it is the one action performable while the vault is down, so it
+        // must not be the clause that a rewording of a first route quietly drops.
+        + ' Or set vault.practices_enabled=false in .planning/config.json.');
+}
+/**
+ * Compare ONE plan statement against ONE summary statement — the first relation
+ * between two artifacts this module has ever expressed (TGATE-01's third
+ * clause, under D-09).
+ *
+ * THE RELATION. A summary's identifier set must COVER its own plan's,
+ * plan by plan. Not the intersection, not a phase-wide union: a SUPERSET test
+ * against exactly one counterpart. Both rejected alternatives fail the same
+ * way, VACUOUSLY. An intersection test passes for a summary that kept one
+ * identifier and dropped the rest. A phase aggregate passes when one plan
+ * dropped every practice and a sibling happened to carry the same identifiers.
+ * A gate that cannot fail is not a gate, and this workstream has already
+ * shipped one coverage gate that reported `passed` while parsing nothing.
+ *
+ * The aggregate also cannot satisfy TGATE-03, which requires the failure to
+ * name the file and section to fix: an aggregate has no file to name. That is
+ * why every problem returned here is filed against the SUMMARY — it is the
+ * artifact whose record is incomplete and the one an operator must repair.
+ *
+ * RETURNS PROBLEMS, NEVER A BOOLEAN. The caller composes them into its own
+ * verdict alongside every other problem it holds, exactly as it does with the
+ * single-statement validator's. A boolean here would force a second, parallel
+ * verdict composition in the handler.
+ *
+ * PURE. Two parsed statements in, problems out. It opens no file, stats
+ * nothing, and invokes no git — deliberately, and not merely as tidiness. The
+ * two alternatives for pairing were considered and are unusable in this
+ * workflow: artifacts are copied out of executor worktrees as a routine step,
+ * which destroys modification times, and `.planning/` is gitignored, so there
+ * is no history to read. Only the recorded plan identifier and the recorded
+ * generation timestamp — both frozen REQUIRED keys in both stage variants —
+ * survive both. The divergence check, which does read a manifest, is the
+ * router's and lives there.
+ *
+ * NEVER THROWS, on the validator's reasoning verbatim: this sits on the read
+ * path for an attacker-influenceable document, and a throw would turn a
+ * halt-on-error gate into a permanently stopped build.
+ */
+function comparePracticeCoverage(planStatement, summaryStatement, options) {
+    const opts = isPlainObject(options) ? options : {};
+    const file = typeof opts.file === 'string' && opts.file !== '' ? opts.file : 'the summary artifact';
+    const planFile = typeof opts.planFile === 'string' && opts.planFile !== '' ? opts.planFile : 'its plan artifact';
+    // Anything that is not the strict word is tolerant, so an absent option, an
+    // undefined one and a misspelt one all land on the silent arm rather than on
+    // the blocking one. Fail-open is the correct default for THIS parameter and
+    // only for this one: it is the caller's declaration of which question is
+    // being asked, and a typo must not invent a halt nobody declared.
+    const strictness = opts.strictness === 'strict' ? 'strict' : 'tolerant';
+    const problems = [];
+    try {
+        // ── the state gate: THREE outcomes, not two (04-13, CR-01) ─────────────
+        //
+        // THE TOLERANT ARM, and its reasoning is 04-07's PRESERVED VERBATIM below
+        // because 04-13 does not challenge a word of it. What 04-13 changes is that
+        // this paragraph used to be the WHOLE answer, at every call site:
+        //
+        //   > SUPPRESSED — not failed — unless BOTH halves record a `loaded` vault. A
+        //   > degraded run legitimately recorded no universe and may legitimately have
+        //   > recorded no practices at all (D-04), and Phase 3 REQUIRES it to write a
+        //   > trace stating the degraded state and its reason. The miss is therefore
+        //   > already a recorded fact in the artifact; a comparison that additionally
+        //   > blocked would be rejecting a correct record of a real failure. What keeps
+        //   > this from being an escape hatch is 04-02's pin: the state is derived by
+        //   > the CLI from the vault fixture and cannot be selected through any
+        //   > statement-builder option.
+        //
+        // THE STRICT ARM, and why the paragraph above stops being the whole answer
+        // there. At the two WRITE points the gate asks *is this a correct record?*
+        // and a degraded record is correct. At `ship:pre` and `verify:post` it asks
+        // a different question: *does this record prove the phase was governed?* A
+        // degraded half answering a loaded plan proves nothing — it records that
+        // the vault was unreachable, which is a fact about the machine and not
+        // about the work. Scoring "proved nothing" as "passed" was the fail-open
+        // (CR-01): a summary written while `.planning/vault/` was absent recorded
+        // an empty ledger and this gate returned zero problems, so a phase that
+        // promised practices and accounted for none SHIPPED RECORDED AS GOVERNED.
+        // The record is neither a valid proof nor a rejectable record; it is an
+        // UNPROVEN one, and that third outcome had no name.
+        //
+        // STRICTNESS IS A PROPERTY OF THE CALL SITE, exactly as D-10 already made
+        // it one flag ago for an unpaired plan — normal mid-phase, a defect at
+        // ship. The same flag carries this, so the tolerant points stay
+        // byte-identically silent on the very fixture the strict points block on.
+        //
+        // WHY THE STRICT ARM IS A GATE AND NOT A TRAP, stated honestly rather than
+        // rounded off: the remedy's availability is PARTIAL. Three of the
+        // resolver's five degraded causes are cleared by re-fetching and
+        // regenerating from the main checkout the strict points run on; a recorded
+        // miss and a stale cache whose refresh fails are NOT — regeneration
+        // reproduces them exactly. There the block is still deliberate, because the
+        // remedy is OPERATIONAL rather than a re-run: restore vault reachability,
+        // or turn the practices capability off for this project. Both are stated in
+        // the tail, both are performable with the vault down, and the residual is
+        // accepted: while a client vault is genuinely unreachable, a correct record
+        // and a blocked ship coexist. That is the intended behaviour of a
+        // workstream whose premise is that a vault miss must never silently produce
+        // ungoverned code.
+        //
+        // REJECTED, one sentence each, so the next reader does not re-open them.
+        // Rejecting a degraded statement at VALIDATION time blocks everywhere and
+        // fails a correct record of a real failure — D-04 is right, and at the
+        // write points the remedy reproduces the block. An ADVISORY-only problem is
+        // measurably invisible: a non-blocking verdict sets no message and the
+        // enforcer prints only the message, so it would restate the silence in a
+        // quieter channel. Letting the existing uncovered-identifier kind fire on
+        // an empty ledger yields one problem per promised id for ONE cause, and
+        // points each at a section where the fix does not live. A phase-level
+        // aggregate cannot name a file, which TGATE-03 requires.
+        //
+        // SYMMETRIC ON PURPOSE — either half, not only the summary. A degraded PLAN
+        // at ship time is equally unproven: it says no practices governed the work
+        // because the vault was unreachable when it was planned. Closing only the
+        // summary arm would leave the mirror-image hole, which is this phase's own
+        // signature failure.
+        //
+        // THE BOUNDARY, AND IT IS A PROHIBITION. `validateTraceStatement`'s
+        // degraded suppression is UNCHANGED, at every strictness, and must stay so.
+        // It takes no strictness parameter and must not be given one. The reason is
+        // informational, not stylistic: a lone degraded statement records no
+        // universe and no practices, so there is nothing to compare and identifier
+        // resolution there is VACUOUS rather than suppressed-with-content. The
+        // judgement below is possible only because the PLAN half says what was
+        // promised. Do not "complete the set" by adding a strict arm there — that
+        // is precisely the everywhere-block D-04 argues against, arrived at from
+        // the other side.
+        const planState = traceVaultStateOf(planStatement);
+        const summaryState = traceVaultStateOf(summaryStatement);
+        if (planState !== 'loaded' || summaryState !== 'loaded') {
+            if (strictness !== 'strict')
+                return problems;
+            const summaryUnproven = summaryState !== 'loaded';
+            const planUnproven = planState !== 'loaded';
+            // ONE problem per pair, and it RETURNS: a ledger that proved nothing
+            // cannot be compared, so continuing into the coverage loop and the
+            // staleness check would report three problems for one cause and give an
+            // operator three things to chase.
+            //
+            // The reason quoted is the SUMMARY's when the summary is unproven, and
+            // the plan's otherwise — one reason, not two, because both halves
+            // degraded is overwhelmingly one environment failing once, and a second
+            // bounded artifact value would double the untrusted share of a head that
+            // already carries two.
+            const reason = summaryUnproven
+                ? traceVaultReasonOf(summaryStatement)
+                : traceVaultReasonOf(planStatement);
+            problems.push({
+                // Filed against the UNPROVEN half rather than always the summary, which
+                // is this function's only departure from that rule and is TGATE-03's
+                // own clause: the artifact to regenerate is the one whose run could not
+                // read the vault. With both halves unproven the summary is named, as
+                // the artifact whose record was supposed to answer.
+                file: summaryUnproven ? file : planFile,
+                kind: TRACE_PROBLEM_KIND.COVERAGE_PAIR_UNPROVABLE,
+                detail: `${planUnproven && summaryUnproven
+                    ? 'both halves of this pair record'
+                    : summaryUnproven
+                        ? 'this summary records'
+                        : 'the plan this summary answers records'} no loaded vault, so nothing proves plan ` +
+                    `"${collapseControlChars(boundedToken(tracePlanIdOf(planStatement)))}" was governed ` +
+                    `— reason: "${collapseControlChars(boundedToken(reason))}".`,
+                // 04-11's mechanism, and the head above contains NO part of the
+                // command: this is the fourth remedy-bearing kind, added by the plan
+                // that follows the fix for the truncated-remedy bug's third occurrence.
+                tail: unprovablePairTail(reason),
+            });
+            return problems;
+        }
+        // Built ONCE, then probed per identifier — a scan per id turns a large
+        // ledger into a quadratic walk (T-4-22), the same bound the resolution
+        // check is written to.
+        const covered = new Set(traceEmittedIdsOf(summaryStatement));
+        const seen = new Set();
+        for (const id of traceEmittedIdsOf(planStatement)) {
+            // De-duplicated: a plan that recorded one id twice has a duplication
+            // defect with its own kind, and must not also produce two coverage
+            // problems for one gap.
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            if (covered.has(id))
+                continue;
+            // ONE problem PER uncovered identifier, never one aggregate: TGATE-03
+            // requires the failure to name the identifier at fault, and a single
+            // problem standing for three dropped practices makes the count
+            // meaningless.
+            problems.push({
+                file,
+                kind: TRACE_PROBLEM_KIND.COVERAGE_PLAN_UNCOVERED,
+                detail: `practice id "${collapseControlChars(boundedToken(id))}" is recorded in the plan trace of ` +
+                    `${planFile} and appears nowhere in this summary's ledger, so the executor's record does ` +
+                    `not account for it. A partial overlap is not coverage.`,
+            });
+        }
+        // ── staleness: the recorded timestamps, compared STRICTLY (D-11) ────────
+        //
+        // Strict on purpose. Equal timestamps are not stale — a plan and a summary
+        // generated inside the same clock tick is an ordinary fast run, and
+        // blocking it would fail correct records for a clock's resolution.
+        // Unparseable on either side yields NO stale problem: an unreadable
+        // timestamp is a required-key defect the single-statement validator already
+        // owns, and reporting it twice from two places gives an operator two
+        // problems for one cause.
+        const planAt = Date.parse(traceGeneratedAtOf(planStatement));
+        const summaryAt = Date.parse(traceGeneratedAtOf(summaryStatement));
+        if (Number.isFinite(planAt) && Number.isFinite(summaryAt) && summaryAt < planAt) {
+            problems.push({
+                file,
+                kind: TRACE_PROBLEM_KIND.COVERAGE_PAIR_STALE,
+                // SHORTNESS WAS THE MITIGATION; THE TAIL IS NOW THE MECHANISM (04-11,
+                // CR-05). The previous reasoning, quoted verbatim so this reads as the
+                // upgrade it is rather than as a loss:
+                //
+                //   "THE DETAIL IS DELIBERATELY SHORT, and the reason is CR-02's, not
+                //    style. The router bounds every detail at `TRACE_DETAIL_CAP` before
+                //    it reaches the message, so a detail that runs long loses its TAIL
+                //    — and the tail is the remedy. A stale-pair block whose remedy was
+                //    truncated away is exactly the trap D-11 exists to prevent, so the
+                //    prose names the plan IDENTIFIER rather than repeating the plan's
+                //    path (the summary's own path is already the problem's `file`),
+                //    keeping the whole detail inside the cap with the remedy intact."
+                //
+                // Every sentence of that was true and the detail still overflowed. A
+                // budget argument is not a mechanism: the three values interpolated
+                // here are read straight out of an artifact, `boundedToken` allows 80
+                // characters apiece, V8's `Date.parse` accepts trailing parenthesised
+                // text so a 62-character timestamp is trivially reachable, and the
+                // measured worst case came to 418 against the 399-character budget. The
+                // remedy was the part that fell off.
+                //
+                // THIS WAS THE THIRD OCCURRENCE OF ONE BUG. 04-07 shipped a
+                // 480-character stale-pair detail against the same cap and lost the
+                // same remedy; a guard was added. 04-08 built `traceDetail`'s head/tail
+                // split and two cap tests. EACH FIX ADDRESSED ONE SITE — 04-08's guard
+                // measures the tails the ROUTER writes, and a remedy living in a leaf's
+                // HEAD was invisible to it. The prose below is still short, because a
+                // message a reader can read is worth having, but shortness no longer
+                // protects the command: the command is in the tail, concatenated after
+                // the truncation has already happened, so prose and remedy no longer
+                // compete for the same 400 characters at all.
+                detail: `this summary's trace was generated at ` +
+                    `"${collapseControlChars(boundedToken(traceGeneratedAtOf(summaryStatement)))}", BEFORE the ` +
+                    `plan trace it answers at ` +
+                    `"${collapseControlChars(boundedToken(traceGeneratedAtOf(planStatement)))}", so it records ` +
+                    `an earlier version of plan ` +
+                    `"${collapseControlChars(boundedToken(tracePlanIdOf(planStatement)))}".`,
+                tail: ` Regenerate the execute-stage trace in place, against the file named here: ` +
+                    TRACE_REGENERATE_COMMAND,
+            });
+        }
+        return problems;
+    }
+    catch (e) {
+        return [
+            {
+                file,
+                kind: TRACE_PROBLEM_KIND.VALIDATOR_ERROR,
+                detail: `the coverage comparison could not complete: ${boundedToken(String(e?.message ?? e))}`,
+            },
+        ];
+    }
+}
+// ─── The body block, read back against the ledger (D-05-07) ─
+//
+// A vault-enabled plan carries TWO surfaces: the `vault:` frontmatter LEDGER
+// (the audit record) and the `<vault_practices>` BODY BLOCK (the practice text
+// the executor re-anchors against per task). One CLI emits both from one
+// matcher run, which is what makes a cross-check cheap — and until this section
+// nothing performed it. `docs/vault-trace-format.md` § "The two blocks" records
+// the history: the check was named as Phase 4's, then Phase 5's, then recorded
+// UNASSIGNED (D-05-07) because no requirement named it. The operator's request
+// of 2026-10-03, after the 2026-10-02 probe, is the amendment that assigns it.
+//
+// PURE, like the validator above it: artifact TEXT and the PARSED STATEMENT in,
+// problems out. It opens no file, reads no manifest and runs no matcher. Text
+// is verified against the `textSha256` the ledger RECORDS, never by re-rendering
+// — a second matcher run would make the verdict a function of this machine's
+// vault cache, which D-01 removed from this gate on purpose, and would block
+// every machine whose cache has moved past the pin.
+const PRACTICES_BLOCK_OPEN = '<vault_practices>';
+const PRACTICES_BLOCK_CLOSE = '</vault_practices>';
+/** A sha256 hex digest, and nothing else, is a text digest. */
+const TEXT_DIGEST_PATTERN = /^[0-9a-f]{64}$/;
+/**
+ * The body-block family as a SET, so the router's message footer can tell a
+ * body remedy from a ledger remedy without spelling the kinds a second time.
+ */
+const PRACTICES_BLOCK_KINDS = new Set([
+    TRACE_PROBLEM_KIND.PRACTICES_BLOCK_ABSENT,
+    TRACE_PROBLEM_KIND.PRACTICES_BLOCK_DUPLICATE,
+    TRACE_PROBLEM_KIND.PRACTICES_BLOCK_STATE_MISMATCH,
+    TRACE_PROBLEM_KIND.PRACTICES_BLOCK_EMPTY,
+    TRACE_PROBLEM_KIND.PRACTICES_BLOCK_ID_MISSING,
+    TRACE_PROBLEM_KIND.PRACTICES_BLOCK_ID_UNEXPECTED,
+    TRACE_PROBLEM_KIND.PRACTICES_BLOCK_TEXT_MISMATCH,
+]);
+/**
+ * The command that regenerates a body block, named in every body-block remedy.
+ * ONE constant, exported, for the reason `TRACE_REGENERATE_COMMAND` is one.
+ */
+const PRACTICES_BLOCK_REGENERATE_COMMAND = 'pp_run vault practices match <files_modified...> --block';
+/**
+ * The trusted tail every body-block problem carries. Author-written, constant,
+ * independent of every fixture input (T-4-43), and measured against the ONE
+ * detail cap: 148 characters, leaving the head 251.
+ */
+const PRACTICES_BLOCK_TAIL = ` Regenerate the block and embed the output verbatim, from ${PRACTICES_BLOCK_OPEN} to ` +
+    `${PRACTICES_BLOCK_CLOSE}: ${PRACTICES_BLOCK_REGENERATE_COMMAND}`;
+/**
+ * The normalisation BOTH digest sites apply, so copy drift that changes no
+ * character of the practice text — CRLF line endings, trailing whitespace a
+ * planner's editor stripped or added, blank lines at either end — does not read
+ * as a content change, while any edit to the text itself does.
+ */
+function normalizePracticeText(text) {
+    return (typeof text === 'string' ? text : '')
+        .replace(/\r\n?/g, '\n')
+        .split('\n')
+        .map((line) => line.replace(/[ \t]+$/, ''))
+        .join('\n')
+        .trim();
+}
+/** sha256 hex of the normalised practice text. */
+function practiceTextDigest(text) {
+    return node_crypto_1.default.createHash('sha256').update(normalizePracticeText(text), 'utf8').digest('hex');
+}
+/**
+ * Read the body block(s) out of an artifact.
+ *
+ * The frontmatter is skipped first: the block is a BODY construct and a `---`
+ * document can carry anything in a YAML block scalar. Outside a block, a
+ * markdown code fence and an HTML comment are skipped too — a tag quoted as an
+ * example or commented out is not a block the executor reads as one, and
+ * counting it would let an example satisfy the presence check (plan-checker
+ * remark 2 on D-05-07). Tags are matched at column 0 only, which is where
+ * the renderer puts them and where the planner reference says they go; an
+ * entry is a fenced region whose FIRST `id:` line
+ * precedes its `ask:`/`excerpt:` label — the degraded and refused sections are
+ * fenced too, but render `- **id** — …` lines and never an `id:` line, so they
+ * are not entries. Everything after the label up to the fence end is the text.
+ */
+function parsePracticesBlock(content) {
+    const lines = String(content ?? '').replace(/\r\n?/g, '\n').split('\n');
+    let start = 0;
+    if (lines[0] === '---') {
+        const close = lines.indexOf('---', 1);
+        if (close > 0)
+            start = close + 1;
+    }
+    const out = { blocks: 0, unterminated: false, entries: [], prose: [] };
+    let i = start;
+    let inCodeFence = false;
+    let inComment = false;
+    while (i < lines.length) {
+        const head = lines[i].trimEnd();
+        if (inComment) {
+            if (head.includes('-->'))
+                inComment = false;
+            i += 1;
+            continue;
+        }
+        if (inCodeFence) {
+            if (/^(`{3,}|~{3,})/.test(head))
+                inCodeFence = false;
+            i += 1;
+            continue;
+        }
+        if (/^(`{3,}|~{3,})/.test(head)) {
+            inCodeFence = true;
+            i += 1;
+            continue;
+        }
+        if (head.startsWith('<!--') && !head.includes('-->')) {
+            inComment = true;
+            i += 1;
+            continue;
+        }
+        if (head !== PRACTICES_BLOCK_OPEN) {
+            i += 1;
+            continue;
+        }
+        let j = i + 1;
+        while (j < lines.length && lines[j].trimEnd() !== PRACTICES_BLOCK_CLOSE)
+            j += 1;
+        if (j >= lines.length) {
+            out.unterminated = true;
+            return out;
+        }
+        out.blocks += 1;
+        let cur = null;
+        for (let k = i + 1; k < j; k += 1) {
+            const t = lines[k].trimEnd();
+            if (t === practicesMod.EXTERNAL_CONTENT_FENCE_START) {
+                cur = { id: '', labelled: false, text: [] };
+                continue;
+            }
+            if (t === practicesMod.EXTERNAL_CONTENT_FENCE_END) {
+                if (cur !== null && cur.id !== '') {
+                    out.entries.push({ id: cur.id, text: cur.labelled ? cur.text.join('\n') : null });
+                }
+                cur = null;
+                continue;
+            }
+            if (cur !== null) {
+                if (cur.labelled) {
+                    cur.text.push(lines[k]);
+                }
+                else if (cur.id === '' && t.startsWith('id: ')) {
+                    cur.id = t.slice(4).trim();
+                }
+                else if (cur.id !== '' && (t === 'ask:' || t === 'excerpt:')) {
+                    cur.labelled = true;
+                }
+                continue;
+            }
+            // Prose is what is left: not a heading, not a quote, not an HTML comment
+            // (the renderer may stamp the block's first line with a `<!-- … -->`
+            // provenance comment; it is neither an entry nor a sentence).
+            const bare = t.trim();
+            if (bare !== '' && !bare.startsWith('#') && !bare.startsWith('>') && !bare.startsWith('<!--')) {
+                out.prose.push(bare);
+            }
+        }
+        i = j + 1;
+    }
+    return out;
+}
+/** Does a prose line state that the vault itself was never read? */
+function statesVaultNotRead(line) {
+    return (line === practicesMod.PRACTICES_VAULT_ABSENT_SENTENCE
+        || line === practicesMod.PRACTICES_VAULT_UNREADABLE_SENTENCE
+        || line.startsWith('Practices could not be checked'));
+}
+/**
+ * Compare ONE plan artifact's `<vault_practices>` body block against its parsed
+ * `vault:` ledger statement. Returns problems, never a boolean, on the
+ * validator's reasoning; NEVER THROWS, on the validator's reasoning too.
+ *
+ * THE FIVE QUESTIONS, in order, each one short-circuiting the next:
+ *   1. Is there exactly one block?            → absent / duplicate
+ *   2. Does the block agree with the ledger about whether the vault was READ?
+ *      A loaded ledger beside a vault-not-read sentence → state_mismatch
+ *   3. Does it deliver ANY entry when the ledger promises ≥1?  → empty
+ *   4. Do the two id sets agree, both ways?    → id_missing / id_unexpected
+ *   5. For every entry: with a `textSha256` on its ledger line, does the text
+ *      under `ask:`/`excerpt:` digest to it; without one, is there any text
+ *      there at all?                           → text_mismatch
+ *
+ * An absent block is a defect WHATEVER the ledger lists, including nothing: the
+ * block is written in every degraded state too, and `docs/practices-format.md`
+ * is explicit that a silent omission is indistinguishable from the capability
+ * being off. The `empty` question is asked only when the ledger promises
+ * something, because a block that correctly says "none apply" over an empty
+ * ledger has delivered exactly what was recorded.
+ *
+ * Question 5's DIGEST half is SKIPPED, not failed, for a ledger entry without a
+ * digest: the key is optional (a minor addition), a ledger written before it
+ * existed is a correct record, and blocking it on text alone would halt every
+ * phase planned on an earlier engine at ship time. What such an entry still
+ * must have is SOME text — the renderer never emits a labelled entry with none,
+ * so a blank or label-less entry is a defect whatever the ledger's age. A
+ * placeholder like "(see vault)" on a pre-digest ledger is NOT caught, and is
+ * recorded as the one shape this check leaves open (plan-checker remark 1).
+ * Questions 1–4 need no digest and run on every ledger.
+ */
+function validatePracticesBody(content, statement, options) {
+    const opts = isPlainObject(options) ? options : {};
+    const file = typeof opts.file === 'string' && opts.file !== '' ? opts.file : 'the artifact';
+    const problems = [];
+    const add = (kind, detail) => {
+        problems.push({ file, kind, detail, tail: PRACTICES_BLOCK_TAIL });
+    };
+    const safe = (v) => collapseControlChars(boundedToken(v));
+    try {
+        if (opts.stage !== 'plan')
+            return problems;
+        if (!isPlainObject(statement))
+            return problems;
+        // The ledger's half: ids in recorded order, de-duplicated (a duplicated id
+        // is its own defect with its own kind), and the digest each carries.
+        const ledgerIds = [];
+        const digests = new Map();
+        const predicate = isPlainObject(statement['predicate']) ? statement['predicate'] : {};
+        const practices = Array.isArray(predicate['practices']) ? predicate['practices'] : [];
+        for (const raw of practices) {
+            const entry = isPlainObject(raw) ? raw : {};
+            const id = typeof entry['id'] === 'string' ? entry['id'] : '';
+            if (id === '' || ledgerIds.includes(id))
+                continue;
+            ledgerIds.push(id);
+            const digest = entry['textSha256'];
+            if (typeof digest === 'string' && digest !== '')
+                digests.set(id, digest);
+        }
+        const promised = ledgerIds.length;
+        const promisedText = `${promised} practice id${promised === 1 ? '' : 's'}`;
+        const parsed = parsePracticesBlock(typeof content === 'string' ? content : '');
+        // ── 1. exactly one block ──────────────────────────────────────────────
+        if (parsed.unterminated) {
+            add(TRACE_PROBLEM_KIND.PRACTICES_BLOCK_ABSENT, `${file} opens a ${PRACTICES_BLOCK_OPEN} block that is never closed, so no executor can tell ` +
+                `where the client's practice text ends; its vault: ledger records ${promisedText}.`);
+            return problems;
+        }
+        if (parsed.blocks === 0) {
+            add(TRACE_PROBLEM_KIND.PRACTICES_BLOCK_ABSENT, `${file} carries a vault: ledger recording ${promisedText} but no ${PRACTICES_BLOCK_OPEN} block, ` +
+                `so the executor that reads this plan receives no practice text at all — the ledger records ` +
+                `governance the plan does not deliver.`);
+            return problems;
+        }
+        if (parsed.blocks > 1) {
+            add(TRACE_PROBLEM_KIND.PRACTICES_BLOCK_DUPLICATE, `${file} carries ${parsed.blocks} ${PRACTICES_BLOCK_OPEN} blocks where a plan carries exactly one, ` +
+                `so which practice text governs this plan is ambiguous.`);
+            return problems;
+        }
+        // ── 2. the block and the ledger agree about whether the vault was READ ─
+        //
+        // One direction only, and argued: a `degraded` ledger beside a block full
+        // of entries is CONSISTENT (a stale cache still matches), and a `degraded`
+        // ledger beside the absent sentence is consistent too. The disagreement
+        // that can mislead is a block telling the executor the vault was never
+        // fetched about a run whose ledger records a loaded pin — the "fake
+        // degraded" shape the probe planted. Fires whatever the ledger promises,
+        // including nothing: it is a statement about the run, not about a count.
+        if (traceVaultStateOf(statement) === 'loaded' && parsed.prose.some(statesVaultNotRead)) {
+            add(TRACE_PROBLEM_KIND.PRACTICES_BLOCK_STATE_MISMATCH, `the ${PRACTICES_BLOCK_OPEN} block in ${file} states that the client vault was not read, while ` +
+                `its vault: ledger records state "loaded" with ${promisedText}. The block tells the executor ` +
+                `nothing was fetched about a run that recorded a pin, so the two halves of this plan's record ` +
+                `disagree about what happened.`);
+            return problems;
+        }
+        // ── 3. the block delivers something when the ledger promises something ─
+        if (promised > 0 && parsed.entries.length === 0) {
+            add(TRACE_PROBLEM_KIND.PRACTICES_BLOCK_EMPTY, `the ${PRACTICES_BLOCK_OPEN} block in ${file} renders no practice entry while its vault: ledger ` +
+                `records ${promisedText}. The executor applies what the block delivers, so these practices ` +
+                `govern nothing.`);
+            return problems;
+        }
+        // ── 4. the two id sets agree, both ways ───────────────────────────────
+        const bodyIds = [];
+        for (const e of parsed.entries)
+            if (!bodyIds.includes(e.id))
+                bodyIds.push(e.id);
+        const bodySet = new Set(bodyIds);
+        const ledgerSet = new Set(ledgerIds);
+        for (const id of ledgerIds) {
+            if (bodySet.has(id))
+                continue;
+            add(TRACE_PROBLEM_KIND.PRACTICES_BLOCK_ID_MISSING, `practice "${safe(id)}" is recorded in the vault: ledger of ${file} and has no entry in its ` +
+                `${PRACTICES_BLOCK_OPEN} block, so the executor never sees its text.`);
+        }
+        for (const id of bodyIds) {
+            if (ledgerSet.has(id))
+                continue;
+            add(TRACE_PROBLEM_KIND.PRACTICES_BLOCK_ID_UNEXPECTED, `the ${PRACTICES_BLOCK_OPEN} block in ${file} carries an entry for practice "${safe(id)}" that its ` +
+                `vault: ledger does not record, so the two halves of this plan's record disagree about which ` +
+                `practices apply.`);
+        }
+        // ── 5. the text is the text the matcher rendered — or, without a digest,
+        //       is at least THERE ────────────────────────────────────────────────
+        const checked = new Set();
+        for (const e of parsed.entries) {
+            if (checked.has(e.id) || !ledgerSet.has(e.id))
+                continue;
+            checked.add(e.id);
+            const want = digests.get(e.id);
+            const blank = e.text === null || normalizePracticeText(e.text) === '';
+            if (want === undefined) {
+                // The digest-free floor. The renderer always emits the label and the
+                // text under it, so an entry with neither is not a copy of anything
+                // the matcher produced.
+                if (!blank)
+                    continue;
+                add(TRACE_PROBLEM_KIND.PRACTICES_BLOCK_TEXT_MISMATCH, `practice "${safe(e.id)}" in the ${PRACTICES_BLOCK_OPEN} block of ${file} carries no practice ` +
+                    `text under ask:/excerpt:, so the executor is handed an identifier and nothing to apply.`);
+                continue;
+            }
+            const got = blank ? '' : practiceTextDigest(e.text);
+            if (got === want)
+                continue;
+            add(TRACE_PROBLEM_KIND.PRACTICES_BLOCK_TEXT_MISMATCH, `the text under practice "${safe(e.id)}" in the ${PRACTICES_BLOCK_OPEN} block of ${file} is not ` +
+                `the text the matcher rendered when its vault: ledger was written` +
+                (e.text === null
+                    ? ' (the entry carries no ask:/excerpt: section)'
+                    : ' (it was altered, shortened or replaced)') +
+                `, so the executor is not reading the client's practice.`);
+        }
+        return problems;
+    }
+    catch (e) {
+        return [
+            {
+                file,
+                kind: TRACE_PROBLEM_KIND.VALIDATOR_ERROR,
+                detail: `the body-block check could not complete: ${boundedToken(String(e?.message ?? e))}`,
+            },
+        ];
+    }
+}
+module.exports = {
+    buildTraceStatement,
+    serializeTraceBlock,
+    renderPracticesApplied,
+    parseVaultTraceBlock,
+    validateTraceStatement,
+    // 04-07 (D-09): the pair comparison. Exported because the RELATION is the
+    // router's to compose — the leaf compares one pair at a time and returns
+    // problems, and the router enumerates, pairs and folds them into its
+    // envelope. Keeping it here rather than in the handler keeps every structural
+    // judgement about a trace in the leaf, which is the property that stops a
+    // second, drifting implementation from growing in an adapter.
+    comparePracticeCoverage,
+    // D-05-07: the body-block check, its digest and its remedy
+    // command. The router composes the problems exactly as it composes the
+    // validator's; the two digest sites (builder and body check) share
+    // `practiceTextDigest`, so the normalisation is written once.
+    validatePracticesBody,
+    practiceTextDigest,
+    PRACTICES_BLOCK_REGENERATE_COMMAND,
+    PRACTICES_BLOCK_KINDS,
+    TRACE_REQUIRED_KEYS,
+    TRACE_PROBLEM_KIND,
+    TRACE_BLOCK_KEY,
+    TRACE_STATEMENT_TYPE,
+    TRACE_PREDICATE_TYPE,
+    TRACE_SCHEMA_VERSION,
+    TRACE_STATUS_VALUES,
+    TRACE_ID_PATTERN,
+    // 10-08 (MECH-03, D-10-05): the analyzer-provenance lead. Exported so the
+    // test that PINS it against its owner — `AUDIT_ENFORCED_BY_LEAD` in
+    // `src/vault-audit.cts` — can compare the two shipped strings rather than a
+    // copy of either. See the constant's own comment for why this module holds a
+    // second spelling instead of importing the first.
+    TRACE_ENFORCED_BY_LEAD,
+    // Moved here from src/check-command-router.cts by 04-05 and exported: the
+    // validator's missing-universe remedy and the handler's block message must
+    // name the SAME command, and the handler already imports this module.
+    TRACE_REGENERATE_COMMAND,
+    PRACTICES_APPLIED_HEADING,
+    // The reader allowlist: pp-core's own predicate type plus any the org
+    // profile lists (same major). The validator takes the list through its
+    // options, so a gate passes `acceptedPredicateTypes(root)`.
+    acceptedPredicateTypes,
+    TRACE_WORKTREE_CACHE_NOTE,
+    // The recorded check: census, read back for the mechanical audit.
+    readRecordedCensus,
+};