@pareto4/pp-core 1.8.2 → 1.10.0

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

@@ -40,6 +40,14 @@ const prohibition_enforcement_cjs_1 = require("./prohibition-enforcement.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const vaultModule = require("./vault.cjs");
 const { vaultStatus, readManifest } = vaultModule;
+const git_base_branch_cjs_1 = require("./git-base-branch.cjs");
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const vaultPracticesModule = require("./vault-practices.cjs");
+const { matchPractices, boundedToken, VALID_SEVERITIES } = vaultPracticesModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatterModule = require("./frontmatter.cjs");
+const { extractFrontmatter } = frontmatterModule;
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 function normalizePhrase(text) {
     // eslint-disable-next-line @typescript-eslint/no-base-to-string
@@ -56,10 +64,18 @@ function softPhrase(text) {
         return '';
     return words.slice(0, SOFT_PHRASE_MIN_WORDS).join(' ');
 }
+function escapeRegExpLiteral(text) {
+    // Decision ids are project-authored (CONTEXT.md), not attacker-controlled, but an
+    // unescaped metacharacter (e.g. a stray `.` or `(`) still turns the id into an
+    // unintended pattern — crashing `new RegExp(...)` on invalid syntax or silently
+    // mis-matching a haystack that only resembles it. This is malformed-input hardening,
+    // not a security boundary.
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 function decisionMentioned(haystack, decision) {
     if (!haystack)
         return false;
-    if (new RegExp(`\\b${decision.id}\\b`).test(haystack))
+    if (new RegExp(`\\b${escapeRegExpLiteral(decision.id)}\\b`).test(haystack))
         return true;
     const phrase = softPhrase(decision.text);
     return phrase ? normalizePhrase(haystack).includes(phrase) : false;
@@ -967,7 +983,439 @@ function cmdVaultStatus(cwd, raw) {
         fetchedAt: vs.fetchedAt ?? null,
     }, raw, undefined);
 }
-function routeCheckCommand({ args, cwd, raw }) {
+// ─── ship.practices query handler (INJ-03, Phase 28) ──────────────────────────
+// Hard caps for the ship-time practices gate (D-05 line cap, T-28-03 DoS bound
+// on top of vault-practices.cts's own PRACTICE_COUNT_CAP/MATCHED_FILES_CAP).
+const SHIP_DIFF_FILE_CAP = 2000;
+const PRACTICE_LINE_CAP = 10;
+/**
+ * Read `.planning/config.json` and report whether the vault-practices
+ * feature is fully active for the ship gate: `vault.enabled === true` AND
+ * `vault.practices_enabled === true` (requires-closure, mirrors Phase 25's
+ * activation gate). Read-and-swallow — same shape as `readParetoConfig`.
+ * Absent/malformed config or either flag not strictly `true` reports both
+ * as inactive, which is the fail-closed default for an opt-in capability.
+ */
+function readShipPracticesFlags(root) {
+    const configPath = node_path_1.default.join(root, '.planning', 'config.json');
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(configPath, 'utf-8'));
+        const vault = parsed['vault'] ?? {};
+        return {
+            enabled: vault['enabled'] === true,
+            practicesEnabled: vault['practices_enabled'] === true,
+        };
+    }
+    catch {
+        return { enabled: false, practicesEnabled: false };
+    }
+}
+/**
+ * Map a practice's tier to the plain-English phrase used inline in a ship
+ * summary line (D-05/COMM-01) — `null` (no manifest tier recorded) reads as
+ * "the vault" rather than leaking the internal tier vocabulary.
+ */
+function shipTierPhrase(tier) {
+    if (tier === 'client')
+        return "the client's own standards";
+    if (tier === 'fallback')
+        return 'the shared standards';
+    return 'the vault';
+}
+const SHIP_REVIEW_SOFT_NOTE = 'No practices review recorded for this phase.';
+/**
+ * Choose which phase REVIEW.md file the ship-summary pointer should read
+ * (T-28-06). Two-tier rule, in this order:
+ *
+ *   1. If any entry is a bare `<digits>-REVIEW.md` (the documented default
+ *      name), choose it — the lexicographically first when several exist
+ *      (defensive; should not occur in practice).
+ *   2. Otherwise, among round-suffixed `<digits>-REVIEW-<suffix>.md` entries,
+ *      choose the one with the GREATEST mtime, breaking ties by the
+ *      lexicographically greatest name.
+ *
+ * Both tiers anchor on `^\d+-REVIEW` deliberately: other workflows write
+ * differently-prefixed review artifacts into the SAME phase directory
+ * (`NN-UI-REVIEW.md` from ui-review, `NN-EVAL-REVIEW.md` from eval-review)
+ * whose names also end in `-REVIEW.md`. A suffix-only test would let a UI or
+ * eval review satisfy tier 1 and short-circuit the mtime rule entirely — or,
+ * with both `NN-REVIEW.md` and `NN-EVAL-REVIEW.md` present, pick the
+ * eval file purely because `E` sorts before `R`.
+ *
+ * An alphabetical-only pick (`ls | head -1` style, the pattern
+ * `ship.md`'s SECURITY_FILE resolution uses) would prefer a superseded
+ * pre-gap-closure snapshot over the final numbered round purely because
+ * `p` sorts before `r` — this is the exact Phase-27 shape RESEARCH.md
+ * Pitfall 2 documents (nine round-suffixed files plus a pre-gap-closure
+ * file, no bare file). The mtime rule avoids that failure; do not
+ * replace it with a name-only sort.
+ */
+function chooseShipReviewFile(dir) {
+    let entries;
+    try {
+        entries = node_fs_1.default.readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    const bare = entries.filter((e) => /^\d+-REVIEW\.md$/.test(e)).sort();
+    if (bare.length > 0)
+        return bare[0];
+    const roundSuffixed = entries.filter((e) => /^\d+-REVIEW-[^/]+\.md$/.test(e));
+    if (roundSuffixed.length === 0)
+        return null;
+    let best = null;
+    let bestMtimeMs = -Infinity;
+    for (const name of roundSuffixed) {
+        let mtimeMs;
+        try {
+            mtimeMs = node_fs_1.default.statSync(node_path_1.default.join(dir, name)).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        if (best === null || mtimeMs > bestMtimeMs || (mtimeMs === bestMtimeMs && name > best)) {
+            best = name;
+            bestMtimeMs = mtimeMs;
+        }
+    }
+    return best;
+}
+/**
+ * Build the trailing "what did the code review record" pointer line
+ * (D-08/D-09). Reads `.planning/STATE.md`'s `current_phase`, resolves the
+ * phase directory via `findPhaseInternal` (never a hand-built
+ * `.planning/phases/` path, never a directory glob outside the chosen phase
+ * directory), chooses the right REVIEW.md file via `chooseShipReviewFile`,
+ * and reads its `practices.total` count. Every step degrades to the soft
+ * note on ANY failure — missing/unreadable STATE.md, unset current_phase,
+ * an unresolved phase directory, no REVIEW.md file, a review file lacking
+ * the `practices` key, or a non-numeric/negative total — never throws,
+ * never changes the verdict's `status`.
+ */
+function buildShipReviewPointerLine(root) {
+    try {
+        const statePath = node_path_1.default.join(root, '.planning', 'STATE.md');
+        const stateContent = node_fs_1.default.readFileSync(statePath, 'utf-8');
+        const stateFm = extractFrontmatter(stateContent);
+        const currentPhase = stateFm['current_phase'];
+        if (currentPhase === undefined || currentPhase === null || currentPhase === '') {
+            return SHIP_REVIEW_SOFT_NOTE;
+        }
+        const phaseResult = findPhaseInternal(root, currentPhase);
+        if (!phaseResult)
+            return SHIP_REVIEW_SOFT_NOTE;
+        const phaseDir = node_path_1.default.join(root, phaseResult.directory);
+        const chosen = chooseShipReviewFile(phaseDir);
+        if (!chosen)
+            return SHIP_REVIEW_SOFT_NOTE;
+        const reviewContent = node_fs_1.default.readFileSync(node_path_1.default.join(phaseDir, chosen), 'utf-8');
+        const reviewFm = extractFrontmatter(reviewContent);
+        const practicesBlock = reviewFm['practices'];
+        if (typeof practicesBlock !== 'object' || practicesBlock === null || Array.isArray(practicesBlock)) {
+            return SHIP_REVIEW_SOFT_NOTE;
+        }
+        const totalRaw = practicesBlock['total'];
+        const total = typeof totalRaw === 'string' ? Number(totalRaw) : totalRaw;
+        if (typeof total !== 'number' || !Number.isFinite(total) || !Number.isInteger(total) || total < 0) {
+            return SHIP_REVIEW_SOFT_NOTE;
+        }
+        return `Code review recorded ${total} practice advisories — see ${chosen}.`;
+    }
+    catch {
+        return SHIP_REVIEW_SOFT_NOTE;
+    }
+}
+/**
+ * ship.practices query handler (INJ-03).
+ *
+ * Reproduces the whole ship-time practices check by hand: resolves the
+ * branch diff a pull request would actually merge (never the working
+ * tree), filters out planning-directory paths and deletions (D-02), matches
+ * the filtered file list against the vault's practices using the frozen
+ * Phase 24 matcher as a library, and prints a compact, severity-ordered,
+ * token-bounded summary (D-05/D-06) ending with a pointer to what the code
+ * review recorded (D-08/D-09). Never throws; every fallible step ends in
+ * exactly one `output()` call and a `return`, so the process exits 0 on
+ * every path (T-28-05). `block` is always `false` — this handler never
+ * blocks (D-04: deterministic report only, no judged pass).
+ *
+ * Reuse: `resolveBaseBranch` (git-base-branch.cts) for the diff base,
+ * `execGit` (shell-command-projection.cts) for the diff subprocess,
+ * `matchPractices` + `boundedToken` + `VALID_SEVERITIES` (vault-practices.cts)
+ * for matching and safe rendering.
+ *
+ * Invocable as: pp_run check ship.practices [--raw]
+ * The dot → hyphen normalization in routeCheckCommand maps "ship.practices"
+ * to the "ship-practices" branch — the handler ignores `args` entirely
+ * (D-03: zero new flags), which is what makes the gate hand-reproducible as
+ * a bare `pp_run check ship.practices`.
+ */
+function cmdShipPractices(cwd, _args, raw) {
+    // Step 1 — root.
+    let root;
+    try {
+        root = findProjectRoot(cwd) || cwd;
+    }
+    catch {
+        root = cwd;
+    }
+    // Step 2 — inert guard (SC3 defence in depth; the registered gate's `when`
+    // condition already prevents this handler being called in this state, so
+    // this guard exists so a manual invocation on a non-vault project also
+    // prints nothing).
+    const { enabled, practicesEnabled } = readShipPracticesFlags(root);
+    if (!enabled || !practicesEnabled) {
+        output({ status: 'inert', block: false, message: '' }, raw, undefined);
+        return;
+    }
+    // Step 3 — base branch. Never re-derive the precedence ladder here; the
+    // generic gate dispatch passes this handler no arguments at all, so it
+    // must own this resolution itself (RESEARCH Pitfall 3).
+    const base = (0, git_base_branch_cjs_1.resolveBaseBranch)(root);
+    // Step 4 — diff: the branch diff a pull request would actually merge,
+    // never the working tree (D-01). `core.quotepath=off` at the subprocess
+    // seam keeps non-ASCII paths literal — with git's default quoting they
+    // arrive C-quoted (`".planning/caf\303\251.md"`), which both bypasses the
+    // Step 5 `.planning/` exclusion (the path starts with `"`) and makes
+    // legitimate non-ASCII files unmatched by every applies-to glob.
+    const diffResult = (0, shell_command_projection_cjs_1.execGit)(['-c', 'core.quotepath=off', 'diff', '--name-only', '--diff-filter=d', `${base}...HEAD`], { cwd: root });
+    if (diffResult.exitCode !== 0 || diffResult.error) {
+        output({
+            status: 'warn',
+            block: false,
+            message: 'Practices could not be checked: the change set could not be read.',
+        }, raw, undefined);
+        return;
+    }
+    // Step 5 — filter (D-02): drop empties, normalize separators, drop
+    // .planning/** paths. Deletions are already excluded by --diff-filter=d;
+    // a rename contributes only its new path.
+    let files = diffResult.stdout
+        .split('\n')
+        .map((f) => f.trim())
+        .filter((f) => f.length > 0)
+        .map((f) => f.replace(/\\/g, '/'))
+        .filter((f) => !f.startsWith('.planning/'));
+    let filesCapped = false;
+    if (files.length > SHIP_DIFF_FILE_CAP) {
+        files = files.slice(0, SHIP_DIFF_FILE_CAP);
+        filesCapped = true;
+    }
+    // Step 6 — match, using the frozen Phase 24 matcher as a library.
+    let result;
+    try {
+        result = matchPractices({ cwd: root, files });
+    }
+    catch {
+        output({
+            status: 'warn',
+            block: false,
+            message: 'Practices could not be checked: the practices could not be read.',
+        }, raw, undefined);
+        return;
+    }
+    // Step 7 — degraded results (D-07) / Step 8 — compact summary (D-05/D-06).
+    const bodyLines = [];
+    const totalMatches = result.matched.length + result.global.length;
+    const counts = { critical: 0, warning: 0, info: 0 };
+    if (result.practicesProcessed === 0) {
+        bodyLines.push('Practices checked — none found in the vault.');
+    }
+    else if (totalMatches === 0) {
+        bodyLines.push('Practices checked — none apply to this change set.');
+    }
+    else {
+        for (const m of result.matched)
+            counts[m.severity] += 1;
+        for (const g of result.global)
+            counts[g.severity] += 1;
+        bodyLines.push(`Practices checked — ${totalMatches} apply to this change set (${counts.critical} critical, ${counts.warning} warning, ${counts.info} info) across ${files.length} changed files.`);
+        const entries = [
+            ...result.matched.map((m) => ({
+                id: m.id, severity: m.severity, scope: 'scoped', tier: m.tier, path: m.path, matchedCount: m.matchedCount,
+            })),
+            ...result.global.map((g) => ({
+                id: g.id, severity: g.severity, scope: 'global', tier: g.tier, path: g.path,
+            })),
+        ];
+        entries.sort((a, b) => {
+            const sevDiff = VALID_SEVERITIES.indexOf(a.severity) - VALID_SEVERITIES.indexOf(b.severity);
+            if (sevDiff !== 0)
+                return sevDiff;
+            if (a.scope !== b.scope)
+                return a.scope === 'scoped' ? -1 : 1;
+            return a.id.localeCompare(b.id);
+        });
+        // Only `id` and `path` are vault-authored tokens (T-28-02) — bound them
+        // through boundedToken before interpolation. `severity` is a closed enum
+        // and `matchedCount` is a number, so neither needs bounding. Never read
+        // `ask`/`excerpt`/`winningGlobs`/`matchedFiles` here (D-06) and never
+        // call `renderPracticesReport` — it prints the practice prose.
+        const practiceLines = entries.map((e) => {
+            const idTok = boundedToken(e.id);
+            const pathTok = boundedToken(e.path);
+            const phrase = shipTierPhrase(e.tier);
+            return e.scope === 'scoped'
+                ? `- ${idTok} — ${e.severity} — applies to ${e.matchedCount} changed file(s) — from ${phrase} at ${pathTok}`
+                : `- ${idTok} — ${e.severity} — always applies — from ${phrase} at ${pathTok}`;
+        });
+        // Step 9 — cap (D-05): never truncate silently.
+        if (practiceLines.length > PRACTICE_LINE_CAP) {
+            const omitted = practiceLines.length - PRACTICE_LINE_CAP;
+            bodyLines.push(...practiceLines.slice(0, PRACTICE_LINE_CAP));
+            bodyLines.push(`+${omitted} more not shown — ${totalMatches} practices apply in total.`);
+        }
+        else {
+            bodyLines.push(...practiceLines);
+        }
+    }
+    // Step 10 — truncation note: only when Step 5 capped the file list.
+    if (filesCapped) {
+        bodyLines.push(`Only the first ${SHIP_DIFF_FILE_CAP} changed files were checked.`);
+    }
+    // Review pointer (D-08/D-09) — always the final line for every branch that
+    // reaches this point (the inert branch and the two "could not be checked"
+    // branches above already returned and appended nothing).
+    bodyLines.push(buildShipReviewPointerLine(root));
+    // Step 11 — output once. status is 'pass' for every branch that ran the
+    // check (including the two zero-result branches); block is always false.
+    output({
+        status: 'pass',
+        block: false,
+        message: bodyLines.join('\n'),
+        counts: { total: totalMatches, critical: counts.critical, warning: counts.warning, info: counts.info },
+        filesConsidered: files.length,
+    }, raw, undefined);
+}
+const _defaultCheckCore = { output };
+// The four flags `check practices-review` recognizes. Any other `--`-prefixed
+// token is rejected BY NAME (mirrors vault-command-router.cts's
+// RECOGNIZED_MATCH_FLAGS guard) — but unlike that guard, rejection here still
+// exits 0: this command is advisory, and a typo in a workflow step must never
+// break a review run.
+const RECOGNIZED_PRACTICES_REVIEW_FLAGS = new Set(['--review', '--corpus-json', '--boundaries', '--quotes']);
+/**
+ * cmdCheckPracticesReview — `check practices-review` handler (plan 27-29,
+ * VERIF-01/COMM-01). Reads the REVIEW.md at `--review`, dispatches to the
+ * compiled `src/practices-review-check.cts` module's `runReviewCheck`, and
+ * prints its plain-English lines verbatim. Placement rationale: the review
+ * check is advisory and must behave identically whether the vault capability
+ * is active or not, so it lives in the always-available core `check` family
+ * rather than behind the `vault.enabled`-gated `vault` family, even though the
+ * data it inspects originates from the vault.
+ *
+ * Exit status is 0 on EVERY path — missing `--review`, unreadable file,
+ * absent practices section, malformed corpus JSON, the parse cap tripped, an
+ * unrecognized flag, or (round 7, WR-03) a bare positional token, which now
+ * reports the argument that was not understood rather than being silently
+ * discarded — because a review path named without its flag would otherwise
+ * produce the same zero-byte output as a clean review. A boundary or quote
+ * shortfall is a defect in the REVIEW.md, not in the reviewed code; failing
+ * the review would punish the wrong artifact.
+ *
+ * Corpus precedence: `--corpus-json` when present, otherwise
+ * `process.env.VAULT_QUOTE_CORPUS` (what the workflow step sets), otherwise
+ * empty (no comparison, no output from that half).
+ *
+ * Test seams: `_check` injects a mock of the compiled module (default: the
+ * real compiled practices-review checker, lazy-required INSIDE this function
+ * so it only loads when the command is actually dispatched); `_core` injects
+ * a mock output sink. Production callers pass neither.
+ */
+function cmdCheckPracticesReview({ args }, _check, _core) {
+    const c = _core ?? _defaultCheckCore;
+    let reviewPath;
+    let corpusJsonFlag;
+    let boundariesFlag = false;
+    let quotesFlag = false;
+    const rest = args.slice(2);
+    for (let i = 0; i < rest.length; i++) {
+        const tok = rest[i];
+        if (tok === '--review' || tok === '--corpus-json') {
+            // WR-03: a value-taking flag whose value is missing (trailing token),
+            // empty (T-27-R8-05), or flag-shaped (the next token starts with "--")
+            // must never consume that token as its value — route through the same
+            // usage-message path the unrecognized-flag guard below already uses,
+            // and return before any file read is attempted. The empty-string case
+            // belongs HERE rather than at the read guard below: `--review ''`
+            // currently passes this guard, sets `reviewPath` to the empty string,
+            // then fails the truthiness test at the read guard, which is the
+            // deliberate feature-off path — so the invocation produces zero bytes
+            // at exit 0, byte-identical to a clean review. The one call site that
+            // matters reaches this shape whenever the workflow's `REVIEW_PATH`
+            // variable expands empty.
+            const candidate = rest[i + 1];
+            if (candidate === undefined || candidate === '' || candidate.startsWith('--')) {
+                const msg = `Flag "${tok}" requires a value. Supported: --review <path>, --corpus-json <string>, --boundaries, --quotes.`;
+                c.output(msg, true, msg);
+                return;
+            }
+            if (tok === '--review')
+                reviewPath = candidate;
+            else
+                corpusJsonFlag = candidate;
+            i++;
+        }
+        else if (tok === '--boundaries') {
+            boundariesFlag = true;
+        }
+        else if (tok === '--quotes') {
+            quotesFlag = true;
+        }
+        else if (tok.startsWith('--') && !RECOGNIZED_PRACTICES_REVIEW_FLAGS.has(tok)) {
+            const msg = `Unrecognized flag "${tok}" for check practices-review. Supported: --review <path>, --corpus-json <string>, --boundaries, --quotes.`;
+            c.output(msg, true, msg);
+            return;
+        }
+        else {
+            // WR-03 (round 7): a bare positional token — a review path named
+            // without its flag — must never be silently discarded. Discarding it
+            // exits 0 with zero bytes, byte-identical to a clean review, which is
+            // exactly the false-clean signal this function's whole design exists
+            // to avoid. Route through the same usage-message path the unrecognized-
+            // flag guard above already uses, and return before any file read.
+            const msg = `Unexpected argument "${tok}" for check practices-review. Did you mean --review ${tok}? Supported: --review <path>, --corpus-json <string>, --boundaries, --quotes.`;
+            c.output(msg, true, msg);
+            return;
+        }
+    }
+    // WR-02: track a failed read separately from "no --review given at all" so
+    // the operator-visible line below fires ONLY when a path was actually
+    // supplied and could not be read — never for the feature-off case (no
+    // --review flag), which must keep producing zero bytes (T-27-98).
+    let reviewText = '';
+    let reviewReadFailed = false;
+    if (reviewPath) {
+        try {
+            reviewText = node_fs_1.default.readFileSync(reviewPath, 'utf8');
+        }
+        catch {
+            reviewText = '';
+            reviewReadFailed = true;
+        }
+    }
+    const resolvedCorpusJson = corpusJsonFlag ?? process.env['VAULT_QUOTE_CORPUS'] ?? '';
+    const runBoth = !boundariesFlag && !quotesFlag;
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const mod = _check ?? require('./practices-review-check.cjs');
+    const result = mod.runReviewCheck({
+        reviewText,
+        corpusJson: resolvedCorpusJson,
+        boundaries: runBoth || boundariesFlag,
+        quotes: runBoth || quotesFlag,
+    });
+    const renderedLines = [...result.lines];
+    if (reviewReadFailed && reviewPath) {
+        // Plain English, no exception text / errno / internal identifier (COMM-01).
+        // Emitted on stdout (via c.output's raw path) because the workflow step
+        // that dispatches this arm redirects stderr with `2>/dev/null || true`.
+        renderedLines.unshift(`The review file at ${reviewPath} could not be read — the boundary and client-quote checks did not run.`);
+    }
+    const text = renderedLines.length > 0 ? renderedLines.join('\n') + '\n' : '';
+    c.output(text, true, text);
+}
+function routeCheckCommand({ args, cwd, raw, _check, _core }) {
     // Normalize dots to hyphens in the subcommand so both forms are accepted.
     // This makes `check.query = "ui.plan-gate"` (dotted form in capability.json gates)
     // directly runnable as `pp_run check ui.plan-gate` — the dot is normalized to
@@ -1011,6 +1459,12 @@ function routeCheckCommand({ args, cwd, raw }) {
         cmdShipPlatformDrift(cwd, args, raw);
         return;
     }
+    if (subcommand === 'ship-practices') {
+        // ship.practices — deterministic branch-diff practices re-check (INJ-03, Phase 28).
+        // Dot-to-hyphen normalization means query "ship.practices" routes here.
+        cmdShipPractices(cwd, args, raw);
+        return;
+    }
     if (subcommand === 'vault-status') {
         // vault.status — advisory vault cache state query (Phase 13, D-01/D-02).
         // Dot-to-hyphen normalization means query "vault.status" routes here.
@@ -1033,6 +1487,20 @@ function routeCheckCommand({ args, cwd, raw }) {
         cmdVerifyCodebaseDrift(cwd, raw);
         return;
     }
+    if (subcommand === 'practices-review') {
+        // IN-02: this arm deliberately diverges from every sibling `check`
+        // subcommand in two ways. (1) It always emits raw text rather than
+        // honouring the `raw` flag's JSON envelope — the workflow steps and their
+        // tests depend on byte-identical operator lines, not a JSON wrapper.
+        // (2) `--review` paths resolve against the invoking process's working
+        // directory (inside cmdCheckPracticesReview), not the router-resolved
+        // `cwd` parameter — which is what the workflow's `"${REVIEW_PATH}"`
+        // expansion already supplies. Both shapes are pinned by the CLI-seam
+        // tests in tests/practices-review-check.test.cjs, so changing either is a
+        // deliberate contract change, not a refactor.
+        cmdCheckPracticesReview({ args }, _check, _core);
+        return;
+    }
     if (subcommand === 'prohibition-enforcement') {
         // The deterministic test-tier prohibition PRODUCER/gate (#1259, ADR-550 D5d). Locates the
         // wired mechanical check (node-test or lint-rule), confirms fail-first, runs it, builds
@@ -1041,7 +1509,7 @@ function routeCheckCommand({ args, cwd, raw }) {
         (0, prohibition_enforcement_cjs_1.routeProhibitionEnforcement)(args, raw);
         return;
     }
-    error('Unknown check subcommand. Available: auto-mode, decision-coverage-plan, decision-coverage-verify, gap-analysis-plan-post, prohibition-enforcement, ship-platform-drift, tdd-review-checkpoint, ui-plan-gate, ui-safety-gate, vault-status, verify-schema-drift, verify-codebase-drift', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+    error('Unknown check subcommand. Available: auto-mode, decision-coverage-plan, decision-coverage-verify, gap-analysis-plan-post, practices-review, prohibition-enforcement, ship-platform-drift, ship-practices, tdd-review-checkpoint, ui-plan-gate, ui-safety-gate, vault-status, verify-schema-drift, verify-codebase-drift', ERROR_REASON.SDK_UNKNOWN_COMMAND);
 }
 module.exports = {
     routeCheckCommand,
@@ -1052,5 +1520,7 @@ module.exports = {
     cmdGapAnalysisPlanPost,
     cmdTddReviewCheckpoint,
     cmdShipPlatformDrift,
+    cmdShipPractices,
     cmdVaultStatus,
+    cmdCheckPracticesReview,
 };

package/pp-core/bin/lib/clusters.cjs

@@ -121,6 +121,9 @@ exports.CLUSTERS = Object.freeze({
         'mempalace-recall',
         'mempalace-capture',
         'surface',
+        // Operator-driven outward action, grouped with the other push-shaped
+        // entrypoints (ship, pr-branch) rather than with the read-only vault loop.
+        'vault-promote',
     ]),
 });
 /**

package/pp-core/bin/lib/config.cjs

@@ -143,21 +143,6 @@ function validateShipPrBodySections(value) {
 function buildNewProjectConfig(userChoices) {
     const choices = userChoices || {};
     const homedir = node_os_1.default.homedir();
-    // Detect API key availability
-    const braveKeyFile = node_path_1.default.join(homedir, '.gsd', 'brave_api_key');
-    const hasBraveSearch = !!(process.env['BRAVE_API_KEY'] || node_fs_1.default.existsSync(braveKeyFile));
-    const firecrawlKeyFile = node_path_1.default.join(homedir, '.gsd', 'firecrawl_api_key');
-    const hasFirecrawl = !!(process.env['FIRECRAWL_API_KEY'] || node_fs_1.default.existsSync(firecrawlKeyFile));
-    const exaKeyFile = node_path_1.default.join(homedir, '.gsd', 'exa_api_key');
-    const hasExaSearch = !!(process.env['EXA_API_KEY'] || node_fs_1.default.existsSync(exaKeyFile));
-    const tavilyKeyFile = node_path_1.default.join(homedir, '.gsd', 'tavily_api_key');
-    const hasTavilySearch = !!(process.env['TAVILY_API_KEY'] || node_fs_1.default.existsSync(tavilyKeyFile));
-    const refKeyFile = node_path_1.default.join(homedir, '.gsd', 'ref_api_key');
-    const hasRefSearch = !!(process.env['REF_API_KEY'] || node_fs_1.default.existsSync(refKeyFile));
-    const perplexityKeyFile = node_path_1.default.join(homedir, '.gsd', 'perplexity_api_key');
-    const hasPerplexity = !!(process.env['PERPLEXITY_API_KEY'] || node_fs_1.default.existsSync(perplexityKeyFile));
-    const jinaKeyFile = node_path_1.default.join(homedir, '.gsd', 'jina_api_key');
-    const hasJina = !!(process.env['JINA_API_KEY'] || node_fs_1.default.existsSync(jinaKeyFile));
     // Load user-level defaults from ~/.gsd/defaults.json if available
     const globalDefaultsPath = node_path_1.default.join(homedir, '.gsd', 'defaults.json');
     let userDefaults = {};
@@ -184,13 +169,13 @@ function buildNewProjectConfig(userChoices) {
         commit_docs: CONFIG_DEFAULTS.commit_docs,
         parallelization: CONFIG_DEFAULTS.parallelization,
         search_gitignored: CONFIG_DEFAULTS.search_gitignored,
-        brave_search: hasBraveSearch,
-        firecrawl: hasFirecrawl,
-        exa_search: hasExaSearch,
-        tavily_search: hasTavilySearch,
-        ref_search: hasRefSearch,
-        perplexity: hasPerplexity,
-        jina: hasJina,
+        brave_search: false,
+        firecrawl: false,
+        exa_search: false,
+        tavily_search: false,
+        ref_search: false,
+        perplexity: false,
+        jina: false,
         git: {
             branching_strategy: CONFIG_DEFAULTS.branching_strategy,
             create_tag: true,

package/pp-core/bin/lib/io.cjs

@@ -177,6 +177,13 @@ const ERROR_REASON = Object.freeze({
     SECURITY_SCAN_FAILED: 'security_scan_failed',
     // platform-bindings
     PLATFORM_BINDINGS_PARSE_FAILED: 'platform_bindings_parse_failed',
+    // vault write-back promote arm (Phase 29 WRB-01/03)
+    VAULT_PROMOTE_DISABLED: 'vault_promote_disabled',
+    VAULT_PROMOTE_INVALID_PRACTICE: 'vault_promote_invalid_practice',
+    VAULT_PROMOTE_SECRET_DETECTED: 'vault_promote_secret_detected',
+    VAULT_PROMOTE_TARGET_REFUSED: 'vault_promote_target_refused',
+    VAULT_PROMOTE_CONCURRENT_EDIT: 'vault_promote_concurrent_edit',
+    VAULT_PROMOTE_TRANSPORT_FAILED: 'vault_promote_transport_failed',
     // generic
     USAGE: 'usage',
     UNKNOWN: 'unknown',

package/pp-core/bin/lib/loop-resolver.cjs

@@ -461,6 +461,12 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
     if (state.warnings && state.warnings.length > 0) {
         envelope.warnings = state.warnings;
     }
+    // No rawValue third argument, so --raw emits the JSON envelope rather than
+    // plain text. This is deliberate and load-bearing: 23 workflow call sites do
+    // `HOOKS_JSON=$(pp_run loop render-hooks <point> --raw)` and read `activeHooks`
+    // off the parsed envelope. Callers who want the human-readable text read the
+    // envelope's `rendered` field. Same convention as the deliberate
+    // `output(result, raw, undefined)` sites in src/check-command-router.cts.
     coreOutput(envelope, raw);
 }
 module.exports = {