@pareto4/pp-core 1.12.0 → 1.13.0

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

@@ -44,6 +44,7 @@ exports.CLUSTERS = Object.freeze({
         'eval-review',
         'add-tests',
         'secure-phase',
+        'vault-review',
     ]),
     milestone: Object.freeze([
         'new-milestone',

package/pp-core/bin/lib/command-aliases.cjs

@@ -712,6 +712,13 @@ exports.NON_FAMILY_COMMAND_ALIASES = [
         ],
         "mutation": true
     },
+    {
+        "canonical": "phase.manifest",
+        "aliases": [
+            "phase manifest"
+        ],
+        "mutation": true
+    },
     {
         "canonical": "phase.mvp-mode",
         "aliases": [

package/pp-core/bin/lib/compose-bindings.cjs

@@ -47,6 +47,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.COMPOSE_BINDINGS_FLAGS = exports.SEED_VALUE_MAX_LENGTH = void 0;
 exports._resetPlatformTagMemoForTests = _resetPlatformTagMemoForTests;
+exports.listStableTagsAt = listStableTagsAt;
+exports.pickLatestStableTag = pickLatestStableTag;
 exports.resolveCreatedWithFrom = resolveCreatedWithFrom;
 exports.composeBindings = composeBindings;
 exports.redactComposeResultForEmission = redactComposeResultForEmission;
@@ -398,33 +400,7 @@ function resolveLatestPlatformTag(cwd, repo, provider, opts) {
         return cached;
     let result;
     try {
-        const lsOutput = typeof opts._lsRemote === 'function'
-            ? opts._lsRemote(url)
-            : node_child_process_1.default.execFileSync('git', ['ls-remote', '--tags', '--refs', '--sort=-v:refname', url, 'v*'], {
-                encoding: 'utf-8',
-                timeout: 10_000,
-                maxBuffer: 512 * 1024,
-                windowsHide: true,
-                stdio: ['ignore', 'pipe', 'pipe'],
-            });
-        const tags = lsOutput
-            .split('\n')
-            .map((line) => {
-            const m = line.match(/\brefs\/tags\/([^\s^]+)$/);
-            return m ? m[1].trim() : '';
-        })
-            .filter((t) => t && (0, semver_compare_cjs_1.isStableTripletSemver)(t));
-        if (tags.length === 0) {
-            result = { tag: null, warnings: [] };
-        }
-        else {
-            let latest = tags[0];
-            for (const t of tags) {
-                if ((0, semver_compare_cjs_1.compareSemverCore)(t, latest) > 0)
-                    latest = t;
-            }
-            result = { tag: latest, warnings: [] };
-        }
+        result = { tag: pickLatestStableTag(listStableTagsAt(url, opts)), warnings: [] };
     }
     catch {
         result = {
@@ -437,6 +413,44 @@ function resolveLatestPlatformTag(cwd, repo, provider, opts) {
     platformTagMemo.set(url, result);
     return result;
 }
+/**
+ * List the stable `vX.Y.Z` tags at `url`, never shell-eval'd (T-34-25):
+ * `git ls-remote` is spawned with an argv array, bounded by
+ * `timeout`/`maxBuffer`/`windowsHide` (T-34-26), with the child's stderr piped
+ * and discarded. `--` ends the options, so a flag-shaped target can never be
+ * read as one. Filtered with `isStableTripletSemver`, the single blessed
+ * predicate. THROWS on any git fault — callers own the degrade policy. Shared
+ * by the platform-tag lookup and `vault update`.
+ */
+function listStableTagsAt(url, opts = {}) {
+    const lsOutput = typeof opts._lsRemote === 'function'
+        ? opts._lsRemote(url)
+        : node_child_process_1.default.execFileSync('git', ['ls-remote', '--tags', '--refs', '--sort=-v:refname', '--', url, 'v*'], {
+            encoding: 'utf-8',
+            timeout: 10_000,
+            maxBuffer: 512 * 1024,
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    return lsOutput
+        .split('\n')
+        .map((line) => {
+        const m = line.match(/\brefs\/tags\/([^\s^]+)$/);
+        return m ? m[1].trim() : '';
+    })
+        .filter((t) => t && (0, semver_compare_cjs_1.isStableTripletSemver)(t));
+}
+/** The highest tag by `compareSemverCore`, or `null` for an empty list. */
+function pickLatestStableTag(tags) {
+    if (tags.length === 0)
+        return null;
+    let latest = tags[0];
+    for (const t of tags) {
+        if ((0, semver_compare_cjs_1.compareSemverCore)(t, latest) > 0)
+            latest = t;
+    }
+    return latest;
+}
 /**
  * Read the first readable, semver-shaped `VERSION` file among the candidate
  * locations resolved against `baseDir`, returning `<binName>@<version>`.

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

@@ -43,6 +43,9 @@ const model_catalog_cjs_1 = require("./model-catalog.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const federatedConfigModule = require("./federated-config.cjs");
 const { mergeFederatedConfig } = federatedConfigModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const capabilityActivationModule = require("./capability-activation.cjs");
+const { activationConfigFilesFor } = capabilityActivationModule;
 // The capability-registry.cjs is generated and lives in the same gsd-core/bin/lib/ output dir.
 // Both config-loader.cjs and capability-registry.cjs land in gsd-core/bin/lib/ at build time.
 // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
@@ -341,16 +344,154 @@ function _applyFederatedOverlay(baseConfig, userConfig) {
     _applyFederatedValues(cloned, _fedOverlay.values, _fedOverlay.validKeys);
     return cloned;
 }
-function loadConfig(cwd, options = {}) {
+/**
+ * The workstream `loadConfig` reads for `options`: an explicit `workstream`
+ * option, then `workstreamContext.ws`, then `GSD_WORKSTREAM`. Shared with
+ * `configFilesFor` so the two can never resolve different workstreams.
+ */
+function _activeWorkstreamFor(options) {
     const activeWorkstream = Object.prototype.hasOwnProperty.call(options, 'workstream')
         ? options['workstream']
         : (options['workstreamContext'] && Object.prototype.hasOwnProperty.call(options['workstreamContext'], 'ws'))
             ? options['workstreamContext']['ws']
             : (process.env['GSD_WORKSTREAM'] || null);
+    return typeof activeWorkstream === 'string' ? activeWorkstream : null;
+}
+function _configPathsFor(cwd, ws) {
+    return {
+        rootConfigPath: ws ? node_path_1.default.join(planningRoot(cwd), 'config.json') : null,
+        configPath: node_path_1.default.join(planningDir(cwd, ws), 'config.json'),
+    };
+}
+/** `~/.gsd/defaults.json` (or under `GSD_HOME`): read only in a pre-project context (#1683). */
+function _globalDefaultsPath() {
+    return node_path_1.default.join(process.env['GSD_HOME'] || node_os_1.default.homedir(), '.gsd', 'defaults.json');
+}
+/** The #1683 predicate: the global defaults are consulted only when the active planning dir is absent. */
+function _readsGlobalDefaults(cwd, ws) {
+    return !node_fs_1.default.existsSync(planningDir(cwd, ws));
+}
+/**
+ * Every config file `loadConfig(cwd, options)` reads, as absolute paths in read
+ * order. ONE owner of "which config files does the loader read": `loadConfig`
+ * takes its paths from the same `_configPathsFor`, so a reader that must refuse
+ * an unreadable config (`unreadableConfigFiles` below) parses exactly these
+ * files without restating the workstream ladder.
+ *
+ * Why a caller needs it: `loadConfig` swallows a parse failure in every one of
+ * these files (root → "workstream config stands alone", active → the defaults),
+ * so its RESULT cannot say whether it read the project's config or read
+ * nothing. Files that do not exist are still listed; absence is not a failure
+ * for `loadConfig`, and the caller decides what it means.
+ */
+function configFilesFor(cwd, options = {}) {
+    const ws = _activeWorkstreamFor(options);
+    const { rootConfigPath, configPath } = _configPathsFor(cwd, ws);
+    const files = [];
+    if (rootConfigPath)
+        files.push(rootConfigPath);
+    files.push(configPath);
+    if (_readsGlobalDefaults(cwd, ws))
+        files.push(_globalDefaultsPath());
+    return files;
+}
+/** The error text is bounded; composed text never reaches the cap, but it holds anyway. */
+const UNREADABLE_ERROR_CAP = 200;
+/**
+ * Describe why a config file could not be used WITHOUT echoing it. V8's
+ * `JSON.parse` messages sometimes quote the input (`Unexpected token '}',
+ * "{"a":tru}" is not valid JSON`), so only the position is carried over.
+ */
+function _describeConfigReadFailure(err) {
+    const e = err;
+    if (e && typeof e.code === 'string' && /^[A-Z][A-Z0-9_]*$/.test(e.code))
+        return `cannot be read (${e.code})`;
+    const message = e && typeof e.message === 'string' ? e.message : '';
+    const lineCol = /\(line (\d+) column (\d+)\)/.exec(message);
+    if (lineCol)
+        return `not valid JSON (line ${lineCol[1]}, column ${lineCol[2]})`;
+    const position = /at position (\d+)/.exec(message);
+    if (position)
+        return `not valid JSON (at position ${position[1]})`;
+    if (/Unexpected end of JSON input/.test(message))
+        return 'not valid JSON (the text ends before the JSON does)';
+    return 'not valid JSON';
+}
+/** How a refusal names a config file: never an absolute user path. */
+function _configDisplayPath(cwd, abs) {
+    const under = (base) => {
+        const rel = node_path_1.default.relative(base, abs);
+        return rel !== '' && !rel.startsWith('..') && !node_path_1.default.isAbsolute(rel) ? rel.split(node_path_1.default.sep).join('/') : null;
+    };
+    const inProject = under(cwd);
+    if (inProject !== null)
+        return inProject;
+    const homeOverride = process.env['GSD_HOME'];
+    const inHomeOverride = homeOverride ? under(homeOverride) : null;
+    if (inHomeOverride !== null)
+        return `$GSD_HOME/${inHomeOverride}`;
+    const inHome = under(node_os_1.default.homedir());
+    if (inHome !== null)
+        return `~/${inHome}`;
+    return node_path_1.default.basename(abs);
+}
+/**
+ * Every config file the hook resolver would read that EXISTS but cannot be
+ * used: unreadable, not JSON, or JSON that is not an object (`loadConfig`
+ * reads none of an array's or a null's keys and answers the defaults, the same
+ * silent fallback as a parse failure). Empty when every file is usable or
+ * absent: a MISSING config is a fresh project and reads as the defaults.
+ *
+ * The files are the union, in first-seen order, of the loader's list
+ * (`configFilesFor`) and the activation resolver's raw levels
+ * (`activationConfigFilesFor`, which can name a root config the loader never
+ * opens under `GSD_PROJECT`). Reads go through `platformReadSync`, the reader
+ * `loadConfig` uses, so a file the loader can read is never called unreadable.
+ *
+ * This is the ONE owner of "can the project's config be read". Both swallowing
+ * readers (`loadConfig`, `resolveConfigKey`) stay tolerant for their many
+ * callers; a caller whose answer governs a gate (`loop render-hooks`, the vault
+ * load verdict) asks this first and refuses. Never throws.
+ */
+function unreadableConfigFiles(cwd, options = {}) {
+    const out = [];
+    let files;
+    try {
+        files = [...new Set([...configFilesFor(cwd, options), ...activationConfigFilesFor(cwd)])];
+    }
+    catch (err) {
+        // An invalid GSD_WORKSTREAM / GSD_PROJECT segment: the config cannot be located, so it cannot be read.
+        return [{ file: '.planning/config.json', error: `cannot be located (${err instanceof Error ? err.message : String(err)})`.slice(0, UNREADABLE_ERROR_CAP) }];
+    }
+    for (const file of files) {
+        let error = null;
+        try {
+            const raw = (0, shell_command_projection_cjs_1.platformReadSync)(file);
+            if (raw === null)
+                continue;
+            const parsed = JSON.parse(raw);
+            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                error = 'valid JSON but not an object, so none of its settings can be read';
+            }
+        }
+        catch (err) {
+            error = _describeConfigReadFailure(err);
+        }
+        if (error !== null)
+            out.push({ file: _configDisplayPath(cwd, file), error: error.slice(0, UNREADABLE_ERROR_CAP) });
+    }
+    return out;
+}
+/** One line per unreadable file, `<file>: <error>`, for a refusal message. */
+function describeUnreadableConfig(unreadable) {
+    return unreadable.map((u) => `${u.file}: ${u.error}`).join('; ');
+}
+function loadConfig(cwd, options = {}) {
     // When GSD_WORKSTREAM is set, load root config first so workstream config
     // can inherit from it. This prevents users from duplicating model_overrides,
     // workflow.*, etc. across every workstream config (#2714).
-    const ws = typeof activeWorkstream === 'string' ? activeWorkstream : (activeWorkstream === null ? null : null);
+    const ws = _activeWorkstreamFor(options);
+    const paths = _configPathsFor(cwd, ws);
     // #315 — per-call lazy memo: all three detection sites inside this loadConfig
     // call operate on the same cwd and the subrepo set cannot change mid-call, so
     // a single scan is sufficient. The memo is scoped to THIS call (not module-level)
@@ -364,8 +505,8 @@ function loadConfig(cwd, options = {}) {
         return cachedSubRepos.slice();
     };
     let rootParsed = null;
-    if (ws) {
-        const rootConfigPath = node_path_1.default.join(planningRoot(cwd), 'config.json');
+    if (paths.rootConfigPath) {
+        const rootConfigPath = paths.rootConfigPath;
         try {
             const raw = (0, shell_command_projection_cjs_1.platformReadSync)(rootConfigPath);
             if (raw === null)
@@ -400,7 +541,7 @@ function loadConfig(cwd, options = {}) {
             // Root config missing or unparseable — workstream config stands alone
         }
     }
-    const configPath = node_path_1.default.join(planningDir(cwd, ws), 'config.json');
+    const configPath = paths.configPath;
     const defaults = CONFIG_DEFAULTS;
     try {
         const raw = (0, shell_command_projection_cjs_1.platformReadSync)(configPath);
@@ -625,7 +766,7 @@ function loadConfig(cwd, options = {}) {
     }
     catch {
         // Fall back to ~/.gsd/defaults.json only for truly pre-project contexts (#1683)
-        if (node_fs_1.default.existsSync(planningDir(cwd, ws))) {
+        if (!_readsGlobalDefaults(cwd, ws)) {
             if (rootParsed) {
                 // Workstream has no config.json: re-parse using root config as the sole source.
                 // (FIX 2: overlay is applied recursively in the re-entrant loadConfig call)
@@ -642,8 +783,7 @@ function loadConfig(cwd, options = {}) {
             }
         }
         try {
-            const home = process.env['GSD_HOME'] || node_os_1.default.homedir();
-            const globalDefaultsPath = node_path_1.default.join(home, '.gsd', 'defaults.json');
+            const globalDefaultsPath = _globalDefaultsPath();
             const raw = (0, shell_command_projection_cjs_1.platformReadSync)(globalDefaultsPath);
             if (raw === null)
                 throw new Error('missing');
@@ -698,6 +838,9 @@ function loadConfig(cwd, options = {}) {
 }
 module.exports = {
     loadConfig,
+    configFilesFor,
+    unreadableConfigFiles,
+    describeUnreadableConfig,
     isGitIgnored,
     CONFIG_DEFAULTS,
     _getConfigDefault,

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

@@ -10,6 +10,7 @@
  * CJS callers that only use {id, text} safely ignore the extra fields.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDecisionsReport = parseDecisionsReport;
 exports.parseDecisions = parseDecisions;
 const DISCRETION_HEADINGS = new Set([
     "claude's discretion",
@@ -17,6 +18,67 @@ const DISCRETION_HEADINGS = new Set([
     'claude discretion',
 ]);
 const NON_TRACKABLE_TAGS = new Set(['informational', 'folded', 'deferred']);
+// ── The decision-bullet grammar ────────────────────────────────────────────────────────────────────────────
+//
+// Why a grammar rather than one regex: this repository writes THREE bullet
+// forms, and originally only the first was readable. The two others were
+// not exotic — they are what `discuss-phase` emits and what hand-authored
+// CONTEXT.md files use — so a parser that reads only form A hands a blocking
+// coverage gate an empty decision set and lets it report a clean pass. That is
+// the defect this grammar retires (todo: decision-coverage-gate-false-pass).
+//
+//   Form A  `- **D-NN:** text`                  → arm A
+//   Form B  `- **D-NN: Title.** text`           → arm B (title may wrap: arm D)
+//   Form C  `- **D-NN** text`                   → arm C
+//
+// HEAD matches the bullet opener and splits off `rest` (everything after the id
+// and its optional `[tags]` group). The id rule is #3575's, unchanged: the first
+// character after `D-` must be alphanumeric, so `D--x` and `D-_x` still fail
+// HEAD and reach the parse-miss guard.
+const BULLET_HEAD_RE = /^\s*-\s+\*\*D-([A-Za-z0-9][A-Za-z0-9_-]*)(?:\s*\[([^\]]+)\])?(.*)$/;
+// Arm A — form A, widened. The run before the FIRST `:**` may now contain `:`.
+// #1343 wrote that run as `[^:*]*`, which is what dropped every bold-title
+// bullet AND `- **D-07 ratio 3:1:** w` (that miss used to be pinned as a floor;
+// it now parses as D-07 / "w"). Lazy `[^*]*?` still stops at the first `:**`.
+const ARM_A_RE = /^([^*]*?):\*\*\s*(.*)$/;
+// Arm B — form B, the bold title. The title MAY contain `:` because real
+// titles carry backticked loop points (`plan:post`, `execute:post`, `check:`);
+// a title regex that excluded `:` measured four misses across two phases.
+const ARM_B_RE = /^([^*]*?):\s*([^*]*?)\s*\*\*\s*(.*)$/;
+// Arm C — the bold closes with no colon before it (`- **D-VH-1** body`, and
+// `- **D-13 → see D-14.** *(reserved)*`). The only thing this form lacks is
+// punctuation; the id is unambiguous, so it is admitted.
+const ARM_C_RE = /^([^*]*?)\s*\*\*\s*(.*)$/;
+// Arm D — no closing `**` on this line: a form-B title that wraps onto the
+// next line. The existing continuation logic appends the following indented
+// lines, stray `**` included (they are cosmetic in the resulting text).
+const ARM_D_RE = /^([^*]*)$/;
+/**
+ * Read a decision bullet's text out of `rest` (the remainder of the bullet line
+ * after the id and optional `[tags]`), trying arms A → B → C → D; first match
+ * wins. Returns null when no arm matches, which sends the line to the
+ * parse-miss guard.
+ *
+ * The guard is NOT vacuous after this widening: a malformed id fails HEAD, and
+ * a `rest` carrying a `*` in no arm shape (`- **D-01 *italic* no close`)
+ * matches no arm.
+ */
+function readBulletText(rest) {
+    const a = rest.match(ARM_A_RE);
+    if (a)
+        return a[2];
+    const b = rest.match(ARM_B_RE);
+    // Headline first, so a six-word `softPhrase` is drawn from the title.
+    if (b)
+        return (b[2] + ' ' + b[3]).trim();
+    const c = rest.match(ARM_C_RE);
+    if (c)
+        return (c[1] + ' ' + c[2]).trim();
+    const d = rest.match(ARM_D_RE);
+    if (d)
+        return d[1].replace(/^\s*:?\s*/, '').trim();
+    return null;
+}
 /**
  * Strip fenced code blocks from `content` so example `<decisions>` snippets
  * inside ```` ``` ```` do not pollute the parser (review F11).
@@ -40,34 +102,28 @@ function extractDecisionsBlock(content) {
     return matches.map((m) => m[1]).join('\n\n');
 }
 /**
- * Parse trackable decisions from CONTEXT.md content.
+ * Parse CONTEXT.md content into BOTH channels: the decisions that were read,
+ * and the bullets that could not be.
  *
- * Returns ALL D-NN decisions found inside `<decisions>` (including
- * non-trackable ones, with `trackable: false`). Callers that only want the
- * gate-enforced decisions should filter `.filter(d => d.trackable)`.
+ * `decisions` holds ALL D-NN decisions found inside `<decisions>` (including
+ * non-trackable ones, with `trackable: false`). `unparsed` holds every line
+ * that opened like a decision bullet and matched no arm of the grammar.
+ *
+ * The second channel exists because "the block was empty" and "the parser
+ * could not read any of it" are opposite situations that a coverage gate used
+ * to report identically — as a clean pass on a total of zero.
  */
-function parseDecisions(content) {
+function parseDecisionsReport(content) {
     if (!content || typeof content !== 'string')
-        return [];
+        return { decisions: [], unparsed: [] };
     const block = extractDecisionsBlock(content);
     if (block === null)
-        return [];
+        return { decisions: [], unparsed: [] };
     const lines = block.split(/\r?\n/);
     const out = [];
+    const unparsed = [];
     let category = '';
     let inDiscretion = false;
-    // Bullet line: `- **D-NN[ [tags]]:** text`
-    // Phase 6 (#3575): aligned to CJS regex — accepts alphanumeric IDs (D-01, D-INFRA-01, D-FOO_BAR)
-    // in addition to numeric-only IDs (D-42). The first character after `D-` must
-    // be alphanumeric, so malformed shapes like `D--foo` or `D-_bar` are rejected.
-    // CJS callers consume {id, text} and ignore the optional extras.
-    // #1343: `[^:*]*` replaces the old `\s*` before `:**` so that a freeform run
-    // such as `(parenthetical)`, an em-dash, or other prose between the optional
-    // bracket-tag group and the closing `:**` is tolerated rather than silently
-    // dropping the whole decision. `[^:*]*` subsumes plain whitespace and stops
-    // correctly at `:**`. Capture groups 1 (id), 2 (bracket tags), 3 (text) are
-    // unchanged.
-    const bulletRe = /^\s*-\s+\*\*D-([A-Za-z0-9][A-Za-z0-9_-]*)(?:\s*\[([^\]]+)\])?[^:*]*:\*\*\s*(.*)$/;
     let current = null;
     const flush = () => {
         if (current) {
@@ -94,29 +150,36 @@ function parseDecisions(content) {
             inDiscretion = DISCRETION_HEADINGS.has(normalized);
             continue;
         }
-        const bulletMatch = line.match(bulletRe);
-        if (bulletMatch) {
+        const headMatch = line.match(BULLET_HEAD_RE);
+        const bulletText = headMatch ? readBulletText(headMatch[3]) : null;
+        if (headMatch && bulletText !== null) {
             flush();
-            const id = `D-${bulletMatch[1]}`;
-            const tags = bulletMatch[2]
-                ? bulletMatch[2]
+            const id = `D-${headMatch[1]}`;
+            const tags = headMatch[2]
+                ? headMatch[2]
                     .split(',')
                     .map((t) => t.trim().toLowerCase())
                     .filter(Boolean)
                 : [];
             const trackable = !inDiscretion && !tags.some((t) => NON_TRACKABLE_TAGS.has(t));
-            current = { id, text: bulletMatch[3], category, tags, trackable };
+            current = { id, text: bulletText, category, tags, trackable };
             continue;
         }
         // Parse-miss guard (#1343): a line that looks like a `D-NN` decision bullet
-        // but failed `bulletRe` (e.g. a `:` or `*` inside the pre-colon run) must NOT
+        // but failed HEAD (malformed id) or matched no arm of the grammar must NOT
         // be silently dropped — a narrowed trackable set lets a blocking coverage gate
         // report a false pass. Surface it loudly instead.
+        //
+        // The miss is now recorded as DATA as well, so a gate can fail
+        // on it rather than warning past it. The `console.warn` stays: the stderr
+        // signal is what a human running the command by hand sees, and it is pinned
+        // by the #1343 regression tests.
         if (/^\s*-\s+\*\*D-/.test(line)) {
             // A malformed D-bullet still starts a (failed) new decision, so it ends the
             // previous one — flush before warning so a following continuation line cannot
             // be mis-appended to the prior valid decision.
             flush();
+            unparsed.push({ line: trimmed, category });
             console.warn(`parseDecisions: ignored unparseable decision bullet: ${trimmed}`);
             continue;
         }
@@ -132,5 +195,19 @@ function parseDecisions(content) {
         }
     }
     flush();
-    return out;
+    return { decisions: out, unparsed };
+}
+/**
+ * Parse trackable decisions from CONTEXT.md content.
+ *
+ * Returns ALL D-NN decisions found inside `<decisions>` (including
+ * non-trackable ones, with `trackable: false`). Callers that only want the
+ * gate-enforced decisions should filter `.filter(d => d.trackable)`.
+ *
+ * This signature is unchanged, and so is its behaviour. A caller that must not
+ * treat an unreadable bullet as an ABSENT decision — any gate that reports a
+ * verdict — should call `parseDecisionsReport` and read `unparsed`.
+ */
+function parseDecisions(content) {
+    return parseDecisionsReport(content).decisions;
 }

package/pp-core/bin/lib/dispatch-plan.cjs

@@ -34,7 +34,8 @@
  * here): researcher, pattern mapper,
  * planner (always) and plan checker passes; then code reviewer and fixer,
  * the heavy-tier install run (`phase.install-run`, src/install-run.cts),
- * verifier, security auditor and nyquist auditor. `totals.spawns` counts every agent spawn of every stage, as an upper
+ * verifier, security auditor, nyquist auditor and — heavy tier, vault
+ * practices on — the agent practice review. `totals.spawns` counts every agent spawn of every stage, as an upper
  * bound: entries marked `conditional` run only when the step before them asks
  * for it (a revision after a failed check, a fix after review findings).
  */
@@ -69,6 +70,7 @@ exports.STAGE_AGENTS = Object.freeze({
     codeFixer: 'pp-code-fixer',
     nyquistAuditor: 'pp-nyquist-auditor',
     securityAuditor: 'pp-security-auditor',
+    vaultReviewer: 'pp-vault-reviewer',
 });
 function spawn(id, agent, gate, reason, conditional = false) {
     return { id, kind: 'spawn', agent, gate, reason, conditional };
@@ -79,6 +81,9 @@ function step(id, gate, reason) {
 /**
  * The planning and verification stages of a phase, from its resolved tier.
  * `planBounceScript`: bounce runs only with a configured script.
+ * `vaultReview`: the project's vault practices apply (`vaultReviewApplies`,
+ * src/vault.cts — the caller reads it); the agent practice review is spawned
+ * only when that AND the tier's `vault_review` gate are both on.
  */
 function computeTierStages(tier, opts = {}) {
     const g = tier.gates;
@@ -117,6 +122,9 @@ function computeTierStages(tier, opts = {}) {
         verify.push(spawn('verify-security', exports.STAGE_AGENTS.securityAuditor, 'security_enforcement', 'threat-model verification (SECURITY.md)'));
     if (g.nyquist_validation)
         verify.push(spawn('verify-nyquist', exports.STAGE_AGENTS.nyquistAuditor, 'nyquist_validation', 'validation-gap audit (VALIDATION.md)'));
+    if (g.vault_review && opts.vaultReview === true) {
+        verify.push(spawn('verify-vault-review', exports.STAGE_AGENTS.vaultReviewer, 'vault_review', 'agent practice review of the client vault (VAULT-REVIEW.md); reports, never gates'));
+    }
     return { plan, verify };
 }
 function normalizePath(file) {
@@ -255,6 +263,7 @@ function waveDefects(spawns, byId) {
  * order; `phaseDir` is the phase directory relative to the project root.
  */
 function computeDispatchPlan(phase, phaseDir, plans, policy, tier = null, tierOpts = {}) {
+    const contributions = (tierOpts.executorContributions ?? []).map((c) => ({ capId: c.capId, fragment: c.fragment }));
     const byId = new Map(plans.map((p) => [p.id, p]));
     const skippedComplete = plans.filter((p) => p.has_summary).map((p) => p.id);
     const incomplete = plans.filter((p) => !p.has_summary && (!policy.gapsOnly || p.gap_closure === true));
@@ -294,6 +303,7 @@ function computeDispatchPlan(phase, phaseDir, plans, policy, tier = null, tierOp
                     build_reason: buildReason(members),
                     checkpoint: members.some((q) => !q.autonomous),
                     expected_summaries: entries.map((e) => e.summary),
+                    contributions: contributions.map((c) => ({ ...c })),
                 });
                 continue;
             }
@@ -311,6 +321,7 @@ function computeDispatchPlan(phase, phaseDir, plans, policy, tier = null, tierOp
                 build_reason: buildReason([p]),
                 checkpoint: !p.autonomous,
                 expected_summaries: [entry.summary],
+                contributions: contributions.map((c) => ({ ...c })),
             });
         }
         const defects = waveDefects(spawns, byId);

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

@@ -216,6 +216,24 @@ function reconstructFrontmatter(obj) {
     }
     return lines.join('\n');
 }
+/**
+ * The raw lines of a top-level `key:` block inside a `---` frontmatter match —
+ * the `key:` line plus every following line that is blank or indented, up to
+ * the next column-0 key — with trailing blank lines dropped, or `null` when the
+ * frontmatter has no such top-level block.
+ */
+function rawTopLevelBlock(frontmatterMatch, key) {
+    const lines = frontmatterMatch.split(/\r?\n/).slice(1, -1);
+    const start = lines.findIndex((l) => l === `${key}:` || new RegExp(`^${key}:\\s*$`).test(l));
+    if (start === -1)
+        return null;
+    let end = start + 1;
+    while (end < lines.length && (lines[end].trim() === '' || /^\s/.test(lines[end])))
+        end += 1;
+    while (end > start + 1 && lines[end - 1].trim() === '')
+        end -= 1;
+    return lines.slice(start, end).join('\n');
+}
 function spliceFrontmatter(content, newObj) {
     const match = content.match(/^---\r?\n[\s\S]+?\r?\n---/);
     if (match) {
@@ -238,6 +256,25 @@ function spliceFrontmatter(content, newObj) {
         catch {
             /* fall through to regeneration on any comparison hiccup */
         }
+        // The practice-trace ledger (`vault:`, docs/vault-trace-format.md) is a list
+        // of maps the lossy serializer cannot re-emit. When the caller left it
+        // untouched — `frontmatter set <plan> wave 2`, the plan-graph write-back —
+        // its raw lines are carried over verbatim instead of being regenerated.
+        const ledger = rawTopLevelBlock(match[0], 'vault');
+        if (ledger !== null) {
+            try {
+                const original = extractFrontmatter(content);
+                if (frontmatterDeepEqual(original.vault, newObj.vault)) {
+                    const rest = { ...newObj };
+                    delete rest.vault;
+                    const restStr = reconstructFrontmatter(rest);
+                    return `---\n${restStr}${restStr === '' ? '' : '\n'}${ledger}\n---` + content.slice(match[0].length);
+                }
+            }
+            catch {
+                /* fall through to regeneration */
+            }
+        }
         const yamlStr = reconstructFrontmatter(newObj);
         return `---\n${yamlStr}\n---` + content.slice(match[0].length);
     }