@pareto4/pp-core 1.11.1 → 1.12.1

package/pp-core/workflows/execute-phase/steps/post-merge-gate.md

@@ -1,52 +1,45 @@
 # Step: post_merge_gate
 
-Post-merge build & test gate. Runs after all worktrees in a wave are merged
-(parallel mode), or after the last plan completes (serial mode). Catches
-cross-plan integration failures that individual worktree self-checks cannot
-detect.
+Post-merge build & test gate. Runs exactly once per wave, after the wave's merge
+step — the wave's one full-suite run (`suite_runs: 1` in the dispatch plan); no
+executor runs the full suite. Catches cross-plan integration failures that
+per-plan checks cannot detect.
 
-**Step A — Build gate:**
+**Step A — Build gate:** run it only when the dispatch plan's wave `build` is true.
+When it is false (no plan in the wave touches source), print
+`⚠ Post-merge build gate skipped — no plan in this wave touches source` and go to Step B.
 
 ```bash
-_PP_SHIM_NAME="pp-tools.cjs"; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; pp_run() { "$PP_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$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
-# Resolve build command: project config > Xcode > Makefile > language sniff
-BUILD_CMD=$(pp_run query config-get workflow.build_command --default "" 2>/dev/null || true)
+_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
+# Resolve build command: project config first, else the shared sniff ladder
+PP_GATE_BIN=$(printf '%s\n' "${PP_TOOLS:+${PP_TOOLS%/*}:}$PATH" | tr : '\n' | while IFS= read -r d; do if [ -r "$d/detect-build-commands.sh" ]; then printf %s "$d"; break; fi; done)
+BUILD_CMD=$(pp_run query config-get workflow.build_command --default "" --raw 2>/dev/null || true)
 if [ -z "$BUILD_CMD" ]; then
-  XCODEPROJ=$(find . -maxdepth 2 -name "*.xcodeproj" -not -path "*/node_modules/*" 2>/dev/null | head -1)
-  if [ -n "$XCODEPROJ" ]; then
-    # Xcode project: get first scheme from xcodebuild -list -json
-    XCODE_SCHEME=$(xcodebuild -list -json -project "$XCODEPROJ" 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('project',{}).get('schemes',[None])[0] or '')" 2>/dev/null || true)
-    if [ -n "$XCODE_SCHEME" ]; then
-      BUILD_CMD="xcodebuild build -scheme '$XCODE_SCHEME' -destination 'platform=iOS Simulator,name=iPhone 16'"
-    else
-      BUILD_CMD="xcodebuild build -destination 'platform=iOS Simulator,name=iPhone 16'"
-    fi
-  elif [ -f "Makefile" ] && grep -q "^build:" Makefile; then
-    BUILD_CMD="make build"
-  elif [ -f "Justfile" ] || [ -f "justfile" ]; then
-    BUILD_CMD="just build"
-  elif [ -f "Cargo.toml" ]; then
-    BUILD_CMD="cargo build"
-  elif [ -f "go.mod" ]; then
-    BUILD_CMD="go build ./..."
-  elif [ -f "pyproject.toml" ] || [ -f "requirements.txt" ]; then
-    BUILD_CMD="python -m py_compile $(find . -name '*.py' -not -path './.planning/*' -not -path './node_modules/*' | head -20 | tr '\n' ' ')"
-  elif [ -f "package.json" ] && grep -q '"build"' package.json; then
-    BUILD_CMD="npm run build"
+  if [ -r "$PP_GATE_BIN/detect-build-commands.sh" ]; then
+    . "$PP_GATE_BIN/detect-build-commands.sh"; BUILD_CMD=$(pp_detect_build_cmd)
   else
-    BUILD_CMD=""
-    echo "⚠ No build command detected — skipping build gate"
+    echo "✗ pp-core sniff ladder not found beside pp-tools — cannot detect a build command"
   fi
 fi
-# Run build with 5-minute timeout
+# Run build through the shared portable timeout wrapper (5-minute budget)
 BUILD_EXIT=0
-if [ -n "$BUILD_CMD" ]; then
-  timeout 300 bash -c "$BUILD_CMD" 2>&1
+if [ -z "$BUILD_CMD" ]; then
+  echo "⚠ Post-merge build gate NOT RUN — no build command detected (not a pass, not a failure)"
+elif [ ! -r "$PP_GATE_BIN/portable-timeout.sh" ]; then
+  echo "✗ Post-merge build gate NEVER RAN — portable-timeout.sh not found beside pp-tools; refusing to run unbounded (D-09-03)"
+  BUILD_EXIT=127
+  WAVE_FAILURE_COUNT=$((WAVE_FAILURE_COUNT + 1))
+else
+  . "$PP_GATE_BIN/portable-timeout.sh"
+  run_with_timeout 300 bash -c "$BUILD_CMD" 2>&1
   BUILD_EXIT=$?
   if [ "${BUILD_EXIT}" -eq 0 ]; then
     echo "✓ Post-merge build gate passed"
-  elif [ "${BUILD_EXIT}" -eq 124 ]; then
-    echo "⚠ Post-merge build gate timed out after 5 minutes"
+  elif is_timeout_exit "${BUILD_EXIT}"; then
+    echo "⚠ Post-merge build gate timed out after 300 seconds (exit ${BUILD_EXIT}) — not counted as a failure"
+  elif [ "${BUILD_EXIT}" -eq 127 ]; then
+    echo "✗ Post-merge build gate NEVER RAN — command not found (exit 127): ${BUILD_CMD}"
+    WAVE_FAILURE_COUNT=$((WAVE_FAILURE_COUNT + 1))
   else
     echo "✗ Post-merge build gate failed (exit code ${BUILD_EXIT})"
     WAVE_FAILURE_COUNT=$((WAVE_FAILURE_COUNT + 1))
@@ -54,64 +47,70 @@ if [ -n "$BUILD_CMD" ]; then
 fi
 ```
 
-**If `BUILD_EXIT` is 0 (pass):** `✓ Build gate passed` → proceed to Test gate.
+The gate reports five distinct outcomes; do not collapse them.
 
-**If `BUILD_EXIT` is 124 (timeout):** Log warning, treat as non-blocking, continue to Test gate.
+**`NOT RUN`:** no build command was configured and the sniff ladder found no tool. This is neither a pass nor a failure — `WAVE_FAILURE_COUNT` is untouched. Proceed to the Test gate.
 
-**If `BUILD_EXIT` is non-zero (build failure):** Increment `WAVE_FAILURE_COUNT` (same semantics as test failures). Present failure output and offer "Fix now" or "Continue" options (same as step 5.8).
+**`BUILD_EXIT` 0 (pass):** `✓ Build gate passed` → proceed to Test gate.
+
+**`BUILD_EXIT` 124 or 142 (timeout — GNU `timeout` reports 124, the perl `alarm` fallback reports 142; `is_timeout_exit` accepts both):** Log warning, treat as non-blocking, do NOT increment `WAVE_FAILURE_COUNT`, continue to Test gate.
+
+**`BUILD_EXIT` 127 (`NEVER RAN`):** The command was not found, or the timeout wrapper itself was missing so nothing was launched. A build that never ran is not a passing build: increment `WAVE_FAILURE_COUNT` and report the command text, never "failed".
+
+**`BUILD_EXIT` any other non-zero (build failure):** Increment `WAVE_FAILURE_COUNT` (same semantics as test failures). Present failure output and offer "Fix now" or "Continue" options (same as step 5.8).
 
 **Step B — Test gate:**
 
 ```bash
-# Resolve test command: project config > Xcode > Makefile > language sniff
-TEST_CMD=$(pp_run query config-get workflow.test_command --default "" 2>/dev/null || true)
+# Resolve test command: project config first, else the shared sniff ladder
+PP_GATE_BIN=$(printf '%s\n' "${PP_TOOLS:+${PP_TOOLS%/*}:}$PATH" | tr : '\n' | while IFS= read -r d; do if [ -r "$d/detect-build-commands.sh" ]; then printf %s "$d"; break; fi; done)
+TEST_CMD=$(pp_run query config-get workflow.test_command --default "" --raw 2>/dev/null || true)
 if [ -z "$TEST_CMD" ]; then
-  XCODEPROJ=$(find . -maxdepth 2 -name "*.xcodeproj" -not -path "*/node_modules/*" 2>/dev/null | head -1)
-  if [ -n "$XCODEPROJ" ]; then
-    # Xcode project: reuse scheme detected above (or re-detect)
-    if [ -z "${XCODE_SCHEME:-}" ]; then
-      XCODE_SCHEME=$(xcodebuild -list -json -project "$XCODEPROJ" 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('project',{}).get('schemes',[None])[0] or '')" 2>/dev/null || true)
-    fi
-    if [ -n "$XCODE_SCHEME" ]; then
-      TEST_CMD="xcodebuild test -scheme '$XCODE_SCHEME' -destination 'platform=iOS Simulator,name=iPhone 16'"
-    else
-      TEST_CMD="xcodebuild test -destination 'platform=iOS Simulator,name=iPhone 16'"
-    fi
-  elif [ -f "Makefile" ] && grep -q "^test:" Makefile; then
-    TEST_CMD="make test"
-  elif [ -f "Justfile" ] || [ -f "justfile" ]; then
-    TEST_CMD="just test"
-  elif [ -f "package.json" ]; then
-    TEST_CMD="npm test"
-  elif [ -f "Cargo.toml" ]; then
-    TEST_CMD="cargo test"
-  elif [ -f "go.mod" ]; then
-    TEST_CMD="go test ./..."
-  elif [ -f "pyproject.toml" ] || [ -f "requirements.txt" ]; then
-    TEST_CMD="python -m pytest -x -q --tb=short 2>&1 || uv run python -m pytest -x -q --tb=short"
+  if [ -r "$PP_GATE_BIN/detect-build-commands.sh" ]; then
+    . "$PP_GATE_BIN/detect-build-commands.sh"; TEST_CMD=$(pp_detect_test_cmd)
   else
-    TEST_CMD="true"
-    echo "⚠ No test runner detected — skipping post-merge test gate"
+    echo "✗ pp-core sniff ladder not found beside pp-tools — cannot detect a test command"
   fi
 fi
-# Run test suite with 5-minute timeout
+# Run test suite through the shared portable timeout wrapper (5-minute budget)
 TEST_EXIT=0
-timeout 300 bash -c "$TEST_CMD" 2>&1
-TEST_EXIT=$?
-if [ "${TEST_EXIT}" -eq 0 ]; then
-  echo "✓ Post-merge test gate passed — no cross-plan conflicts"
-elif [ "${TEST_EXIT}" -eq 124 ]; then
-  echo "⚠ Post-merge test gate timed out after 5 minutes"
-else
-  echo "✗ Post-merge test gate failed (exit code ${TEST_EXIT})"
+if [ -z "$TEST_CMD" ]; then
+  echo "⚠ Post-merge test gate NOT RUN — no test runner detected (not a pass, not a failure)"
+elif [ ! -r "$PP_GATE_BIN/portable-timeout.sh" ]; then
+  echo "✗ Post-merge test gate NEVER RAN — portable-timeout.sh not found beside pp-tools; refusing to run unbounded (D-09-03)"
+  TEST_EXIT=127
   WAVE_FAILURE_COUNT=$((WAVE_FAILURE_COUNT + 1))
+else
+  . "$PP_GATE_BIN/portable-timeout.sh"
+  run_with_timeout 300 bash -c "$TEST_CMD" 2>&1
+  TEST_EXIT=$?
+  if [ "${TEST_EXIT}" -eq 0 ]; then
+    echo "✓ Post-merge test gate passed — no cross-plan conflicts"
+  elif is_timeout_exit "${TEST_EXIT}"; then
+    echo "⚠ Post-merge test gate timed out after 300 seconds (exit ${TEST_EXIT}) — not counted as a failure"
+  elif [ "${TEST_EXIT}" -eq 127 ]; then
+    echo "✗ Post-merge test gate NEVER RAN — command not found (exit 127): ${TEST_CMD}"
+    WAVE_FAILURE_COUNT=$((WAVE_FAILURE_COUNT + 1))
+  else
+    echo "✗ Post-merge test gate failed (exit code ${TEST_EXIT})"
+    WAVE_FAILURE_COUNT=$((WAVE_FAILURE_COUNT + 1))
+  fi
 fi
 ```
 
+**If the `NOT RUN` line printed:** no runner was configured and none was detected. Record the
+gate as skipped — not passed, not failed — and leave `WAVE_FAILURE_COUNT` alone.
+
 **If `TEST_EXIT` is 0 (pass):** `✓ Post-merge test gate: {N} tests passed — no cross-plan conflicts` → continue to orchestrator tracking update.
 
-**If `TEST_EXIT` is 124 (timeout):** Log warning, treat as non-blocking, continue. Tests may need a longer budget or manual run.
+**If `TEST_EXIT` is 124 or 142 (timeout — 124 from GNU `timeout`, 142 from the perl `alarm`
+fallback; `is_timeout_exit` accepts both):** Log warning, treat as non-blocking, do NOT
+increment `WAVE_FAILURE_COUNT`, continue. Tests may need a longer budget or manual run.
+
+**If `TEST_EXIT` is 127 (`NEVER RAN`):** The runner was not found, or the timeout wrapper was
+missing so nothing was launched. Report the command text and increment `WAVE_FAILURE_COUNT` —
+a suite that never ran is not a green suite, and it must never be reported as a plain failure.
 
-**If `TEST_EXIT` is non-zero (test failure):** Increment `WAVE_FAILURE_COUNT` to track
+**If `TEST_EXIT` is any other non-zero (test failure):** Increment `WAVE_FAILURE_COUNT` to track
 cumulative failures across waves. Subsequent waves should report:
 `⚠ Note: ${WAVE_FAILURE_COUNT} prior wave(s) had test failures`

package/pp-core/workflows/execute-phase/steps/serial-group-dispatch.md

@@ -0,0 +1,72 @@
+# Serial-group dispatch — execute-phase step 3 (`kind: serial-group` spawns)
+
+A serial group is a set of plans in one wave that share only non-source files (a test file, a size
+baseline, a changeset, a doc). `phase.dispatch-plan` gives the group ONE spawn with
+`isolation: main-checkout` and its `plans[]` in run order. Spawn exactly one executor for it — never
+one per plan, never in a worktree (no `isolation=` parameter). Main-checkout spawns run one at a time;
+the wave's worktree spawns may run alongside.
+
+Emit the plan-start heartbeat for the group's first plan, then dispatch (runs in a subagent — no output until the whole group returns; expected, not a freeze):
+
+```text
+Agent(
+  subagent_type="pp-executor",
+  description="Execute serial group {serial_group} of phase {phase_number}: {plan count} plans",
+  model="{executor_model}",  # omit this line when executor_model == "inherit"
+  prompt="
+    <objective>
+    Execute these plans of phase {phase_number}-{phase_name} on the main checkout, one after another, in this order:
+    {for each entry of spawn.plans, numbered:}
+    {n}. {plan.id} — {plan.title} — ${PROJECT_ROOT}/{phase_dir}/{plan file} — touched tests: {plan.touched_tests or "none"} — build: {plan.build}
+    For each plan in turn: execute its tasks with their own atomic commits, write and commit its own SUMMARY.md, run its touched test files, then start the next plan.
+    </objective>
+
+    <dispatch tracking="orchestrator" suite="orchestrator" build="{spawn.build}" />
+
+    <serial_group_rules>
+    - One plan at a time, in the listed order. Each plan gets its own task commits and its own `{plan_id}-SUMMARY.md`, committed before the next plan starts.
+    - Tests: per plan, run only the test files that plan touches (listed above) and its narrower `<verify>` commands. Never the full suite — the orchestrator runs it once after the wave.
+    - Build: only before the tests of a plan whose `build` is true. When the group's `build` is false, run no build at all.
+    - Never call `state.*`, `roadmap.update-plan-progress` or `requirements.mark-complete`, and never stage STATE.md, ROADMAP.md or REQUIREMENTS.md: the orchestrator advances them once per wave.
+    - Never run `size:baseline`; the phase's closing commit re-baselines.
+    - Halt: when a plan cannot finish (verification still failing after repair, a Rule 4 stop, a checkpoint), stop the group at that plan — do not start the next one — and return `## GROUP HALTED` with `**Halted at:** {plan_id}`, the reason, the completed plans with their SUMMARY paths, and the plans not started.
+    - Otherwise return `## GROUP COMPLETE` with one `## PLAN COMPLETE` block per plan, in order.
+    </serial_group_rules>
+
+    <sequential_execution>
+    You are running as a SEQUENTIAL executor agent on the main working tree.
+    Use normal git commits (with hooks). Do NOT use --no-verify.
+    REQUIRED ORDER, per plan: Write SUMMARY.md → commit → only then any narration.
+    </sequential_execution>
+
+    <execution_context>
+    @~/.claude/pp-core/workflows/execute-plan.md
+    @~/.claude/pp-core/templates/summary.md
+    @~/.claude/pp-core/references/checkpoints.md
+    @~/.claude/pp-core/references/tdd.md
+    </execution_context>
+
+    <files_to_read>
+    MANDATORY: load every file listed here with the Read tool before you start the work — this block is your required reading.
+    First resolve repo root: `PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)`
+    - Every plan file listed in <objective> (read the next one again before starting it)
+    - ${PROJECT_ROOT}/.planning/PROJECT.md, ${PROJECT_ROOT}/.planning/STATE.md, ${PROJECT_ROOT}/.planning/config.json (if exists)
+    - ${PROJECT_ROOT}/${phase_dir}/*-CONTEXT.md and *-RESEARCH.md (if they exist)
+    - ${PROJECT_ROOT}/CLAUDE.md or ${PROJECT_ROOT}/.claude/CLAUDE.md, and project skills (if any)
+    </files_to_read>
+
+    ${AGENT_SKILLS}
+
+    <success_criteria>
+    - [ ] Every listed plan executed in order, or the group halted with the halting plan named
+    - [ ] Each task committed individually; one committed SUMMARY.md per completed plan
+    - [ ] No tracking-file writes (the orchestrator advances them once per wave)
+    </success_criteria>
+  "
+)
+```
+
+**On return:**
+- `## GROUP COMPLETE` → emit a plan-complete heartbeat per plan and go on to step 4 (spot-checks use the spawn's `expected_summaries`).
+- `## GROUP HALTED` → the plans before the halt are done (their SUMMARY.md counts for this wave's suite run and tracking commit). Route the halting plan to step 7 (handle failures). The plans after it are not started; they stay incomplete, so a re-run of `phase.dispatch-plan --wave {N}` lists only them.
+- A checkpoint at a plan → `checkpoint_handling`; once resolved, re-run `phase.dispatch-plan --wave {N}` and dispatch the remaining spawn.

package/pp-core/workflows/execute-phase/steps/vault-fetch.md

@@ -1,15 +1,15 @@
-# plan:pre vault fetch + summary (bespoke step dispatch — a0)
+# Vault fetch + summary (plan:pre and execute:pre step dispatch)
 
-Capability-driven dispatch for an active plan:pre step hook where `kind == "step"` and `capId == "vault"`. Runs `vault fetch` then `vault summary` so `.planning/vault/SUMMARY.md` exists on the researcher and planner read paths before the researcher Agent() spawn. The generic step contract dispatches only `ref.skill`/`ref.agent` hooks — not `ref.command` — so this bespoke block owns the `vault fetch` command run. The registry evaluates `when: vault.enabled`; an inert capability yields no hook. `onError: skip` — any failure logs a warning and planning continues; never hard-fails.
+Capability-driven dispatch for an active step hook where `kind == "step"` and `capId == "vault"`, at plan:pre (hooks in `PLAN_PRE_HOOKS_JSON`) or execute:pre (hooks in `EXECUTE_PRE_HOOKS_JSON`). Runs `vault fetch` then `vault summary` so `.planning/vault/SUMMARY.md` exists on the researcher and planner read paths, and so the `vault.status` gate that follows judges a fresh fetch. The generic step contract dispatches only `ref.skill`/`ref.agent` hooks — not `ref.command` — so this bespoke block owns the `vault fetch` command run. The registry evaluates `when: vault.enabled`; an inert capability yields no hook. `onError: skip` — a failed fetch logs a warning and continues; the gate after it decides whether a missing client vault may proceed (it stops only when `vault.required` is true).
 
-Read the active plan:pre step hook from `PLAN_PRE_HOOKS_JSON` (in-context) where `kind == "step"` and `capId == "vault"`.
+Read the active step hook from the point's hooks JSON (in-context) where `kind == "step"` and `capId == "vault"`.
 
-**If no active vault step hook exists:** skip (non-Pareto project, `vault.enabled` false, or vault bindings absent).
+**If no active vault step hook exists:** skip (`vault.enabled` is not true).
 
 **If an active vault step hook exists** (recognizable by `capId == "vault"` + `ref.command == "vault fetch"`):
 
 ```bash
-_PP_SHIM_NAME="pp-tools.cjs"; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; pp_run() { "$PP_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$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
+_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
 # vault fetch: populates .planning/vault/ cache + manifest
 if ! pp_run vault fetch 2>&1; then
   echo "⚠ vault fetch failed — continuing without vault context (onError:skip)" >&2

package/pp-core/workflows/execute-phase/steps/vault-load-gate.md

@@ -1,119 +1,26 @@
-# Vault load gate — advisory (plan:pre + execute:pre)
+# Vault load gate (plan:pre + execute:pre)
 
-Advisory gate that confirms vault load state before planning or build. The host sets
-`VAULT_GATE_POINT` to `plan` (for plan:pre) or `execute` (for execute:pre) before
-executing this step — **one file serves both call sites** (D-05). The §8 message table
-(design §8) column is selected by this parameter.
-
-Gated entirely on `.platform-bindings.json`: when no bindings file is present, this gate
-is a **no-op** — fully inert for non-Pareto projects. The verdict is read from
-`pp_run check vault.status --raw` — a pure manifest read that never fetches, never errors,
-and degrades to `{"present":false}` on any problem (D-02).
-
-```bash
-_PP_SHIM_NAME="pp-tools.cjs"; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; pp_run() { "$PP_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$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
-VAULT_GATE_PRESENT=$(pp_run query platform-bindings --pick present 2>/dev/null || echo false)
-```
-
-**If `VAULT_GATE_PRESENT` != `true`:** skip entirely (non-Pareto project — fully inert).
+One file serves both call sites: the host sets `VAULT_GATE_POINT` to `plan` (plan:pre) or
+`execute` (execute:pre) before executing this step. The verdict, its wording and whether it
+blocks are decided by the CLI — `computeVaultVerdict` is the only owner. This step relays the
+card verbatim and reads one field; it never re-derives any part of the verdict.
 
 ```bash
-VAULT_VERDICT=$(pp_run check vault.status --raw 2>/dev/null || echo '{"present":false}')
-VAULT_STATUS=$(printf '%s' "$VAULT_VERDICT" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(JSON.parse(d).status||'miss');}catch{process.stdout.write('miss');}")
-VAULT_TIER=$(printf '%s' "$VAULT_VERDICT" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(JSON.parse(d).tier||'');}catch{process.stdout.write('');}")
-VAULT_FALLBACK_REASON=$(printf '%s' "$VAULT_VERDICT" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(JSON.parse(d).fallbackReason||'');}catch{process.stdout.write('');}")
-VAULT_REPO=$(printf '%s' "$VAULT_VERDICT" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const p=JSON.parse(d);process.stdout.write(p.repo||p.source||'');}catch{process.stdout.write('');}")
-VAULT_REF=$(printf '%s' "$VAULT_VERDICT" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(JSON.parse(d).ref||'');}catch{process.stdout.write('');}")
-VAULT_SHA=$(printf '%s' "$VAULT_VERDICT" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const s=JSON.parse(d).resolvedSha||'';process.stdout.write(s.slice(0,8));}catch{process.stdout.write('');}")
-VAULT_FILE_COUNT=$(printf '%s' "$VAULT_VERDICT" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(String(JSON.parse(d).fileCount??0));}catch{process.stdout.write('0');}")
-VAULT_STALE=$(printf '%s' "$VAULT_VERDICT" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(String(!!JSON.parse(d).stale));}catch{process.stdout.write('false');}")
-VAULT_FETCHED_AT=$(printf '%s' "$VAULT_VERDICT" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(JSON.parse(d).fetchedAt||'');}catch{process.stdout.write('');}")
-# Compute human-readable cache age when stale
-VAULT_AGE=""
-if [ "$VAULT_STALE" = "true" ] && [ -n "$VAULT_FETCHED_AT" ]; then
-  VAULT_AGE=$(VAULT_FETCHED_AT="$VAULT_FETCHED_AT" node -e "const ms=Date.now()-new Date(process.env.VAULT_FETCHED_AT).getTime();const d=Math.floor(ms/86400000);const h=Math.floor((ms%86400000)/3600000);process.stdout.write(d>0?d+'d':h+'h');")
-fi
-# Detect --auto / --chain in host $ARGUMENTS (non-interactive pipeline mode — D-08)
-AUTO_MODE=false
-if echo "${ARGUMENTS:-}" | grep -qE -- '--auto|--chain'; then AUTO_MODE=true; fi
+_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
+VAULT_CARD=$(pp_run check vault.status --card --point "${VAULT_GATE_POINT:-plan}")
+VAULT_ACTION=$(pp_run check vault.status --pick action)
 ```
 
-Select message based on `VAULT_STATUS`, `VAULT_TIER`, and `VAULT_GATE_POINT`, then handle confirmation.
-
----
-
-## §8 Message table — plan:pre column (`VAULT_GATE_POINT` == `plan`)
-
-**`fetched` + `tier: client`:**
-
-> Client vault loaded from `` `${VAULT_REPO}@${VAULT_REF}` `` (`` `${VAULT_FILE_COUNT}` `` files, sha `` `${VAULT_SHA}` ``). Planning will apply client standards.
-
-Surface this message and require an explicit `confirmed` acknowledgment (`AskUserQuestion`, or a typed `confirmed` in TEXT_MODE). Advisory checkpoint, not a hard block.
-
-**`fetched` + `tier: fallback` (intentionally more prominent — design §8):**
-
-> ℹ Loaded **shared Pareto vault** `` `${VAULT_REPO}@${VAULT_REF}` `` (`` `${VAULT_FILE_COUNT}` `` files) — *${VAULT_FALLBACK_REASON}*. Planning will apply Pareto defaults, not client-specific standards. Proceed?
-
-Surface this message and require an explicit `confirmed` acknowledgment (`AskUserQuestion`, or a typed `confirmed` in TEXT_MODE). The fallback confirmation is deliberately more prominent than the client tier: proceeding on Pareto defaults instead of the client's own standards is a state the user should consciously acknowledge.
-
-**`cache` (all tiers failed, using cached copy):**
-
-> ⚠ Could not reach client or shared vault — using cached copy from `` `${VAULT_FETCHED_AT}` `` (tier `` `${VAULT_TIER}` ``, may be stale). Proceed?
-
-Surface this warning and require an explicit `confirmed` acknowledgment (`AskUserQuestion`, or a typed `confirmed` in TEXT_MODE).
-
-**`miss` (no vault reachable, no cached copy):**
-
-> ⚠ No vault reachable (client or shared) and no cached copy. Planning will proceed WITHOUT vault context.
-
-Surface this warning and require an explicit `confirmed` acknowledgment (`AskUserQuestion`, or a typed `confirmed` in TEXT_MODE).
-
----
-
-## §8 Message table — execute:pre column (`VAULT_GATE_POINT` == `execute`)
-
-**`fetched` + `tier: client`:**
-
-> Client vault present (`` `${VAULT_REPO}@${VAULT_REF}` ``). Build will apply client patterns.
-
-Surface this message and require an explicit `confirmed` acknowledgment (`AskUserQuestion`, or a typed `confirmed` in TEXT_MODE). Advisory checkpoint, not a hard block.
-
-**`fetched` + `tier: fallback` (intentionally more prominent — design §8):**
-
-> ℹ Using shared Pareto vault — *${VAULT_FALLBACK_REASON}*. Build applies Pareto defaults. Proceed?
-
-Surface this message and require an explicit `confirmed` acknowledgment (`AskUserQuestion`, or a typed `confirmed` in TEXT_MODE). The fallback confirmation is deliberately more prominent than the client tier.
-
-**`cache` (all tiers failed, using cached copy):**
-
-> ⚠ Could not reach client or shared vault — using cached copy from `` `${VAULT_FETCHED_AT}` `` (tier `` `${VAULT_TIER}` ``, may be stale). Proceed?
-
-Surface this warning and require an explicit `confirmed` acknowledgment (`AskUserQuestion`, or a typed `confirmed` in TEXT_MODE).
-
-**`miss` (no vault reachable, no cached copy):**
-
-> ⚠ No vault reachable (client or shared) and no cached copy. Build will proceed WITHOUT vault context.
-
-Surface this warning and require an explicit `confirmed` acknowledgment (`AskUserQuestion`, or a typed `confirmed` in TEXT_MODE).
-
----
-
-## Stale suffix (applies to all statuses)
-
-When `VAULT_STALE` is `true`, append ` (cache is \`${VAULT_AGE}\` old)` to the selected message before surfacing it to the user.
-
----
-
-## --auto / --chain behavior (D-08)
-
-When `AUTO_MODE` is `true`: **do not display an interactive prompt**. Instead, print the selected message (including stale suffix when applicable) as a log line, then continue without requiring `confirmed`. This ensures a non-interactive pipeline run leaves an auditable record that Pareto defaults / cache / miss were in effect — especially important for the `tier: fallback`, `cache`, and `miss` cases. Never hard-blocks.
-
----
-
-## Confirmation (interactive mode)
-
-When `AUTO_MODE` is `false`:
+**If either command fails** (non-zero exit, or `VAULT_ACTION` is empty): the gate is
+declared `onError: halt` — STOP and report that the vault gate could not be evaluated. A pure
+read that crashed is never treated as a pass.
 
-Use `AskUserQuestion` to surface the selected message and await `confirmed`. In TEXT_MODE (`--text` in `$ARGUMENTS`), replace `AskUserQuestion` with a plain-text prompt and accept a typed `confirmed`. This is an advisory checkpoint only — the gate **never hard-blocks**; proceeding after `confirmed` (or with a timeout / empty input) is always allowed.
+**Otherwise relay `VAULT_CARD` to the user verbatim** (when non-empty), then act on
+`VAULT_ACTION` only:
 
-`TEXT_MODE` follows the same rule as the host workflow (`--text` in `$ARGUMENTS`): replace `AskUserQuestion` with a plain-text numbered prompt.
+| `VAULT_ACTION` | What to do |
+|---|---|
+| `none` | The vault is disabled — continue silently. |
+| `proceed` | The client vault is loaded — show the card and continue. |
+| `confirm` | Degraded and `vault.required` is false. Interactive: ask for an explicit `confirmed` (`AskUserQuestion`; in TEXT_MODE — `--text` in `$ARGUMENTS` — a plain-text prompt accepting a typed `confirmed`), then continue. With `--auto` / `--chain` in `$ARGUMENTS`: log the card and continue without prompting. |
+| `stop` | `vault.required` is true and the client vault is not loaded. **STOP** — do not plan or build, in any mode (including `--auto` / `--chain`). The card names the remedy; the operator re-runs the command after fixing it. |