@pareto4/pp-core 1.12.1 → 1.17.1

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

@@ -0,0 +1,98 @@
+# `execute:pre` capability dispatch — fetch, then decide (GATE-03)
+
+Extracted from `execute-phase.md` so the host loop body keeps shrinking, per ADR-857 Phase 6.
+`steps/` files are outside `tests/workflow-size-baseline.json` by design; the host is not.
+
+This step is dispatched from `execute-phase.md`'s `execute_pre_dispatch` step, which sits *before*
+`safe_resume_gate` deliberately: that is the first step that can spawn an executor, and the gate must
+run before any code is written, not after.
+
+Read the `activeHooks` array from the `EXECUTE_PRE_HOOKS_JSON=` line the host's render fence printed, in-context (do NOT pipe it through a
+shell parser).
+
+**Admission first (D-28, D-05).** `execute-phase.md` Reads this file unconditionally, so this is the
+first point on the execute path that can refuse a config the gate cannot read. It precedes the inert
+branch below because that branch is exactly what a broken config reaches: no hook renders at all.
+Without `.platform-bindings.json` it is inert and prints nothing.
+
+```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
+VAULT_ADMIT_PRESENT=$(pp_run query platform-bindings --pick present 2>/dev/null || echo true)
+VAULT_ADMIT=inert
+if [ "$VAULT_ADMIT_PRESENT" = true ]; then VAULT_ADMIT=$(pp_run vault admission 2>/dev/null || echo unrecognised); fi
+case "$VAULT_ADMIT" in on) echo "VAULT_ADMIT=on" ;; off|inert) : ;; *) pp_run vault admission --explain; echo "PARETO_GATE_BLOCKED:vault.admission"; exit 1 ;; esac
+```
+
+**If `activeHooks` is empty or absent:** skip the rest of this file silently. This branch is what
+keeps a project with no active `execute:pre` capability structurally inert.
+
+**Otherwise, in this order — the order is the requirement:**
+
+1. **Fetch first.** For any active entry where `kind == "step"` and `capId == "vault"`, set
+   `VAULT_FETCH_HOOKS_JSON=$EXECUTE_PRE_HOOKS_JSON`, then Read and
+   execute `pp-core/workflows/execute-phase/steps/vault-fetch.md`. The fetch is attempted *before*
+   any block decision so a fresh clone or a CI runner with a reachable vault fetches and passes,
+   rather than being blocked for a cache it never had a chance to populate (GATE-03).
+
+   The binding is not decoration and it is not the same shape as step 2's: `vault-fetch.md` is
+   Read from three call sites at two loop points, so it guards on the **parameter**
+   `VAULT_FETCH_HOOKS_JSON` and names no caller's own payload variable. Until 02-10 it named
+   `plan-phase.md`'s, which this dispatcher never sets and never aliased — and the instruction
+   immediately after the guard is *"if no active vault step hook exists: skip"*. A literal
+   reading therefore skipped the `execute:pre` fetch outright and let step 2 decide on whatever
+   cache happened to exist, which is exactly the fresh-clone false block this ordering exists to
+   prevent (02-VERIFICATION, G-2). Binding it here is the whole fix at this call site.
+
+2. **Then gate.** Set `GATE_POINT=execute:pre`, `GATE_HOOKS_JSON=$EXECUTE_PRE_HOOKS_JSON`,
+   `GATE_POSITIONAL_ARG="${PHASE_NUMBER}"` and `GATE_WS` to the active workstream name (empty in flat
+   mode) — a phase-number positional cannot resolve without it on a partitioned project — then Read and follow
+   `pp-core/workflows/execute-phase/steps/check-query-gate.md` — the single generic `check.query`
+   gate enforcer (GATE-02, D-VH-7). It owns the halt decision; do not restate its loop here.
+
+3. **Then render.** If the workflow is still running, set `VAULT_GATE_POINT=execute` and Read and
+   execute `pp-core/workflows/execute-phase/steps/vault-load-gate.md`. It reports the load state for
+   the operator and decides nothing — the decision was step 2's.
+
+   This line is what makes the load-gate file's `execute:pre` message column live. Until this phase
+   that column was written and never dispatched: the execute half of a file that claimed to serve
+   both call sites was dead code.
+
+4. **Then anchor the phase.** If the workflow is still running, run
+   `pp_run vault manifest start "${PHASE_DIR}" --raw` (the host's initialize step already binds
+   `pp_run` and parses `phase_dir` from `INIT`) and print its one-line result to the operator.
+
+   It records `phases[<phase>].startCommit = HEAD` in `.phase-manifest.json` — the anchor both
+   `check vault.audit` and `check vault.review` scope the phase from on a project that commits
+   straight to its base branch (UAT-6-F1). It writes only when no anchor exists, so a resume or a
+   `--gaps-only` run keeps the original one. On a phase that was already executed without an anchor
+   (its directory holds a `*-SUMMARY.md`) it refuses with `phase-already-executed` and writes nothing:
+   HEAD there sits after the phase's own commits, and the audit scopes such a phase from its SUMMARY
+   trace digests instead. An entry left under this phase number by a different phase directory (a
+   number reused after a milestone reset) is stale, and `start` replaces it with a fresh anchor.
+   The verb is inert without the practices capability,
+   exits 0 on every path, and reports a failure as `ok: false` with a reason that is printed and
+   never halts — the audit's SUMMARY trace-digest fallback and its stated fallback ground are the
+   degraded path.
+
+4b. **Then record the mode-neutral start anchor (D-31).** If the workflow is still running and the
+   `activeHooks` array holds an entry with `capId == "vault"` (the same mechanical check step 1 uses
+   for the fetch), run `pp_run vault anchor start "${PHASE_DIR}" --raw` and print its one-line result
+   to the operator. Otherwise skip it.
+
+   It writes `${PHASE_DIR}/.vault-anchors.json` with `start` = HEAD. Every record the phase's
+   executors write later (the execute-stage `vault trace scaffold` ledger, the `vault standards
+   consulted` anchor line) reads it as its START anchor, beside the END anchor (HEAD at write time)
+   the CLI records itself. A commit is then covered only when it falls inside some record's
+   start..end range, so an ungoverned commit followed by any record can no longer hide behind that
+   record's end. The practices-only manifest start in step 4 is not enough: it exists only when
+   `vault.practices_enabled` is on, so a standards-mode phase would have no start at all. Re-running
+   at a new HEAD (a resumed run, `--wave N`, `--gaps-only`) records that HEAD as the start of every
+   record written from now on (D-98), so nothing committed between two runs is claimed by a later
+   record; the earlier start stays in the file's history, where a worktree executor's end-only record
+   written before the resume still finds the start that preceded its own end. The phase's own commits
+   made between its last record and the resume are then uncovered, and the strict gate names them with
+   their repair: `vault anchor backfill <summary> --from <a recorded start> --attest <commit>`, the
+   operator's attestation of each commit by its own id; nothing is widened, and every check lists it.
+   The verb prints nothing and writes nothing unless `vault admission` answers
+   `on`, exits 0 on every path, and reports a refusal as `ok: false` with a reason that is printed
+   and never halts. A phase that has no start anchor fails at the strict points instead.

package/pp-core/workflows/execute-phase/steps/per-plan-worktree-gate.md

@@ -0,0 +1,94 @@
+# Per-plan worktree decision (#2772)
+
+Run this for **each plan in the current wave** before its `Agent()` dispatch. The output `USE_WORKTREES_FOR_PLAN` gates the dispatch branch (worktree mode vs sequential mode) for that plan only — other plans in the same wave can still take the worktree path.
+
+`SUBMODULE_PATHS` is computed once in the `initialize` step (parsed from `.gitmodules`).
+
+`PLAN_FILES` is the whitespace-separated list of paths the plan declared it will touch, extracted from the `phase-plan-index` JSON loaded in `discover_and_group_plans`:
+
+```bash
+# plan_json is the JSON object for this plan from PLAN_INDEX.plans[]
+# files_modified is an array of strings (repo-relative paths or globs)
+PLAN_FILES=$(jq -r '.files_modified // [] | join(" ")' <<<"$plan_json")
+plan_id=$(jq -r '.id' <<<"$plan_json")
+```
+
+Then run the per-plan gate:
+
+```bash
+USE_WORKTREES_FOR_PLAN="$USE_WORKTREES"
+
+if [ -n "$SUBMODULE_PATHS" ] && [ "$USE_WORKTREES_FOR_PLAN" != "false" ]; then
+  if [ -z "$PLAN_FILES" ]; then
+    # Fallback: planned paths are unknown/unparseable — fall back to the safe
+    # behavior (disable worktree isolation for this plan) and log why.
+    echo "[worktree] Plan ${plan_id}: files_modified missing/unparseable — disabling worktree isolation as a safety fallback (submodule project)"
+    USE_WORKTREES_FOR_PLAN=false
+  else
+    # Compute intersection with glob-safe normalization. Both sides are
+    # normalized (strip leading "./", strip trailing "/") and matched
+    # bidirectionally so a globby planned path like "vendor/**/*.c" still
+    # matches submodule "vendor/foo", and "./vendor/foo/bar.c" matches
+    # submodule "vendor/foo".
+    INTERSECT=""
+    set -f  # disable globbing while iterating literal patterns
+    for sm_raw in $SUBMODULE_PATHS; do
+      # Normalize submodule path: strip ./ prefix and trailing /
+      sm="${sm_raw#./}"
+      sm="${sm%/}"
+      [ -z "$sm" ] && continue
+      for pf_raw in $PLAN_FILES; do
+        # Normalize planned path the same way
+        pf="${pf_raw#./}"
+        pf="${pf%/}"
+        [ -z "$pf" ] && continue
+        matched=0
+        # Direction 1: planned path is the submodule or lies inside it
+        case "$pf" in
+          "$sm"|"$sm"/*) matched=1 ;;
+        esac
+        # Direction 2: submodule lies inside the planned path (e.g. plan
+        # declares "vendor" or a glob expanding to a directory containing
+        # the submodule).
+        if [ "$matched" -eq 0 ]; then
+          case "$sm" in
+            "$pf"|"$pf"/*) matched=1 ;;
+          esac
+        fi
+        # Direction 3: planned path uses a glob — strip glob wildcards
+        # and check whether the resulting prefix overlaps the submodule
+        # path in either direction.
+        if [ "$matched" -eq 0 ]; then
+          case "$pf" in
+            *'*'*|*'?'*|*'['*)
+              # Take the literal prefix before the first glob metachar.
+              prefix="${pf%%[*?[]*}"
+              prefix="${prefix%/}"
+              if [ -n "$prefix" ]; then
+                case "$sm" in
+                  "$prefix"|"$prefix"/*) matched=1 ;;
+                esac
+                if [ "$matched" -eq 0 ]; then
+                  case "$prefix" in
+                    "$sm"|"$sm"/*) matched=1 ;;
+                  esac
+                fi
+              fi
+              ;;
+          esac
+        fi
+        if [ "$matched" -eq 1 ]; then
+          INTERSECT="$INTERSECT $pf_raw"
+        fi
+      done
+    done
+    set +f
+    if [ -n "$INTERSECT" ]; then
+      echo "[worktree] Plan ${plan_id}: planned paths intersect submodule paths (${INTERSECT# }) — disabling worktree isolation for this plan"
+      USE_WORKTREES_FOR_PLAN=false
+    fi
+  fi
+fi
+```
+
+After running this for the plan, the dispatch branches in `execute_waves` step 3 MUST gate on `USE_WORKTREES_FOR_PLAN` for the current plan, not on the project-level `USE_WORKTREES`. Track which plans in this wave actually used worktrees (append `plan_id` to a `WAVE_WORKTREE_PLANS` accumulator when `USE_WORKTREES_FOR_PLAN != false`) — the post-wave cleanup step (5.5) uses this to decide whether worktree-merge cleanup is needed at all.

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

@@ -1,13 +1,11 @@
 # Step: post_merge_gate
 
-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:** 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.
+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.
+
+**Step A — Build gate:**
 
 ```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

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

@@ -1,25 +1,126 @@
-# Vault fetch + summary (plan:pre and execute:pre step dispatch)
+# vault fetch + summary — the bespoke step dispatch, served at `plan:pre` and `execute:pre`
 
-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).
+Capability-driven dispatch for an active vault step hook where `kind == "step"` and `capId == "vault"`. The `vault` capability declares that step at **two** loop points — `plan:pre` and `execute:pre` — and this one file serves both, Read from ten call sites — nine hook-mode callers at those two points and one direct-mode caller with no loop point (see the Direct mode paragraph below); the caller table below names them. Runs `vault fetch`, which now writes `.planning/vault/SUMMARY.md` itself (STRICT-05). What that buys differs by point and both reasons are real: at `plan:pre` the summary exists on the researcher and planner read paths before the researcher `Agent()` spawn; at `execute:pre` the fetch is attempted *before* the gate decides, so a fresh clone or a CI runner with a reachable vault fetches and passes rather than being blocked for a cache it never had a chance to populate (GATE-03). 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.
 
-Read the active step hook from the point's hooks JSON (in-context) where `kind == "step"` and `capId == "vault"`.
+## Callers — bind `VAULT_FETCH_HOOKS_JSON` (hook mode) or set `VAULT_FETCH_DIRECT` (direct mode) before Reading this file
 
-**If no active vault step hook exists:** skip (`vault.enabled` is not true).
+`VAULT_FETCH_HOOKS_JSON` is a **parameter**, in exactly the sense `check-query-gate.md`'s
+`GATE_HOOKS_JSON` is one: this file never renders hooks itself, and the caller sets it to the
+`activeHooks` payload the caller already rendered for **its own** loop point. This file therefore
+names no caller's payload variable anywhere, deliberately — it is Read from ten places, nine at
+two loop points and one with no loop point at all, so any one variable name is dead at the other
+nine, and the guard's next instruction is *skip*. A step file that hard-names one caller's variable
+does not merely mis-document the other callers; it silently turns their fetch off
+(02-VERIFICATION, G-2).
 
-**If an active vault step hook exists** (recognizable by `capId == "vault"` + `ref.command == "vault fetch"`):
+| Caller | Loop point | Binding |
+|--------|------------|---------|
+| `pp-core/workflows/plan-phase.md`, `### plan:pre vault fetch + summary` | `plan:pre` | `VAULT_FETCH_HOOKS_JSON` ← the `plan:pre` payload that section already has in scope |
+| `pp-core/workflows/autonomous.md`, §3a.5-i, the `ref.command` + `capId == "vault"` branch | `plan:pre` | `VAULT_FETCH_HOOKS_JSON` ← the `plan:pre` payload §3a.5 rendered |
+| `pp-core/workflows/execute-phase/steps/execute-pre-dispatch.md`, step 1 "Fetch first" | `execute:pre` | `VAULT_FETCH_HOOKS_JSON` ← the `execute:pre` payload that dispatcher already reads its `activeHooks` from |
+| `pp-core/workflows/quick.md`, Step 2.4 (16-11) | `plan:pre` | `VAULT_FETCH_HOOKS_JSON` ← quick's `plan:pre` payload, filtered in the fence to the `vault` and `vault-practices` capabilities, after its own admission fence |
+| `pp-core/workflows/debug.md`, § 0b Vault admission and load gate (16-14) | `plan:pre` | `VAULT_FETCH_HOOKS_JSON` ← debug's `plan:pre` payload, filtered in the fence to the `vault` and `vault-practices` capabilities, after its own admission fence |
+| `pp-core/workflows/code-review-fix.md`, `vault_admission_gate` (16-15) | `execute:pre` | `VAULT_FETCH_HOOKS_JSON` ← the door's `execute:pre` payload, filtered in the fence to the `vault` and `vault-practices` capabilities, after its own admission fence |
+| `pp-core/workflows/validate-phase.md`, § 0.5 (16-15) | `execute:pre` | `VAULT_FETCH_HOOKS_JSON` ← the door's `execute:pre` payload, filtered in the fence to the `vault` and `vault-practices` capabilities, after its own admission fence |
+| `pp-core/workflows/add-tests.md`, `vault_admission_gate` (16-15) | `execute:pre` | `VAULT_FETCH_HOOKS_JSON` ← the door's `execute:pre` payload, filtered in the fence to the `vault` and `vault-practices` capabilities, after its own admission fence |
+| `pp-core/workflows/audit-fix.md`, `vault_admission_gate` (16-15) | `execute:pre` | `VAULT_FETCH_HOOKS_JSON` ← the door's `execute:pre` payload, filtered in the fence to the `vault` and `vault-practices` capabilities, after its own admission fence |
+| `pp-core/workflows/discovery-sprint/vault-context.md`, § 2 "Fetch" (Read from Flow 2 Step 1 and prefill Step 0 of the discovery sprint) | none — direct mode (D-11-09) | `VAULT_FETCH_DIRECT=true`; the payload parameter is left empty; the two activation guards run first, in order |
+
+A **next caller** (the eleventh) inherits one obligation and one only: bind this parameter from the payload it
+rendered for its own point, before the Read — or, when it has no loop point, run the two activation
+guards and set `VAULT_FETCH_DIRECT` (Direct mode below). Nothing in this file needs to change to
+accommodate it — that is the whole reason both parameters exist instead of a sentence naming a
+caller's variable.
+
+The step's static `onError: skip` remains the **registry-level dispatch policy** and is unchanged. Layered on top of it is a **runtime** decision this block makes for itself: when `vault.required` is true, a failed fetch or an unwritten summary hard-stops with `PARETO_GATE_BLOCKED:vault.fetch` and a non-zero exit (STRICT-03, GATE-09). A static `onError` cannot depend on a config value, which is why the arm lives here rather than in the capability declaration. With `vault.required` false — the default — every path below behaves exactly as it did before: a warning, and the run continues.
+
+**Admission first (D-28, D-05).** This check runs before the hook-presence check below because a loop-point host renders no vault hook at all on a config the gate cannot read, so without it a direct or unconditional caller would skip the fetch silently. It is inert without `.platform-bindings.json` (a probe that cannot answer, such as on a malformed bindings file, defers to the verb, which checks bindings first itself); `on`, `off` and `inert` continue to the hook check exactly as before, and anything else (`config-unreadable`, or no answer) halts naming the file and the repair (research C-4).
 
 ```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
-# vault fetch: populates .planning/vault/ cache + manifest
-if ! pp_run vault fetch 2>&1; then
+VAULT_ADMIT_PRESENT=$(pp_run query platform-bindings --pick present 2>/dev/null || echo true)
+VAULT_ADMIT=inert
+if [ "$VAULT_ADMIT_PRESENT" = true ]; then VAULT_ADMIT=$(pp_run vault admission 2>/dev/null || echo unrecognised); fi
+case "$VAULT_ADMIT" in on) echo "VAULT_ADMIT=on" ;; off|inert) : ;; *) pp_run vault admission --explain; echo "PARETO_GATE_BLOCKED:vault.admission"; exit 1 ;; esac
+```
+
+Read the active vault step hook from `VAULT_FETCH_HOOKS_JSON` (in-context) where `kind == "step"` and `capId == "vault"`. A caller binding this payload to `$X` means the JSON on the `X=` line the caller's render fence PRINTED (D-99): a payload a fence only assigned is invisible in the next call.
+
+**If no active vault step hook exists** and `VAULT_FETCH_DIRECT` is not the literal `true`: skip (non-Pareto project, `vault.enabled` false, or vault bindings absent).
+
+**Direct mode — `VAULT_FETCH_DIRECT` (D-11-09):** consulted **only** when `VAULT_FETCH_HOOKS_JSON` is empty, mirroring the `GATE_DIRECT_QUERY` parameter `check-query-gate.md` already ships for build entry points that declare no loop-host frontmatter. A caller with no loop point cannot render a payload at all: the `vault` capability declares this step at exactly `plan:pre` and `execute:pre`, and the twelve canonical loop points are frozen by the loop-host contract, so there is no third point such a caller could render and no payload for it to bind. Setting this parameter to the literal `true` makes the block below run exactly as it does for an active hook — the same `vault fetch`, the same `.planning/vault/SUMMARY.md` write, the same three arms and the same required-miss halt token and non-zero exit — so a direct caller inherits the first of the two `plan:pre` halt surfaces from its owner rather than authoring a fourth copy of it (D-11-11). A direct caller MUST run the two activation guards itself first, in this order: `pp_run query platform-bindings --pick present` (when not `true`, do not Read this file at all — non-Pareto project, fully inert), then `pp_run vault admission` (16-04, D-28: on `on`, Read this file; on `off` or `inert`, do not Read it; on anything else, `config-unreadable` or no answer, print `pp_run vault admission --explain` and halt with `PARETO_GATE_BLOCKED:vault.admission` and a non-zero exit, because a config the gate cannot read is not a vault that is off). A direct dispatch has not been through the registry's `when` evaluation and therefore carries none of its inertness, which is the same obligation `check-query-gate.md` § Direct-query mode places on a direct caller of the gate. Hook-mode callers are unaffected: with a non-empty payload this parameter is never read, so all hook-mode callers behave exactly as they did before it existed.
+
+The block below also records the verdict before and after the fetch and says so when the fetch changed it (D-08-08): the plan:pre / execute:pre ordering is fetch-then-gate (`plan-phase.md` §5.1 then §5.6; `execute-pre-dispatch.md` steps 1-2), so a by-hand `check vault.status` taken earlier can legitimately disagree with the gate — the disagreement is temporal, and this line is what makes it explicable (D-08-05). Both snapshots are pure reads (D-08-04): they report the manifest, they never fetch, and they add nothing at all on a run that does not reach the block — an inactive hook with no direct-mode caller — because they live inside the run condition above and nowhere else.
+
+**If an active vault step hook exists** (recognizable by `capId == "vault"` + `ref.command == "vault fetch"`) — or `VAULT_FETCH_DIRECT` is `true` with an empty payload:
+
+```bash
+# vault.required — read ONCE, with an explicit default (STRICT-03). The key is
+# declared in `capabilities/vault/capability.json`, so this read returns the
+# project's configured value; with it set true the hard-stop arm below is live.
+VAULT_REQUIRED=$(pp_run query config-get vault.required --raw --default false 2>/dev/null || echo false)
+
+# vault fetch: populates .planning/vault/ cache + manifest AND writes
+# .planning/vault/SUMMARY.md itself. The separate `vault summary` subcommand
+# call that used to live here is deliberately GONE (STRICT-05): the fetch and the
+# summary were paired only by this markdown, so a direct CLI fetch, an --auto run
+# that never dispatched this step, or an agent skipping the second instruction
+# each produced a populated cache with no SUMMARY.md. The pairing is now code.
+# D-08-08: a pure read of the manifest as it stands BEFORE this fetch rewrites
+# it. This is the reading an operator's own by-hand `check vault.status` would
+# have produced a moment ago, captured here because nothing downstream can
+# reconstruct it once the fetch has landed.
+VAULT_PRE_VERDICT=$(pp_run check vault.status --raw 2>/dev/null || echo '{}')
+VAULT_FETCH_JSON=$(pp_run vault fetch --raw 2>/dev/null || echo '{}')
+VAULT_SOURCE=$(printf '%s' "$VAULT_FETCH_JSON" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(JSON.parse(d).source||'');}catch{process.stdout.write('');}")
+VAULT_SUMMARY_WRITTEN=$(printf '%s' "$VAULT_FETCH_JSON" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(String(JSON.parse(d).summaryWritten===true));}catch{process.stdout.write('false');}")
+VAULT_SUMMARY_ERROR=$(printf '%s' "$VAULT_FETCH_JSON" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(String(JSON.parse(d).summaryError||''));}catch{process.stdout.write('');}")
+VAULT_FETCH_REASON=$(printf '%s' "$VAULT_FETCH_JSON" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const p=JSON.parse(d);process.stdout.write(String(p.fallbackReason||p.warning||''));}catch{process.stdout.write('');}")
+
+# D-08-08: the same pure read AFTER the fetch, and a comparison of the five
+# fields that decide the gate. Values are envelope fields this file's siblings
+# already print; `reason` is a frozen code. Pipes and newlines are stripped and
+# each summary is cut at 300 characters, because the two summaries are carried
+# through a single pipe-delimited string that `cut` then splits.
+VAULT_POST_VERDICT=$(pp_run check vault.status --raw 2>/dev/null || echo '{}')
+VAULT_VERDICT_DIFF=$(PRE="$VAULT_PRE_VERDICT" POST="$VAULT_POST_VERDICT" node -e "const F=['tier','ref','stale','block','reason'];const g=(s)=>{let p={};try{p=JSON.parse(s)||{};}catch{p={};}return F.map((k)=>k+'='+String(p[k]===undefined||p[k]===null?'':p[k])).join(' ').replace(/[\r\n|]/g,'').slice(0,300);};const a=g(process.env.PRE||'');const b=g(process.env.POST||'');process.stdout.write(a===b?'same||':'changed|'+a+'|'+b);")
+VAULT_VERDICT_CHANGED=$(printf '%s' "$VAULT_VERDICT_DIFF" | cut -d'|' -f1)
+VAULT_VERDICT_BEFORE=$(printf '%s' "$VAULT_VERDICT_DIFF" | cut -d'|' -f2)
+VAULT_VERDICT_AFTER=$(printf '%s' "$VAULT_VERDICT_DIFF" | cut -d'|' -f3)
+if [ "$VAULT_VERDICT_CHANGED" = "changed" ]; then
+  echo "ℹ vault fetch changed the gate verdict: before — ${VAULT_VERDICT_BEFORE}; after — ${VAULT_VERDICT_AFTER}. A check vault.status read taken before this fetch described the earlier state (D-08-08)."
+fi
+
+# Read the OUTCOME, never the exit code: `pp-tools vault ...` exits 0 on every
+# path by design (D-VH-7 — the command reports, the workflow halts), so the old
+# `if ! pp_run vault fetch` guard could not take its failure branch.
+VAULT_FETCH_FAILED=false
+if [ -z "$VAULT_SOURCE" ] || [ "$VAULT_SOURCE" = "miss" ]; then VAULT_FETCH_FAILED=true; fi
+VAULT_LOAD_OK=true
+if [ "$VAULT_FETCH_FAILED" = "true" ] || [ "$VAULT_SUMMARY_WRITTEN" != "true" ]; then VAULT_LOAD_OK=false; fi
+
+if [ "$VAULT_REQUIRED" = "true" ] && [ "$VAULT_LOAD_OK" = "false" ]; then
+  # Arm 3 — vault.required is on: a miss, a failed fetch and an unwritable
+  # summary all hard-stop (D-VH-4). Print the failure verbatim, then the named
+  # halt token and a non-zero exit — the same two halves the extracted enforcer
+  # uses, so an agent stops and an unattended runner sees the exit code.
+  echo "✗ vault could not be loaded and vault.required is true (STRICT-03)" >&2
+  if [ -n "$VAULT_FETCH_REASON" ]; then echo "  fetch: $VAULT_FETCH_REASON" >&2; fi
+  if [ -n "$VAULT_SUMMARY_ERROR" ]; then echo "  summary: $VAULT_SUMMARY_ERROR" >&2; fi
+  echo "PARETO_GATE_BLOCKED:vault.fetch"
+  exit 1
+elif [ "$VAULT_FETCH_FAILED" = "true" ]; then
+  # Arm 1 — fetch failed, vault.required off. Same effect as before this plan.
   echo "⚠ vault fetch failed — continuing without vault context (onError:skip)" >&2
+  if [ -n "$VAULT_FETCH_REASON" ]; then echo "  reason: $VAULT_FETCH_REASON" >&2; fi
+elif [ "$VAULT_SUMMARY_WRITTEN" != "true" ]; then
+  # Arm 2 — fetch succeeded, the summary did not reach disk. STRICT-05: this is
+  # the branch the confirmation line used to fall through to unconditionally,
+  # pointing agents at a SUMMARY.md that was never written.
+  echo "⚠ vault summary not written — .planning/vault/SUMMARY.md is absent (onError:skip)" >&2
+  if [ -n "$VAULT_SUMMARY_ERROR" ]; then echo "  reason: $VAULT_SUMMARY_ERROR" >&2; fi
 else
-  # vault summary: writes .planning/vault/SUMMARY.md — the bounded index
-  # that planner, researcher, and executor pointers reference.
-  if ! pp_run vault summary 2>&1; then
-    echo "⚠ vault summary failed — SUMMARY.md may be absent (onError:skip)" >&2
-  else
-    echo "✓ vault fetch + summary complete: .planning/vault/SUMMARY.md"
-  fi
+  # The claim is now reachable ONLY when summaryWritten is true.
+  echo "✓ vault fetch + summary complete: .planning/vault/SUMMARY.md"
 fi
 ```