@pareto4/pp-core 1.12.1 → 1.13.0

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

@@ -37,6 +37,7 @@ 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;
@@ -333,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);
@@ -473,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;
@@ -630,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.
@@ -682,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,
@@ -711,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) {
@@ -911,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('');
@@ -1086,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,
@@ -1098,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;
@@ -1131,8 +1356,14 @@ 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) {
@@ -1140,7 +1371,7 @@ function computeVaultVerdict(cwd) {
         let cachedView = readCachedView('');
         try {
             binding = readClientBinding(cwd);
-            cachedView = readCachedView(cwd);
+            cachedView = readCachedView(cwd, vaultDir);
         }
         catch {
             /* display-only; the verdict below does not depend on them */
@@ -1157,12 +1388,15 @@ function computeVaultVerdict(cwd) {
             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 {
@@ -1177,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';
@@ -1215,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 = {};
@@ -1239,7 +1490,11 @@ function renderVaultCard(v, point) {
     const subject = point === 'plan' ? 'Planning' : 'Build';
     const lines = [];
     const unreadableConfig = v.reason === 'config_unreadable';
-    const headlineNote = unreadableConfig ? ' — the project config cannot be read' : v.required ? ' — vault.required is true' : '';
+    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;
@@ -1342,6 +1597,7 @@ module.exports = {
     // Helpers exported for tests / the future router (12-02/12-03).
     readManifest,
     writeManifest,
+    manifestRecordsMiss,
     usableFiles,
     cfgGet,
     readBindings,
@@ -1361,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,
@@ -1371,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.
 
@@ -42,6 +43,9 @@ so a refusal stops the workflow: relay the stderr line and stop. Never read a re
 
 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`
 
@@ -69,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

package/pp-core/references/planner-vault-practices.md

@@ -53,7 +53,7 @@ Applies at the `write_phase_prompt` step.
 
 **Vault practices block (only when the vault-practices capability is active):** This whole subsection applies ONLY when the injected `plan:pre -> into: planner` fragment for vault-practices is present in your context — i.e. `vault.enabled` AND `vault.practices_enabled` are both true for this project. When that fragment is absent, do nothing described here: write no `<vault_practices>` block at all, and this PLAN.md stays byte-identical to a plan produced without the capability.
 
-When the fragment IS present: for EACH plan, after that plan's `files_modified` list is finalized and BEFORE calling Write on that plan's PLAN.md, run `pp-tools vault practices match <files_modified...> --block` as an ordinary Bash action against that plan's own files — this call happens in-turn, mid-planning, not before planning starts (the CLI genuinely cannot run any earlier, since `files_modified` does not exist yet at `plan:pre` time).
+When the fragment IS present: for EACH plan, after that plan's `files_modified` list is finalized and BEFORE calling Write on that plan's PLAN.md, run `pp_run vault practices match <files_modified...> --block` as an ordinary Bash action against that plan's own files — this call happens in-turn, mid-planning, not before planning starts (the CLI genuinely cannot run any earlier, since `files_modified` does not exist yet at `plan:pre` time).
 
 **Embed that command's output VERBATIM as the plan's `<vault_practices>` block — byte for byte, from `<vault_practices>` to `</vault_practices>`.** Do not rename a field, re-order an entry, add or move a fence marker, re-wrap, summarise, or omit anything. The CLI already emits the finished block in the exact shape `docs/practices-format.md` defines: the opening notice, the scoped and global groups, the documented field names, and the whole-entry external-content fencing. It ALWAYS includes every practice the matcher returns with `scope: global`, labeled global — that is now guaranteed by the command rather than left to a plan-time judgement call (D-03), and it is never yours to drop one. It also emits the correct degraded one-line state on its own when there is nothing to show, so the block is never silently absent.
 
@@ -65,3 +65,48 @@ Write the block using exactly one of these three degraded one-line states — ve
 - Matcher ran, zero matched AND zero global practices returned: `Practices checked — none apply to this plan's files.` (D-13)
 - Matcher ran, no practices directory found in any fetched vault tier: `Practices checked — none found in the vault.` (D-14)
 - The matcher CLI call itself failed: planning continues regardless — this is advisory, not a blocker, mirroring the vault fetch step's own skip-on-error discipline — and the block carries `Practices could not be checked: <reason>.` (D-15)
+
+### Frontmatter trace ledger — after the plan graph, then fill
+
+**When:** last. Write the plans, run `pp_run query phase-plan-index "$PHASE"`, write back each plan's
+computed `wave` / `serial_group`, and apply any `merge_candidates` merge FIRST (`planner-plan-graph.md`).
+A merge changes a plan's `files_modified` and its identifier, and the ledger's subject list and practice
+set are derived from exactly those, so a ledger written before the plan graph settled describes a
+different plan. Only then, for each final plan, re-run the `--block` match if its `files_modified`
+changed, and add the ledger.
+
+**What to run:** `pp_run vault trace scaffold --stage plan --plan <plan-id> <files_modified...>`. Put the
+returned block in that plan's **frontmatter**, under its top-level `vault:` key, exactly as emitted —
+after `title:`, `wave`, `serial_group` and `chain_reason`, the same verbatim discipline the body block
+gets. A later `pp_run frontmatter set` on the plan keeps the ledger's lines as they are.
+
+**The `<plan-id>` is not free-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. The command refuses any other shape outright rather than emitting a block you would have to redo.
+
+**What you fill, and only this:** per practice entry, the `status`, a one-line `reason`, and `tasks` —
+the task ids in this plan the practice is expected to govern. **The pin and the practice list are not
+yours to write.** Never type a `ref`, a `resolvedSha` or a digest, and never re-derive, re-order or trim
+the practice list: those are the fields the command exists to produce.
+
+**The three status words** are the existing vocabulary and are never re-coined:
+- `applied` — the practice governs the work and will be followed.
+- `not-applicable` — the practice was considered and ruled out for this plan.
+- `deviated` — the practice loses to something that outranks it, and the `reason` says to what.
+
+**A ruled-out practice gets a line, not silence.** A practice you considered and set aside is recorded
+`not-applicable` **with its reason**. That auditable ruled-out set is the point of the ledger: an
+omitted entry and a never-considered one look the same to every later reader.
+
+**The ledger and the body block have different jobs.** The `vault:` ledger is the **audit record**: our
+keys, our values, one bounded client-authored token (the practice `id`), and **no client prose** — YAML
+has no fence, so practice text copied into frontmatter has left the fence. The `<vault_practices>` body
+block is the **reference content** the executor re-anchors against per task; it **keeps its fences**.
+
+**Degraded or absent vault:** the ledger is still obtained and embedded, carrying the degraded state and
+its reason — a degraded run must leave an artifact that says so, not one indistinguishable from a
+project that was never vault-enabled. The three degraded one-line states above still govern the body
+block. The `override` field is always `null`; it is never yours to write.
+
+**Re-run rule:** if a plan-checker revision or `plan_bounce` later changes that plan's `files_modified`,
+re-run the scaffold and replace the block, exactly as the body block is re-run.
+
+**Shape:** `docs/vault-trace-format.md` is the contract for the block's fields — read the shape there.