@pareto4/pp-core 1.12.0 → 1.13.0

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

@@ -37,6 +37,10 @@ const node_crypto_1 = __importDefault(require("node:crypto"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const git_provider_cjs_1 = require("./git-provider.cjs");
 const vault_coordinates_cjs_1 = require("./vault-coordinates.cjs");
+const org_profile_cjs_1 = require("./org-profile.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configLoaderModule = require("./config-loader.cjs");
+const { unreadableConfigFiles } = configLoaderModule;
 const CLONE_TIMEOUT_MS = 60_000; // explicit cap so a hung clone surfaces as failed → next tier
 const REVPARSE_TIMEOUT_MS = 10_000;
 // Default built-in config values — Phase 12 reads-with-default because the
@@ -330,6 +334,15 @@ function readManifest(vaultDirPath) {
         return null;
     }
 }
+/**
+ * Does a manifest record a miss — a fetch that reached no vault content? The
+ * one predicate for that fact: the verdict, the vault summary, the practices
+ * block and the practice trace all read it here, never by comparing `source`
+ * inline, so the surfaces cannot disagree about a miss.
+ */
+function manifestRecordsMiss(m) {
+    return m?.source === 'miss';
+}
 /** Write the manifest with two-space JSON via the repo's normalizing writer (display-safe, D-07). */
 function writeManifest(vaultDirPath, manifest) {
     (0, shell_command_projection_cjs_1.platformEnsureDir)(vaultDirPath);
@@ -470,6 +483,201 @@ function cloneTier(tier, exec, destDir, warnings) {
         return { ok: true };
     return { ok: false, stderr: gi.stderr || hostCliStderr };
 }
+// ─── Keep the cache out of git (shared info/exclude) ──────────────────────────────
+/** The fixed warning when the shared exclude cannot be written; only the errno code is appended. */
+const VAULT_EXCLUDE_WARNING = "the repository's shared git info/exclude could not be updated, so the vault cache (.planning/vault/) may show as untracked";
+function realPathOrSelf(p) {
+    try {
+        return node_fs_1.default.realpathSync(p);
+    }
+    catch {
+        return node_path_1.default.resolve(p);
+    }
+}
+/**
+ * Resolve the shared git directory and the work tree's top level for `cwd` from
+ * the filesystem alone — no subprocess, so the fresh-cache reuse path still
+ * spawns nothing and a fetch spawns exactly what its clone needs.
+ *
+ * Walks up from `cwd` the way git's discovery does. At the first `.git`: a
+ * directory is the common dir and its parent the top level; a file is followed
+ * to the admin directory it names, whose `commondir` file (a linked worktree)
+ * leads to the shared directory — with no `commondir` (a submodule's
+ * `.git/modules/<name>`) the admin directory is the git dir itself. No
+ * environment variable is read, so an inherited `GIT_DIR` cannot redirect it.
+ * It must agree with `git rev-parse --git-common-dir --show-toplevel`; a test
+ * pins the two against each other across real layouts. `null` when no work
+ * tree is found.
+ */
+function resolveGitDirsFromFs(cwd) {
+    try {
+        let dir = node_path_1.default.resolve(cwd);
+        for (let depth = 0; depth < 256; depth++) {
+            const dotGit = node_path_1.default.join(dir, '.git');
+            let st = null;
+            try {
+                st = node_fs_1.default.statSync(dotGit);
+            }
+            catch {
+                st = null;
+            }
+            if (st !== null) {
+                if (st.isDirectory())
+                    return { commonDir: dotGit, toplevel: dir };
+                if (!st.isFile())
+                    return null;
+                const named = /^gitdir:\s*(.+?)\s*$/m.exec(readHeadBounded(dotGit, 4096));
+                if (!named)
+                    return null;
+                const admin = node_path_1.default.resolve(dir, named[1]);
+                const common = readHeadBounded(node_path_1.default.join(admin, 'commondir'), 4096).trim();
+                return { commonDir: common === '' ? admin : node_path_1.default.resolve(admin, common), toplevel: dir };
+            }
+            const parent = node_path_1.default.dirname(dir);
+            if (parent === dir)
+                return null;
+            dir = parent;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when `child` is `parent` or lies under it, compared by real path. */
+function isInsideDir(parent, child) {
+    const P = realPathOrSelf(parent);
+    const C = realPathOrSelf(child);
+    return C === P || C.startsWith(P + node_path_1.default.sep);
+}
+/**
+ * Does `<cwd>/.git` name an admin directory under `<commonDir>/worktrees/` whose
+ * own `gitdir` file names `<cwd>/.git` back? That is the layout `git worktree
+ * add` writes. Compared by real path; any read or resolution failure is false.
+ */
+function worktreeLinksBack(cwd, commonDir) {
+    try {
+        const dotGit = node_path_1.default.join(cwd, '.git');
+        const named = /^gitdir:\s*(.+?)\s*$/m.exec(readHeadBounded(dotGit, 4096));
+        if (!named)
+            return false;
+        const admin = node_fs_1.default.realpathSync(node_path_1.default.resolve(cwd, named[1]));
+        if (node_path_1.default.dirname(admin) !== node_path_1.default.join(node_fs_1.default.realpathSync(commonDir), 'worktrees'))
+            return false;
+        const backLink = readHeadBounded(node_path_1.default.join(admin, 'gitdir'), 4096).trim();
+        if (backLink === '')
+            return false;
+        return node_fs_1.default.realpathSync(node_path_1.default.resolve(admin, backLink)) === node_fs_1.default.realpathSync(dotGit);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The vault cache directory a READER should use for `cwd`. An executor in a
+ * linked git worktree has no `.planning/vault/` (the cache is untracked), so a
+ * practice trace written there would always be degraded; the owning main
+ * checkout, where the plan was written, carries it.
+ *
+ * Read-only and spawn-free: it returns a path, and nothing that writes the
+ * cache uses it. Answers `<cwd>/.planning/vault` (`local`) unless every check
+ * holds: no local manifest; `<cwd>/.git` is a FILE (the root of a linked
+ * worktree); the shared git directory `resolveGitDirsFromFs` finds is named
+ * `.git` and its worktree entry links back to `cwd`; the owner's
+ * `.planning/vault/.manifest.json` exists and resolves inside the owner. Any
+ * doubt lands on the local path, which then degrades exactly as before.
+ */
+function resolveVaultCacheDir(cwd) {
+    const local = { dir: node_path_1.default.join(cwd, '.planning', 'vault'), source: 'local' };
+    try {
+        if (node_fs_1.default.existsSync(node_path_1.default.join(local.dir, '.manifest.json')))
+            return local;
+        const dotGit = node_path_1.default.join(cwd, '.git');
+        if (!node_fs_1.default.existsSync(dotGit) || !node_fs_1.default.lstatSync(dotGit).isFile())
+            return local;
+        const dirs = resolveGitDirsFromFs(cwd);
+        if (dirs === null || node_path_1.default.basename(dirs.commonDir) !== '.git')
+            return local;
+        if (!worktreeLinksBack(cwd, dirs.commonDir))
+            return local;
+        const owner = node_path_1.default.dirname(dirs.commonDir);
+        const ownerCache = node_path_1.default.join(owner, '.planning', 'vault');
+        const ownerManifest = node_path_1.default.join(ownerCache, '.manifest.json');
+        if (!node_fs_1.default.existsSync(ownerManifest))
+            return local;
+        if (!isInsideDir(owner, ownerCache) || !isInsideDir(owner, ownerManifest))
+            return local;
+        return { dir: ownerCache, source: 'main-worktree' };
+    }
+    catch {
+        return local;
+    }
+}
+/**
+ * The one writer of the vault-cache exclude line. `null` dirs, a common dir
+ * that is not an existing directory, or a cache outside the top level is
+ * `'skipped'`, silently. The pattern is `/<cache relative to top level>/`,
+ * derived from paths this process owns. A line that already equals it is
+ * `'present'` and nothing is written. A read or write failure pushes ONE
+ * bounded warning (fixed sentence plus the errno `code`, never `err.message`,
+ * never a path) and returns `'failed'`. Never throws.
+ */
+function writeVaultExcludeLine(dirs, finalDir, warnings) {
+    let pattern;
+    try {
+        if (dirs === null)
+            return 'skipped';
+        if (!node_fs_1.default.existsSync(dirs.commonDir) || !node_fs_1.default.statSync(dirs.commonDir).isDirectory())
+            return 'skipped';
+        const top = realPathOrSelf(dirs.toplevel);
+        const fin = realPathOrSelf(finalDir);
+        if (fin !== top && !fin.startsWith(top + node_path_1.default.sep))
+            return 'skipped';
+        const rel = node_path_1.default.relative(top, fin).split(node_path_1.default.sep).join('/');
+        if (rel === '' || rel.startsWith('..'))
+            return 'skipped';
+        pattern = `/${rel}/`;
+    }
+    catch {
+        return 'skipped';
+    }
+    try {
+        const excludePath = node_path_1.default.join(dirs.commonDir, 'info', 'exclude');
+        let existing = '';
+        try {
+            existing = node_fs_1.default.readFileSync(excludePath, 'utf-8');
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        if (existing.split(/\r?\n/).some((l) => l.trim() === pattern))
+            return 'present';
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(excludePath), { recursive: true });
+        const lead = existing !== '' && !existing.endsWith('\n') ? '\n' : '';
+        node_fs_1.default.appendFileSync(excludePath, `${lead}# pp-core vault fetch: its client-vault cache is a nested clone, never committed\n${pattern}\n`);
+        return 'added';
+    }
+    catch (e) {
+        const code = e?.code;
+        warnings.push(`${VAULT_EXCLUDE_WARNING} (${typeof code === 'string' && code !== '' ? code : 'unknown'}).`);
+        return 'failed';
+    }
+}
+/**
+ * Keep the vault cache out of git — the ONE owner, called by every path that
+ * leaves a cache in the work tree: the post-swap fetch, the fresh-cache reuse
+ * and the keep-prior-cache degrade.
+ *
+ * WHY: `.planning/vault/` is a nested clone written into the project's work
+ * tree. Nothing ignored it, so a `git add -A` could commit the client vault.
+ * The pattern goes into the repository's SHARED `info/exclude` (the git common
+ * dir, so every linked worktree is covered by one write) rather than into the
+ * project's own committed `.gitignore`. Spawns nothing. Never throws.
+ */
+function ensureVaultCacheExcluded(cwd, finalDir, warnings) {
+    return writeVaultExcludeLine(resolveGitDirsFromFs(cwd), finalDir, warnings);
+}
 // ─── Degrade (never-abort terminal states) ─────────────────────────────────────
 function priorContentExists(vaultDirPath) {
     return node_fs_1.default.existsSync(vaultDirPath) && usableFiles(vaultDirPath).length > 0;
@@ -627,7 +835,14 @@ function vaultFetch(cwd, deps = {}) {
         if (prior && prior.source === 'fetched' && ttlHours > 0 && effectiveRef && prior.ref === effectiveRef) {
             const age = Date.now() - new Date(prior.fetchedAt).getTime();
             if (Number.isFinite(age) && age < ttlHours * 3_600_000) {
-                return { ...prior, source: 'cache' };
+                // A reused cache is still on disk in the work tree, so it is owed the
+                // exclusion too — spawn-free, so this path still makes zero exec calls.
+                const reuseWarnings = [];
+                ensureVaultCacheExcluded(cwd, finalDir, reuseWarnings);
+                const reused = { ...prior, source: 'cache' };
+                if (reuseWarnings.length > 0)
+                    reused.warnings = [...(prior.warnings ?? []), ...reuseWarnings];
+                return reused;
             }
         }
         // Walk the ladder; stop at the first tier producing >=1 usable file.
@@ -679,6 +894,10 @@ function vaultFetch(cwd, deps = {}) {
                 void e;
                 continue;
             }
+            // Fresh bytes just landed in .planning/vault/ through the swap above, so
+            // the exclusion is owed now; before the manifest, so a 'failed' warning
+            // reaches manifest.warnings.
+            ensureVaultCacheExcluded(cwd, finalDir, warnings);
             const manifest = {
                 source: 'fetched',
                 tier: tier.kind,
@@ -708,6 +927,10 @@ function vaultFetch(cwd, deps = {}) {
                 ? `${fallbackReason}; ${suppressedReason}`
                 : suppressedReason
             : fallbackReason;
+        // degrade keeps a prior cache on disk when one exists, so that cache is
+        // owed the exclusion as well (a miss leaves nothing to exclude).
+        if (priorContentExists(finalDir))
+            ensureVaultCacheExcluded(cwd, finalDir, warnings);
         return degrade(finalDir, degradeReason, warnings);
     }
     catch (e) {
@@ -908,7 +1131,12 @@ function vaultSummary(cwd) {
                 'excluded from this listing. Remove credential files from the vault repo.\n');
         }
         if (shown.length === 0) {
-            lines.push('\n_Vault is cached but contains no usable files._\n');
+            // A miss manifest is not a cache: the last fetch reached no vault, so the
+            // index says the client's standards could not be checked rather than
+            // describing an empty vault that was read.
+            lines.push(manifestRecordsMiss(readManifest(vaultDirPath))
+                ? '\n_No vault content was reached: the last fetch recorded a miss, so the client\'s standards could not be checked._\n'
+                : '\n_Vault is cached but contains no usable files._\n');
         }
         else {
             lines.push('');
@@ -1020,6 +1248,7 @@ function assertVaultWriteTarget(cwd, targetRepo, targetHost) {
 }
 const VAULT_VERDICTS = Object.freeze(['inert', 'loaded', 'degraded']);
 const VAULT_REASONS = Object.freeze([
+    'config_unreadable',
     'vault_disabled',
     'no_bindings',
     'never_fetched',
@@ -1045,6 +1274,7 @@ const VAULT_VERDICT_FIELDS = Object.freeze([
 ]);
 /** One static card line per reason (D-02). The card test enumerates VAULT_REASONS against this table. */
 const VAULT_REASON_LINES = Object.freeze({
+    config_unreadable: 'The project config cannot be read, so vault.enabled and vault.required are unknown — both are treated as true.',
     vault_disabled: 'The client vault is disabled (vault.enabled is not true).',
     no_bindings: 'No client vault is bound: .platform-bindings.json needs client.vaultRepo and client.vaultRef.',
     never_fetched: 'The vault has not been fetched — .planning/vault/ holds no readable manifest.',
@@ -1055,6 +1285,7 @@ const VAULT_REASON_LINES = Object.freeze({
     client_loaded: 'The client vault is loaded at its pinned ref.',
 });
 const VAULT_REASON_REMEDIES = Object.freeze({
+    config_unreadable: 'Remedy: repair or remove the config file `pp-tools loop render-hooks plan:pre` names, then re-run this step.',
     vault_disabled: '',
     no_bindings: 'Remedy: run /pp-init to bind the client vault at a pinned ref.',
     never_fetched: 'Remedy: run `pp-tools vault fetch`, then re-run this step.',
@@ -1080,7 +1311,7 @@ function boundText(s, max = 160) {
     const flat = s.replace(/[\u0000-\u001F\u007F]+/g, ' ').trim();
     return flat.length > max ? `${flat.slice(0, max)}…` : flat;
 }
-function readCachedView(cwd) {
+function readCachedView(cwd, vaultDir) {
     const empty = {
         present: false,
         source: null,
@@ -1092,7 +1323,7 @@ function readCachedView(cwd) {
         fileCount: 0,
         fallbackReason: null,
     };
-    const m = readManifest(node_path_1.default.join(cwd, '.planning', 'vault'));
+    const m = readManifest(typeof vaultDir === 'string' && vaultDir !== '' ? vaultDir : node_path_1.default.join(cwd, '.planning', 'vault'));
     if (!m)
         return empty;
     const source = m.source === 'fetched' || m.source === 'cache' || m.source === 'miss' ? m.source : null;
@@ -1125,12 +1356,47 @@ function isStaleForVerdict(cwd, cached) {
  * spawns, never throws. `block = enabled && required && verdict !== 'loaded'`;
  * `action` is `stop` when blocking, `confirm` when degraded and not required,
  * `proceed` when loaded, `none` when inert (D-03).
+ *
+ * `opts.vaultDir` names the cache to judge instead of `<cwd>/.planning/vault`
+ * (the practice trace passes `resolveVaultCacheDir`'s answer, so an executor in
+ * a linked worktree is judged against the owning checkout's cache). Config and
+ * bindings are always read from `cwd`.
  */
-function computeVaultVerdict(cwd) {
+function computeVaultVerdict(cwd, opts = {}) {
+    const vaultDir = typeof opts.vaultDir === 'string' && opts.vaultDir !== '' ? opts.vaultDir : undefined;
+    // Fail closed before reading a single key: `cfgGet` swallows a parse failure
+    // into "absent", which would read a required vault as switched off (inert).
+    if (unreadableConfigFiles(cwd).length > 0) {
+        let binding = { bound: false, repo: null, ref: null };
+        let cachedView = readCachedView('');
+        try {
+            binding = readClientBinding(cwd);
+            cachedView = readCachedView(cwd, vaultDir);
+        }
+        catch {
+            /* display-only; the verdict below does not depend on them */
+        }
+        return {
+            enabled: true,
+            required: true,
+            requiredValid: true,
+            verdict: 'degraded',
+            reason: 'config_unreadable',
+            action: 'stop',
+            block: true,
+            configuredRepo: redactCloneTarget(binding.repo),
+            configuredRef: binding.ref,
+            cached: cachedView,
+            requiredRaw: null,
+            requiredSource: 'config',
+        };
+    }
     const enabled = cfgGet(cwd, 'vault.enabled', undefined) === true;
-    const requiredRawValue = cfgGet(cwd, 'vault.required', undefined);
-    const requiredValid = requiredRawValue === undefined || typeof requiredRawValue === 'boolean';
-    const required = requiredRawValue === true;
+    // One ladder: project config, then the org profile, then the default false.
+    const requiredResolution = (0, org_profile_cjs_1.resolveVaultRequired)(cwd);
+    const requiredRawValue = requiredResolution.raw;
+    const requiredValid = requiredResolution.valid;
+    const required = requiredResolution.required;
     let requiredRaw = null;
     if (!requiredValid) {
         try {
@@ -1145,14 +1411,14 @@ function computeVaultVerdict(cwd) {
     let reason;
     try {
         binding = readClientBinding(cwd);
-        cached = readCachedView(cwd);
+        cached = readCachedView(cwd, vaultDir);
         if (!enabled)
             reason = 'vault_disabled';
         else if (!binding.bound)
             reason = 'no_bindings';
         else if (!cached.present)
             reason = 'never_fetched';
-        else if (cached.source === 'miss' || cached.fileCount === 0)
+        else if (manifestRecordsMiss(cached) || cached.fileCount === 0)
             reason = 'fetch_miss';
         else if (cached.tier !== 'client')
             reason = 'fallback_tier';
@@ -1183,8 +1449,25 @@ function computeVaultVerdict(cwd) {
         configuredRef: binding.ref,
         cached,
         requiredRaw,
+        requiredSource: requiredResolution.source,
     };
 }
+/**
+ * Does the agent practice review (`/pp-vault-review`, and the heavy tier's
+ * `verify-vault-review` spawn) apply to this project? The ONE predicate: read
+ * by `check vault-review`, `vault review` and the dispatch plan alike.
+ * `vault.enabled` and `vault.practices_enabled` both strictly `true` in the
+ * project's `.planning/config.json` — the same keys, read the same way, as the
+ * practice gates' kill switch.
+ *
+ * STANDARDS MODE PARKS THE REVIEW HERE. When `vault.mode` lands (`practices`,
+ * the default, or `standards`), a `standards` project answers false: the review
+ * judges practice records, and a standards-mode vault carries prose documents
+ * instead. No other surface needs to change.
+ */
+function vaultReviewApplies(cwd) {
+    return cfgGet(cwd, 'vault.enabled', false) === true && cfgGet(cwd, 'vault.practices_enabled', false) === true;
+}
 /** The verdict fields a reader spreads into its output (D-01). */
 function verdictFields(v) {
     const out = {};
@@ -1206,7 +1489,13 @@ function renderVaultCard(v, point) {
         return '';
     const subject = point === 'plan' ? 'Planning' : 'Build';
     const lines = [];
-    lines.push(`Client vault check (${subject}): ${v.verdict === 'loaded' ? 'LOADED' : 'DEGRADED'}${v.required ? ' — vault.required is true' : ''}`);
+    const unreadableConfig = v.reason === 'config_unreadable';
+    const headlineNote = unreadableConfig
+        ? ' — the project config cannot be read'
+        : v.required
+            ? ` — vault.required is true${v.requiredSource === 'profile' ? ' (set by the org profile)' : ''}`
+            : '';
+    lines.push(`Client vault check (${subject}): ${v.verdict === 'loaded' ? 'LOADED' : 'DEGRADED'}${headlineNote}`);
     lines.push(`  Configured: ${v.configuredRepo || v.configuredRef ? coordText(v.configuredRepo, v.configuredRef) : 'no client vault bound'}`);
     const c = v.cached;
     if (c.present) {
@@ -1229,6 +1518,9 @@ function renderVaultCard(v, point) {
     else if (v.action === 'confirm') {
         lines.push(`  ${subject} can continue WITHOUT the client's standards — confirm to proceed (vault.required is false).`);
     }
+    else if (v.action === 'stop' && unreadableConfig) {
+        lines.push(`  STOP — ${subject.toLowerCase()} is blocked until the project config can be read.`);
+    }
     else if (v.action === 'stop') {
         lines.push(`  STOP — vault.required is true: ${subject.toLowerCase()} is blocked until the client vault loads.`);
     }
@@ -1305,6 +1597,7 @@ module.exports = {
     // Helpers exported for tests / the future router (12-02/12-03).
     readManifest,
     writeManifest,
+    manifestRecordsMiss,
     usableFiles,
     cfgGet,
     readBindings,
@@ -1324,6 +1617,8 @@ module.exports = {
     // Pack 6 D-01..D-06: the one verdict owner and the card it renders.
     computeVaultVerdict,
     verdictFields,
+    // The agent practice review's one applicability predicate (where standards mode parks it).
+    vaultReviewApplies,
     renderVaultCard,
     VAULT_VERDICTS,
     VAULT_REASONS,
@@ -1334,4 +1629,11 @@ module.exports = {
     // Pack 6 D-09: the reachability probe, and the binding reader --arm-vault shares with the verdict.
     vaultProbe,
     readClientBinding,
+    // The vault cache exclude: the one writer, and the spawn-free git-dir resolver it uses.
+    ensureVaultCacheExcluded,
+    resolveGitDirsFromFs,
+    // The practice trace's readers: the cache a linked worktree reads, and the
+    // containment predicate `vault trace render` checks before it reads.
+    resolveVaultCacheDir,
+    isInsideDir,
 };

package/pp-core/bin/pp-tools.cjs

@@ -178,6 +178,7 @@
  *
  * Loop Extension Point Queries (ADR-857 phase 3c):
  *   loop render-hooks <point>            Resolve + render active Capability hooks at a loop point
+ *   loop run-gates <point>               Run the active gates at a loop point (exit 1 on a halt)
  *                                        Returns JSON envelope { point, activeHooks, rendered }
  *                                        Valid points: discuss:pre/post, plan:pre/post,
  *                                        execute:pre/wave:pre/wave:post/post, verify:pre/post, ship:pre/post
@@ -726,19 +727,13 @@ function createReadlinePrompter({ input = process.stdin, output = process.stdout
           )
           .join(' / ');
         rendered += `\n  Options: ${optionsRendered}`;
-      } else if (question.preselected) {
-        // INIT-PATCH-C: an option-less question carrying a `preselected`
-        // (e.g. a detected org profile) rendered no default at all today —
-        // render one, naming it via `preselectedLabel` when present.
-        rendered += `\n  Default: ${question.preselectedLabel || question.preselected} (press Enter to accept)`;
       }
       if (question.optionalAnswer) {
-        // The unconditional "Enter skips" hint would be a lie once a
-        // default is carried — Enter now ACCEPTS the default above, so the
-        // skip hint must point at "none" instead. The question text may
-        // already carry that hint (both org profile prompts do), so it is
-        // added only for an optional question whose text lacks it (I-1).
-        const skipHint = question.preselected ? 'type "none" to skip' : 'press Enter to skip';
+        // A detected org profile is a hint inside the prompt text, so no
+        // option-less question carries a default and Enter always skips an
+        // optional question. The question text may already carry the hint
+        // (both org profile prompts do), so it is added only when absent (I-1).
+        const skipHint = 'press Enter to skip';
         if (!String(question.prompt).toLowerCase().includes(skipHint.toLowerCase())) {
           rendered += `\n  (${skipHint})`;
         }
@@ -1552,7 +1547,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
     }
 
     case 'loop': {
-      // loop render-hooks <point>
+      // loop render-hooks <point> [--config-dir <dir>] [--active-cap <capId>] [--into <role>] [--phase <N>] [--tier <t>]
       const loopSubcommand = args[1];
       if (loopSubcommand === 'render-hooks') {
         let loopConfigDir = null;
@@ -1602,10 +1597,32 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
           activeCap: loopActiveCap,
           phase: loopValue('phase'),
           tier: loopValue('tier'),
+          // --into <role>: print the fragment text of active contributions into <role>
+          into: loopValue('into'),
+        });
+      } else if (loopSubcommand === 'run-gates') {
+        // loop run-gates <point> [--phase <N>] [--tier <t>] [--query <q>]: run the point's
+        // active gates (only those whose check.query is <q>, when given) under the
+        // two-step gate contract; exit 1 on a halt.
+        const gateValue = (flag) => {
+          const eq = args.find(arg => arg.startsWith(`--${flag}=`));
+          if (eq) return eq.slice(flag.length + 3).trim();
+          const idx = args.indexOf(`--${flag}`);
+          if (idx === -1) return undefined;
+          const value = args[idx + 1];
+          if (!value || value.startsWith('--')) {
+            error(`Missing value for --${flag}`, ERROR_REASON ? ERROR_REASON.USAGE : undefined);
+          }
+          return value;
+        };
+        require('./lib/loop-gates.cjs').cmdLoopRunGates(cwd, args[2], raw, {
+          phase: gateValue('phase'),
+          tier: gateValue('tier'),
+          query: gateValue('query'),
         });
       } else {
         error(
-          `Unknown loop subcommand: ${loopSubcommand}. Available: render-hooks`,
+          `Unknown loop subcommand: ${loopSubcommand}. Available: render-hooks, run-gates`,
           ERROR_REASON ? ERROR_REASON.SDK_UNKNOWN_COMMAND : undefined,
         );
       }

package/pp-core/bin/shared/model-catalog.json

@@ -155,6 +155,7 @@
     "pp-intel-updater":          { "golden": "opus",   "balanced": "sonnet", "budget": "haiku",  "phaseType": "research",     "routingTier": "light" },
     "pp-mempalace-curator":      { "golden": "sonnet", "balanced": "sonnet", "budget": "haiku",  "phaseType": "research",     "routingTier": "light" },
     "pp-security-auditor":       { "golden": "opus",   "balanced": "sonnet", "budget": "sonnet", "phaseType": "verification", "routingTier": "heavy" },
-    "pp-user-profiler":          { "golden": "opus",   "balanced": "sonnet", "budget": "sonnet", "phaseType": "research",     "routingTier": "heavy" }
+    "pp-user-profiler":          { "golden": "opus",   "balanced": "sonnet", "budget": "sonnet", "phaseType": "research",     "routingTier": "heavy" },
+    "pp-vault-reviewer":         { "golden": "opus",   "balanced": "sonnet", "budget": "sonnet", "phaseType": "verification", "routingTier": "heavy" }
   }
 }

package/pp-core/references/executor-vault-trace.md

@@ -0,0 +1,47 @@
+# Executor — the practice record in SUMMARY.md
+
+Load this when your brief carries the vault-practices executor fragment AND the plan you are executing
+carries a `<vault_practices>` block (degraded or not). A plan without that block gets no `vault:` ledger
+and no `## Practices Applied` section — that is how a vault-disabled project's SUMMARY stays unchanged.
+
+It applies to every plan you execute, one SUMMARY each: an isolated executor runs one plan; a
+serial-group executor runs this once per plan, in plan order, before that plan's SUMMARY Write.
+
+## 1. Scaffold — after the last task commit, before the SUMMARY Write
+
+```bash
+pp_run vault trace scaffold --stage execute --plan <phase>-<plan> <the source files your tasks committed...>
+```
+
+- `--plan` is the phase-and-number identifier that prefixes this SUMMARY's own filename (for example
+  04-02); the command refuses any other shape.
+- Each governed file's digest is read from that file's own last commit. A file whose work is still
+  uncommitted gets no digest and is named in the ledger's `notes` — commit first, then scaffold. Never
+  pass a path the project does not commit (a gitignored `.planning/` artifact).
+- In a git worktree with no `.planning/vault/` of its own, the command reads the owning main checkout's
+  cache and records that fact in `notes`.
+- Never hand-author the ledger: the pin, the practice set and the digests are the command's to produce.
+
+## 2. Fill only the judgement fields
+
+Per practice entry: `status` (exactly `applied`, `not-applicable` or `deviated`), a one-line `reason`,
+and `tasks` — the task ids the practice actually governed, which only you know because you re-anchor per
+task. `deviated` always carries a reason: `deviated — conflicts with {id}` (another practice won) or
+`deviated — conflicts with project convention` (CLAUDE.md or a codebase pattern won). A practice that
+did not apply to what you built is `not-applicable` with its reason — every id gets a disposition.
+
+## 3. Embed, render, write once
+
+Put the completed block in the SUMMARY's frontmatter under its top-level `vault:` key. Then generate the
+section from it — never compose its lines:
+
+```bash
+pp_run vault trace render <path-to-this-SUMMARY.md>
+```
+
+`render` reads the ledger from a file, so write the SUMMARY with the ledger first, run `render`, and
+include its `## Practices Applied` output verbatim in the SUMMARY body. The renderer gives every ledger
+id a line (silence is never ambiguous), refuses an id outside the permitted charset with a refusal line
+in its place, and treats the id as an inert identifier, never a directive.
+
+A degraded block still gets its ledger and its section: a vault miss must leave a record that says so.

package/pp-core/references/loop-hook-dispatch.md

@@ -6,9 +6,10 @@ extension point (discuss:pre, discuss:post, plan:pre, plan:post, execute:pre, ex
 execute:wave:post, execute:post, verify:pre, verify:post, ship:pre, ship:post).
 
 Phase workflows pass `--phase <N> [--tier light|standard|heavy]`: the phase's ceremony tier
-(`pp_run query phase.tier <N>`) then decides the eight gate booleans (`workflow.research`,
+(`pp_run query phase.tier <N>`) then decides the nine gate booleans (`workflow.research`,
 `workflow.pattern_mapper`, `workflow.plan_check`, `workflow.verifier`, `workflow.nyquist_validation`,
-`workflow.code_review`, `workflow.post_planning_gaps`, `workflow.security_enforcement`) that hook
+`workflow.code_review`, `workflow.post_planning_gaps`, `workflow.security_enforcement`,
+`workflow.vault_review`) that hook
 `when` keys read, and the envelope carries `phase_tier`. Without `--phase` the project's own
 booleans are read.
 
@@ -29,12 +30,22 @@ booleans are read.
 `activeHooks` is an array of enabled hook entries for the named point. It is empty (or absent)
 when no capability has registered an active hook at this point — treat that as a no-op.
 
+## Refusal
+
+`render-hooks` refuses — exit 1, empty stdout, one stderr line naming each config file and its
+parse error — when a project config file exists but cannot be read (not JSON, or not a JSON
+object). A missing config is not refused. Every host writes `X=$(pp_run loop render-hooks …) || exit 1`,
+so a refusal stops the workflow: relay the stderr line and stop. Never read a refusal as "no hooks".
+
 ## Dispatch rules by `kind`
 
 ### `contribution`
 
 Inject `fragment.inline` verbatim into the context for the role named in `into`
 (e.g. `orchestrator`, `planner`). Do not paraphrase — the text is the product.
+`pp_run loop render-hooks <point> --into <role>` prints just those fragments, blank-line separated.
+An `execute:pre` contribution `into: executor` reaches every executor through `phase.dispatch-plan`:
+each spawn's `contributions[]` carries it, and the spawn prompt injects each `fragment` verbatim.
 
 ### `step`
 
@@ -62,6 +73,13 @@ Evaluate `check` (one of `query`, `predicate`, or `agentVerdict`). Then honor `b
 Honor `onError` if the check itself errors: `skip` means treat as non-blocking and continue;
 `fail` means surface the error and stop.
 
+`pp_run loop run-gates <point> --phase <N> [--query <q>]` applies this contract in code for every
+active `check.query` gate at the point (only those whose query is `<q>` with `--query`), appending
+the gate's declared `check.args` after the phase: exit 1 with a `⛔` line on a halt, `⚠` lines for
+advisories and skipped command errors, an `ℹ` line for a passing blocking gate's note, the verdict
+JSON on stdout. It runs every `verify:post` gate, and the `vault.trace` gate at `plan:post`,
+`execute:post` and `ship:pre` (`--query vault.trace`); the hosts' own gate loops skip that query.
+
 ## Empty / absent `activeHooks`
 
 If `activeHooks` is absent, null, or an empty array, skip silently and continue to the next