@pareto4/pp-core 1.12.1 → 1.13.0

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

@@ -382,6 +382,80 @@ function renderLoopHooks(resolved) {
     return lines.join('\n');
 }
 // ─── I/O command handler ───────────────────────────────────────────────────────
+/**
+ * The refusal text for a caller that resolves hooks over an unreadable config.
+ * One wording for every such caller (`loop render-hooks`, `phase.dispatch-plan`).
+ */
+function unreadableConfigRefusal(what, unreadable) {
+    return (`${what} refused: the project config cannot be read, so no hook can be resolved ` +
+        `(rendering anyway would silently drop every hook the config switches on, a required client vault among them). ` +
+        `${describeUnreadableConfig(unreadable)}. Repair or remove the file, then re-run. Stop this workflow here.`);
+}
+/**
+ * Resolve the active hooks at `point` for the project at `cwd`, exactly as
+ * `loop render-hooks` does: refuse an unreadable config, load the config
+ * snapshot once, overlay the phase tier's gate booleans when one is given,
+ * resolve capability state over the same snapshot, then resolve the hooks.
+ * The ONE owner of "which hooks are active here" for every caller that needs
+ * the answer in code (`loop render-hooks`, `phase.dispatch-plan`'s executor
+ * contributions). Never exits; the caller decides how to report a refusal.
+ */
+function resolveProjectLoopHooks(cwd, point, opts = {}) {
+    // Fail closed on a config that exists but cannot be read. Every hook's `when`
+    // and activation key is read from it, and both readers below swallow a parse
+    // failure into the defaults, so rendering anyway drops exactly the hooks the
+    // project switched on — a required client vault's fetch and blocking gate
+    // among them. A MISSING config is not refused: that is a fresh project, and
+    // the defaults are its real settings.
+    const unreadable = unreadableConfigFiles(cwd);
+    if (unreadable.length > 0) {
+        return { ok: false, reason: 'config_unreadable', message: unreadableConfigRefusal(opts.what ?? `loop render-hooks ${point}`, unreadable) };
+    }
+    // Load the config snapshot ONCE and share it with both the capability-state
+    // resolver (via configOverride) and loop-hook resolution, so federated keys
+    // present in loadConfig resolve identically for `active` and for hook when/
+    // configValues. Keys absent from loadConfig still fall through to raw
+    // .planning/config.json reads (precedence levels 2-3) in each pass.
+    let config;
+    try {
+        config = loadConfig(cwd);
+    }
+    catch {
+        config = {};
+    }
+    if (opts.phaseTier)
+        config = (0, phase_tier_cjs_1.overlayTierGates)(config, opts.phaseTier);
+    const state = resolveCapabilityRuntimeState(cwd, opts.configDir, config);
+    // Registry is the static generated module — same object capability-state uses internally.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const registry = require('./capability-registry.cjs');
+    const capabilityStatesById = new Map();
+    for (const cap of state.capabilities || []) {
+        capabilityStatesById.set(cap.id, cap);
+    }
+    try {
+        const resolved = resolveLoopHooks({ point, registry, config, cwd, capabilityStatesById });
+        return { ok: true, resolved, warnings: state.warnings ?? [] };
+    }
+    catch (err) {
+        return { ok: false, reason: 'invalid_point', message: (err instanceof Error) ? err.message : String(err) };
+    }
+}
+/**
+ * The `fragment.inline` text of every active contribution into `role`, in
+ * resolved order, with the capability that contributed it.
+ */
+function contributionsInto(resolved, role) {
+    const out = [];
+    for (const h of resolved.activeHooks) {
+        if (h.kind !== 'contribution' || h.into !== role)
+            continue;
+        if (typeof h.fragment?.inline !== 'string')
+            continue;
+        out.push({ capId: h.capId, fragment: h.fragment.inline });
+    }
+    return out;
+}
 /**
  * Command entry point: load registry + config, resolve + render, emit envelope.
  *
@@ -396,6 +470,10 @@ function renderLoopHooks(resolved) {
  * pre-cutover keys like `workflow.ui_phase` that live in config.json but are not
  * yet exposed through loadConfig's whitelist.
  *
+ * Unreadable config: when any project config file exists but cannot be parsed
+ * (`unreadableConfigFiles`), every mode refuses before rendering — exit 1,
+ * empty stdout, one stderr line naming each file and its parse error.
+ *
  * --active-cap <capId>: when present, resolves hooks for <point> exactly as the
  * normal path does, then prints exactly `true` (if any resolved activeHook has
  * capId === <capId>) or `false` followed by a single newline, and exits 0.
@@ -403,6 +481,13 @@ function renderLoopHooks(resolved) {
  * Missing <capId> value → coreError + non-zero exit.
  * Unknown/inactive capId → `false` (not an error).
  *
+ * --into <role>: resolves exactly as the normal path does, then prints the
+ * `fragment.inline` text of each active contribution whose `into` equals
+ * <role>, in resolved order, separated by one blank line, with a trailing
+ * newline when anything printed. Nothing at all (empty stdout, exit 0) when no
+ * contribution matches. No JSON envelope; `--raw` is ignored. `--active-cap`
+ * takes precedence: given both, `--into` is ignored.
+ *
  * --phase <N> [--tier light|standard|heavy] (pack 9): resolve the phase's
  * ceremony tier (src/phase-tier.cts) and overlay its gate booleans
  * (`workflow.research`, `workflow.pattern_mapper`, …) on the config snapshot
@@ -422,37 +507,15 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
         coreError('--active-cap requires a <capId> value (e.g. --active-cap tdd)');
         return;
     }
-    // Fail closed on a config that exists but cannot be read. Every hook's `when`
-    // and activation key is read from it, and both readers below swallow a parse
-    // failure into the defaults, so rendering anyway drops exactly the hooks the
-    // project switched on — a required client vault's fetch and blocking gate
-    // among them — and exits 0. A MISSING config is not refused: that is a fresh
-    // project, and the defaults are its real settings. stdout stays empty so a
-    // host capturing `$(…)` never reads a refusal as "no hooks".
-    const unreadable = unreadableConfigFiles(cwd);
-    if (unreadable.length > 0) {
-        coreError(`loop render-hooks ${point} refused: the project config cannot be read, so no hook can be resolved ` +
-            `(rendering anyway would silently drop every hook the config switches on, a required client vault among them). ` +
-            `${describeUnreadableConfig(unreadable)}. Repair or remove the file, then re-run. Stop this workflow here.`, ERROR_REASON.CONFIG_PARSE_FAILED);
+    // --into <role> mode: emit matching contribution fragment text only
+    const intoRole = typeof options['into'] === 'string' ? options['into'] : undefined;
+    if (activeCapId === undefined && intoRole !== undefined && intoRole.trim() === '') {
+        coreError('Missing value for --into (e.g. --into executor)', ERROR_REASON.USAGE);
         return;
     }
     const runtimeConfigDir = typeof options['configDir'] === 'string'
         ? options['configDir']
         : undefined;
-    // Load the config snapshot ONCE and share it with both the capability-state
-    // resolver (via configOverride) and loop-hook resolution, so federated keys
-    // present in loadConfig resolve identically for `active` and for hook when/
-    // configValues — eliminating the previous double loadConfig() call. Note: keys
-    // absent from loadConfig still fall through to raw .planning/config.json reads
-    // (precedence levels 2-3) in each pass; that residual re-read window is
-    // pre-existing (unchanged by this consolidation), not introduced here.
-    let config;
-    try {
-        config = loadConfig(cwd);
-    }
-    catch {
-        config = {};
-    }
     const tierPhase = typeof options['phase'] === 'string' && options['phase'] !== '' ? options['phase'] : null;
     const tierCli = typeof options['tier'] === 'string' && options['tier'] !== '' ? options['tier'] : null;
     let phaseTier = null;
@@ -461,32 +524,29 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
             coreError('--tier needs one of light, standard, heavy');
             return;
         }
-        phaseTier = (0, phase_tier_cjs_1.resolvePhaseTierForProject)(cwd, tierPhase, tierCli);
-        config = (0, phase_tier_cjs_1.overlayTierGates)(config, phaseTier);
+        // The refusal below must come first: never resolve a tier from a config it cannot read.
+        if (unreadableConfigFiles(cwd).length === 0)
+            phaseTier = (0, phase_tier_cjs_1.resolvePhaseTierForProject)(cwd, tierPhase, tierCli);
     }
-    const state = resolveCapabilityRuntimeState(cwd, runtimeConfigDir, config);
-    // Registry is the static generated module — same object capability-state uses internally.
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const registry = require('./capability-registry.cjs');
-    const capabilityStatesById = new Map();
-    for (const cap of state.capabilities || []) {
-        capabilityStatesById.set(cap.id, cap);
-    }
-    let resolved;
-    try {
-        resolved = resolveLoopHooks({ point, registry, config, cwd, capabilityStatesById });
-    }
-    catch (err) {
-        const msg = (err instanceof Error) ? err.message : String(err);
-        coreError(msg);
+    const outcome = resolveProjectLoopHooks(cwd, point, { configDir: runtimeConfigDir, phaseTier });
+    if (!outcome.ok) {
+        coreError(outcome.message, outcome.reason === 'config_unreadable' ? ERROR_REASON.CONFIG_PARSE_FAILED : undefined);
         return;
     }
+    const resolved = outcome.resolved;
     // --active-cap mode: print exactly 'true' or 'false' with no envelope
     if (activeCapId !== undefined) {
         const isActive = resolved.activeHooks.some((h) => h.capId === activeCapId);
         process.stdout.write(isActive ? 'true\n' : 'false\n');
         return;
     }
+    // --into mode: fragment text of the active contributions targeting <role>
+    if (intoRole !== undefined) {
+        const texts = contributionsInto(resolved, intoRole).map((c) => c.fragment);
+        if (texts.length > 0)
+            process.stdout.write(texts.join('\n\n') + '\n');
+        return;
+    }
     const rendered = renderLoopHooks(resolved);
     const envelope = {
         point: resolved.point,
@@ -496,8 +556,8 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
     if (phaseTier) {
         envelope.phase_tier = { phase: tierPhase, tier: phaseTier.tier, source: phaseTier.source, suppressed: phaseTier.suppressed };
     }
-    if (state.warnings && state.warnings.length > 0) {
-        envelope.warnings = state.warnings;
+    if (outcome.warnings.length > 0) {
+        envelope.warnings = outcome.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
@@ -511,6 +571,8 @@ module.exports = {
     resolveLoopHooks,
     renderLoopHooks,
     cmdLoopRenderHooks,
+    resolveProjectLoopHooks,
+    contributionsInto,
     // Exported for tests
     _getNestedConfigValue,
     _resolveActivationValue,

package/pp-core/bin/lib/org-profile.cjs

@@ -48,10 +48,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HOST_FORBIDDEN_CHARS = exports.PROFILE_REJECTED_CLONE_TARGET_PATTERNS = exports.ORG_PROFILE_SEED_KEYS = exports.ORG_PROFILE_SEED_SECTION = exports.ORG_PROFILE_ALLOWLIST = exports.ORG_PROFILE_DATA_FILE = exports.ORG_PROFILE_CONFIG_KEY = void 0;
+exports.HOST_FORBIDDEN_CHARS = exports.PROFILE_REJECTED_CLONE_TARGET_PATTERNS = exports.ORG_PROFILE_SEED_KEYS = exports.ORG_PROFILE_SEED_SECTION = exports.ORG_PROFILE_ALLOWLIST = exports.TRACE_ACCEPTED_PREDICATE_MAX = exports.TRACE_ACCEPTED_PREDICATES_CAP = exports.VAULT_TRACE_ACCEPTED_PREDICATES_KEY = exports.VAULT_REQUIRED_CONFIG_KEY = exports.ORG_PROFILE_DATA_FILE = exports.ORG_PROFILE_CONFIG_KEY = void 0;
+exports.resolveGlobalPackageRootCandidates = resolveGlobalPackageRootCandidates;
+exports.globalRootCandidatesFor = globalRootCandidatesFor;
 exports.resolveOrgProfileDocument = resolveOrgProfileDocument;
 exports.resolveOrgProfile = resolveOrgProfile;
 exports.readProfileValue = readProfileValue;
+exports.resolveVaultRequired = resolveVaultRequired;
+exports.resolveAcceptedTracePredicates = resolveAcceptedTracePredicates;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 // ─── Constants ───────────────────────────────────────────────────────────────
@@ -62,10 +66,41 @@ exports.ORG_PROFILE_CONFIG_KEY = 'org.profile';
 /** The fixed filename read from the resolved package's own directory — never the
  * package's `main`/`exports` entry, and never loaded via `require` (D-08). */
 exports.ORG_PROFILE_DATA_FILE = 'org-profile.json';
+/** The dotted key naming the vault load policy, declared boolean (default
+ * false) by `capabilities/vault/capability.json`. Named once here so neither
+ * the allowlist, the value guard nor `resolveVaultRequired` restates it. */
+exports.VAULT_REQUIRED_CONFIG_KEY = 'vault.required';
 /**
- * D-06's fixed allowlist: a profile may contribute exactly these five dotted
+ * The dotted key naming the practice-trace predicate types a READER accepts
+ * besides pp-core's own (`TRACE_PREDICATE_TYPE` in src/vault-trace.cts). It
+ * exists so a project that switches engine mid-engagement can keep reading
+ * the traces its earlier engine wrote: the org profile of that engagement
+ * lists the earlier engine's predicate URI here. Writers never use it — pp-core
+ * always writes its own URI — and pp-core itself names no such URI.
+ */
+exports.VAULT_TRACE_ACCEPTED_PREDICATES_KEY = 'vault.trace.accepted_predicates';
+/** At most this many accepted predicate URIs, each at most this long. */
+exports.TRACE_ACCEPTED_PREDICATES_CAP = 8;
+exports.TRACE_ACCEPTED_PREDICATE_MAX = 200;
+/**
+ * D-06's fixed allowlist: a profile may contribute exactly these seven dotted
  * config keys. Entry order is not contractual; membership is. Anything else
  * present in a profile document is dropped with a bounded warning.
+ *
+ * FIVE COORDINATES AND ONE POLICY. The first five answer where to fetch from.
+ * `vault.required` answers whether the vault load is mandatory, so one
+ * org-profile package can turn the load gate on across a fleet without a
+ * per-repository edit. That is this list's sharpest widening: an `npm update`
+ * of the profile package can move a build gate without a review in the
+ * consuming repository. It is bounded three ways: project config outranks the
+ * profile, so any project can opt out explicitly; the profile can only raise
+ * the gate from the built-in default `false` (a gate turning on fails
+ * closed); and the value guard accepts only the two boolean literals.
+ * `vault.enabled` (arming the capability) stays off the list.
+ *
+ * `vault.trace.accepted_predicates` is READ-ONLY widening: it lets the trace
+ * readers accept another engine's predicate URI (a list of https URIs). It
+ * changes no writer and no gate polarity.
  */
 exports.ORG_PROFILE_ALLOWLIST = Object.freeze([
     'vault.provider',
@@ -73,6 +108,8 @@ exports.ORG_PROFILE_ALLOWLIST = Object.freeze([
     'vault.fallback_ref',
     'vault.fallback_host',
     'platform.host',
+    exports.VAULT_REQUIRED_CONFIG_KEY,
+    exports.VAULT_TRACE_ACCEPTED_PREDICATES_KEY,
 ]);
 /**
  * The single top-level key naming the Phase 34 init-only seed section.
@@ -220,62 +257,108 @@ function describeUnknown(value) {
         return Object.prototype.toString.call(value);
     }
 }
-// ─── resolveGlobalPackageRoot ────────────────────────────────────────────────
+// ─── Global package roots ────────────────────────────────────────────────────
 /**
- * D-03's "global" half of the two-path resolution ladder, as a pure
- * heuristic with NO subprocess spawn (this repo avoids spawning a
- * subprocess for a computation that does not strictly require one):
+ * D-03's "global" half of the two-path resolution ladder, as a pure heuristic
+ * with NO subprocess spawn. Returns an ORDERED list of existing candidate
+ * roots (a single root silently missed Homebrew layouts):
  *
  * 1. `NPM_CONFIG_PREFIX` / `npm_config_prefix`, when set to a non-blank
  *    string: `<prefix>/node_modules` on `win32`, `<prefix>/lib/node_modules`
  *    otherwise.
- * 2. Otherwise, derived from `process.execPath`: with
- *    `execDir = path.dirname(process.execPath)`, `path.join(execDir,
- *    'node_modules')` on `win32`, `path.resolve(execDir, '..', 'lib',
- *    'node_modules')` otherwise.
+ * 2. Every PATH directory containing a `node` entry, mapped through the same
+ *    `<bin>` → `<global tree>` rule — WITHOUT resolving symlinks. This is what
+ *    finds Homebrew: `process.execPath` resolves `/opt/homebrew/bin/node` into
+ *    the Cellar, whose `lib/node_modules` exists but holds only npm, while the
+ *    real global tree lives at `/opt/homebrew/lib/node_modules` beside the
+ *    PATH symlink.
+ * 3. Derived from `process.execPath` — still correct for nvm/Volta layouts.
  *
- * The candidate is returned only when `fs.existsSync(candidate)`;
- * otherwise `null`.
+ * Candidates are deduped and filtered to `fs.existsSync`; resolution tries
+ * each in order (first hit wins), so an existing-but-empty earlier root cannot
+ * mask a later root that holds the package.
  *
- * Accepted residual: an nvm/Volta-style layout that honours neither
- * `NPM_CONFIG_PREFIX` nor places the global tree beside the node binary
- * will simply not resolve a globally-installed profile — this degrades
- * per D-09 (falls through to the no-profile behaviour with a warning)
- * rather than failing.
+ * Detection (the `/pp-init` org-profile hint and its invariant check) passes
+ * `explicitPrefixOnly: true`: with `NPM_CONFIG_PREFIX` set, only the prefix
+ * root is scanned, because a hint must never come from a tree the operator did
+ * not point at. Detection roots are therefore a subset of resolution roots.
  *
- * pp-core's own install directory is deliberately NOT a candidate here:
- * the AI-runtime install is a bare directory copy with no `package.json`
- * and no `node_modules` of its own, so resolving relative to it would
- * never find a sibling package.
+ * pp-core's own install directory is deliberately NOT a candidate: the
+ * runtime install is a bare directory copy with no `node_modules` of its own.
  */
-function resolveGlobalPackageRoot() {
+const GLOBAL_ROOT_PATH_SCAN_CAP = 64;
+/** npm's own `<bin dir>` → `<global node_modules>` mapping. */
+function globalRootFromBinDir(binDir) {
+    return process.platform === 'win32' ? node_path_1.default.join(binDir, 'node_modules') : node_path_1.default.resolve(binDir, '..', 'lib', 'node_modules');
+}
+function resolveGlobalPackageRootCandidates(opts = {}) {
+    const candidates = [];
+    const push = (c) => {
+        if (!candidates.includes(c))
+            candidates.push(c);
+    };
+    const existing = () => candidates.filter((c) => {
+        try {
+            return node_fs_1.default.existsSync(c);
+        }
+        catch {
+            return false;
+        }
+    });
     try {
         const prefixEnv = process.env.NPM_CONFIG_PREFIX ?? process.env.npm_config_prefix;
-        let candidate;
         if (typeof prefixEnv === 'string' && prefixEnv.trim() !== '') {
             const prefix = prefixEnv.trim();
-            candidate =
-                process.platform === 'win32' ? node_path_1.default.join(prefix, 'node_modules') : node_path_1.default.join(prefix, 'lib', 'node_modules');
+            push(process.platform === 'win32' ? node_path_1.default.join(prefix, 'node_modules') : node_path_1.default.join(prefix, 'lib', 'node_modules'));
+            // An explicit prefix is authoritative for detection; one that points
+            // nowhere yields [] — never a fall-through to PATH.
+            if (opts.explicitPrefixOnly === true)
+                return existing();
         }
-        else {
-            const execDir = node_path_1.default.dirname(process.execPath);
-            candidate =
-                process.platform === 'win32'
-                    ? node_path_1.default.join(execDir, 'node_modules')
-                    : node_path_1.default.resolve(execDir, '..', 'lib', 'node_modules');
+        const pathDirs = (process.env.PATH ?? '')
+            .split(node_path_1.default.delimiter)
+            .filter((d) => d.trim() !== '')
+            .slice(0, GLOBAL_ROOT_PATH_SCAN_CAP);
+        const nodeNames = process.platform === 'win32' ? ['node.exe', 'node.cmd', 'node'] : ['node'];
+        for (const dir of pathDirs) {
+            for (const name of nodeNames) {
+                let found = false;
+                try {
+                    found = node_fs_1.default.existsSync(node_path_1.default.join(dir, name));
+                }
+                catch {
+                    // unreadable PATH entry — skip it
+                }
+                if (found) {
+                    push(globalRootFromBinDir(dir));
+                    break;
+                }
+            }
         }
-        return node_fs_1.default.existsSync(candidate) ? candidate : null;
+        push(globalRootFromBinDir(node_path_1.default.dirname(process.execPath)));
     }
     catch {
-        return null;
+        // degrade to whatever was collected before the fault
     }
+    return existing();
+}
+/**
+ * Map the `_globalRoot` test seam (a single root, or `null` for "no global
+ * root found") onto the candidate-list shape; when the seam is absent, run the
+ * production heuristic. The seam wins over `explicitPrefixOnly`.
+ */
+function globalRootCandidatesFor(opts) {
+    if (opts && opts._globalRoot !== undefined) {
+        return opts._globalRoot === null ? [] : [opts._globalRoot];
+    }
+    return resolveGlobalPackageRootCandidates({ explicitPrefixOnly: opts?.explicitPrefixOnly === true });
 }
 // ─── resolveProfilePackage ───────────────────────────────────────────────────
 /**
  * D-03's two-path resolution ladder. Attempt `require.resolve(pkgName +
  * '/package.json', { paths: [cwd] })` first and report `source: 'project'`;
- * on failure attempt the same with `paths: [globalRoot]` when a global root
- * was found and report `source: 'global'`; otherwise `null`. The
+ * on failure attempt the same with `paths: [root]` for each global candidate
+ * root in order and report `source: 'global'`; otherwise `null`. The
  * project-local hit always wins when both would resolve — the global
  * attempt is only ever reached when the project attempt threw.
  *
@@ -283,19 +366,19 @@ function resolveGlobalPackageRoot() {
  * 220-228): the same try/catch-returns-null shape, one level removed
  * (resolving a data file's sibling `package.json`, not a CLI entry point).
  */
-function resolveProfilePackage(pkgName, cwd, globalRoot) {
+function resolveProfilePackage(pkgName, cwd, globalRoots) {
     try {
         return { pkgJsonPath: require.resolve(`${pkgName}/package.json`, { paths: [cwd] }), source: 'project' };
     }
     catch {
-        // fall through to the global attempt below
+        // fall through to the global attempts below
     }
-    if (globalRoot) {
+    for (const globalRoot of globalRoots) {
         try {
             return { pkgJsonPath: require.resolve(`${pkgName}/package.json`, { paths: [globalRoot] }), source: 'global' };
         }
         catch {
-            // fall through to null below
+            // try the next candidate root
         }
     }
     return null;
@@ -388,6 +471,45 @@ function flattenProfileDocument(doc) {
  */
 function profileValueDisposition(key, value) {
     try {
+        // The one boolean-typed member, disposed of before the string-only scalar
+        // guard below would reject its natural JSON form. Carried as the canonical
+        // string "true" / "false".
+        if (key === exports.VAULT_REQUIRED_CONFIG_KEY) {
+            if (value === true || value === false)
+                return { ok: true, value: String(value) };
+            if (typeof value === 'string') {
+                const t = value.trim();
+                if (t === 'true' || t === 'false')
+                    return { ok: true, value: t };
+            }
+            return { ok: false, reason: 'value must be the boolean true or false' };
+        }
+        // The one list-typed member. Carried forward as a canonical JSON array
+        // string, so `contributes` stays a string map.
+        if (key === exports.VAULT_TRACE_ACCEPTED_PREDICATES_KEY) {
+            const list = Array.isArray(value) ? value : null;
+            if (list === null || list.length === 0) {
+                return { ok: false, reason: 'value must be a non-empty list of https URIs' };
+            }
+            if (list.length > exports.TRACE_ACCEPTED_PREDICATES_CAP) {
+                return { ok: false, reason: `value lists more than ${exports.TRACE_ACCEPTED_PREDICATES_CAP} URIs` };
+            }
+            const kept = [];
+            for (const item of list) {
+                if (typeof item !== 'string')
+                    return { ok: false, reason: 'every entry must be a string' };
+                const t = item.trim();
+                if (t.length > exports.TRACE_ACCEPTED_PREDICATE_MAX) {
+                    return { ok: false, reason: `an entry is longer than ${exports.TRACE_ACCEPTED_PREDICATE_MAX} characters` };
+                }
+                if (!/^https:\/\/[^\s\x00-\x1f\x7f"'<>`\\]+$/.test(t)) {
+                    return { ok: false, reason: 'every entry must be an https URI with no whitespace or quotes' };
+                }
+                if (!kept.includes(t))
+                    kept.push(t);
+            }
+            return { ok: true, value: JSON.stringify(kept) };
+        }
         if (typeof value !== 'string') {
             return { ok: false, reason: 'value must be a string' };
         }
@@ -458,7 +580,7 @@ function profileValueDisposition(key, value) {
  * The `_globalRoot` option is the repo's `_`-prefixed test seam convention
  * (as used by `_vault` / `_exec` / `_writeBack` in
  * `src/vault-command-router.cts`); production callers omit it and the
- * module calls `resolveGlobalPackageRoot()`. Passing `_globalRoot`
+ * module walks `resolveGlobalPackageRootCandidates()`. Passing `_globalRoot`
  * explicitly (including `null`, to simulate "no global root found")
  * overrides the production heuristic for that one call.
  *
@@ -498,16 +620,19 @@ function resolveOrgProfileDocument(cwd, opts) {
         if (pkgName === '') {
             return absentDocShape();
         }
-        // Step 2: resolve the package (project, then global).
-        const globalRoot = opts && opts._globalRoot !== undefined ? opts._globalRoot : resolveGlobalPackageRoot();
-        const hit = resolveProfilePackage(pkgName, cwd, globalRoot);
+        // Step 2: resolve the package (project, then every global candidate).
+        const globalRoots = globalRootCandidatesFor(opts);
+        const hit = resolveProfilePackage(pkgName, cwd, globalRoots);
         if (!hit) {
             const echoed = sanitizeForWarning(pkgName);
+            const probed = globalRoots.length > 0
+                ? `the global npm root(s) ${globalRoots.map((r) => sanitizeForWarning(r)).join(', ')}`
+                : 'no locatable global npm root';
             return {
                 ...absentDocShape(),
                 configured: pkgName,
                 warnings: [
-                    bound(`org profile "${echoed}" was not found — resolution was attempted from the project and the global npm root and found nothing. Falling back to built-in defaults.`),
+                    bound(`org profile "${echoed}" was not found — resolution was attempted from the project and ${probed} and found nothing. Falling back to built-in defaults.`),
                 ],
             };
         }
@@ -694,3 +819,52 @@ function readProfileValue(cwd, key, opts) {
         source: resolution.source,
     };
 }
+/**
+ * The ONE ladder for `vault.required`, which `computeVaultVerdict` (the
+ * verdict owner) and `vault org-profile` both read:
+ *
+ * 1. The project's `.planning/config.json`. A present value wins, whatever
+ *    it is: a JSON boolean is used as is; anything else is treated as false
+ *    and reported as invalid (the gate card names it), never passed on to the
+ *    profile — an explicit project value is the project's decision.
+ * 2. The org profile, already narrowed to "true" / "false" by the value guard.
+ * 3. The registered default, false.
+ *
+ * Never throws.
+ */
+function resolveVaultRequired(cwd, opts) {
+    try {
+        const raw = cfgGet(cwd, exports.VAULT_REQUIRED_CONFIG_KEY, undefined);
+        if (raw !== undefined) {
+            return { required: raw === true, source: 'config', valid: typeof raw === 'boolean', raw, warnings: [] };
+        }
+        const profile = readProfileValue(cwd, exports.VAULT_REQUIRED_CONFIG_KEY, opts);
+        if (profile.value === 'true' || profile.value === 'false') {
+            return { required: profile.value === 'true', source: 'profile', valid: true, raw: undefined, warnings: profile.warnings };
+        }
+        return { required: false, source: 'default', valid: true, raw: undefined, warnings: profile.warnings };
+    }
+    catch {
+        return { required: false, source: 'default', valid: true, raw: undefined, warnings: [] };
+    }
+}
+// ─── resolveAcceptedTracePredicates ──────────────────────────────────────────
+/**
+ * The extra practice-trace predicate types the org profile lists under
+ * `vault.trace.accepted_predicates` — `[]` when there is no profile, the key is
+ * absent, or its value was refused by the value guard. Org profile only: a
+ * project config value is not read (the key is not a project setting). Never
+ * throws.
+ */
+function resolveAcceptedTracePredicates(cwd, opts) {
+    try {
+        const profile = readProfileValue(cwd, exports.VAULT_TRACE_ACCEPTED_PREDICATES_KEY, opts);
+        if (typeof profile.value !== 'string')
+            return [];
+        const parsed = JSON.parse(profile.value);
+        return Array.isArray(parsed) ? parsed.filter((v) => typeof v === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -6,7 +6,7 @@
  * Unsupported in this router:
  * - scaffold: routed through top-level scaffold command.
  *
- * CJS-only subcommands: mvp-mode, dispatch-plan, install-run, tier, tier-propose (dispatched directly, before hub).
+ * CJS-only subcommands: mvp-mode, dispatch-plan, install-run, tier, tier-propose, manifest (dispatched directly, before hub).
  *
  * #3788: dispatch is mediated by CommandRoutingHub. The public entry point
  * and observable CLI behaviour are unchanged.
@@ -73,6 +73,12 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
         phase.cmdPhaseTierPropose(cwd, args.slice(2), raw);
         return;
     }
+    // `manifest start|record` (pack 10): write `.phase-manifest.json`, which
+    // `/pp-undo --phase` reads (src/phase-manifest.cts).
+    if (subcommand === 'manifest') {
+        phase.cmdPhaseManifest(cwd, args.slice(2), raw);
+        return;
+    }
     // ── Build the CJS registry ──────────────────────────────────────────────────
     // Each handler receives a ctx object from the hub and must return a HubResult.
     const cjsRegistry = {