@pareto4/pp-core 1.12.1 → 1.13.0

package/pp-core/bin/lib/vault-command-router.cjs

@@ -1,4 +1,7 @@
 'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 /**
  * Vault command router — CLI subcommand dispatcher for `pp-tools vault`.
  *
@@ -29,7 +32,14 @@
  */
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const io = require("./io.cjs");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// The trace render arm resolves its containment boundary from the project
+// root. project-root.cjs is a leaf (node builtins only), so this adds no cycle.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const projectRootMod = require("./project-root.cjs");
+const { findProjectRoot } = projectRootMod;
 const { ERROR_REASON } = io;
 // Default CoreModule implementation. _core seam overrides this for test injection.
 const _defaultCore = { output: io.output };
@@ -46,7 +56,86 @@ const VAULT_SUBCOMMANDS = Object.freeze([
     { name: 'practices', readsVerdict: false },
     { name: 'org-profile', readsVerdict: false },
     { name: 'probe', readsVerdict: false },
+    { name: 'trace', readsVerdict: false },
+    { name: 'audit', readsVerdict: false },
+    { name: 'update', readsVerdict: false },
+    { name: 'review', readsVerdict: false },
 ]);
+/**
+ * The two trace stages and the two trace verbs, declared once: the `--stage`
+ * validation, the verb check and the operator-facing messages that name the
+ * permitted values are all derived from these lists, so they cannot disagree.
+ * The values are the frozen contract's (`docs/vault-trace-format.md`).
+ */
+const TRACE_STAGES = ['plan', 'execute'];
+const TRACE_VERBS = ['scaffold', 'render'];
+/**
+ * The plan-identifier shape `vault trace scaffold --plan` accepts: a phase
+ * segment (digits, an optional letter, optional decimal parts) followed by one
+ * or more numeric segments — the plan-identifier grammar `agents/pp-planner.md`
+ * and `src/phase-id.cts` use. It is exactly the prefix of the artifact's own
+ * filename (`04-02` for `04-02-PLAN.md`, `02.3-01` for `02.3-01-PLAN.md`), so a
+ * trace gate comparing the recorded identifier with the filename can never be
+ * handed one the writer could not emit. It rejects what is not a plan
+ * identifier at all: a bare plan number (`01`), a task label (`T1`), a slug
+ * (`04-01-vault-trace`) or an empty string.
+ */
+const SCAFFOLD_PLAN_ID_RE = /^\d+[A-Za-z]?(?:\.\d+)*(?:-\d+)+$/;
+/**
+ * The required form, in ONE wording, stated in this rejection message and in
+ * `pp-core/references/planner-vault-practices.md`. ASCII only and no
+ * backticks, so the same bytes survive a JSON string, markdown and a terminal.
+ */
+const SCAFFOLD_PLAN_ID_FORM = "The plan identifier must be the plan's phase-and-number identifier, exactly the " +
+    'prefix of its artifact filename (for example 04-02), not a bare plan number, a task ' +
+    'label or a slug.';
+/**
+ * Bound on the head read the `trace render` arm performs. The trace lives in
+ * the artifact's FRONTMATTER, so a head read is the exact region the parser
+ * needs, and an artifact body of any size can never make this arm read more.
+ */
+const TRACE_ARTIFACT_READ_BYTES = 262_144;
+/** Repo-relative artifact paths, long enough for a workstream phase tree. */
+const TRACE_REFUSAL_PATH_CAP = 200;
+/** A `gitCommit` digest: lowercase hex at sha1 or sha256 length. */
+const GIT_COMMIT_DIGEST_RE = /^[0-9a-f]{40}$|^[0-9a-f]{64}$/;
+/**
+ * Bound and control-character-collapse a caller-supplied path before it
+ * reaches a refusal message: the message reaches an operator's terminal and,
+ * on the workflow path, an agent's context, so a hostile path must not forge
+ * an extra line of output nor run to arbitrary length.
+ */
+function boundedPath(value) {
+    const collapsed = value
+        .replace(/[\u0000-\u001F\u007F]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (collapsed === '')
+        return '(an empty value)';
+    return collapsed.length > TRACE_REFUSAL_PATH_CAP
+        ? `${collapsed.slice(0, TRACE_REFUSAL_PATH_CAP)}…`
+        : collapsed;
+}
+/**
+ * Is the vault-practices capability fully active for this project? Both
+ * `vault.enabled` and `vault.practices_enabled` must be strictly `true` — the
+ * same requires-closure the promote preflight and `ship.practices` apply. The
+ * trace arms gate on this FIRST, before the flag allowlist, so an inert project
+ * stays byte-identically silent on every path, a mistyped one included.
+ */
+function tracePracticesActive(cfgGet, cwd) {
+    return cfgGet(cwd, 'vault.enabled', false) === true && cfgGet(cwd, 'vault.practices_enabled', false) === true;
+}
+/** The value token after each of `flags`, by index, so a flag's value is never read as a positional. */
+function flagValueIndices(argv, flags) {
+    const indices = new Set();
+    for (const flag of flags) {
+        const i = argv.indexOf(flag);
+        if (i !== -1)
+            indices.add(i + 1);
+    }
+    return indices;
+}
 /**
  * Render a short plain-text `vault org-profile` report from its structured
  * shape — one line naming the pointer, one naming the resolution, a
@@ -98,7 +187,7 @@ function renderOrgProfileReport(report) {
     return lines.join('\n');
 }
 // ─── Implementation ───────────────────────────────────────────────────────────
-function routeVaultCommand({ args, cwd, raw, error, _vault, _core, _practices, _exec, _writeBack, _orgProfile, _coordinates, _provider, }) {
+function routeVaultCommand({ args, cwd, raw, error, _vault, _core, _practices, _exec, _writeBack, _orgProfile, _coordinates, _provider, _trace, _audit, _update, }) {
     // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
     const vault = _vault ?? require('./vault.cjs');
     const c = _core ?? _defaultCore;
@@ -268,6 +357,9 @@ function routeVaultCommand({ args, cwd, raw, error, _vault, _core, _practices, _
             [coordinates.SHARED_REF_CONFIG_KEY]: shared.ref,
             [coordinates.SHARED_HOST_CONFIG_KEY]: shared.host,
             [coordinates.PLATFORM_HOST_CONFIG_KEY]: platformHost.host,
+            // The policy row, through the same ladder the load gate reads, so a
+            // profile value that won is not reported as overridden by null.
+            [orgProfile.VAULT_REQUIRED_CONFIG_KEY]: String(orgProfile.resolveVaultRequired(cwd).required),
         };
         // Build `effective`'s key list from ORG_PROFILE_ALLOWLIST rather than a
         // fresh literal array, so a future allowlist change surfaces here
@@ -334,11 +426,378 @@ function routeVaultCommand({ args, cwd, raw, error, _vault, _core, _practices, _
             c.output(report, true, renderOrgProfileReport(report));
         }
     }
+    else if (subcommand === 'trace') {
+        routeTrace({ args, cwd, raw, error, vault, c, _exec, _trace });
+    }
+    else if (subcommand === 'audit') {
+        routeAudit({ args, cwd, raw, error, vault, c, _exec, _audit });
+    }
+    else if (subcommand === 'review') {
+        routeReview({ args, cwd, raw, c });
+    }
+    else if (subcommand === 'update') {
+        // `vault update [<tag>] [--yes]`: without --yes it reports the plan and
+        // writes nothing; see src/vault-update.cts for the contract.
+        const RECOGNIZED_UPDATE_FLAGS = new Set(['--raw', '--yes']);
+        const unrecognizedUpdateFlag = args.slice(2).find((a) => a.startsWith('--') && !RECOGNIZED_UPDATE_FLAGS.has(a));
+        if (unrecognizedUpdateFlag !== undefined) {
+            error(`Unrecognized flag "${boundedPath(unrecognizedUpdateFlag)}" for vault update. Supported: --yes, --raw.`, ERROR_REASON.SDK_FAIL_FAST);
+            return;
+        }
+        const updatePositionals = args.slice(2).filter((a) => !a.startsWith('--'));
+        if (updatePositionals.length > 1) {
+            error('vault update takes at most one tag, e.g. "pp-tools vault update v1.4.0".', ERROR_REASON.SDK_FAIL_FAST);
+            return;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+        const updateMod = _update ?? require('./vault-update.cjs');
+        const updateResult = updateMod.vaultUpdate(cwd, {
+            target: updatePositionals[0] ?? null,
+            apply: args.includes('--yes'),
+        });
+        if (!updateResult.ok) {
+            error(updateResult.message, ERROR_REASON.SDK_FAIL_FAST);
+            return;
+        }
+        if (raw) {
+            c.output(updateResult, true, JSON.stringify(updateResult));
+        }
+        else {
+            c.output(updateResult, true, updateMod.renderVaultUpdate(updateResult));
+        }
+    }
     else {
         error(`Unknown vault subcommand. Available: ${VAULT_SUBCOMMANDS.map((x) => x.name).join(', ')}`, ERROR_REASON.SDK_UNKNOWN_COMMAND);
     }
 }
+/**
+ * `vault trace scaffold|render` — the practice-trace producer.
+ *
+ * The CLI owns everything that must be PROVABLE — the pinned ref, the
+ * resolved sha, the practice-id set and the per-file digests — and the agent
+ * writes only the judgement half (`status`, `reason`, `tasks`). Provability
+ * cannot rest on an agent transcribing a forty-character sha.
+ *
+ * NEITHER ARM WRITES A FILE. The producer emits text the agent embeds in the
+ * single write it already performs. Patching a plan's frontmatter here would
+ * have to round-trip it through the shared serializer, which cannot re-emit
+ * nested object lists, so the same write would damage the plan's own
+ * must-haves block.
+ */
+function routeTrace({ args, cwd, raw, error, vault, c, _exec, _trace, }) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const realVault = require('./vault.cjs');
+    const cfgGet = vault.cfgGet ? vault.cfgGet.bind(vault) : realVault.cfgGet;
+    const verb = args[2];
+    const traceArgs = args.slice(3);
+    if (verb !== 'scaffold' && verb !== 'render') {
+        error(`Unknown trace subcommand. Available: ${TRACE_VERBS.join(', ')}`, ERROR_REASON.SDK_UNKNOWN_COMMAND);
+        return;
+    }
+    // Inert unless both vault keys are on: no output at all, before any flag check.
+    if (!tracePracticesActive(cfgGet, cwd))
+        return;
+    if (verb === 'scaffold') {
+        const RECOGNIZED_SCAFFOLD_FLAGS = new Set(['--stage', '--plan', '--raw']);
+        const unrecognized = traceArgs.find((a) => a.startsWith('--') && !RECOGNIZED_SCAFFOLD_FLAGS.has(a));
+        if (unrecognized !== undefined) {
+            error(`Unrecognized flag "${unrecognized}" for vault trace scaffold. ` +
+                `Supported: positional file paths, --stage <${TRACE_STAGES.join('|')}>, --plan <id>, --raw.`, ERROR_REASON.SDK_FAIL_FAST);
+            return;
+        }
+        const valueIndices = flagValueIndices(traceArgs, ['--stage', '--plan']);
+        const stageIdx = traceArgs.indexOf('--stage');
+        const stage = stageIdx !== -1 ? traceArgs[stageIdx + 1] : undefined;
+        if (stage === undefined || !TRACE_STAGES.includes(stage)) {
+            error(`Missing or unrecognized --stage value for vault trace scaffold. Supported: ${TRACE_STAGES.join(', ')}.`, ERROR_REASON.SDK_FAIL_FAST);
+            return;
+        }
+        const planIdx = traceArgs.indexOf('--plan');
+        const planId = planIdx !== -1 ? traceArgs[planIdx + 1] : undefined;
+        if (planId === undefined || planId.startsWith('--')) {
+            error('No plan identifier was given. Usage: vault trace scaffold ' +
+                `--stage <${TRACE_STAGES.join('|')}> --plan <id> [files...] [--raw].`, ERROR_REASON.SDK_MISSING_ARG);
+            return;
+        }
+        if (!SCAFFOLD_PLAN_ID_RE.test(planId)) {
+            error(`Invalid --plan value "${boundedPath(planId)}" for vault trace scaffold. ${SCAFFOLD_PLAN_ID_FORM} ` +
+                'A trace gate compares the identifier a plan artifact records against the one its own filename states.', ERROR_REASON.SDK_FAIL_FAST);
+            return;
+        }
+        const files = traceArgs.filter((a, i) => !a.startsWith('--') && !valueIndices.has(i));
+        // The execute stage records, per governed file, the commit that last
+        // produced it, so the statement asserts something falsifiable. A file with
+        // no commit yields no digest — the leaf records that gap as a loud note; a
+        // HEAD fallback would paper over a real coverage hole.
+        const runGit = _exec ?? shell_command_projection_cjs_1.execGit;
+        const fileInputs = files.map((name) => {
+            if (stage !== 'execute')
+                return name;
+            const res = runGit(['log', '-1', '--format=%H', '--', name], { cwd });
+            const digest = res.exitCode === 0 ? res.stdout.trim() : '';
+            return GIT_COMMIT_DIGEST_RE.test(digest) ? { name, gitCommit: digest } : name;
+        });
+        // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+        const traceMod = _trace ?? require('./vault-trace.cjs');
+        // No files is a REAL path: a documentation-only plan is still governed by
+        // the global practices, and its ruled-out set must stay auditable.
+        const statement = traceMod.buildTraceStatement({ cwd, stage, plan: planId, files: fileInputs });
+        if (raw) {
+            c.output(statement, true, JSON.stringify(statement));
+        }
+        else {
+            c.output(statement, true, traceMod.serializeTraceBlock(statement));
+        }
+        return;
+    }
+    // ── render ──
+    const RECOGNIZED_RENDER_FLAGS = new Set(['--raw']);
+    const unrecognizedRender = traceArgs.find((a) => a.startsWith('--') && !RECOGNIZED_RENDER_FLAGS.has(a));
+    if (unrecognizedRender !== undefined) {
+        error(`Unrecognized flag "${unrecognizedRender}" for vault trace render. Supported: a positional artifact path, --raw.`, ERROR_REASON.SDK_FAIL_FAST);
+        return;
+    }
+    const artifactPath = traceArgs.find((a) => !a.startsWith('--'));
+    if (artifactPath === undefined) {
+        error('No artifact path was given. Usage: vault trace render <artifact> [--raw].', ERROR_REASON.SDK_MISSING_ARG);
+        return;
+    }
+    // CONTAINMENT, decided BEFORE the read (the bounded reader returns '' on any
+    // problem and never throws, so a decision taken on its result would be none).
+    // The rendered section is included verbatim in SUMMARY.md, so an out-of-tree
+    // file must never become its content. The predicate is the real leaf's, not
+    // the `_vault` seam's: a security decision is not switchable by a mock.
+    if (artifactPath.indexOf('\u0000') !== -1) {
+        error(`The artifact path is not a usable path: ${boundedPath(artifactPath)}`, ERROR_REASON.SDK_FAIL_FAST);
+        return;
+    }
+    let projectRoot;
+    try {
+        projectRoot = findProjectRoot(cwd) || cwd;
+    }
+    catch {
+        projectRoot = cwd;
+    }
+    const artifactAbs = node_path_1.default.resolve(cwd, artifactPath);
+    if (!realVault.isInsideDir(projectRoot, artifactAbs)) {
+        error(`The artifact path resolves outside the project and was not read: ${boundedPath(artifactPath)}`, ERROR_REASON.SDK_FAIL_FAST);
+        return;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const traceMod = _trace ?? require('./vault-trace.cjs');
+    const readHead = vault.readHeadBounded ? vault.readHeadBounded.bind(vault) : realVault.readHeadBounded;
+    const content = readHead(artifactAbs, TRACE_ARTIFACT_READ_BYTES);
+    const parsed = traceMod.parseVaultTraceBlock(content, artifactPath);
+    // THE LEDGER, AND ONLY THE LEDGER: this arm never calls the matcher, so the
+    // rendered section cannot disagree with the frontmatter it is generated
+    // from. An absent ledger yields no section; an empty one yields the heading
+    // plus one explanatory line (the leaf's renderer).
+    const rendered = parsed.present ? traceMod.renderPracticesApplied(parsed.statement) : '';
+    if (raw) {
+        c.output(parsed, true, JSON.stringify(parsed));
+    }
+    else {
+        c.output(parsed, true, rendered);
+    }
+}
+/**
+ * `vault audit <phase> [--range <from>..<to>] [--raw]` — the operator's view of
+ * the mechanical practice audit.
+ *
+ * A PASS-THROUGH: it collects arguments, calls `runVaultAudit` and prints the
+ * leaf's own envelope (`--raw`) or the leaf's own report. `check vault.audit`
+ * serializes the same envelope from the same engine, and the phase argument is
+ * resolved by the same `resolveDecisionPhaseDir`, so the report cannot disagree
+ * with the gate that blocks on it.
+ *
+ * Inert (no output at all) unless both vault keys are on, decided before the
+ * flag allowlist so an inert project is silent on every path. A malformed
+ * `--range` is refused by the leaf's own predicate and never echoed. The
+ * range's value is excluded by index, so the flag may precede the phase.
+ */
+function routeAudit({ args, cwd, raw, error, vault, c, _exec, _audit, }) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const realVault = require('./vault.cjs');
+    const cfgGet = vault.cfgGet ? vault.cfgGet.bind(vault) : realVault.cfgGet;
+    if (!tracePracticesActive(cfgGet, cwd))
+        return;
+    const auditArgs = args.slice(2);
+    const RECOGNIZED_AUDIT_FLAGS = new Set(['--raw', '--range']);
+    const unrecognized = auditArgs.find((a) => a.startsWith('--') && !RECOGNIZED_AUDIT_FLAGS.has(a));
+    if (unrecognized !== undefined) {
+        error(`Unrecognized flag "${boundedPath(unrecognized)}" for vault audit. Supported: a phase directory or number, --raw, --range <from>..<to>.`, ERROR_REASON.SDK_FAIL_FAST);
+        return;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const auditMod = _audit ?? require('./vault-audit.cjs');
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const checkRouter = require('./check-command-router.cjs');
+    const rangeAt = auditArgs.indexOf('--range');
+    const rangeValue = rangeAt === -1 ? undefined : auditArgs[rangeAt + 1];
+    if (rangeAt !== -1) {
+        // The real leaf's predicate: a range check is not switchable by a test mock.
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const leaf = require('./vault-audit.cjs');
+        if (typeof rangeValue !== 'string' || !leaf.isValidOperatorRange(rangeValue)) {
+            error(checkRouter.AUDIT_RANGE_REFUSED_MESSAGE, ERROR_REASON.SDK_FAIL_FAST);
+            return;
+        }
+    }
+    const phaseArg = auditArgs.find((a, i) => !a.startsWith('--') && !(rangeAt !== -1 && i === rangeAt + 1));
+    if (phaseArg === undefined) {
+        error('No phase directory or phase number was given. Usage: vault audit <phase-dir|phase-number> [--range <from>..<to>] [--raw].', ERROR_REASON.SDK_MISSING_ARG);
+        return;
+    }
+    let root;
+    try {
+        root = findProjectRoot(cwd) || cwd;
+    }
+    catch {
+        root = cwd;
+    }
+    const phase = checkRouter.resolveDecisionPhaseDir(root, cwd, phaseArg);
+    if (!phase) {
+        const unresolved = {
+            status: 'unresolved',
+            block: true,
+            message: `Vault audit: "${boundedPath(phaseArg)}" is neither an existing directory inside the project nor a `
+                + 'phase the locator resolves, so no practice was compared against anything. Repair: re-run this '
+                + 'command with the phase directory or number.',
+        };
+        c.output(unresolved, true, raw ? JSON.stringify(unresolved) : unresolved.message);
+        return;
+    }
+    const result = auditMod.runVaultAudit({
+        root,
+        phaseDir: phase.abs,
+        exec: _exec ?? shell_command_projection_cjs_1.execGit,
+        ...(typeof rangeValue === 'string' ? { range: rangeValue } : {}),
+    });
+    // The leaf's object, untouched: the operator view and the gate serialize the
+    // same envelope, and nothing between the leaf and the screen rebuilds it.
+    if (raw) {
+        c.output(result, true, JSON.stringify(result));
+    }
+    else {
+        c.output(result, true, auditMod.renderAuditReport(result));
+    }
+}
+const REVIEW_VERBS = ['scaffold', 'finalize'];
+const REVIEW_USAGE = 'vault review scaffold|finalize <phase> [--force] [--raw]';
+/** The artifact a review writes in its phase directory: `<NN>-VAULT-REVIEW.md`. */
+function reviewArtifactName(phaseToken) {
+    return `${phaseToken ? `${phaseToken}-` : ''}VAULT-REVIEW.md`;
+}
+/**
+ * `vault review scaffold|finalize <phase> [--force] [--raw]` — the artifact half
+ * of `/pp-vault-review`. The derivation is `check vault-review`'s, through the
+ * same exported resolver and composer, so all three see one phase and one
+ * payload.
+ *
+ *   - `scaffold` writes `<phase-dir>/<NN>-VAULT-REVIEW.md` from the payload:
+ *     every computed section, every derived row, one `TODO` row per practice
+ *     the agent must judge, and the three computed lines. It does not replace
+ *     an existing review unless `--force` is given.
+ *   - `finalize` re-stamps the rate, counts and coverage lines from the rows the
+ *     agent wrote (the only writer of those lines), writes the file back when
+ *     that changed it, and reports every problem: the validator's (a `TODO`
+ *     left, a missing reason, a reclassified derived row, a score) and the
+ *     population's (a practice dropped, added or duplicated).
+ *
+ * Exit 0 on every path and no `block` key on any envelope: the review reports
+ * and never gates, so a problem is a repair item, never a halt.
+ */
+function routeReview({ args, cwd, raw, c, }) {
+    const say = (envelope, text) => {
+        c.output(envelope, true, raw ? JSON.stringify(envelope) : text);
+    };
+    const verb = args[2];
+    if (!REVIEW_VERBS.includes(verb)) {
+        const statement = `Vault review: "${boundedPath(typeof verb === 'string' ? verb : '')}" is not a review verb, so nothing was ` +
+            `reviewed. Usage: ${REVIEW_USAGE}.`;
+        say({ status: 'usage', statement }, statement);
+        return;
+    }
+    const force = verb === 'scaffold' && args.includes('--force');
+    const tokens = args.slice(3).filter((a) => a !== '--raw' && !(force && a === '--force'));
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const checkRouter = require('./check-command-router.cjs');
+    const target = checkRouter.resolveVaultReviewTarget(cwd, tokens, REVIEW_USAGE);
+    if (!target.ok) {
+        say({ status: target.status, statement: target.statement }, target.statement);
+        return;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const leaf = require('./vault-review.cjs');
+    const payload = checkRouter.composeVaultReviewPayload(target.root, target.phase, target.phaseToken);
+    const name = reviewArtifactName(target.phaseToken);
+    const file = `${target.phase.rel}/${name}`;
+    const abs = node_path_1.default.join(target.phase.abs, name);
+    const partition = (payload.partition ?? {});
+    const coverage = typeof payload.mechanicalCoverageLine === 'string' ? payload.mechanicalCoverageLine : null;
+    if (verb === 'scaffold') {
+        if (node_fs_1.default.existsSync(abs) && !force) {
+            const statement = `Vault review: ${file} already exists, so it was left as it is. Re-run with --force to replace it ` +
+                'with a fresh scaffold, or run vault review finalize to check it.';
+            say({ status: 'exists', file, statement }, statement);
+            return;
+        }
+        const text = leaf.renderReviewScaffold(payload, {
+            date: new Date().toISOString().slice(0, 10),
+            phaseToken: target.phaseToken,
+        });
+        node_fs_1.default.writeFileSync(abs, text, 'utf-8');
+        const toJudge = Array.isArray(partition.remainder) ? partition.remainder.length : 0;
+        const derived = (Array.isArray(partition.naUniverse) ? partition.naUniverse.length : 0) +
+            (Array.isArray(partition.naNoFile) ? partition.naNoFile.length : 0);
+        const statement = `Vault review: wrote ${file} (arm: ${String(payload.arm)}; ${toJudge} practice(s) to judge, ` +
+            `${derived} derived N-A${payload.refusesCleanRender === true ? '; no clean review may be rendered from it' : ''}).`;
+        say({ status: 'written', file, arm: payload.arm, toJudge, derived, refusesCleanRender: payload.refusesCleanRender === true, statement }, statement);
+        return;
+    }
+    // finalize
+    let current;
+    try {
+        current = node_fs_1.default.readFileSync(abs, 'utf-8');
+    }
+    catch {
+        const statement = `Vault review: ${file} does not exist, so there is nothing to finalize. Run vault review scaffold first.`;
+        say({ status: 'absent', file, statement }, statement);
+        return;
+    }
+    const stamped = leaf.stampReviewLines(current, { coverageLine: coverage });
+    if (stamped.stamped && stamped.text !== current)
+        node_fs_1.default.writeFileSync(abs, stamped.text, 'utf-8');
+    const result = leaf.validateReviewArtifact(stamped.text, { expectedCoverageLine: coverage });
+    const problems = [...result.problems, ...leaf.compareReviewPopulation(result.rows, partition)];
+    const envelope = {
+        status: problems.length === 0 ? 'valid' : 'problems',
+        file,
+        rateLine: result.expectedRateLine,
+        countsLine: result.expectedCountsLine,
+        problems,
+    };
+    const text = [
+        `Vault review: ${file}`,
+        result.expectedRateLine,
+        result.expectedCountsLine,
+        ...(problems.length === 0
+            ? ['No repair items.']
+            : [
+                `Repair items (${problems.length}) — fix them in the artifact, then run vault review finalize again:`,
+                ...problems.map((p) => `- ${p.kind}${p.id ? ` (${p.id})` : ''}${p.line ? `, line ${p.line}` : ''}: ${p.detail}`),
+            ]),
+        'This review reports and does not gate.',
+    ].join('\n');
+    say(envelope, text);
+}
 module.exports = {
     routeVaultCommand,
     VAULT_SUBCOMMANDS,
+    // The scaffold's plan-identifier shape and its one wording, exported so a
+    // trace gate's filename extractor and the planner reference are checked
+    // against the running module rather than a restated copy.
+    SCAFFOLD_PLAN_ID_RE,
+    SCAFFOLD_PLAN_ID_FORM,
+    TRACE_STAGES,
 };