@pareto4/pp-core 1.13.0 → 1.18.0

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

@@ -0,0 +1,1504 @@
+"use strict";
+/**
+ * src/vault-standards.cts — the `<vault_standards>` record (Vault Assurance
+ * v1.2, Phase 15-05; D-07, D-08, D-09, D-10, D-13, D-17..D-20, D-29).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the git-ignored `pp-core/bin/lib/vault-standards.cjs`; do NOT
+ * hand-edit the compiled output. Behaviour is locked by
+ * `tests/vault-standards.test.cjs`, which also pins the agent-facing contract
+ * `pp-core/references/planner-vault-standards.md` to this grammar in both
+ * directions (D-10).
+ *
+ * A plan records which INDEX-listed standards documents
+ * governed it, in ONE body block the CLI emits (`vault standards block`), and
+ * the plan's SUMMARY records which of them the executor read (`## Standards
+ * Consulted`, rendered by `vault standards consulted`). This module is the ONE
+ * owner of:
+ *   - the block grammar: tags, the stamp line, the document line, the closed
+ *     degraded set, the CLI-only override line (`STANDARDS_GRAMMAR` is the
+ *     single text the reference quotes),
+ *   - the reason-clause rules (D-09),
+ *   - the `## Standards Consulted` section grammar (D-13),
+ *   - the serializers the verbs print through and the whole-line parsers the
+ *     gate reads through,
+ *   - the pure judgement of a parsed record against a measured state,
+ *   - the frozen `STANDARDS_PROBLEM_KIND` table and every standards sentence,
+ *   - the plan-id form `SCAFFOLD_PLAN_ID_RE` (moved here from the vault
+ *     router, which re-exports it), so the verbs and the gate share one form.
+ *
+ * It imports only `./vault-index.cjs`, which imports nothing, and (16-06) the
+ * seal leaf `./vault-seal.cjs` for the one anchor grammar, whose top level
+ * imports only `fs` and `path` (D-41). This is load-bearing: the vault router
+ * (15-07) and the check router (15-08) both require this leaf, and a leaf whose
+ * dependencies are themselves import-free at load time cannot close a require
+ * cycle among them (the seal leaf requires this one back LAZILY, inside its
+ * functions). The entry head split and the display
+ * sanitiser are reused from there, never re-spelled
+ * (Phase 14 D-06/D-17/D-32): the grammar for a `- \`path\` — …` line is one
+ * grammar across INDEX.md, discovery's vault context and this record.
+ *
+ * Nothing here reads config, the filesystem, the environment or the clock.
+ * The measured state (the loaded pin, the resolved INDEX paths, the index
+ * status, whether `vault.required` is on) is computed by the caller and passed
+ * in as a value.
+ *
+ * Message discipline (T-15-20, D-14): every text echoed from a record passes
+ * `sanitiseVaultText`, and every path passes `displayVaultPath`, so a record
+ * cannot smuggle terminal control bytes or bidi overrides into a gate message. The leaf never knows WHY a path is not a resolved INDEX
+ * entry (withheld, unsafe, unresolved and absent look the same to it), so no
+ * detail can confirm that a refused path names a credential. Every detail ends
+ * with a repair remedy and never names a destructive verb.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STANDARDS_PROBLEM_KIND = exports.STANDARDS_GRAMMAR = exports.STANDARDS_DETAIL_CAP = exports.SCAFFOLD_PLAN_ID_RE = exports.STANDARDS_ANCHOR_PREFIX = exports.STANDARDS_SHA_RE = exports.STANDARDS_NONE = exports.STANDARDS_CONSULTED_NOT_READ = exports.STANDARDS_CONSULTED_READ = exports.STANDARDS_OVERRIDE_GATE = exports.STANDARDS_OVERRIDE_PREFIX = exports.STANDARDS_INDEX_STATUSES = exports.STANDARDS_COULD_NOT_CHECK_CODES = exports.STANDARDS_INDEX_MISSING_CODE = exports.STANDARDS_DEGRADED_KINDS = exports.STANDARDS_REASON_MARKER = exports.STANDARDS_REASON_MAX = exports.STANDARDS_CONSULTED_HEADING = exports.STANDARDS_STAMP_SEPARATOR = exports.STANDARDS_STAMP_PREFIX = exports.VAULT_STANDARDS_TAG_CLOSE = exports.VAULT_STANDARDS_TAG_OPEN = void 0;
+exports.validateReasonClause = validateReasonClause;
+exports.standardsIndexRepair = standardsIndexRepair;
+exports.standardsVaultRepairLead = standardsVaultRepairLead;
+exports.standardsProblemDetail = standardsProblemDetail;
+exports.standardsEchoDegraded = standardsEchoDegraded;
+exports.serializeStandardsBlock = serializeStandardsBlock;
+exports.formatStandardsAnchorLine = formatStandardsAnchorLine;
+exports.parseStandardsAnchorLine = parseStandardsAnchorLine;
+exports.serializeConsultedSection = serializeConsultedSection;
+exports.findLiveSection = findLiveSection;
+exports.parseStandardsBlock = parseStandardsBlock;
+exports.parseConsultedSection = parseConsultedSection;
+exports.standardsLoadedPin = standardsLoadedPin;
+exports.standardsMeasuredIndexStatus = standardsMeasuredIndexStatus;
+exports.standardsResolvedPaths = standardsResolvedPaths;
+exports.standardsDegradedLineFor = standardsDegradedLineFor;
+exports.judgeStandardsPlan = judgeStandardsPlan;
+exports.judgeConsultedSummary = judgeConsultedSummary;
+exports.compareConsulted = compareConsulted;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const vaultIndexLeaf = require("./vault-index.cjs");
+const { splitVaultEntryLine, displayVaultPath, sanitiseVaultText, DISPLAY_UNSAFE_TEXT_CHAR_RE, VAULT_ENTRY_PREFIX, VAULT_ENTRY_SEPARATOR, } = vaultIndexLeaf;
+// 16-06 (D-35): the anchor grammar has ONE owner, the seal leaf. Static and
+// cycle-free: its top level imports only Node built-ins (D-41).
+const vault_seal_cjs_1 = require("./vault-seal.cjs");
+// ─── Vocabulary (D-07, D-08) ─────────────────────────────────────────────────
+/** The block's opening tag; counted only as a whole line at column 0. */
+exports.VAULT_STANDARDS_TAG_OPEN = '<vault_standards>';
+/** The block's closing tag; counted only as a whole line at column 0. */
+exports.VAULT_STANDARDS_TAG_CLOSE = '</vault_standards>';
+/** The first line inside the block, and inside the consulted section, starts with this. */
+exports.STANDARDS_STAMP_PREFIX = 'Standards record: plan ';
+/** Between the facts of a stamp or an override line: space, middle dot (U+00B7), space. */
+exports.STANDARDS_STAMP_SEPARATOR = ' \u00B7 ';
+/** The SUMMARY section heading: a level-2 ATX heading at column 0, written exactly. */
+exports.STANDARDS_CONSULTED_HEADING = '## Standards Consulted';
+/** The bound on a reason clause, in code points (D-09). */
+exports.STANDARDS_REASON_MAX = 200;
+/** The marker that opens a reason slot. */
+exports.STANDARDS_REASON_MARKER = 'reason: ';
+/**
+ * The closed degraded set (D-08). Exactly one of these replaces the document
+ * lines; never mixed with them. `consulted-none` is the planner's judgement
+ * and carries a reason clause; the other two are emitted by the CLI only, from
+ * the measured index state, and carry a reason CODE.
+ */
+exports.STANDARDS_DEGRADED_KINDS = Object.freeze(['consulted-none', 'index-missing', 'could-not-check']);
+/** The one code an `index-missing` line carries (equal to the vault-index leaf's MISSING reason). */
+exports.STANDARDS_INDEX_MISSING_CODE = 'vault_index_missing';
+/** The codes a `could-not-check` line may carry, closed. */
+exports.STANDARDS_COULD_NOT_CHECK_CODES = Object.freeze([
+    'vault_index_unparseable',
+    'vault_index_empty',
+    'vault_index_unresolvable',
+    'vault_index_unchecked',
+    'vault_not_loaded',
+]);
+/**
+ * The INDEX.md statuses a stamp may carry: the five short forms of the
+ * vault-index leaf's reasons, `ok`, and `not-loaded` (no cached manifest at
+ * all). The leaf test pins the overlap with `vaultIndexReasonShort`.
+ */
+exports.STANDARDS_INDEX_STATUSES = Object.freeze([
+    'ok',
+    'missing',
+    'unparseable',
+    'empty',
+    'unresolvable',
+    'unchecked',
+    'not-loaded',
+]);
+/**
+ * The code each non-ok status implies on the record's degraded line. `ok`
+ * implies document lines or `consulted-none`; `missing` implies
+ * `index-missing`; every other status implies `could-not-check` with exactly
+ * this code.
+ */
+const STATUS_CODE = Object.freeze({
+    missing: exports.STANDARDS_INDEX_MISSING_CODE,
+    unparseable: 'vault_index_unparseable',
+    empty: 'vault_index_empty',
+    unresolvable: 'vault_index_unresolvable',
+    unchecked: 'vault_index_unchecked',
+    'not-loaded': 'vault_not_loaded',
+});
+/** The override line (CLI-only, the last line before the close tag) starts with this. */
+exports.STANDARDS_OVERRIDE_PREFIX = 'Override: gate ';
+/**
+ * The one gate a standards override line may name: the blocking load gate's
+ * `check.query`. The block verb writes it (the vault router's
+ * `TRACE_OVERRIDE_GATE` is this constant), and the judgement accepts no other
+ * (D-35).
+ */
+exports.STANDARDS_OVERRIDE_GATE = 'vault.status';
+/**
+ * The timestamp form the block verb writes (`Date.prototype.toISOString`, UTC,
+ * milliseconds). An override line whose `at` slot is not this form was not
+ * written by the verb (D-35).
+ */
+const OVERRIDE_WHEN_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+/**
+ * Is `s` exactly a timestamp `toISOString` would write? The form, then a
+ * round trip: the parsed date must print back as the same text, so a date V8
+ * rolls over (`2026-02-31` reads as `2026-03-03`) is refused rather than
+ * accepted as "a real date" (15-REVIEW iter-2 IN-01).
+ */
+function isVerbTimestamp(s) {
+    if (typeof s !== 'string' || !OVERRIDE_WHEN_RE.test(s))
+        return false;
+    const d = new Date(s);
+    return !Number.isNaN(d.getTime()) && d.toISOString() === s;
+}
+/** The consulted status for a document the executor Read in full. */
+exports.STANDARDS_CONSULTED_READ = 'read';
+/** The consulted status for a document the executor did not read; a clause follows. */
+exports.STANDARDS_CONSULTED_NOT_READ = 'not read: ';
+/** The literal written in the repo, ref and sha slots when no manifest was loaded. */
+exports.STANDARDS_NONE = 'none';
+/** A full git object id, lowercase: the only sha form a record may carry. */
+exports.STANDARDS_SHA_RE = /^[0-9a-f]{40}$/;
+/**
+ * The optional anchor line of a `## Standards Consulted` section starts with
+ * this (16-06, D-14/D-31/D-35). It is in the section's own `- ` list grammar,
+ * and the CLI writes it as the section's last line: the commit the record's
+ * work started from (when the plan's directory recorded one with
+ * `vault anchor start`) and HEAD when the section was rendered. A record
+ * written before 16-06 has no such line and parses exactly as before.
+ */
+exports.STANDARDS_ANCHOR_PREFIX = '- anchors: ';
+/**
+ * The plan-identifier form a record must carry,
+ * one of two alternatives:
+ *
+ *   - a PHASE plan id: one or more digits with an optional letter, optional
+ *     `.N` decimal parts, and at least one `-N` part (`15-02`, `2.1-03`,
+ *     `7a-10`);
+ *   - a QUICK-TASK id (16-05, D-29; research C-5): six date digits, a hyphen
+ *     and three lowercase base-36 characters (`261011-8yt`), exactly what
+ *     `cmdInitQuick` builds (`yymmdd` + `-` + the two-second block of the day
+ *     in base 36, padded to three). Before 16-05 a quick task could not record
+ *     at all, and the refusal was intermittent: an all-digit encoding such as
+ *     `261011-123` happened to match the phase form, a lettered one such as
+ *     `261011-8yt` did not.
+ *
+ * It rejects a bare plan number, a task label, a slugged identifier, an
+ * uppercase or wrong-length quick id and the empty string, each of which would
+ * mismatch the plan id the gate reads from a canonical filename. The phase
+ * alternative is byte-identical to the pre-16-05 pattern, and the whole is one
+ * anchored group so `filenamePlanId` can strip the anchors and embed it.
+ *
+ * Moved verbatim from `src/vault-command-router.cts` (15-05), which re-exports
+ * it under the same name. The read side's filename extractor
+ * (`filenamePlanId` in `src/check-command-router.cts`) builds its pattern from
+ * this value (15-REVIEW WR-06), so the form is read and written by one owner.
+ */
+exports.SCAFFOLD_PLAN_ID_RE = /^(?:\d+[A-Za-z]?(?:\.\d+)*(?:-\d+)+|\d{6}-[0-9a-z]{3})$/;
+/** The bound on a problem detail, in code points; equal to the trace handler's detail cap. */
+exports.STANDARDS_DETAIL_CAP = 400;
+const SEP = exports.STANDARDS_STAMP_SEPARATOR;
+const EM = VAULT_ENTRY_SEPARATOR; // the entry separator, owned by vault-index
+const EM_TRIMMED = VAULT_ENTRY_SEPARATOR.trimEnd(); // ' —'
+/**
+ * Every accepted line form, with `<placeholders>`. This is the single text the
+ * reference doc quotes; the doc pin test reads each value and finds it in the
+ * doc byte for byte.
+ */
+exports.STANDARDS_GRAMMAR = Object.freeze({
+    stamp: `${exports.STANDARDS_STAMP_PREFIX}<plan-id>${SEP}vault <repo> @ <ref>${SEP}sha <40-hex>${SEP}INDEX.md <status>`,
+    stampNotLoaded: `${exports.STANDARDS_STAMP_PREFIX}<plan-id>${SEP}vault ${exports.STANDARDS_NONE} @ ${exports.STANDARDS_NONE}${SEP}sha ${exports.STANDARDS_NONE}${SEP}INDEX.md not-loaded`,
+    document: `${VAULT_ENTRY_PREFIX}<index-path>\`${EM}<ref> @ <40-hex>${EM}${exports.STANDARDS_REASON_MARKER}<one clause>`,
+    consultedNone: `- (consulted-none)${EM}${exports.STANDARDS_REASON_MARKER}<one clause>`,
+    indexMissing: `- (index-missing)${EM}${exports.STANDARDS_INDEX_MISSING_CODE}`,
+    couldNotCheck: '- (could-not-check)' + EM + '<code>',
+    override: `${exports.STANDARDS_OVERRIDE_PREFIX}<gate>${SEP}suppressed <suppressed-reason>${SEP}by <who>${SEP}at <iso-8601>${SEP}${exports.STANDARDS_REASON_MARKER}<operator text>`,
+    consultedStamp: `${exports.STANDARDS_STAMP_PREFIX}<plan-id>${SEP}vault <repo> @ <ref>${SEP}sha <40-hex>`,
+    consultedRead: `${VAULT_ENTRY_PREFIX}<index-path>\`${EM}${exports.STANDARDS_CONSULTED_READ}`,
+    consultedNotRead: `${VAULT_ENTRY_PREFIX}<index-path>\`${EM}${exports.STANDARDS_CONSULTED_NOT_READ}<one clause>`,
+    consultedUnfilled: `${VAULT_ENTRY_PREFIX}<index-path>\`${EM_TRIMMED}`,
+    // 16-06: the optional anchor line, in its three CLI-written forms.
+    consultedAnchors: `${exports.STANDARDS_ANCHOR_PREFIX}start <commit>${SEP}end <commit>`,
+    consultedAnchorsEndOnly: `${exports.STANDARDS_ANCHOR_PREFIX}end <commit>`,
+    consultedAnchorsBackfilled: `${exports.STANDARDS_ANCHOR_PREFIX}end <commit>${SEP}backfilled by <who> at <iso-8601>`,
+});
+/**
+ * The frozen standards problem kinds (D-17). Every value is `standards_` plus
+ * the lower-snake key, so none can collide with a trace handler kind (the leaf
+ * test asserts disjointness).
+ * The two pairing kinds are produced by the HANDLER (15-08); this leaf owns
+ * their texts only.
+ */
+exports.STANDARDS_PROBLEM_KIND = Object.freeze({
+    BLOCK_ABSENT: 'standards_block_absent',
+    BLOCK_DUPLICATE: 'standards_block_duplicate',
+    BLOCK_UNTERMINATED: 'standards_block_unterminated',
+    BLOCK_MALFORMED: 'standards_block_malformed',
+    REASON_INVALID: 'standards_reason_invalid',
+    DOCUMENT_DUPLICATE: 'standards_document_duplicate',
+    DEGRADED_MIXED: 'standards_degraded_mixed',
+    NONE_WITHOUT_REASON: 'standards_none_without_reason',
+    PATH_NOT_RESOLVED: 'standards_path_not_resolved',
+    PIN_MISMATCH: 'standards_pin_mismatch',
+    CACHE_UNREADABLE: 'standards_cache_unreadable',
+    DEGRADED_UNTRUE: 'standards_degraded_untrue',
+    CONSULTED_ABSENT: 'standards_consulted_absent',
+    CONSULTED_MISMATCH: 'standards_consulted_mismatch',
+    PLAN_ID_MISMATCH: 'standards_plan_id_mismatch',
+    PAIR_MISSING: 'standards_pair_missing',
+    ORPHAN_SUMMARY: 'standards_orphan_summary',
+    // 16-06 (D-35): a line carrying the anchor prefix that is not one of the
+    // anchor line's forms, or a second anchor line. Appended LAST. A section with
+    // NO anchor line has no problem: write points are silent on a missing anchor
+    // (D-16); the strict points' `anchor_missing` is the trace gate's (16-07).
+    ANCHOR_MALFORMED: 'standards_anchor_malformed',
+});
+const NEWLINE_RE = /[\r\n\u0085\u2028\u2029]/;
+const TILDE_FENCE_RE = /~{3,}/;
+/**
+ * Judge one reason clause: non-empty after trim; at most
+ * `STANDARDS_REASON_MAX` code points (not UTF-16 units); no newline (CR, LF,
+ * NEL, U+2028, U+2029); no backtick at all; no code fence (a run of three
+ * tildes); no block tag; nothing
+ * the display sanitiser would rewrite (15-REVIEW WR-03: a control character
+ * such as ESC or BEL, a bidi override, a line or paragraph separator), judged
+ * by asking `sanitiseVaultText` itself, so the refused set has one owner. Runs
+ * of U+0020 and U+0020 at the ends are not judged here: the sanitiser only
+ * tidies them. Any other character the sanitiser rewrites is refused wherever
+ * it sits, the ends included (iter-2 WR-04). So is every character of the
+ * display-safety set vault-index owns (`DISPLAY_UNSAFE_TEXT_CHAR_RE`, iter-3
+ * IN-01), which adds the invisible format and default-ignorable code points
+ * the sanitiser leaves alone (zero-width space, word joiner, soft hyphen,
+ * tag characters): text a human reviewer cannot see must not reach a record
+ * an agent reads. `"` and `\` are not in that set and stay legal in prose.
+ * A document body pasted as a reason fails the bound or the newline rule.
+ * Never throws.
+ */
+function validateReasonClause(text) {
+    if (typeof text !== 'string' || text.trim() === '')
+        return { ok: false, why: 'empty' };
+    if (NEWLINE_RE.test(text))
+        return { ok: false, why: 'newline' };
+    if (Array.from(text.trim()).length > exports.STANDARDS_REASON_MAX)
+        return { ok: false, why: 'too_long' };
+    if (text.includes('`'))
+        return { ok: false, why: 'backtick' };
+    if (TILDE_FENCE_RE.test(text)) {
+        return { ok: false, why: 'fence_marker' };
+    }
+    if (text.includes(exports.VAULT_STANDARDS_TAG_OPEN) || text.includes(exports.VAULT_STANDARDS_TAG_CLOSE)) {
+        return { ok: false, why: 'block_tag' };
+    }
+    // 15-REVIEW iter-2 WR-04: the comparison side tidies U+0020 ONLY. `trim()`
+    // strips every Unicode whitespace character (tab, U+000B, U+000C, U+FEFF,
+    // U+00A0 ...), so it agreed with the sanitiser about those characters at
+    // either end and let them through; the parser trims line ends only, so one
+    // right after `reason: ` survived into the record.
+    const spacesTidied = text.replace(/ +/g, ' ').replace(/^ | $/g, '');
+    if (sanitiseVaultText(text, exports.STANDARDS_REASON_MAX * 4) !== spacesTidied || DISPLAY_UNSAFE_TEXT_CHAR_RE.test(text)) {
+        return { ok: false, why: 'control' };
+    }
+    return { ok: true };
+}
+const WHY_TEXT = Object.freeze({
+    empty: 'empty',
+    too_long: `longer than ${exports.STANDARDS_REASON_MAX} characters`,
+    newline: 'more than one line',
+    backtick: 'carrying a backtick',
+    fence_marker: 'carrying a fence marker',
+    block_tag: 'carrying a block tag',
+    control: 'carrying a control, bidi, separator or invisible format character',
+});
+const ECHO_MAX = 80;
+const PATH_MAX = 120;
+const PLAN_ID_ECHO_MAX = 40;
+function echo(s, max = ECHO_MAX) {
+    return sanitiseVaultText(typeof s === 'string' ? s : '', max);
+}
+function echoPath(p) {
+    return displayVaultPath(typeof p === 'string' ? p : '', PATH_MAX);
+}
+function echoPlanId(p) {
+    const t = echo(p, PLAN_ID_ECHO_MAX);
+    return t === '' ? '<plan-id>' : t;
+}
+function subjectOf(ctx) {
+    const a = echo(ctx.artifact, ECHO_MAX);
+    return a === '' ? 'The artifact' : a;
+}
+function lineSuffix(ctx) {
+    return typeof ctx.line === 'number' && Number.isFinite(ctx.line) ? ` (line ${Math.floor(ctx.line)})` : '';
+}
+function blockRemedy(planId) {
+    return `Re-run \`pp-tools vault standards block --plan ${echoPlanId(planId)} <index-path...>\`, embed its output verbatim and fill only the reason slots.`;
+}
+const CONSULTED_REMEDY = 'Re-run `pp-tools vault standards consulted <plan-path>`, embed its section verbatim in the SUMMARY, fill each status slot with `read` or `not read: <one clause>`, and commit the SUMMARY.';
+/** The repair for a malformed anchor line (16-06): regenerate it, or back-fill an unanchored record, attributed. */
+const ANCHOR_REMEDY = 'Restore the anchor line `pp-tools vault standards consulted <plan-path>` printed, or, for a record that never had one, run `pp-tools vault anchor backfill <summary> --at <sha>`.';
+/**
+ * The cause and the repair for a measured index status on which no document
+ * can be listed (15-REVIEW iter-3 WR-01), or null on `ok`. ONE owner for the
+ * four surfaces that state it: the block verb's refusal, the consulted verb's
+ * refusal, and the trace gate's details on a document record
+ * (`standards_path_not_resolved`, `standards_pin_mismatch`,
+ * `standards_cache_unreadable`) and on a degraded record
+ * (`standards_degraded_untrue`, the D-29 advisory). Before it, the gate sent a
+ * document record on a degraded INDEX back to "choose from its entries" while
+ * the verb named the INDEX repair: following the gate's remedy replaced a
+ * governed plan's document record with a degraded one. The repair is a
+ * sentence stem with no final stop, so each surface appends its own re-run.
+ * An unknown status fails closed to the INDEX repair, never to null.
+ */
+function standardsIndexRepair(status) {
+    return status === 'ok' ? null : indexRepairFor(status);
+}
+const LOAD_REPAIR = 'Run `pp-tools vault fetch` to load the vault';
+const INDEX_REPAIR = 'Repair INDEX.md in the vault repo and run `pp-tools vault fetch`';
+/** `standardsIndexRepair` for a status the caller already knows is not `ok`. */
+function indexRepairFor(status) {
+    if (status === 'not-loaded')
+        return { cause: 'no vault is loaded', repair: LOAD_REPAIR };
+    return {
+        cause: isIndexStatus(status) && status !== 'ok' ? `the index is ${status}` : 'the index is in an unknown state',
+        repair: INDEX_REPAIR,
+    };
+}
+/**
+ * The lead the trace gate's blocking message puts before its "repair each
+ * file in place" footer when a listed standards problem names a vault repair
+ * from `standardsIndexRepair` (iter-3 WR-01), else ''. The footer points at
+ * the two record producers; while the vault is not loaded or its INDEX is
+ * degraded, regenerating a record can only write a degraded one, so the
+ * vault repair the line names comes first. Detected by the owner's own
+ * repair text, which `composeDetail` never truncates.
+ */
+function standardsVaultRepairLead(problems) {
+    const kinds = Object.values(exports.STANDARDS_PROBLEM_KIND);
+    const repairs = [LOAD_REPAIR, INDEX_REPAIR];
+    let names = false;
+    for (const p of problems ?? []) {
+        const kind = p?.kind;
+        const detail = p?.detail;
+        if (typeof kind === 'string' && kinds.includes(kind) && typeof detail === 'string' && repairs.some((r) => detail.includes(r)))
+            names = true;
+    }
+    return names
+        ? 'A line above names a vault repair: make it first, because until the vault loads with a usable INDEX.md, regenerating a record can only write a degraded one. '
+        : '';
+}
+function lowerFirst(s) {
+    return `${s.charAt(0).toLowerCase()}${s.slice(1)}`;
+}
+/** The load repair (no manifest at gate time), the only remedy `standards_cache_unreadable` needs. */
+const FETCH_REMEDY = `${LOAD_REPAIR}, then re-run this check.`;
+/**
+ * Join a variable head and a constant remedy under the detail cap. The head is
+ * cut (with `…`) so the remedy is never truncated: the remedy is what makes a
+ * detail actionable.
+ */
+function composeDetail(head, remedy) {
+    const remedyLen = Array.from(remedy).length;
+    const room = exports.STANDARDS_DETAIL_CAP - remedyLen - 1;
+    const points = Array.from(head);
+    const cut = points.length <= room ? head : `${points.slice(0, Math.max(0, room - 1)).join('')}\u2026`;
+    return `${cut} ${remedy}`;
+}
+/**
+ * The finished detail for one kind. Every echoed value passes the sanitiser
+ * (paths through `displayVaultPath`); every detail ends with a repair remedy
+ * and is at most `STANDARDS_DETAIL_CAP` code points. The texts never name a
+ * destructive verb (INVARIANT 4's class; the leaf test sweeps all 17).
+ */
+function standardsProblemDetail(kind, ctx = {}) {
+    const c = ctx && typeof ctx === 'object' ? ctx : {};
+    const subject = subjectOf(c);
+    const where = c.where === 'section' ? `the ${exports.STANDARDS_CONSULTED_HEADING} section` : `the ${exports.VAULT_STANDARDS_TAG_OPEN} block`;
+    const sectionRemedy = c.where === 'section';
+    const path = echoPath(c.path);
+    switch (kind) {
+        case exports.STANDARDS_PROBLEM_KIND.BLOCK_ABSENT:
+            return composeDetail(`${subject} carries no ${exports.VAULT_STANDARDS_TAG_OPEN} block at column 0 outside code fences, comments and frontmatter; every plan carries one while the vault is on, including a plan that writes no code.`, blockRemedy(c.planId));
+        case exports.STANDARDS_PROBLEM_KIND.BLOCK_DUPLICATE:
+            return composeDetail(`${subject} carries ${typeof c.count === 'number' ? c.count : 'more than one'} ${exports.VAULT_STANDARDS_TAG_OPEN} blocks; the gate reads exactly one. Replace them with a single regenerated block.`, blockRemedy(c.planId));
+        case exports.STANDARDS_PROBLEM_KIND.BLOCK_UNTERMINATED:
+            return composeDetail(`${subject} opens ${exports.VAULT_STANDARDS_TAG_OPEN}${lineSuffix(c)} and never closes it with ${exports.VAULT_STANDARDS_TAG_CLOSE} at column 0.`, blockRemedy(c.planId));
+        case exports.STANDARDS_PROBLEM_KIND.BLOCK_MALFORMED:
+            return composeDetail(`${subject}: ${where} ${echo(c.part, 160) || 'does not match the standards grammar'}${lineSuffix(c)}.`, sectionRemedy ? CONSULTED_REMEDY : blockRemedy(c.planId));
+        case exports.STANDARDS_PROBLEM_KIND.REASON_INVALID: {
+            const which = c.where === 'section' ? `the not-read clause for ${path}` : c.path ? `the reason for ${path}` : 'the consulted-none reason';
+            return composeDetail(`${subject}: ${which} is ${WHY_TEXT[c.why ?? 'empty'] ?? 'invalid'}; a reason is one clause of at most ${exports.STANDARDS_REASON_MAX} characters with no newline, backtick, fence marker, block tag, control or invisible character.`, 'Rewrite it as one short clause.');
+        }
+        case exports.STANDARDS_PROBLEM_KIND.DOCUMENT_DUPLICATE:
+            return composeDetail(`${subject}: ${where} lists ${path} more than once; each INDEX path appears once.`, sectionRemedy ? CONSULTED_REMEDY : blockRemedy(c.planId));
+        case exports.STANDARDS_PROBLEM_KIND.DEGRADED_MIXED:
+            return composeDetail(`${subject}: the ${exports.VAULT_STANDARDS_TAG_OPEN} block carries a degraded line and document lines together; a record is one or the other.`, blockRemedy(c.planId));
+        case exports.STANDARDS_PROBLEM_KIND.NONE_WITHOUT_REASON:
+            return composeDetail(`${subject} records consulted-none with an empty reason slot; it must say why no indexed standards document applies to this plan.`, 'Fill the reason slot with one clause.');
+        case exports.STANDARDS_PROBLEM_KIND.PATH_NOT_RESOLVED: {
+            // iter-3 WR-01: on a degraded INDEX there are no entries to choose
+            // from, and the only record the block verb can then write is a degraded
+            // one, so the detail names the measured status and the INDEX repair.
+            const fix = c.indexStatus === undefined ? null : standardsIndexRepair(c.indexStatus);
+            if (fix !== null) {
+                return composeDetail(`${subject} lists standards documents, but ${fix.cause}${c.indexStatus === 'not-loaded' ? '' : ' at the loaded sha'}, so no listed document can be checked against it.`, `${fix.repair}, then re-run this check.`);
+            }
+            return composeDetail(`${subject} lists ${path}, which is not a resolved INDEX entry at the loaded sha.`, `Re-read the ## INDEX section of .planning/vault/SUMMARY.md, choose from its entries, and ${lowerFirst(blockRemedy(c.planId))}`);
+        }
+        case exports.STANDARDS_PROBLEM_KIND.PIN_MISMATCH: {
+            const what = c.path ? `${path} at` : 'its stamp at';
+            const against = sectionRemedy ? `the plan's ${exports.VAULT_STANDARDS_TAG_OPEN} block records` : 'the loaded vault is';
+            const fix = sectionRemedy || c.indexStatus === undefined ? null : standardsIndexRepair(c.indexStatus);
+            return composeDetail(`${subject} records ${what} ${echo(c.recorded) || '<none>'}, but ${against} ${echo(c.loaded) || '<none>'}; a standards record must name the pin the documents were read at.`, sectionRemedy
+                ? CONSULTED_REMEDY
+                : fix !== null
+                    ? `${fix.repair}, then re-read the documents at the loaded pin. ${blockRemedy(c.planId)}`
+                    : `Re-read the documents at the loaded pin. ${blockRemedy(c.planId)}`);
+        }
+        case exports.STANDARDS_PROBLEM_KIND.CACHE_UNREADABLE:
+            return composeDetail(`${subject} names standards documents, but the vault cache could not be read at gate time, so its pins and paths cannot be checked.`, FETCH_REMEDY);
+        case exports.STANDARDS_PROBLEM_KIND.DEGRADED_UNTRUE:
+            if (c.required === true && c.overrideUnverified === true) {
+                // D-35: an override line counts only when the load gate's own verdict,
+                // recomputed now, blocks for the reason the line records.
+                return composeDetail(`${subject} records ${echo(c.recorded) || 'a degraded line'} while vault.required is on, and its override line does not match the load gate's blocking verdict now, so it suppresses nothing.`, `Re-run \`pp-tools vault standards block --plan ${echoPlanId(c.planId)}\` with PP_VAULT_OVERRIDE_REASON set where it runs, and embed its output verbatim.`);
+            }
+            if (c.required === true) {
+                // iter-3 WR-01: the repair follows the measured status (no vault
+                // loaded needs a fetch, not an INDEX restore); an unknown or absent
+                // status keeps the INDEX repair, as before.
+                const fix = indexRepairFor(c.indexStatus ?? 'missing');
+                return composeDetail(`${subject} records ${echo(c.recorded) || 'a degraded line'} while vault.required is on: the load gate should have stopped this plan, and the block carries no override line.`, `${fix.repair}, then re-run \`pp-tools vault standards block --plan ${echoPlanId(c.planId)}\`; to pass the load gate on purpose, set PP_VAULT_OVERRIDE_REASON where the block verb runs.`);
+            }
+            return composeDetail(`${subject} records ${echo(c.recorded) || 'a degraded line'}, but the gate measures INDEX.md ${echo(c.measured) || 'in another state'}.`, blockRemedy(c.planId));
+        case exports.STANDARDS_PROBLEM_KIND.CONSULTED_ABSENT:
+            return composeDetail(`${subject} has no ${exports.STANDARDS_CONSULTED_HEADING} section at column 0 outside code fences and comments.`, CONSULTED_REMEDY);
+        case exports.STANDARDS_PROBLEM_KIND.CONSULTED_MISMATCH: {
+            let head;
+            switch (c.form) {
+                case 'unfilled':
+                    head = `${subject}: the status slot for ${path} is empty; it must say \`read\` or \`not read: <one clause>\`.`;
+                    break;
+                case 'missing':
+                    head = `${subject}: ${path} is in the plan's ${exports.VAULT_STANDARDS_TAG_OPEN} block but not in its ${exports.STANDARDS_CONSULTED_HEADING} section.`;
+                    break;
+                case 'extra':
+                    head = `${subject}: ${path} is in the ${exports.STANDARDS_CONSULTED_HEADING} section but not in the plan's ${exports.VAULT_STANDARDS_TAG_OPEN} block.`;
+                    break;
+                default:
+                    head = `${subject}: the ${exports.STANDARDS_CONSULTED_HEADING} section and the plan's ${exports.VAULT_STANDARDS_TAG_OPEN} block disagree: a degraded record is echoed by its exact degraded line, and a document record by its documents.`;
+            }
+            return composeDetail(head, CONSULTED_REMEDY);
+        }
+        case exports.STANDARDS_PROBLEM_KIND.PLAN_ID_MISMATCH:
+            return composeDetail(`${subject} records plan ${echoPlanId(c.planId)}, but its filename names plan ${echoPlanId(c.filenamePlanId)}.`, sectionRemedy ? CONSULTED_REMEDY : blockRemedy(c.filenamePlanId ?? c.planId));
+        case exports.STANDARDS_PROBLEM_KIND.PAIR_MISSING:
+            return composeDetail(`${subject}: plan ${echoPlanId(c.planId)} has no SUMMARY carrying its ${exports.STANDARDS_CONSULTED_HEADING} section, which this gate point requires.`, `Execute the plan, then ${CONSULTED_REMEDY.charAt(0).toLowerCase()}${CONSULTED_REMEDY.slice(1)}`);
+        case exports.STANDARDS_PROBLEM_KIND.ORPHAN_SUMMARY:
+            return composeDetail(`${subject} carries ${exports.STANDARDS_CONSULTED_HEADING} for plan ${echoPlanId(c.planId)}, but no PLAN in this phase records that plan id.`, `Render the section from the PLAN this SUMMARY belongs to. ${CONSULTED_REMEDY}`);
+        case exports.STANDARDS_PROBLEM_KIND.ANCHOR_MALFORMED:
+            // 16-06: the anchor line is the CLI's; a hand-typed or edited one is
+            // dropped, never read as a commit, and this names the part, not the value.
+            return composeDetail(`${subject}: the ${exports.STANDARDS_CONSULTED_HEADING} section ${echo(c.part, 160) || 'carries an anchor line outside its grammar'}${lineSuffix(c)}; the anchor line is written by the CLI, never typed.`, ANCHOR_REMEDY);
+        default:
+            return composeDetail(`${subject}: the standards record does not match its grammar.`, blockRemedy(c.planId));
+    }
+}
+function problem(kind, ctx) {
+    const out = { kind, detail: standardsProblemDetail(kind, ctx) };
+    if (typeof ctx.path === 'string')
+        out.path = ctx.path;
+    if (typeof ctx.line === 'number')
+        out.line = ctx.line;
+    return out;
+}
+// ─── Serializers ─────────────────────────────────────────────────────────────
+function slot(v) {
+    return typeof v === 'string' && v !== '' ? v : exports.STANDARDS_NONE;
+}
+function reasonSlot(reason) {
+    const r = typeof reason === 'string' ? reason : '';
+    return r === '' ? exports.STANDARDS_REASON_MARKER.trimEnd() : `${exports.STANDARDS_REASON_MARKER}${r}`;
+}
+/**
+ * A degraded line as it may be echoed (15-REVIEW WR-03, defence in depth for
+ * the `vault standards consulted` output and its `--raw` envelope): a
+ * consulted-none clause the reason rules accept is returned byte for byte, so
+ * the section still matches its block; any other clause is sanitised first.
+ * The CLI-only kinds carry a code from a closed set and are returned as they are.
+ */
+function standardsEchoDegraded(d) {
+    if (d.kind !== 'consulted-none' || d.reason === '' || validateReasonClause(d.reason).ok)
+        return { kind: d.kind, reason: d.reason };
+    return { kind: d.kind, reason: sanitiseVaultText(d.reason, exports.STANDARDS_REASON_MAX + 1) };
+}
+function degradedLine(d) {
+    if (d.kind === 'consulted-none')
+        return `- (consulted-none)${EM}${reasonSlot(standardsEchoDegraded(d).reason)}`;
+    return `- (${d.kind})${EM}${d.reason}`;
+}
+function stampLine(r, withStatus) {
+    const base = `${exports.STANDARDS_STAMP_PREFIX}${r.planId}${SEP}vault ${slot(r.repo)} @ ${slot(r.ref)}${SEP}sha ${slot(r.sha)}`;
+    return withStatus ? `${base}${SEP}INDEX.md ${r.indexStatus}` : base;
+}
+function token(s) {
+    const t = sanitiseVaultText(typeof s === 'string' ? s : '', ECHO_MAX).replace(/\s+/g, '_');
+    return t === '' ? 'unknown' : t;
+}
+function overrideLine(o) {
+    const who = sanitiseVaultText(o.who, ECHO_MAX).split(SEP).join(' - ') || 'unknown';
+    const reason = sanitiseVaultText(o.reason, exports.STANDARDS_REASON_MAX + 1) || 'unspecified';
+    return `${exports.STANDARDS_OVERRIDE_PREFIX}${token(o.gate)}${SEP}suppressed ${token(o.suppressedReason)}${SEP}by ${who}${SEP}at ${token(o.when)}${SEP}${exports.STANDARDS_REASON_MARKER}${reason}`;
+}
+/**
+ * Check a record is one the parser accepts back; throws a plain Error naming
+ * the first violation. The verbs only ever serialize records they measured,
+ * so a throw here is an engine bug, never an operator input.
+ */
+function assertSerializable(r) {
+    if (!r || typeof r !== 'object')
+        throw new Error('serializeStandardsBlock: record is not an object');
+    if (typeof r.planId !== 'string' || !exports.SCAFFOLD_PLAN_ID_RE.test(r.planId)) {
+        throw new Error('serializeStandardsBlock: planId does not match SCAFFOLD_PLAN_ID_RE');
+    }
+    if (!exports.STANDARDS_INDEX_STATUSES.includes(r.indexStatus)) {
+        throw new Error('serializeStandardsBlock: indexStatus is outside STANDARDS_INDEX_STATUSES');
+    }
+    const documents = Array.isArray(r.documents) ? r.documents : [];
+    if (r.degraded && documents.length > 0) {
+        throw new Error('serializeStandardsBlock: a degraded record carries no document lines');
+    }
+    if (r.degraded && !exports.STANDARDS_DEGRADED_KINDS.includes(r.degraded.kind)) {
+        throw new Error('serializeStandardsBlock: degraded kind is outside STANDARDS_DEGRADED_KINDS');
+    }
+    if (!r.degraded && documents.length === 0) {
+        throw new Error('serializeStandardsBlock: a record carries document lines or one degraded line');
+    }
+    for (const d of documents) {
+        if (!exports.STANDARDS_SHA_RE.test(String(d.sha)) || typeof d.ref !== 'string' || /\s/.test(d.ref) || d.ref === '') {
+            throw new Error('serializeStandardsBlock: a document line needs a ref and a 40-hex sha');
+        }
+    }
+    const stampProblem = checkRecordConsistency({ indexStatus: r.indexStatus, sha: slot(r.sha), documents, degraded: r.degraded });
+    if (stampProblem !== null)
+        throw new Error(`serializeStandardsBlock: ${stampProblem}`);
+}
+/**
+ * The block text the `vault standards block` verb prints: the open tag, the
+ * stamp, the document lines (empty reason slots by default) or the one
+ * degraded line, the override line when present, the close tag, and a
+ * trailing newline. An empty slot is written `reason:` with no trailing space,
+ * so an editor that strips trailing whitespace cannot change the record; the
+ * parser accepts `reason:` and `reason: <clause>`.
+ */
+function serializeStandardsBlock(record) {
+    assertSerializable(record);
+    const lines = [exports.VAULT_STANDARDS_TAG_OPEN, stampLine(record, true)];
+    if (record.degraded) {
+        lines.push(degradedLine(record.degraded));
+    }
+    else {
+        for (const d of record.documents) {
+            lines.push(`${VAULT_ENTRY_PREFIX}${d.path}\`${EM}${d.ref} @ ${d.sha}${EM}${reasonSlot(d.reason)}`);
+        }
+    }
+    if (record.override)
+        lines.push(overrideLine(record.override));
+    lines.push(exports.VAULT_STANDARDS_TAG_CLOSE);
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * The section's anchor line (16-06, D-35): `- anchors: [start <commit> · ]end
+ * <commit>[ · backfilled by <who> at <iso-8601>]`. Throws on a value its own
+ * parser would refuse, so the writer can never emit a line its reader rejects;
+ * the verbs pass only shas they read from git and a `by` the seal leaf
+ * normalised, so a throw is an engine bug, never an operator input.
+ */
+function formatStandardsAnchorLine(anchors) {
+    const a = anchors && typeof anchors === 'object' ? anchors : {};
+    if (typeof a.end !== 'string' || !vault_seal_cjs_1.ANCHOR_SHA_RE.test(a.end))
+        throw new Error('formatStandardsAnchorLine: end is not a full lowercase commit id');
+    const hasStart = a.start !== undefined && a.start !== null;
+    if (hasStart && (typeof a.start !== 'string' || !vault_seal_cjs_1.ANCHOR_SHA_RE.test(a.start))) {
+        throw new Error('formatStandardsAnchorLine: start is not a full lowercase commit id');
+    }
+    const hasBackfill = a.backfill !== undefined && a.backfill !== null;
+    if (hasBackfill && !(0, vault_seal_cjs_1.isAnchorBackfill)(a.backfill))
+        throw new Error('formatStandardsAnchorLine: backfill is not { by, at }');
+    const facts = [...(hasStart ? [`start ${a.start}`] : []), `end ${a.end}`];
+    const tail = hasBackfill ? `${SEP}backfilled by ${a.backfill.by} at ${a.backfill.at}` : '';
+    return `${exports.STANDARDS_ANCHOR_PREFIX}${facts.join(SEP)}${tail}`;
+}
+/** `- anchors: [start H · ]end H[ · backfilled by <who> at <at>]`; H is the seal leaf's anchor shape. */
+const ANCHOR_LINE_RE = /^- anchors: (?:start ([0-9a-f]{40}|[0-9a-f]{64}) \u00B7 )?end ([0-9a-f]{40}|[0-9a-f]{64})(?: \u00B7 backfilled by (.+) at (\S+))?$/;
+/**
+ * Read one line as the anchor line, tri-state like `parseDegradedLine`: `null`
+ * when the line is not an anchor line at all (it does not open with the
+ * prefix), `{ ok: false, part }` when it opens with the prefix but is not one of
+ * the forms (a short or uppercase sha, a missing `end`, a malformed back-fill
+ * tail), `{ ok: true, value }` otherwise. The shas are checked against the seal
+ * leaf's `ANCHOR_SHA_RE` and the back-fill against `isAnchorBackfill`, so the
+ * grammar has one owner. Never throws.
+ */
+function parseStandardsAnchorLine(line) {
+    if (typeof line !== 'string' || !line.startsWith(exports.STANDARDS_ANCHOR_PREFIX.trimEnd()))
+        return null;
+    const m = ANCHOR_LINE_RE.exec(line);
+    if (!m) {
+        return { ok: false, part: `carries an anchor line that is not \`- anchors: [start <commit>${SEP}]end <commit>\` with full lowercase commit ids` };
+    }
+    const value = { end: m[2] };
+    if (m[1] !== undefined)
+        value.start = m[1];
+    if (!vault_seal_cjs_1.ANCHOR_SHA_RE.test(value.end) || (value.start !== undefined && !vault_seal_cjs_1.ANCHOR_SHA_RE.test(value.start))) {
+        return { ok: false, part: 'carries an anchor line whose commit is not a full lowercase commit id' };
+    }
+    if (m[3] !== undefined) {
+        const backfill = { by: m[3], at: m[4] };
+        if (!(0, vault_seal_cjs_1.isAnchorBackfill)(backfill)) {
+            return { ok: false, part: 'carries an anchor line whose back-fill is not `backfilled by <who> at <iso-8601>`' };
+        }
+        value.backfill = backfill;
+    }
+    return { ok: true, value };
+}
+/**
+ * The `## Standards Consulted` section the `vault standards consulted` verb
+ * prints: the heading, a blank line, the stamp (no INDEX.md status), then one
+ * entry per block document with an EMPTY status slot — a default of `read`
+ * would let a pasted section claim reads that never happened. A degraded
+ * record echoes its degraded line instead. `opts.entries` fills the slots (the
+ * tests and the reference examples use it); the CLI never does.
+ *
+ * 16-06: `opts.anchors` appends the anchor line LAST. Without it the output is
+ * byte-identical to the pre-16-06 serializer.
+ */
+function serializeConsultedSection(record, opts = {}) {
+    const lines = [exports.STANDARDS_CONSULTED_HEADING, '', stampLine(record, false)];
+    if (record.degraded) {
+        lines.push(degradedLine(record.degraded));
+    }
+    else {
+        const filled = new Map();
+        for (const e of opts.entries ?? [])
+            filled.set(e.path, e);
+        for (const d of record.documents) {
+            const e = filled.get(d.path);
+            const head = `${VAULT_ENTRY_PREFIX}${d.path}\``;
+            if (!e || e.status === 'unfilled')
+                lines.push(`${head}${EM_TRIMMED}`);
+            else if (e.status === 'read')
+                lines.push(`${head}${EM}${exports.STANDARDS_CONSULTED_READ}`);
+            else
+                lines.push(`${head}${EM}${exports.STANDARDS_CONSULTED_NOT_READ}${e.reason ?? ''}`.trimEnd());
+        }
+    }
+    if (opts.anchors)
+        lines.push(formatStandardsAnchorLine(opts.anchors));
+    return `${lines.join('\n')}\n`;
+}
+// ─── Whole-line scanning ─────────────────────────────────────────────────────
+// The fence-open shape of the vault-index leaf (CommonMark: ≤3 spaces of
+// indent, ≥3 backticks or ≥3 tildes; a backtick fence's info string may not
+// carry a backtick). A closing fence uses the same character, at least as long.
+const FENCE_OPEN_RE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+// Any ATX heading at column 0 ends the consulted section.
+const ATX_HEADING_RE = /^#{1,6}(?:[ \t]|$)/;
+// So does a thematic break (CommonMark: up to three spaces of indent, then
+// three or more of one of - * _, optionally spaced). The shipped SUMMARY
+// template closes every SUMMARY with `---` and an italic footer, so a section
+// placed last must end there, not run into the footer (15-REVIEW WR-05).
+const THEMATIC_BREAK_RE = /^ {0,3}([-*_])(?:[ \t]*\1){2,}[ \t]*$/;
+function splitLines(text) {
+    let src = typeof text === 'string' ? text : '';
+    if (src.charCodeAt(0) === 0xfeff)
+        src = src.slice(1);
+    return src.replace(/\r\n?/g, '\n').split('\n').map((l) => l.trimEnd());
+}
+/**
+ * The index of the first body line: past a YAML frontmatter that opens on
+ * line 1 with `---` and closes with a later `---` line. An unclosed
+ * frontmatter is not a frontmatter.
+ */
+function bodyStart(lines) {
+    if (lines[0] !== '---')
+        return 0;
+    const close = lines.indexOf('---', 1);
+    return close > 0 ? close + 1 : 0;
+}
+/**
+ * A scanner over the "live" lines of a markdown body: outside the frontmatter,
+ * fenced code and HTML comments. `stop` lets a caller consume a region itself
+ * (a block's interior) by returning the index to resume after.
+ */
+function liveLineIndexes(lines, from, stop) {
+    const out = [];
+    let inFence = null;
+    let inComment = false;
+    for (let i = from; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (inFence) {
+            const close = FENCE_OPEN_RE.exec(line);
+            if (close && close[1][0] === inFence.char && close[1].length >= inFence.len && close[2].trim() === '')
+                inFence = null;
+            continue;
+        }
+        if (inComment) {
+            if (line.includes('-->'))
+                inComment = false;
+            continue;
+        }
+        const fence = FENCE_OPEN_RE.exec(line);
+        if (fence && !(fence[1][0] === '`' && fence[2].includes('`'))) {
+            inFence = { char: fence[1][0], len: fence[1].length };
+            continue;
+        }
+        const lead = line.trimStart();
+        if (lead.startsWith('<!--')) {
+            if (!lead.slice(4).includes('-->'))
+                inComment = true;
+            continue;
+        }
+        out.push(i);
+        if (stop) {
+            const next = stop(i);
+            if (next !== null)
+                i = next;
+        }
+    }
+    return out;
+}
+/**
+ * Find a section by its exact heading line (16-03). The heading counts only as
+ * a whole column-0 line outside the frontmatter, fenced code and HTML comments;
+ * the section runs to the next ATX heading, the next thematic break or the end
+ * of the text. This is the rule `parseConsultedSection` applies, and it is
+ * exported so `src/vault-seal.cts` (the door-record parser) and the vault
+ * router ask this scanner instead of keeping a second one.
+ * Never throws.
+ */
+function findLiveSection(text, heading) {
+    const lines = splitLines(text);
+    const live = liveLineIndexes(lines, bodyStart(lines));
+    const headings = live.filter((i) => lines[i] === heading);
+    const body = [];
+    if (headings.length > 0) {
+        for (let i = headings[0] + 1; i < lines.length; i += 1) {
+            if (ATX_HEADING_RE.test(lines[i]) || THEMATIC_BREAK_RE.test(lines[i]))
+                break;
+            if (lines[i].trim() !== '')
+                body.push(i);
+        }
+    }
+    return { lines, headings, body };
+}
+// ─── Line parsers ────────────────────────────────────────────────────────────
+const DEGRADED_RE = /^- \((consulted-none|index-missing|could-not-check)\) \u2014 (.*)$/;
+const DEGRADED_PREFIX_RE = /^- \(/;
+const DOCUMENT_TAIL_RE = /^(\S+) @ ([0-9a-f]{40}) \u2014 reason:(?: (.*))?$/;
+const OVERRIDE_RE = /^Override: gate (\S+) \u00B7 suppressed (\S+) \u00B7 by (.+?) \u00B7 at (\S+) \u00B7 reason: (.+)$/;
+function parseDegradedLine(line) {
+    if (!DEGRADED_PREFIX_RE.test(line))
+        return null;
+    const m = DEGRADED_RE.exec(line);
+    if (!m)
+        return { ok: false, part: 'carries a degraded line outside the closed set (consulted-none, index-missing, could-not-check)' };
+    const kind = m[1];
+    const rest = m[2];
+    if (kind === 'consulted-none') {
+        if (rest !== 'reason:' && !rest.startsWith(exports.STANDARDS_REASON_MARKER)) {
+            return { ok: false, part: 'carries a consulted-none line without its `reason:` slot' };
+        }
+        return { ok: true, value: { kind, reason: rest === 'reason:' ? '' : rest.slice(exports.STANDARDS_REASON_MARKER.length) } };
+    }
+    if (kind === 'index-missing') {
+        if (rest !== exports.STANDARDS_INDEX_MISSING_CODE)
+            return { ok: false, part: `carries an index-missing line whose code is not ${exports.STANDARDS_INDEX_MISSING_CODE}` };
+        return { ok: true, value: { kind, reason: rest } };
+    }
+    if (!exports.STANDARDS_COULD_NOT_CHECK_CODES.includes(rest)) {
+        return { ok: false, part: 'carries a could-not-check line whose code is outside the closed set' };
+    }
+    return { ok: true, value: { kind, reason: rest } };
+}
+function parseStampLine(line, withStatus) {
+    if (!line.startsWith(exports.STANDARDS_STAMP_PREFIX))
+        return { ok: false, part: 'does not open with its stamp line' };
+    const facts = line.slice(exports.STANDARDS_STAMP_PREFIX.length).split(SEP);
+    const want = withStatus ? 4 : 3;
+    if (facts.length !== want) {
+        return {
+            ok: false,
+            part: withStatus
+                ? `has a stamp with ${facts.length} of its 4 facts (plan, vault, sha, INDEX.md status)`
+                : `has a stamp with ${facts.length} of its 3 facts (plan, vault, sha) and no INDEX.md status`,
+        };
+    }
+    const [planId, vaultFact, shaFact, statusFact] = facts;
+    if (!exports.SCAFFOLD_PLAN_ID_RE.test(planId))
+        return { ok: false, part: 'has a stamp whose plan id is not a plan identifier such as 15-02' };
+    const v = /^vault (\S+) @ (\S+)$/.exec(vaultFact);
+    if (!v)
+        return { ok: false, part: 'has a stamp whose vault fact is not `vault <repo> @ <ref>`' };
+    const s = /^sha (\S+)$/.exec(shaFact);
+    if (!s || !(exports.STANDARDS_SHA_RE.test(s[1]) || s[1] === exports.STANDARDS_NONE)) {
+        return { ok: false, part: 'has a stamp whose sha is not 40 lowercase hex characters' };
+    }
+    let indexStatus = null;
+    if (withStatus) {
+        const st = /^INDEX\.md (\S+)$/.exec(statusFact);
+        if (!st || !exports.STANDARDS_INDEX_STATUSES.includes(st[1])) {
+            return { ok: false, part: `has a stamp whose INDEX.md status is not one of ${exports.STANDARDS_INDEX_STATUSES.join(', ')}` };
+        }
+        indexStatus = st[1];
+    }
+    return { ok: true, value: { planId, repo: v[1], ref: v[2], sha: s[1], indexStatus } };
+}
+/**
+ * The record's internal agreement: the stamp's INDEX.md status implies which
+ * line the record carries, and `none` in the sha slot is written exactly when
+ * INDEX.md is `not-loaded`, in both directions (15-REVIEW WR-02: the verb
+ * never writes another shape, so `sha none` on a missing or unchecked index
+ * is an edit, and accepting it would let that edit skip the pin comparison).
+ * Returns the violated part, or null.
+ */
+function checkRecordConsistency(r) {
+    const hasDocs = r.documents.length > 0;
+    if (r.indexStatus === 'ok') {
+        if (r.degraded && r.degraded.kind !== 'consulted-none')
+            return `has a stamp saying INDEX.md ok but carries the ${r.degraded.kind} line`;
+    }
+    else {
+        const code = STATUS_CODE[r.indexStatus];
+        const kind = r.indexStatus === 'missing' ? 'index-missing' : 'could-not-check';
+        if (hasDocs || !r.degraded || r.degraded.kind !== kind || r.degraded.reason !== code) {
+            return `has a stamp saying INDEX.md ${r.indexStatus}, which requires the line \`- (${kind}) \u2014 ${code}\``;
+        }
+    }
+    if (r.sha === exports.STANDARDS_NONE && r.indexStatus !== 'not-loaded') {
+        return 'has a stamp whose sha is not 40 lowercase hex characters (none is written only when INDEX.md is not-loaded)';
+    }
+    if (r.indexStatus === 'not-loaded' && r.sha !== exports.STANDARDS_NONE) {
+        return 'has a stamp saying INDEX.md not-loaded with a sha (a record with no loaded manifest writes sha none)';
+    }
+    return null;
+}
+/** The unfilled consulted slot: a head that ends at the separator. */
+function splitUnfilledEntry(line) {
+    if (!line.endsWith(EM_TRIMMED))
+        return null;
+    // Reuse the one head grammar: complete the separator with a probe tail.
+    const probe = splitVaultEntryLine(`${line} _`);
+    if (probe === null || 'malformed' in probe || probe.rest !== '_')
+        return null;
+    return probe.path;
+}
+// ─── parseStandardsBlock ─────────────────────────────────────────────────────
+function parseBlockInterior(lines, open, close, opts) {
+    const problems = [];
+    const base = { artifact: opts.artifact, where: 'block' };
+    const malformed = (part, idx, planId) => problems.push(problem(exports.STANDARDS_PROBLEM_KIND.BLOCK_MALFORMED, { ...base, part, line: idx + 1, planId }));
+    const body = [];
+    for (let i = open + 1; i < close; i += 1)
+        if (lines[i].trim() !== '')
+            body.push(i);
+    if (body.length === 0 || !lines[body[0]].startsWith(exports.STANDARDS_STAMP_PREFIX)) {
+        const at = body.length === 0 ? open : body[0];
+        malformed('does not open with its stamp line', at);
+        return { record: null, problems };
+    }
+    const stamp = parseStampLine(lines[body[0]], true);
+    if (!stamp.ok) {
+        malformed(stamp.part, body[0]);
+        return { record: null, problems };
+    }
+    const planId = stamp.value.planId;
+    const documents = [];
+    const degradedLines = [];
+    let override = null;
+    let overrideAt = -1;
+    const seen = new Set();
+    let structural = false;
+    for (let k = 1; k < body.length; k += 1) {
+        const idx = body[k];
+        const line = lines[idx];
+        if (overrideAt !== -1) {
+            malformed('carries a line after its override line; the override line is last', idx, planId);
+            structural = true;
+            break;
+        }
+        if (line.startsWith(exports.STANDARDS_OVERRIDE_PREFIX)) {
+            const m = OVERRIDE_RE.exec(line);
+            if (!m) {
+                malformed('carries an override line that does not match the override grammar', idx, planId);
+                structural = true;
+                break;
+            }
+            override = { gate: m[1], suppressedReason: m[2], who: m[3], when: m[4], reason: m[5] };
+            overrideAt = idx;
+            continue;
+        }
+        if (line.startsWith(exports.STANDARDS_STAMP_PREFIX)) {
+            malformed('carries a second stamp line', idx, planId);
+            structural = true;
+            break;
+        }
+        const deg = parseDegradedLine(line);
+        if (deg !== null) {
+            if (!deg.ok) {
+                malformed(deg.part, idx, planId);
+                structural = true;
+                break;
+            }
+            degradedLines.push(deg.value);
+            continue;
+        }
+        const head = splitVaultEntryLine(line);
+        if (head === null) {
+            malformed('carries a line that is neither a document line, a degraded line nor the override line', idx, planId);
+            structural = true;
+            break;
+        }
+        if ('malformed' in head) {
+            malformed('carries a document line whose head is not - `<index-path>` followed by the separator', idx, planId);
+            structural = true;
+            break;
+        }
+        const tail = DOCUMENT_TAIL_RE.exec(head.rest);
+        if (!tail) {
+            malformed('carries a document line whose tail is not `<ref> @ <40-hex> \u2014 reason:`', idx, planId);
+            structural = true;
+            break;
+        }
+        if (seen.has(head.path)) {
+            problems.push(problem(exports.STANDARDS_PROBLEM_KIND.DOCUMENT_DUPLICATE, { ...base, path: head.path, line: idx + 1, planId }));
+        }
+        seen.add(head.path);
+        documents.push({ path: head.path, ref: tail[1], sha: tail[2], reason: tail[3] ?? '', line: idx + 1 });
+    }
+    if (structural)
+        return { record: null, problems };
+    if (degradedLines.length > 0 && documents.length > 0) {
+        problems.push(problem(exports.STANDARDS_PROBLEM_KIND.DEGRADED_MIXED, { ...base, planId }));
+        return { record: null, problems };
+    }
+    if (degradedLines.length > 1) {
+        malformed('carries more than one degraded line; a degraded record has exactly one', open, planId);
+        return { record: null, problems };
+    }
+    if (degradedLines.length === 0 && documents.length === 0) {
+        malformed('carries neither a document line nor a degraded line', open, planId);
+        return { record: null, problems };
+    }
+    const record = {
+        planId,
+        repo: stamp.value.repo,
+        ref: stamp.value.ref,
+        sha: stamp.value.sha,
+        indexStatus: stamp.value.indexStatus,
+        documents,
+        degraded: degradedLines[0] ?? null,
+        override,
+    };
+    const inconsistent = checkRecordConsistency(record);
+    if (inconsistent !== null) {
+        malformed(inconsistent, body[0], planId);
+        return { record: null, problems };
+    }
+    return { record, problems };
+}
+/**
+ * Read the `<vault_standards>` block out of a PLAN.md text. Never throws; a
+ * non-string is read as `''`.
+ *
+ * Tags count only as whole lines at column 0 (no indent: more restrictive than
+ * CommonMark's three spaces, and where the CLI puts them), outside the YAML
+ * frontmatter, fenced code and HTML comments — a tag quoted in prose or in an
+ * example is not a block (Pitfall 5). The interior runs to the first column-0
+ * close tag. Two blocks report `standards_block_duplicate` and the first is
+ * still parsed; an open without a close reports `standards_block_unterminated`;
+ * none reports `standards_block_absent`.
+ *
+ * Emptiness of a reason slot is NOT a parse problem: the verb emits empty
+ * slots, and the judgement decides whether an empty slot is acceptable.
+ */
+function parseStandardsBlock(text, opts = {}) {
+    const o = opts && typeof opts === 'object' ? opts : {};
+    const lines = splitLines(text);
+    const opens = [];
+    liveLineIndexes(lines, bodyStart(lines), (i) => {
+        if (lines[i] !== exports.VAULT_STANDARDS_TAG_OPEN)
+            return null;
+        let j = i + 1;
+        while (j < lines.length && lines[j] !== exports.VAULT_STANDARDS_TAG_CLOSE)
+            j += 1;
+        if (j >= lines.length) {
+            opens.push({ open: i, close: null });
+            return lines.length;
+        }
+        opens.push({ open: i, close: j });
+        return j;
+    });
+    if (opens.length === 0) {
+        return {
+            present: false,
+            record: null,
+            problems: [problem(exports.STANDARDS_PROBLEM_KIND.BLOCK_ABSENT, { artifact: o.artifact })],
+            openLine: null,
+            closeLine: null,
+        };
+    }
+    const first = opens[0];
+    if (first.close === null) {
+        return {
+            present: true,
+            record: null,
+            problems: [problem(exports.STANDARDS_PROBLEM_KIND.BLOCK_UNTERMINATED, { artifact: o.artifact, line: first.open + 1 })],
+            openLine: first.open + 1,
+            closeLine: null,
+        };
+    }
+    const interior = parseBlockInterior(lines, first.open, first.close, o);
+    const problems = [...interior.problems];
+    if (opens.length > 1) {
+        problems.unshift(problem(exports.STANDARDS_PROBLEM_KIND.BLOCK_DUPLICATE, {
+            artifact: o.artifact, count: opens.length, planId: interior.record?.planId,
+        }));
+    }
+    return { present: true, record: interior.record, problems, openLine: first.open + 1, closeLine: first.close + 1 };
+}
+// ─── parseConsultedSection ───────────────────────────────────────────────────
+function emptySection(problems, present, headingLine) {
+    return { present, planId: null, repo: null, ref: null, sha: null, entries: [], degraded: null, problems, headingLine };
+}
+/**
+ * Read the `## Standards Consulted` section out of a SUMMARY.md text. Never
+ * throws. The heading counts only as a whole column-0 line, written exactly,
+ * outside the frontmatter, fenced code and HTML comments. The section runs to
+ * the next ATX heading, the next thematic break (the SUMMARY template's `---`
+ * footer rule) or the end of the text, and holds only the CLI's lines:
+ * the stamp, then one entry per block document (or the one degraded line),
+ * blank lines aside. Any other line is malformed; the reference says so.
+ */
+function parseConsultedSection(text, opts = {}) {
+    const o = opts && typeof opts === 'object' ? opts : {};
+    const base = { artifact: o.artifact, where: 'section' };
+    const { lines, headings, body } = findLiveSection(text, exports.STANDARDS_CONSULTED_HEADING);
+    if (headings.length === 0) {
+        return emptySection([problem(exports.STANDARDS_PROBLEM_KIND.CONSULTED_ABSENT, { artifact: o.artifact })], false, null);
+    }
+    const h = headings[0];
+    const malformed = (part, idx) => problem(exports.STANDARDS_PROBLEM_KIND.BLOCK_MALFORMED, { ...base, part, line: idx + 1 });
+    if (headings.length > 1) {
+        return emptySection([malformed('appears more than once', headings[1])], true, h + 1);
+    }
+    if (body.length === 0)
+        return emptySection([malformed('has no stamp line', h)], true, h + 1);
+    const stamp = parseStampLine(lines[body[0]], false);
+    if (!stamp.ok)
+        return emptySection([malformed(stamp.part, body[0])], true, h + 1);
+    const problems = [];
+    const entries = [];
+    const degradedLines = [];
+    const seen = new Set();
+    // 16-06: at most ONE anchor line, anywhere after the stamp. A malformed or a
+    // second one is a problem of its own kind and is DROPPED (never read as a
+    // commit), while the rest of the record still parses, so the section's
+    // other judgements still run.
+    let anchors;
+    let anchorLines = 0;
+    for (let k = 1; k < body.length; k += 1) {
+        const idx = body[k];
+        const line = lines[idx];
+        const anchor = parseStandardsAnchorLine(line);
+        if (anchor !== null) {
+            anchorLines += 1;
+            if (anchorLines > 1) {
+                problems.push(problem(exports.STANDARDS_PROBLEM_KIND.ANCHOR_MALFORMED, {
+                    ...base, part: 'carries more than one anchor line; the section has at most one', line: idx + 1,
+                }));
+                anchors = undefined;
+            }
+            else if (!anchor.ok) {
+                problems.push(problem(exports.STANDARDS_PROBLEM_KIND.ANCHOR_MALFORMED, { ...base, part: anchor.part, line: idx + 1 }));
+            }
+            else {
+                anchors = anchor.value;
+            }
+            continue;
+        }
+        const deg = parseDegradedLine(line);
+        if (deg !== null) {
+            if (!deg.ok)
+                return emptySection([malformed(deg.part, idx)], true, h + 1);
+            degradedLines.push(deg.value);
+            continue;
+        }
+        let entry = null;
+        const unfilled = splitUnfilledEntry(line);
+        if (unfilled !== null) {
+            entry = { path: unfilled, status: 'unfilled', line: idx + 1 };
+        }
+        else {
+            const head = splitVaultEntryLine(line);
+            if (head !== null && !('malformed' in head)) {
+                if (head.rest === exports.STANDARDS_CONSULTED_READ) {
+                    entry = { path: head.path, status: 'read', line: idx + 1 };
+                }
+                else if (head.rest.startsWith(exports.STANDARDS_CONSULTED_NOT_READ) || head.rest === exports.STANDARDS_CONSULTED_NOT_READ.trimEnd()) {
+                    entry = { path: head.path, status: 'not-read', reason: head.rest.slice(exports.STANDARDS_CONSULTED_NOT_READ.length), line: idx + 1 };
+                }
+            }
+        }
+        if (entry === null) {
+            return emptySection([malformed('carries a line that is not the stamp, a degraded line, or an entry ending `read`, `not read: <one clause>` or the empty slot', idx)], true, h + 1);
+        }
+        if (seen.has(entry.path)) {
+            problems.push(problem(exports.STANDARDS_PROBLEM_KIND.DOCUMENT_DUPLICATE, { ...base, path: entry.path, line: idx + 1 }));
+        }
+        seen.add(entry.path);
+        entries.push(entry);
+    }
+    if (degradedLines.length > 0 && entries.length > 0) {
+        return emptySection([malformed('carries a degraded line and entries together', h)], true, h + 1);
+    }
+    if (degradedLines.length > 1) {
+        return emptySection([malformed('carries more than one degraded line', h)], true, h + 1);
+    }
+    if (degradedLines.length === 0 && entries.length === 0) {
+        return emptySection([malformed('carries neither an entry nor a degraded line', h)], true, h + 1);
+    }
+    const parsed = {
+        present: true,
+        planId: stamp.value.planId,
+        repo: stamp.value.repo,
+        ref: stamp.value.ref,
+        sha: stamp.value.sha,
+        entries,
+        degraded: degradedLines[0] ?? null,
+        problems,
+        headingLine: h + 1,
+    };
+    // Reconstructed only when present and well-formed, and only from a single
+    // anchor line: a section with two keeps neither.
+    if (anchors !== undefined && anchorLines === 1)
+        parsed.anchors = anchors;
+    return parsed;
+}
+function isIndexStatus(s) {
+    return typeof s === 'string' && exports.STANDARDS_INDEX_STATUSES.includes(s);
+}
+/**
+ * Whether a degraded line states what the gate measured (D-20): consulted-none
+ * needs a healthy index; index-missing needs `missing`; could-not-check needs
+ * a non-ok status whose code is exactly the recorded one.
+ */
+function degradedAgrees(d, status) {
+    if (!isIndexStatus(status))
+        return false;
+    if (d.kind === 'consulted-none')
+        return status === 'ok';
+    if (status === 'ok')
+        return false;
+    if (d.kind === 'index-missing')
+        return status === 'missing';
+    return STATUS_CODE[status] === d.reason;
+}
+/**
+ * Whether an override line agrees with the load gate NOW (D-35): it names the
+ * load gate, carries the verb's timestamp form, and the load gate's own
+ * verdict, recomputed at gate time, blocks for exactly the reason the line
+ * says it suppressed. A line that fails this suppresses nothing.
+ *
+ * What this does NOT prove (15-REVIEW iter-2 WR-03): who wrote the line. It is
+ * text in a file anyone can edit and carries no signature, and every field
+ * checked here can be read off `check vault.status`, so a line typed by hand
+ * whose fields match is accepted exactly as the verb's own would be. The
+ * guarantee is agreement with the measured state, not CLI provenance; the bound
+ * on a matching line is the execute:pre load gate (which blocks unless
+ * `PP_VAULT_OVERRIDE_REASON` is set where it runs) and the strict points, which
+ * block on any recorded override. `who` and the reason text are not used.
+ */
+function overrideAgrees(o, verdict) {
+    if (!verdict || verdict.block !== true || typeof verdict.reason !== 'string' || verdict.reason === '')
+        return false;
+    if (o.gate !== exports.STANDARDS_OVERRIDE_GATE)
+        return false;
+    if (!isVerbTimestamp(o.when))
+        return false;
+    return o.suppressedReason === verdict.reason;
+}
+function degradedLabel(d) {
+    return d.kind === 'consulted-none' ? 'consulted-none' : `${d.kind} (${d.reason})`;
+}
+/**
+ * The ONE pin comparison, for the stamp and for every document line (D-18):
+ * a recorded pin matches only when BOTH its ref and its full sha equal the
+ * loaded manifest's.
+ */
+function pinDiffers(ref, sha, manifest) {
+    return ref !== manifest.ref || sha !== manifest.sha;
+}
+function pinText(ref, sha) {
+    return `${typeof ref === 'string' ? ref : exports.STANDARDS_NONE} @ ${typeof sha === 'string' ? sha : exports.STANDARDS_NONE}`;
+}
+/** The D-29 first-arm message: the measured state and the remedy; never a claim that a document was consulted. */
+function degradedAdvisory(record, d, status, artifact) {
+    return composeDetail(`${echo(artifact) || 'The artifact'} records ${echo(degradedLabel(d))} and the gate measures INDEX.md ${status} too, so no standards document governed this plan; vault.required is off, so this does not block.`, 
+    // iter-3 WR-01: the repair for the measured status, from the one owner.
+    `To govern it, ${lowerFirst(indexRepairFor(status).repair)}, then re-run \`pp-tools vault standards block --plan ${echoPlanId(record.planId)} <index-path...>\` and embed its output.`);
+}
+/**
+ * The pin a manifest yields, or null when no vault is loaded (15-07). A
+ * manifest with no 40-hex `resolvedSha`, or no single-token ref, is "not
+ * loaded": a miss record (`source: miss`, every coordinate null) and a damaged
+ * file both land here. ONE predicate for the `vault standards block` verb,
+ * which writes the record, and the trace gate, which measures it, so the two
+ * cannot disagree about whether a vault was loaded. Pure: the caller reads the
+ * manifest.
+ */
+function standardsLoadedPin(manifest) {
+    if (!manifest || typeof manifest !== 'object')
+        return null;
+    const m = manifest;
+    if (typeof m.resolvedSha !== 'string' || !exports.STANDARDS_SHA_RE.test(m.resolvedSha))
+        return null;
+    if (typeof m.ref !== 'string' || !/^\S+$/.test(m.ref))
+        return null;
+    return { repo: typeof m.repo === 'string' ? m.repo : null, ref: m.ref, sha: m.resolvedSha };
+}
+/**
+ * The stamp status for a measured state (15-07): `not-loaded` when there is no
+ * loaded pin or no index state, whatever the index function answered (on a
+ * miss record it answers a missing index, and the record must not say so);
+ * `ok`; else the short form of the degraded reason. An unknown reason fails
+ * closed to `unchecked`. Shared by the verb and the gate, like the pin above.
+ */
+function standardsMeasuredIndexStatus(pin, state) {
+    if (pin === null || !state || typeof state !== 'object')
+        return 'not-loaded';
+    if (state.status === 'ok')
+        return 'ok';
+    for (const [status, code] of Object.entries(STATUS_CODE)) {
+        if (status !== 'not-loaded' && code === state.reason)
+            return status;
+    }
+    return 'unchecked';
+}
+/**
+ * The INDEX paths a standards record may name (D-19): exactly the entries that
+ * RESOLVED at the loaded sha, never a file merely present in the cache. ONE
+ * set for the three surfaces that ask it, so they cannot disagree: the block
+ * verb (what may be selected), the consulted verb (what an executor is told to
+ * read, 15-REVIEW WR-04) and the trace gate (what a record may list). Pure:
+ * the caller computes the index state, and passes null when no vault is loaded.
+ */
+function standardsResolvedPaths(state) {
+    const entries = state && Array.isArray(state.entries) ? state.entries : [];
+    return new Set(entries.filter((e) => e.resolution === 'resolved').map((e) => e.path));
+}
+/**
+ * The degraded line a measured status implies when the planner selects no
+ * document: `consulted-none` (empty reason slot) on `ok`, else the CLI-only
+ * line carrying that status's code. The same table `checkRecordConsistency`
+ * enforces, so the verb cannot write a record the parser refuses.
+ */
+function standardsDegradedLineFor(indexStatus) {
+    if (indexStatus === 'ok')
+        return { kind: 'consulted-none', reason: '' };
+    return { kind: indexStatus === 'missing' ? 'index-missing' : 'could-not-check', reason: STATUS_CODE[indexStatus] };
+}
+/**
+ * Judge one parsed PLAN record against the measured state. Pure: no reads, no
+ * config, no clock. Order: the parse problems (a null record returns only
+ * them); the plan id; the reason clauses; then, when the record needs the
+ * cache (document lines or consulted-none) and no manifest was read,
+ * `standards_cache_unreadable` and stop; then the stamp pin; then per document
+ * its resolution and pin (on a degraded INDEX, one resolution problem naming
+ * the measured status and `standardsIndexRepair`'s repair, iter-3 WR-01);
+ * then the degraded arms of D-20/D-29:
+ *   - a degraded line that disagrees with the measured state: untrue;
+ *   - index-missing / could-not-check that agrees, `vault.required` off:
+ *     no problem, an advisory;
+ *   - agrees, `vault.required` on, no override line: untrue (the load gate
+ *     should have stopped the plan);
+ *   - agrees, `vault.required` on, override line present: no problem only
+ *     when the line agrees with `measured.loadVerdict` (D-35: the load gate's
+ *     verdict at gate time blocks for the reason the line records, under the
+ *     gate name and timestamp form the verb writes); otherwise untrue, so a
+ *     line that disagrees with the measured verdict removes nothing. A line
+ *     whose fields match is accepted whoever typed it: the guarantee is
+ *     agreement with measured state, not provenance (iter-2 WR-03).
+ * A degraded record can therefore pass only where the load gate itself would
+ * have let the build continue. The kind table stays at 17: agreement is never
+ * a kind.
+ */
+function judgeStandardsPlan(parsed, measured, ctx) {
+    const problems = Array.isArray(parsed?.problems) ? [...parsed.problems] : [];
+    const record = parsed?.record ?? null;
+    if (record === null)
+        return { problems, advisory: null, overridden: false };
+    const artifact = typeof ctx?.artifact === 'string' ? ctx.artifact : '';
+    const base = { artifact, planId: record.planId };
+    const overridden = record.override !== null && record.override !== undefined;
+    if (typeof ctx?.filenamePlanId === 'string' && ctx.filenamePlanId !== '' && ctx.filenamePlanId !== record.planId) {
+        problems.push(problem(exports.STANDARDS_PROBLEM_KIND.PLAN_ID_MISMATCH, { ...base, filenamePlanId: ctx.filenamePlanId }));
+    }
+    for (const doc of record.documents) {
+        const v = validateReasonClause(doc.reason);
+        if (!v.ok)
+            problems.push(problem(exports.STANDARDS_PROBLEM_KIND.REASON_INVALID, { ...base, path: doc.path, why: v.why, line: doc.line }));
+    }
+    const d = record.degraded;
+    if (d && d.kind === 'consulted-none') {
+        if (d.reason.trim() === '') {
+            problems.push(problem(exports.STANDARDS_PROBLEM_KIND.NONE_WITHOUT_REASON, base));
+        }
+        else {
+            const v = validateReasonClause(d.reason);
+            if (!v.ok)
+                problems.push(problem(exports.STANDARDS_PROBLEM_KIND.REASON_INVALID, { ...base, why: v.why }));
+        }
+    }
+    const manifest = measured && measured.manifest ? measured.manifest : null;
+    const needsCache = record.documents.length > 0 || (d !== null && d.kind === 'consulted-none');
+    if (manifest === null && needsCache) {
+        problems.push(problem(exports.STANDARDS_PROBLEM_KIND.CACHE_UNREADABLE, base));
+        return { problems, advisory: null, overridden };
+    }
+    // iter-3 WR-01: a document record judged where the INDEX is degraded gets
+    // ONE path problem naming the measured status and the INDEX repair (the
+    // consulted verb's words, from `standardsIndexRepair`), never one "choose
+    // from its entries" per path: there are no entries to choose from. Its pin
+    // problems are still reported, each naming the same repair first. An
+    // unknown status keeps the per-path arm, which still blocks.
+    const docStatus = measured ? measured.indexStatus : undefined;
+    const degradedIndex = record.documents.length > 0 && isIndexStatus(docStatus) && docStatus !== 'ok' ? docStatus : undefined;
+    // A loaded pin is always compared, `none` included (15-REVIEW WR-02): a
+    // record with no pin judged where a vault IS loaded was written against
+    // another vault state, and D-29's pin arm applies to it.
+    if (manifest !== null && pinDiffers(String(record.ref), String(record.sha), manifest)) {
+        problems.push(problem(exports.STANDARDS_PROBLEM_KIND.PIN_MISMATCH, {
+            ...base, recorded: pinText(record.ref, record.sha), loaded: pinText(manifest.ref, manifest.sha),
+            ...(degradedIndex !== undefined ? { indexStatus: degradedIndex } : {}),
+        }));
+    }
+    const resolved = measured && measured.resolvedPaths instanceof Set ? measured.resolvedPaths : new Set();
+    if (degradedIndex !== undefined) {
+        problems.push(problem(exports.STANDARDS_PROBLEM_KIND.PATH_NOT_RESOLVED, { ...base, indexStatus: degradedIndex }));
+    }
+    for (const doc of record.documents) {
+        if (degradedIndex === undefined && !resolved.has(doc.path)) {
+            problems.push(problem(exports.STANDARDS_PROBLEM_KIND.PATH_NOT_RESOLVED, { ...base, path: doc.path, line: doc.line }));
+        }
+        if (manifest !== null && pinDiffers(doc.ref, doc.sha, manifest)) {
+            problems.push(problem(exports.STANDARDS_PROBLEM_KIND.PIN_MISMATCH, {
+                ...base, path: doc.path, line: doc.line, recorded: pinText(doc.ref, doc.sha), loaded: pinText(manifest.ref, manifest.sha),
+                ...(degradedIndex !== undefined ? { indexStatus: degradedIndex } : {}),
+            }));
+        }
+    }
+    let advisory = null;
+    if (d) {
+        const status = measured ? measured.indexStatus : undefined;
+        if (!degradedAgrees(d, status)) {
+            problems.push(problem(exports.STANDARDS_PROBLEM_KIND.DEGRADED_UNTRUE, {
+                ...base, recorded: degradedLabel(d), measured: isIndexStatus(status) ? status : 'in an unknown state',
+            }));
+        }
+        else if (d.kind !== 'consulted-none') {
+            if (measured.required !== true) {
+                advisory = degradedAdvisory(record, d, status, artifact);
+            }
+            else if (!overridden) {
+                problems.push(problem(exports.STANDARDS_PROBLEM_KIND.DEGRADED_UNTRUE, {
+                    ...base, recorded: degradedLabel(d), required: true, indexStatus: status,
+                }));
+            }
+            else if (!overrideAgrees(record.override, measured.loadVerdict)) {
+                problems.push(problem(exports.STANDARDS_PROBLEM_KIND.DEGRADED_UNTRUE, {
+                    ...base, recorded: degradedLabel(d), required: true, overrideUnverified: true,
+                }));
+            }
+        }
+    }
+    return { problems, advisory, overridden };
+}
+/**
+ * Judge one parsed SUMMARY section on its own: the parse problems (absent,
+ * malformed, duplicate entry), the plan id against the filename, every
+ * unfilled status slot (a mismatch naming the path and both accepted forms),
+ * and every `not read:` clause by the reason rules.
+ */
+function judgeConsultedSummary(parsed, ctx) {
+    const problems = Array.isArray(parsed?.problems) ? [...parsed.problems] : [];
+    if (!parsed || !parsed.present || parsed.planId === null)
+        return problems;
+    const artifact = typeof ctx?.artifact === 'string' ? ctx.artifact : '';
+    const base = { artifact, planId: parsed.planId, where: 'section' };
+    if (typeof ctx?.filenamePlanId === 'string' && ctx.filenamePlanId !== '' && ctx.filenamePlanId !== parsed.planId) {
+        problems.push(problem(exports.STANDARDS_PROBLEM_KIND.PLAN_ID_MISMATCH, { ...base, filenamePlanId: ctx.filenamePlanId }));
+    }
+    for (const e of parsed.entries) {
+        if (e.status === 'unfilled') {
+            problems.push(problem(exports.STANDARDS_PROBLEM_KIND.CONSULTED_MISMATCH, { ...base, path: e.path, line: e.line, form: 'unfilled' }));
+        }
+        else if (e.status === 'not-read') {
+            const v = validateReasonClause(e.reason ?? '');
+            if (!v.ok)
+                problems.push(problem(exports.STANDARDS_PROBLEM_KIND.REASON_INVALID, { ...base, path: e.path, line: e.line, why: v.why }));
+        }
+    }
+    return problems;
+}
+/**
+ * Compare a PLAN's record with its paired SUMMARY section (D-13): the section
+ * stamp's ref and sha must equal the block's; a degraded block is echoed by
+ * exactly its degraded line; a document block is matched path for path, every
+ * block document once and nothing extra. A null side compares to nothing:
+ * pairing (`standards_pair_missing`, `standards_orphan_summary`) is the
+ * handler's, by recorded plan id.
+ */
+function compareConsulted(record, section, ctx) {
+    if (!record || !section || !section.present || section.planId === null)
+        return [];
+    const problems = [];
+    const base = {
+        artifact: typeof ctx?.artifact === 'string' ? ctx.artifact : '', planId: record.planId, where: 'section',
+    };
+    if (section.ref !== record.ref || section.sha !== record.sha) {
+        problems.push(problem(exports.STANDARDS_PROBLEM_KIND.PIN_MISMATCH, {
+            ...base, recorded: pinText(section.ref, section.sha), loaded: pinText(record.ref, record.sha),
+        }));
+    }
+    if (record.degraded || section.degraded) {
+        const same = record.degraded !== null && section.degraded !== null && section.entries.length === 0
+            && section.degraded.kind === record.degraded.kind && section.degraded.reason === record.degraded.reason;
+        if (!same)
+            problems.push(problem(exports.STANDARDS_PROBLEM_KIND.CONSULTED_MISMATCH, { ...base, form: 'degraded' }));
+        return problems;
+    }
+    const inSection = new Set(section.entries.map((e) => e.path));
+    const inBlock = new Set(record.documents.map((doc) => doc.path));
+    for (const doc of record.documents) {
+        if (!inSection.has(doc.path))
+            problems.push(problem(exports.STANDARDS_PROBLEM_KIND.CONSULTED_MISMATCH, { ...base, path: doc.path, form: 'missing' }));
+    }
+    for (const e of section.entries) {
+        if (!inBlock.has(e.path))
+            problems.push(problem(exports.STANDARDS_PROBLEM_KIND.CONSULTED_MISMATCH, { ...base, path: e.path, line: e.line, form: 'extra' }));
+    }
+    return problems;
+}