@pareto4/pp-core 1.17.1 → 1.18.0

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

@@ -0,0 +1,293 @@
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REVIEW_FILES_CAP = exports.REVIEW_VERDICTS_HEADING = exports.REVIEW_ARTIFACT_MARKER = exports.REVIEW_ARTIFACT_SUFFIX = exports.REVIEW_VERDICTS = void 0;
+exports.deriveStandardsReview = deriveStandardsReview;
+exports.formatReviewCounts = formatReviewCounts;
+exports.validateReviewArtifact = validateReviewArtifact;
+/**
+ * src/vault-standards-review.cts — the derived half of `/pp-vault-review`
+ * (FORK-ONLY, the standards-only vault).
+ *
+ * `/pp-vault-review` reviews a completed phase against the client vault's
+ * standards documents: one verdict per document that governed the phase
+ * (PASS / FAIL / N-A / INCONCLUSIVE), judged by the `pp-vault-reviewer` agent.
+ * This module gives that agent its facts and checks the artifact it writes;
+ * it judges nothing itself. It REPORTS and never gates: no envelope here has a
+ * `block` key, and no capability declares `check vault-review` as a gate.
+ *
+ * `deriveStandardsReview` reads, for one phase:
+ *   - every PLAN's `<vault_standards>` block: which INDEX documents governed
+ *     which plan, and why;
+ *   - every SUMMARY's `## Standards Consulted` section: whether each document
+ *     was read, and the plan's commit anchors;
+ *   - per plan, the commit range those anchors bound (falling back to the
+ *     directory's recorded start, as the seal does) and the source files
+ *     changed in it (planning files excluded);
+ *   - per document, where the cached copy is, so the agent can read it.
+ * It never fetches and never writes. Its only spawns are bounded, read-only
+ * git queries through `execGitLocal`.
+ *
+ * `validateReviewArtifact` checks the `{padded}-VAULT-REVIEW.md` the agent
+ * wrote against the derivation: every governing document appears exactly once
+ * in the verdict table, each verdict is one of the four, a non-PASS verdict
+ * states its reason, and the counts line agrees with the table.
+ *
+ * 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-review.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");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const vaultStandardsLeaf = require("./vault-standards.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const vaultSeal = require("./vault-seal.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const vaultIndexLeaf = require("./vault-index.cjs");
+// ─── Types ───────────────────────────────────────────────────────────────────
+/** The four verdicts, in the order the counts line states them. */
+exports.REVIEW_VERDICTS = Object.freeze(['PASS', 'FAIL', 'N-A', 'INCONCLUSIVE']);
+/** The artifact's file-name suffix and frontmatter marker. */
+exports.REVIEW_ARTIFACT_SUFFIX = '-VAULT-REVIEW.md';
+exports.REVIEW_ARTIFACT_MARKER = 'artifact: vault-review';
+/** The verdict table's heading; the validator finds the table under it. */
+exports.REVIEW_VERDICTS_HEADING = '## Standard Verdicts';
+/** How many changed files one plan lists before it only counts. */
+exports.REVIEW_FILES_CAP = 200;
+/** Bound on a git query a review makes. */
+const REVIEW_GIT_TIMEOUT_MS = 30_000;
+// ─── Derivation ──────────────────────────────────────────────────────────────
+const PLAN_RE = /(^|-)PLAN\.md$/;
+const SUMMARY_RE = /(^|-)SUMMARY\.md$/;
+function readBounded(abs) {
+    try {
+        const st = node_fs_1.default.statSync(abs);
+        if (!st.isFile() || st.size > vaultSeal.TRACE_ARTIFACT_BYTE_CAP)
+            return null;
+        return node_fs_1.default.readFileSync(abs, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+function consultedText(entry, hasSummary) {
+    if (!hasSummary)
+        return 'no summary';
+    if (entry === undefined)
+        return 'unfilled';
+    if (entry.status === 'read')
+        return vaultStandardsLeaf.STANDARDS_CONSULTED_READ;
+    if (entry.status === 'not-read')
+        return `${vaultStandardsLeaf.STANDARDS_CONSULTED_NOT_READ}${entry.reason ?? ''}`.trim();
+    return 'unfilled';
+}
+/**
+ * Derive the review's facts for one phase. Never throws: every fault is a
+ * status or a gap. Inert (with a statement) when the project has no
+ * `.platform-bindings.json` or the vault is off.
+ */
+function deriveStandardsReview(root, cwd, positional, opts = {}) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const vault = require('./vault.cjs');
+    if (!vault.hasPlatformBindings(root) || !vault.isVaultGateActive(cwd)) {
+        return {
+            status: 'inert',
+            statement: 'The client vault is off for this project, so there are no standards to review against.',
+        };
+    }
+    if (positional === undefined || positional === '') {
+        return {
+            status: 'no-argument',
+            statement: 'No phase was given. Re-run with the phase directory or the phase number.',
+        };
+    }
+    if (positional.startsWith('--')) {
+        return { status: 'usage', statement: 'The phase must come first: check vault-review <phase-dir|phase-number> [--raw].' };
+    }
+    const phase = vault.resolveTracePhaseDir(root, cwd, positional);
+    if (!phase) {
+        return {
+            status: 'unresolved',
+            statement: 'That argument is not a phase directory inside the project or a phase number the locator resolves.',
+        };
+    }
+    const exec = opts._exec ?? shell_command_projection_cjs_1.execGitLocal;
+    const gaps = [];
+    let names = [];
+    try {
+        names = node_fs_1.default.readdirSync(phase.abs).sort();
+    }
+    catch {
+        gaps.push(`the phase directory ${phase.rel} could not be listed`);
+    }
+    const summaries = new Map();
+    for (const name of names.filter((n) => SUMMARY_RE.test(n))) {
+        const text = readBounded(node_path_1.default.join(phase.abs, name));
+        if (text === null) {
+            gaps.push(`${name} could not be read (missing, unreadable or over the size cap)`);
+            continue;
+        }
+        const section = vaultStandardsLeaf.parseConsultedSection(text, { artifact: name });
+        if (section.present && section.planId !== null && !summaries.has(section.planId)) {
+            summaries.set(section.planId, { name, section, text });
+        }
+    }
+    const cacheDir = vault.resolveVaultCacheDir(cwd).dir;
+    const isAncestor = vaultSeal.sealIsAncestorVia(shell_command_projection_cjs_1.execGitLocal, root);
+    const plans = [];
+    const documents = new Map();
+    for (const name of names.filter((n) => PLAN_RE.test(n))) {
+        const text = readBounded(node_path_1.default.join(phase.abs, name));
+        if (text === null) {
+            gaps.push(`${name} could not be read (missing, unreadable or over the size cap)`);
+            continue;
+        }
+        const parsed = vaultStandardsLeaf.parseStandardsBlock(text, { artifact: name });
+        const record = parsed.record;
+        if (!parsed.present || record === null) {
+            gaps.push(`${name} carries no readable <vault_standards> block, so the documents that governed it are unknown`);
+            continue;
+        }
+        const summary = summaries.get(record.planId);
+        let range = null;
+        let files = [];
+        let filesTruncated = false;
+        if (summary !== undefined) {
+            const anchors = vaultSeal.resolveRecordAnchors(summary.text, vaultSeal.RECORDED_ARTIFACT_KIND.STANDARDS_CONSULTED, phase.abs, { isAncestor });
+            if (anchors.end !== undefined) {
+                range = { start: anchors.start ?? null, end: anchors.end };
+                if (anchors.start !== undefined) {
+                    const diff = exec(['diff', '--name-only', '-z', '--no-renames', anchors.start, anchors.end], { cwd: root, timeout: REVIEW_GIT_TIMEOUT_MS });
+                    if (diff.exitCode === 0) {
+                        const all = diff.stdout.split('\0').filter((p) => p !== '' && !vaultSeal.isNonSourcePath(p));
+                        filesTruncated = all.length > exports.REVIEW_FILES_CAP;
+                        files = all.slice(0, exports.REVIEW_FILES_CAP);
+                    }
+                    else {
+                        gaps.push(`the files changed by plan ${record.planId} could not be listed from its anchors`);
+                    }
+                }
+                else {
+                    gaps.push(`plan ${record.planId} records an end anchor but no start, so its changed files are unknown`);
+                }
+            }
+            else {
+                gaps.push(`plan ${record.planId}'s Standards Consulted section carries no anchor, so its commit range is unknown`);
+            }
+        }
+        else {
+            gaps.push(`plan ${record.planId} has no SUMMARY with a Standards Consulted section`);
+        }
+        plans.push({
+            planId: record.planId,
+            plan: `${phase.rel}/${name}`,
+            summary: summary === undefined ? null : `${phase.rel}/${summary.name}`,
+            range,
+            files,
+            filesTruncated,
+            degraded: record.degraded === null ? null : `${record.degraded.kind}: ${record.degraded.reason}`,
+        });
+        for (const doc of record.documents) {
+            let entry = documents.get(doc.path);
+            if (entry === undefined) {
+                const abs = node_path_1.default.join(cacheDir, ...doc.path.split('/'));
+                entry = { path: doc.path, cachePath: node_fs_1.default.existsSync(abs) ? abs : null, governed: [] };
+                if (entry.cachePath === null)
+                    gaps.push(`${vaultIndexLeaf.displayVaultPath(doc.path)} is not in the vault cache; fetch the vault to judge it`);
+                documents.set(doc.path, entry);
+            }
+            entry.governed.push({
+                planId: record.planId,
+                reason: doc.reason,
+                consulted: consultedText(summary?.section.entries.find((e) => e.path === doc.path), summary !== undefined),
+            });
+        }
+    }
+    if (plans.length === 0 || documents.size === 0) {
+        return {
+            status: 'no-records',
+            statement: plans.length === 0
+                ? `No plan in ${phase.rel} carries a standards record, so there is nothing to review.`
+                : `No plan in ${phase.rel} was governed by a standards document, so there is nothing to review.`,
+            phaseDir: phase.rel,
+            plans,
+            documents: [],
+            gaps,
+        };
+    }
+    return { status: 'ok', phaseDir: phase.rel, plans, documents: [...documents.values()], gaps };
+}
+/** The counts line, in verdict order: `p PASS · f FAIL · n N-A · i INCONCLUSIVE (of N documents)`. */
+function formatReviewCounts(counts) {
+    const total = exports.REVIEW_VERDICTS.reduce((n, v) => n + counts[v], 0);
+    return `${exports.REVIEW_VERDICTS.map((v) => `${counts[v]} ${v}`).join(' · ')} (of ${total} document${total === 1 ? '' : 's'})`;
+}
+/**
+ * Check a review artifact against the derivation. The verdict table is the
+ * first markdown table under `## Standard Verdicts`; its first column holds the
+ * document path in backticks, the second the verdict, the third the reason
+ * or evidence. Never throws; an empty list means the artifact is well formed.
+ */
+function validateReviewArtifact(text, documents) {
+    const problems = [];
+    if (!text.includes(exports.REVIEW_ARTIFACT_MARKER)) {
+        problems.push({ kind: 'marker_missing', detail: `the frontmatter does not carry "${exports.REVIEW_ARTIFACT_MARKER}"` });
+    }
+    const lines = text.split(/\r?\n/);
+    const at = lines.findIndex((l) => l.trim() === exports.REVIEW_VERDICTS_HEADING);
+    const rows = [];
+    if (at === -1) {
+        problems.push({ kind: 'table_missing', detail: `there is no "${exports.REVIEW_VERDICTS_HEADING}" section` });
+    }
+    else {
+        for (let i = at + 1; i < lines.length && !lines[i].startsWith('## '); i += 1) {
+            const line = lines[i].trim();
+            if (!line.startsWith('|'))
+                continue;
+            const cells = line.slice(1, line.endsWith('|') ? -1 : undefined).split('|').map((c) => c.trim());
+            const m = /^`([^`]+)`$/.exec(cells[0] ?? '');
+            if (!m)
+                continue;
+            rows.push({ path: m[1], verdict: cells[1] ?? '', reason: cells[2] ?? '' });
+        }
+        if (rows.length === 0)
+            problems.push({ kind: 'table_missing', detail: 'the verdict table has no document rows' });
+    }
+    const known = new Set(documents.map((d) => d.path));
+    const seen = new Map();
+    for (const row of rows) {
+        seen.set(row.path, (seen.get(row.path) ?? 0) + 1);
+        if (!known.has(row.path))
+            problems.push({ kind: 'document_unknown', detail: `${row.path} did not govern this phase` });
+        if (!exports.REVIEW_VERDICTS.includes(row.verdict)) {
+            problems.push({ kind: 'verdict_invalid', detail: `${row.path} has verdict "${row.verdict}", not one of ${exports.REVIEW_VERDICTS.join(', ')}` });
+        }
+        else if (row.verdict !== 'PASS' && (row.reason === '' || row.reason === '-')) {
+            problems.push({ kind: 'reason_missing', detail: `${row.path} is ${row.verdict} without a stated reason` });
+        }
+    }
+    for (const doc of documents) {
+        const n = seen.get(doc.path) ?? 0;
+        if (n === 0)
+            problems.push({ kind: 'document_missing', detail: `${doc.path} has no verdict` });
+        if (n > 1)
+            problems.push({ kind: 'document_duplicated', detail: `${doc.path} has ${n} verdict rows` });
+    }
+    const counts = { PASS: 0, FAIL: 0, 'N-A': 0, INCONCLUSIVE: 0 };
+    for (const row of rows) {
+        if (exports.REVIEW_VERDICTS.includes(row.verdict))
+            counts[row.verdict] += 1;
+    }
+    const expected = formatReviewCounts(counts);
+    const countsLine = lines.find((l) => /\bPASS · /.test(l));
+    if (countsLine === undefined) {
+        problems.push({ kind: 'counts_missing', detail: `there is no counts line; it should read "${expected}"` });
+    }
+    else if (!countsLine.includes(expected)) {
+        problems.push({ kind: 'counts_mismatch', detail: `the counts line does not match the table; it should read "${expected}"` });
+    }
+    return problems;
+}

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

@@ -10,7 +10,7 @@
  * `pp-core/references/planner-vault-standards.md` to this grammar in both
  * directions (D-10).
  *
- * In standards mode a plan records which INDEX-listed standards documents
+ * 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
@@ -33,8 +33,8 @@
  * (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, the display
- * sanitiser and the fence markers are reused from there, never re-spelled
+ * 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.
  *
@@ -45,8 +45,7 @@
  *
  * 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, bidi overrides or a live fence marker
- * into a gate message. The leaf never knows WHY a path is not a resolved INDEX
+ * 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.
@@ -74,7 +73,7 @@ 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, EXTERNAL_CONTENT_FENCE_START, EXTERNAL_CONTENT_FENCE_END, VAULT_ENTRY_PREFIX, VAULT_ENTRY_SEPARATOR, } = vaultIndexLeaf;
+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");
@@ -183,7 +182,7 @@ exports.STANDARDS_SHA_RE = /^[0-9a-f]{40}$/;
  */
 exports.STANDARDS_ANCHOR_PREFIX = '- anchors: ';
 /**
- * The plan-identifier form a record (and the practices scaffold) must carry,
+ * 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
@@ -238,8 +237,8 @@ exports.STANDARDS_GRAMMAR = Object.freeze({
 });
 /**
  * The frozen standards problem kinds (D-17). Every value is `standards_` plus
- * the lower-snake key, so none can collide with a practices trace kind or a
- * trace handler kind (the leaf test asserts disjointness against both tables).
+ * 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.
  */
@@ -272,8 +271,8 @@ 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 fence marker (either
- * external-content marker, or a run of three tildes); no block tag; nothing
+ * 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
@@ -297,7 +296,7 @@ function validateReasonClause(text) {
         return { ok: false, why: 'too_long' };
     if (text.includes('`'))
         return { ok: false, why: 'backtick' };
-    if (text.includes(EXTERNAL_CONTENT_FENCE_START) || text.includes(EXTERNAL_CONTENT_FENCE_END) || TILDE_FENCE_RE.test(text)) {
+    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)) {
@@ -431,7 +430,7 @@ function standardsProblemDetail(kind, ctx = {}) {
     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 standards-mode plan carries one, including a plan that writes no code.`, blockRemedy(c.planId));
+            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:
@@ -731,7 +730,7 @@ function splitLines(text) {
 /**
  * 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 (the practices parser's rule).
+ * frontmatter is not a frontmatter.
  */
 function bodyStart(lines) {
     if (lines[0] !== '---')
@@ -786,8 +785,8 @@ function liveLineIndexes(lines, from, stop) {
  * 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 `## Practices Applied` presence test and
- * the door-record parser) asks this scanner instead of keeping a second one.
+ * 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) {