@pareto4/pp-core 1.12.0 → 1.12.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pp-core",
   "displayName": "PP Core",
-  "version": "1.12.0",
+  "version": "1.12.1",
   "description": "PP Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "author": {
     "name": "pareto4",

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "pp-core",
-  "version": "1.12.0",
+  "version": "1.12.1",
   "description": "PP Core — a meta-prompting, context engineering, and spec-driven development system for AI coding agents. Loads pp-core's operating context into every Gemini CLI session.",
   "contextFileName": "GEMINI.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pareto4/pp-core",
-  "version": "1.12.0",
+  "version": "1.12.1",
   "description": "Pareto pp-core — The Pareto Project's AI-assisted engineering framework: meta-prompting, context engineering, and spec-driven development for AI coding agents.",
   "bin": {
     "pp-core": "bin/install.js",

package/pp-core/bin/lib/capability-activation.cjs

@@ -55,6 +55,20 @@ function _readRawConfigKey(filePath, dotKey) {
         return { found: false, value: undefined };
     }
 }
+/**
+ * The raw config files levels 2 and 3 read, in read order: the active
+ * `planningDir(cwd)/config.json`, then the root `planningRoot(cwd)/config.json`
+ * when it is a different file. Exported so `unreadableConfigFiles`
+ * (src/config-loader.cts) parses every file the hook resolver reads — this list
+ * beside `configFilesFor`, the loader's — without restating either. Both levels
+ * skip an unparseable file with a stderr warning and read on, which is the
+ * swallow a gate-governing caller must refuse.
+ */
+function activationConfigFilesFor(cwd) {
+    const wsConfigPath = node_path_1.default.join(planningDir(cwd), 'config.json');
+    const rootConfigPath = node_path_1.default.join(planningRoot(cwd), 'config.json');
+    return wsConfigPath !== rootConfigPath ? [wsConfigPath, rootConfigPath] : [wsConfigPath];
+}
 /**
  * Resolve the raw value for a dotted config key using the four-level precedence
  * walk. Returns { found, value } with the RAW value (not coerced to boolean),
@@ -76,15 +90,10 @@ function resolveConfigKey(dotKey, opts) {
         return { found: true, value: fromConfig.value };
     // Level 2 + 3: raw config.json files (only when cwd is available)
     if (cwd) {
-        const wsConfigPath = node_path_1.default.join(planningDir(cwd), 'config.json');
-        const rootConfigPath = node_path_1.default.join(planningRoot(cwd), 'config.json');
-        const fromWs = _readRawConfigKey(wsConfigPath, dotKey);
-        if (fromWs.found)
-            return { found: true, value: fromWs.value };
-        if (wsConfigPath !== rootConfigPath) {
-            const fromRoot = _readRawConfigKey(rootConfigPath, dotKey);
-            if (fromRoot.found)
-                return { found: true, value: fromRoot.value };
+        for (const filePath of activationConfigFilesFor(cwd)) {
+            const fromFile = _readRawConfigKey(filePath, dotKey);
+            if (fromFile.found)
+                return { found: true, value: fromFile.value };
         }
     }
     // Level 4: registry configSchema default
@@ -110,4 +119,5 @@ module.exports = {
     _readRawConfigKey,
     _resolveActivationValue,
     resolveConfigKey,
+    activationConfigFilesFor,
 };

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/loop-resolver.cjs

@@ -30,10 +30,10 @@
  */
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
-const { output: coreOutput, error: coreError } = ioMod;
+const { output: coreOutput, error: coreError, ERROR_REASON } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const configLoaderModule = require("./config-loader.cjs");
-const { loadConfig } = configLoaderModule;
+const { loadConfig, unreadableConfigFiles, describeUnreadableConfig } = configLoaderModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const capabilityStateModule = require("./capability-state.cjs");
 const { resolveCapabilityRuntimeState } = capabilityStateModule;
@@ -422,6 +422,20 @@ 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);
+        return;
+    }
     const runtimeConfigDir = typeof options['configDir'] === 'string'
         ? options['configDir']
         : undefined;

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

@@ -37,6 +37,9 @@ 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");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configLoaderModule = require("./config-loader.cjs");
+const { unreadableConfigFiles } = configLoaderModule;
 const CLONE_TIMEOUT_MS = 60_000; // explicit cap so a hung clone surfaces as failed → next tier
 const REVPARSE_TIMEOUT_MS = 10_000;
 // Default built-in config values — Phase 12 reads-with-default because the
@@ -1020,6 +1023,7 @@ function assertVaultWriteTarget(cwd, targetRepo, targetHost) {
 }
 const VAULT_VERDICTS = Object.freeze(['inert', 'loaded', 'degraded']);
 const VAULT_REASONS = Object.freeze([
+    'config_unreadable',
     'vault_disabled',
     'no_bindings',
     'never_fetched',
@@ -1045,6 +1049,7 @@ const VAULT_VERDICT_FIELDS = Object.freeze([
 ]);
 /** One static card line per reason (D-02). The card test enumerates VAULT_REASONS against this table. */
 const VAULT_REASON_LINES = Object.freeze({
+    config_unreadable: 'The project config cannot be read, so vault.enabled and vault.required are unknown — both are treated as true.',
     vault_disabled: 'The client vault is disabled (vault.enabled is not true).',
     no_bindings: 'No client vault is bound: .platform-bindings.json needs client.vaultRepo and client.vaultRef.',
     never_fetched: 'The vault has not been fetched — .planning/vault/ holds no readable manifest.',
@@ -1055,6 +1060,7 @@ const VAULT_REASON_LINES = Object.freeze({
     client_loaded: 'The client vault is loaded at its pinned ref.',
 });
 const VAULT_REASON_REMEDIES = Object.freeze({
+    config_unreadable: 'Remedy: repair or remove the config file `pp-tools loop render-hooks plan:pre` names, then re-run this step.',
     vault_disabled: '',
     no_bindings: 'Remedy: run /pp-init to bind the client vault at a pinned ref.',
     never_fetched: 'Remedy: run `pp-tools vault fetch`, then re-run this step.',
@@ -1127,6 +1133,32 @@ function isStaleForVerdict(cwd, cached) {
  * `proceed` when loaded, `none` when inert (D-03).
  */
 function computeVaultVerdict(cwd) {
+    // Fail closed before reading a single key: `cfgGet` swallows a parse failure
+    // into "absent", which would read a required vault as switched off (inert).
+    if (unreadableConfigFiles(cwd).length > 0) {
+        let binding = { bound: false, repo: null, ref: null };
+        let cachedView = readCachedView('');
+        try {
+            binding = readClientBinding(cwd);
+            cachedView = readCachedView(cwd);
+        }
+        catch {
+            /* display-only; the verdict below does not depend on them */
+        }
+        return {
+            enabled: true,
+            required: true,
+            requiredValid: true,
+            verdict: 'degraded',
+            reason: 'config_unreadable',
+            action: 'stop',
+            block: true,
+            configuredRepo: redactCloneTarget(binding.repo),
+            configuredRef: binding.ref,
+            cached: cachedView,
+            requiredRaw: null,
+        };
+    }
     const enabled = cfgGet(cwd, 'vault.enabled', undefined) === true;
     const requiredRawValue = cfgGet(cwd, 'vault.required', undefined);
     const requiredValid = requiredRawValue === undefined || typeof requiredRawValue === 'boolean';
@@ -1206,7 +1238,9 @@ function renderVaultCard(v, point) {
         return '';
     const subject = point === 'plan' ? 'Planning' : 'Build';
     const lines = [];
-    lines.push(`Client vault check (${subject}): ${v.verdict === 'loaded' ? 'LOADED' : 'DEGRADED'}${v.required ? ' — vault.required is true' : ''}`);
+    const unreadableConfig = v.reason === 'config_unreadable';
+    const headlineNote = unreadableConfig ? ' — the project config cannot be read' : v.required ? ' — vault.required is true' : '';
+    lines.push(`Client vault check (${subject}): ${v.verdict === 'loaded' ? 'LOADED' : 'DEGRADED'}${headlineNote}`);
     lines.push(`  Configured: ${v.configuredRepo || v.configuredRef ? coordText(v.configuredRepo, v.configuredRef) : 'no client vault bound'}`);
     const c = v.cached;
     if (c.present) {
@@ -1229,6 +1263,9 @@ function renderVaultCard(v, point) {
     else if (v.action === 'confirm') {
         lines.push(`  ${subject} can continue WITHOUT the client's standards — confirm to proceed (vault.required is false).`);
     }
+    else if (v.action === 'stop' && unreadableConfig) {
+        lines.push(`  STOP — ${subject.toLowerCase()} is blocked until the project config can be read.`);
+    }
     else if (v.action === 'stop') {
         lines.push(`  STOP — vault.required is true: ${subject.toLowerCase()} is blocked until the client vault loads.`);
     }

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

@@ -29,6 +29,13 @@ booleans are read.
 `activeHooks` is an array of enabled hook entries for the named point. It is empty (or absent)
 when no capability has registered an active hook at this point — treat that as a no-op.
 
+## Refusal
+
+`render-hooks` refuses — exit 1, empty stdout, one stderr line naming each config file and its
+parse error — when a project config file exists but cannot be read (not JSON, or not a JSON
+object). A missing config is not refused. Every host writes `X=$(pp_run loop render-hooks …) || exit 1`,
+so a refusal stops the workflow: relay the stderr line and stop. Never read a refusal as "no hooks".
+
 ## Dispatch rules by `kind`
 
 ### `contribution`

package/pp-core/workflows/audit-milestone.md

@@ -146,7 +146,7 @@ For each REQ-ID, determine status using all three sources:
 Skip if the Nyquist capability is inactive.
 
 ```bash
-VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw)
+VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw) || exit 1
 ```
 
 Resolve active step hooks from `VERIFY_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "validate-phase"`.

package/pp-core/workflows/autonomous.md

@@ -273,7 +273,7 @@ Resolve active `plan:pre` hooks:
 
 ```bash
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
-HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw --phase "${PHASE_NUM}")
+HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw --phase "${PHASE_NUM}") || exit 1
 ```
 
 Read the `activeHooks` array directly from `HOOKS_JSON` (in-context — do NOT invoke a shell pipeline). **Compute the active UI step hooks** = entries from `activeHooks` where `kind == "step"` and `ref.skill` is set. **If there are NO active step hooks → skip silently to 3b.** (This covers `workflow.ui_phase=false` — including configurations where only a gate-only entry is present, e.g. `ui_phase=false` + `ui_safety_gate=true` produces `activeHooks=[{kind:"gate"}]`. Autonomous never runs the plan:pre gate — it is always pipeline mode — so a gate-only active set is equivalent to no active step and is silently skipped here. This matches OLD §3a.5 behaviour.)
@@ -406,7 +406,7 @@ Auto-invoke code review and fix chain. Autonomous mode chains both review and fi
 
 **Capability dispatch:**
 ```bash
-EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw --phase "${PHASE_NUM}")
+EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw --phase "${PHASE_NUM}") || exit 1
 ```
 
 Resolve active step hooks from `EXECUTE_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "code-review"`.
@@ -481,7 +481,7 @@ Resolve the active post-verification hooks and the UI-SPEC gate:
 
 ```bash
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
-HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw --phase "${PHASE_NUM}")
+HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw --phase "${PHASE_NUM}") || exit 1
 ```
 
 Read the `activeHooks` array directly from the `HOOKS_JSON` value already in context (do not invoke a shell `jq` pipeline — parse as the JSON object it is). **If `activeHooks` is empty or absent:** skip silently to the iterate step.

package/pp-core/workflows/code-review-fix.md

@@ -77,7 +77,7 @@ FIX_REPORT_PATH="${PHASE_DIR}/${PADDED_PHASE}-REVIEW-FIX.md"
 Check if code review is active via the capability registry:
 
 ```bash
-EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw)
+EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw) || exit 1
 ```
 
 Resolve active step hooks from `EXECUTE_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "code-review"`.

package/pp-core/workflows/code-review.md

@@ -78,7 +78,7 @@ fi
 Check if code review is active via the capability registry:
 
 ```bash
-EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw)
+EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw) || exit 1
 ```
 
 Resolve active step hooks from `EXECUTE_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "code-review"`.

package/pp-core/workflows/discuss-phase.md

@@ -299,7 +299,7 @@ Read `@~/.claude/pp-core/references/scout-codebase.md` — it contains the phase
 
 <step name="dispatch_discuss_pre_hooks">
 ```bash
-DISCUSS_PRE_HOOKS_JSON=$(pp_run loop render-hooks discuss:pre --raw)
+DISCUSS_PRE_HOOKS_JSON=$(pp_run loop render-hooks discuss:pre --raw) || exit 1
 ```
 Apply each entry in `activeHooks` per @~/.claude/pp-core/references/loop-hook-dispatch.md. Empty list → continue to `analyze_phase`.
 </step>
@@ -418,7 +418,7 @@ Write the file.
 
 <step name="dispatch_discuss_post_hooks">
 ```bash
-DISCUSS_POST_HOOKS_JSON=$(pp_run loop render-hooks discuss:post --raw)
+DISCUSS_POST_HOOKS_JSON=$(pp_run loop render-hooks discuss:post --raw) || exit 1
 ```
 Apply each entry in `activeHooks` per @~/.claude/pp-core/references/loop-hook-dispatch.md. Empty list → continue to `propose_tier`.
 </step>

package/pp-core/workflows/execute-phase.md

@@ -70,7 +70,7 @@ Parse `$ARGUMENTS` before loading any context:
 - First positional token → `PHASE_ARG`
 - Optional `--wave N` → `WAVE_FILTER`
 - Optional `--gaps-only` → `GAPS_ONLY=true` (only `gap_closure: true` plans)
-- Optional `--tier light|standard|heavy` → `TIER_FLAG="--tier <value>"` (the phase's ceremony tier for this run; passed to init, dispatch plan and render-hooks)
+- Optional `--tier light|standard|heavy` → `TIER_FLAG="--tier=<value>"` (one word, so zsh passes it as one argument; the phase's ceremony tier for this run; passed to init, dispatch plan and render-hooks)
 - Optional `--cross-ai` → `CROSS_AI_FORCE=true` (force all plans through cross-AI execution)
 - Optional `--no-cross-ai` → `CROSS_AI_DISABLED=true` (disable cross-AI for this run, overrides config and frontmatter)
 - Optional `--unattended` → `UNATTENDED=true` — set by `/pp:autonomous`; prompt sites marked `U-En` apply the rules in `pp-core/references/autonomous-best-effort.md` (Read it at the first such site)
@@ -183,8 +183,8 @@ Resolve `MVP_MODE` once via the centralized `phase.mvp-mode` query verb (precede
 MVP_FLAG_ARG=""
 if [[ "$ARGUMENTS" =~ (^|[[:space:]])--mvp([[:space:]]|$) ]]; then MVP_FLAG_ARG="--cli-flag"; fi
 MVP_MODE=$(pp_run query phase.mvp-mode "${PHASE_NUMBER}" $MVP_FLAG_ARG --pick active)
-EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw --phase "${PHASE_NUMBER}" ${TIER_FLAG})
-TDD_MODE=$(pp_run loop render-hooks execute:post --active-cap tdd)
+EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw --phase "${PHASE_NUMBER}" ${TIER_FLAG}) || exit 1
+TDD_MODE=$(pp_run loop render-hooks execute:post --active-cap tdd) || exit 1
 ```
 
 <step name="safe_resume_gate">
@@ -347,7 +347,7 @@ Read and execute `pp-core/workflows/execute-phase/steps/client-context-gate.md`
 </step>
 
 <step name="execute_pre_vault">
-Before any executor: `EXECUTE_PRE_HOOKS_JSON=$(pp_run loop render-hooks execute:pre --raw)`. For an active `capId == "vault"` step, Read and execute `pp-core/workflows/execute-phase/steps/vault-fetch.md`; then, for an active `vault.status` gate, set `VAULT_GATE_POINT=execute` and Read and execute `pp-core/workflows/execute-phase/steps/vault-load-gate.md`. None active → skip.
+Before any executor: `EXECUTE_PRE_HOOKS_JSON=$(pp_run loop render-hooks execute:pre --raw) || exit 1`. For an active `capId == "vault"` step, Read and execute `pp-core/workflows/execute-phase/steps/vault-fetch.md`; then, for an active `vault.status` gate, set `VAULT_GATE_POINT=execute` and Read and execute `pp-core/workflows/execute-phase/steps/vault-load-gate.md`. None active → skip.
 </step>
 
 <step name="discover_and_group_plans">
@@ -851,7 +851,7 @@ increases monotonically across waves. `{status}` is `complete` (success),
    After worktree merge, post-merge tests, and tracking updates, dispatch capability hooks registered at `execute:wave:post`. The primary hook is the `ui.safety-gate` gate from the UI capability — it verifies that any frontend files changed in this wave conform to the UI-SPEC contract.
 
    ```bash
-   WAVE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:wave:post --raw)
+   WAVE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:wave:post --raw) || exit 1
    ```
 
    Read the `activeHooks` array from `WAVE_POST_HOOKS_JSON` in-context (do NOT pipe through a shell parser).
@@ -1016,7 +1016,7 @@ After all waves:
 
 **Security gate check:**
 ```bash
-VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw --phase "${PHASE_NUMBER}" ${TIER_FLAG})
+VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw --phase "${PHASE_NUMBER}" ${TIER_FLAG}) || exit 1
 SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
 ```
 
@@ -1074,7 +1074,7 @@ Selected wave finished successfully. This phase still has incomplete plans, so p
 
 **Capability gate:**
 ```bash
-EXECUTE_POST_HOOKS_JSON=${EXECUTE_POST_HOOKS_JSON:-$(pp_run loop render-hooks execute:post --raw --phase "${PHASE_NUMBER}" ${TIER_FLAG})}
+EXECUTE_POST_HOOKS_JSON=${EXECUTE_POST_HOOKS_JSON:-$(pp_run loop render-hooks execute:post --raw --phase "${PHASE_NUMBER}" ${TIER_FLAG})} || exit 1
 ```
 
 Resolve active step hooks from `EXECUTE_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "code-review"`.

package/pp-core/workflows/plan-phase.md

@@ -72,7 +72,7 @@ Load all context in one call (paths only to minimize orchestrator context):
 ```bash
 _PP_SHIM_NAME="pp-tools.cjs"; _pp_root() { ( for _v in $(env | sed -n 's/^\(GIT_[A-Za-z0-9_]*\)=.*/\1/p'); do unset "$_v"; done; _c=$(git rev-parse --git-common-dir 2>/dev/null); if [ "${_c##*/}" = .git ] && cd "$_c/.." 2>/dev/null; then pwd -P; else git rev-parse --show-toplevel 2>/dev/null || pwd; fi ); }; pp_run() { case "$PP_TOOLS" in *.cjs) node "$PP_TOOLS" "$@";; *) "$PP_TOOLS" "$@";; esac; }; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(_pp_root)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then :; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
 GRAN_PARAM=""; if [[ "$ARGUMENTS" =~ (^|[[:space:]])--granularity[[:space:]]+([^[:space:]-][^[:space:]]*) ]]; then GRAN_PARAM="--granularity ${BASH_REMATCH[2]}"; fi
-TIER_FLAG=""; if [[ "$ARGUMENTS" =~ (^|[[:space:]])--tier[[:space:]=]+(light|standard|heavy) ]]; then TIER_FLAG="--tier ${BASH_REMATCH[2]}"; fi
+TIER_FLAG=$(printf '%s\n' "$ARGUMENTS" | grep -oE -- '--tier[[:space:]=]+(light|standard|heavy)' | head -1 | sed -E 's/^--tier[[:space:]=]+/--tier=/')
 INIT=$(pp_run query init.plan-phase "$PHASE" $GRAN_PARAM $TIER_FLAG)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_RESEARCHER=$(pp_run query agent-skills pp-phase-researcher)
@@ -432,7 +432,7 @@ If `AI_SPEC_FILE` is non-empty, pass `AI_SPEC_PATH` and `FRAMEWORK_LINE` to the
 
 ### 5.00. plan:pre vault load — ALWAYS, before the skip rule below
 
-Every path runs this before any agent: `PLAN_PRE_HOOKS_JSON=${PLAN_PRE_HOOKS_JSON:-$(pp_run loop render-hooks plan:pre --raw --phase "$PHASE" $TIER_FLAG)}`. Then Read and execute `pp-core/workflows/execute-phase/steps/vault-fetch.md` (active only for a `capId == "vault"` step hook; writes `.planning/vault/SUMMARY.md`; `onError:skip`). Then, if an active plan:pre gate has `check.query == "vault.status"`, set `VAULT_GATE_POINT=plan` and Read and execute `pp-core/workflows/execute-phase/steps/vault-load-gate.md` — it relays the CLI's vault card and acts on its `action` only (`stop` halts planning in every mode; `confirm` asks, or logs under --auto/--chain). Skip silently when neither hook is active.
+Every path runs this before any agent: `PLAN_PRE_HOOKS_JSON=${PLAN_PRE_HOOKS_JSON:-$(pp_run loop render-hooks plan:pre --raw --phase "$PHASE" $TIER_FLAG)} || exit 1`. Then Read and execute `pp-core/workflows/execute-phase/steps/vault-fetch.md` (active only for a `capId == "vault"` step hook; writes `.planning/vault/SUMMARY.md`; `onError:skip`). Then, if an active plan:pre gate has `check.query == "vault.status"`, set `VAULT_GATE_POINT=plan` and Read and execute `pp-core/workflows/execute-phase/steps/vault-load-gate.md` — it relays the CLI's vault card and acts on its `action` only (`stop` halts planning in every mode; `confirm` asks, or logs under --auto/--chain). Skip silently when neither hook is active.
 
 **Skip if:** `--gaps` flag or `--skip-research` flag or `--reviews` flag.
 
@@ -501,7 +501,7 @@ fi
 ```bash
 PHASE_DESC=$(pp_run query roadmap.get-phase "${PHASE}" --pick section)
 if [ -z "${PLAN_PRE_HOOKS_JSON:-}" ]; then
-  PLAN_PRE_HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw --phase "$PHASE" $TIER_FLAG)
+  PLAN_PRE_HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw --phase "$PHASE" $TIER_FLAG) || exit 1
 fi
 ```
 
@@ -584,7 +584,7 @@ test -f "${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md" && echo "VALIDATION_CREATED
 > Capability-driven dispatch. Resolves active `plan:pre` hooks via the capability registry; the security hook's `when` condition is evaluated by the registry.
 
 ```bash
-PLAN_PRE_HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw --phase "$PHASE" $TIER_FLAG)
+PLAN_PRE_HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw --phase "$PHASE" $TIER_FLAG) || exit 1
 ```
 
 Resolve active contribution hooks from `PLAN_PRE_HOOKS_JSON` where `kind == "contribution"` and `capId == "security"`.
@@ -614,7 +614,7 @@ Continue to step 5.6. Security config is passed to the planner in step 8.
 > **Config semantics (cutover fix):** `workflow.ui_phase` gates UI-SPEC *generation* (step); `workflow.ui_safety_gate` gates the *planning block* (gate). Both-on = identical to OLD §5.6. Intended change: `{ui_phase:true, ui_safety_gate:false}` now auto-generates in pipelines but does NOT block manual planning (each key controls exactly what its description says).
 
 ```bash
-PLAN_PRE_HOOKS_JSON=${PLAN_PRE_HOOKS_JSON:-$(pp_run loop render-hooks plan:pre --raw --phase "$PHASE" $TIER_FLAG)}
+PLAN_PRE_HOOKS_JSON=${PLAN_PRE_HOOKS_JSON:-$(pp_run loop render-hooks plan:pre --raw --phase "$PHASE" $TIER_FLAG)} || exit 1
 HOOKS_JSON="$PLAN_PRE_HOOKS_JSON"
 ```
 
@@ -1475,7 +1475,7 @@ Proactive, non-blocking coverage report gated on `workflow.post_planning_gaps`
 `<decisions>` and cross-references each REQ-ID / D-ID against `${PHASE_DIR}/*-PLAN.md`.
 
 ```bash
-PLAN_POST_HOOKS_JSON=$(pp_run loop render-hooks plan:post --raw --phase "$PHASE" $TIER_FLAG)
+PLAN_POST_HOOKS_JSON=$(pp_run loop render-hooks plan:post --raw --phase "$PHASE" $TIER_FLAG) || exit 1
 PHASE_REQ_IDS=$(pp_run query init.plan-phase "$PHASE" --pick phase_req_ids 2>/dev/null || echo TBD)
 ```
 

package/pp-core/workflows/quick.md

@@ -808,7 +808,7 @@ Skip this step entirely if `$FULL_MODE` is false.
 
 **Capability gate:**
 ```bash
-EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw)
+EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw) || exit 1
 ```
 
 Resolve active step hooks from `EXECUTE_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "code-review"`.

package/pp-core/workflows/secure-phase.md

@@ -26,7 +26,7 @@ Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
 
 ```bash
 AUDITOR_MODEL=$(pp_run query resolve-model pp-security-auditor --raw)
-VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw)
+VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw) || exit 1
 ```
 
 Resolve active step hooks from `VERIFY_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "secure-phase"`.

package/pp-core/workflows/ship.md

@@ -90,7 +90,7 @@ Verify the work is ready to ship:
    Resolve active `ship:pre` gate hooks from the capability registry — the registry evaluates each hook's `when` condition, so do **not** read `workflow.security_enforcement` directly:
 
    ```bash
-   SHIP_PRE_HOOKS_JSON=$(pp_run loop render-hooks ship:pre --raw --phase "${phase_number}")
+   SHIP_PRE_HOOKS_JSON=$(pp_run loop render-hooks ship:pre --raw --phase "${phase_number}") || exit 1
    SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
    ```
 
@@ -448,7 +448,7 @@ pp_run query commit "docs(${padded_phase}): ship phase ${PHASE_NUMBER} — PR #$
 > Capability-driven dispatch. Resolves active `ship:post` hooks via the capability registry; each hook's `when` is evaluated by the registry — no inline `config-get`. All `ship:post` hooks are post-ship and additive (`onError: skip`); a failure here never affects the already-created PR.
 
 ```bash
-SHIP_POST_HOOKS_JSON=$(pp_run loop render-hooks ship:post --raw)
+SHIP_POST_HOOKS_JSON=$(pp_run loop render-hooks ship:post --raw) || exit 1
 ```
 
 Read the `activeHooks` array directly from `SHIP_POST_HOOKS_JSON` in-context (do NOT pipe it through a shell parser).

package/pp-core/workflows/validate-phase.md

@@ -30,7 +30,7 @@ Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
 
 ```bash
 AUDITOR_MODEL=$(pp_run query resolve-model pp-nyquist-auditor --raw)
-VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw)
+VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw) || exit 1
 ```
 
 Resolve active step hooks from `VERIFY_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "validate-phase"`.

package/pp-core/workflows/verify-work.md

@@ -41,7 +41,7 @@ _PP_SHIM_NAME="pp-tools.cjs"; _pp_root() { ( for _v in $(env | sed -n 's/^\(GIT_
 GSD_WS=""
 echo "$ARGUMENTS" | grep -qE -- '--ws[[:space:]]+[^[:space:]]+' && GSD_WS=$(echo "$ARGUMENTS" | grep -oE -- '--ws[[:space:]]+[^[:space:]]+')
 PHASE_ARG=$(echo "$ARGUMENTS" | sed -E 's/--ws[[:space:]]+[^[:space:]]+//g' | xargs)
-TIER_FLAG=$(echo "$ARGUMENTS" | grep -oE -- '--tier[[:space:]]+(light|standard|heavy)' | head -1)
+TIER_FLAG=$(printf '%s\n' "$ARGUMENTS" | grep -oE -- '--tier[[:space:]=]+(light|standard|heavy)' | head -1 | sed -E 's/^--tier[[:space:]=]+/--tier=/')
 PHASE_ARG=$(echo "$PHASE_ARG" | sed -E 's/--tier[[:space:]]+[a-z]+//g' | xargs)
 
 INIT=$(pp_run query init.verify-work "${PHASE_ARG}" ${GSD_WS} ${TIER_FLAG})
@@ -113,7 +113,7 @@ Continue to `create_uat_file`.
 Before UAT, check UI capability activation and whether Playwright/Puppeteer MCP tools are available.
 
 ```bash
-PLAN_HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw --phase "${phase_number}" ${TIER_FLAG})
+PLAN_HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw --phase "${phase_number}" ${TIER_FLAG}) || exit 1
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 ```
 
@@ -460,7 +460,7 @@ Present summary:
 **If issues == 0:**
 
 ```bash
-VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw --phase "${phase_number}" ${GSD_WS} ${TIER_FLAG})
+VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw --phase "${phase_number}" ${GSD_WS} ${TIER_FLAG}) || exit 1
 SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
 ```