@pareto4/pp-core 1.13.0 → 1.18.0

package/pp-core/workflows/execute-phase/steps/check-query-gate.md

@@ -0,0 +1,327 @@
+# Generic `check.query` gate enforcer
+
+**Naming note (read this first).** This file lives under `pp-core/workflows/execute-phase/steps/`
+because that directory is the established home for lazily-Read workflow step fragments —
+`plan-phase.md` already Reads two of its siblings across a workflow boundary, and creating a new
+top-level directory has unverified installer implications. The directory name says *execute-phase*,
+but this file serves **ship**, **plan** and **execute** call sites alike. Do not read the path as a
+scope restriction.
+
+This is the **single** generic `check.query` gate enforcer. Before it existed the same enforcement
+loop was written twice — `ship.md` step 6 and `execute-phase.md` step 5.75 — against two contracts
+that disagreed about which envelope field carries the verdict. GATE-02 collapses them into this one
+implementation; **D-VH-7** fixes which contract survives: the two-step one from step 5.75, reading
+the boolean `block`, not `status == "block"`.
+
+This file is **Read lazily** by its callers. It is never eagerly imported, so it costs its callers
+nothing until the moment a gate actually has to be enforced.
+
+## Parameters — set these before Reading this file
+
+| Variable | Required | Meaning |
+|----------|----------|---------|
+| `GATE_POINT` | yes | Loop point label used in operator messages, e.g. `ship:pre`, `execute:pre`, `execute:wave:post`. Message text only; it never changes control flow. |
+| `GATE_HOOKS_JSON` | yes (hook mode) | The already-rendered hooks JSON from the caller's own `pp_run loop render-hooks <point> --raw` call. This file never renders hooks itself. **`GATE_HOOKS_JSON=$X` — in a caller's prose and in the Caller contract below — means the JSON on the `X=` line that caller's render fence PRINTED** (16 review iteration 2 CR-01, D-99): the hooks are read in-context, and the agent's Bash tool starts a fresh shell for every call, so a payload a fence only assigned is invisible, and the guard below would skip a blocking gate silently. Every render fence that feeds this enforcer therefore prints `X={"activeHooks":[…]}` (without the large `rendered` text), and a test fails when one does not. |
+| `GATE_POSITIONAL_ARG` | no | When non-empty, passed to `pp_run check` as a single positional argument after the query name. This is how the wave gate passes the phase number. |
+| `GATE_POSITIONAL_ARG_2` | no | When non-empty, passed to `pp_run check` as a **second** positional argument, after `GATE_POSITIONAL_ARG` and in that order. The `plan:post` caller in `plan-phase.md` §13e uses it to pass the requirement-ID list after the phase directory, which is what `gap-analysis.plan-post` has always received in its fourth argument slot. Setting this while leaving `GATE_POSITIONAL_ARG` empty is a **caller error**: the enforcer passes them positionally in order, so an absent first argument silently shifts this one into the first slot. |
+| `GATE_WS` | no | The active workstream name (the value of `--ws`), empty in flat mode. When non-empty the enforcer appends `--ws "$GATE_WS"` to the check command, because a phase **number** positional cannot be resolved without it on a partitioned project: the locator falls back to the flat `.planning/phases`, which does not exist there, and the handler reports the phase as unresolvable. Handlers are workstream-aware; historically only the call sites were not, and an omitted `--ws` here turned a `blocking: true` gate into a hard halt on every workstream project. Callers passing a phase **directory** in `GATE_POSITIONAL_ARG` do not need it — the path already carries the partition — but setting it is harmless and correct. |
+| `GATE_STAGE` | no | The lifecycle stage the dispatching point represents — `plan` or `execute`. When non-empty the enforcer appends `--stage "$GATE_STAGE"` to the check command. A query that does not understand the flag ignores it, because the flag pair is appended **after** both positionals and therefore never occupies a positional slot. `plan:post` sets it to `plan`, so the trace gate validates that point's own artifacts — the PLAN.md files — and not the SUMMARY.md files of a previous execution. `execute:post` deliberately leaves it **unset**, so that point validates both stages, which is the documented invariant: `plan:post` sees PLAN.md files only, `execute:post` sees both and the PLAN.md side is already known good. |
+| `GATE_UNPAIRED` | no | Whether a plan artifact carrying no executed counterpart is a defect — `strict` or `tolerant`. When non-empty the enforcer appends `--unpaired "$GATE_UNPAIRED"` to the check command; `vault.trace` reads it (04-07, D-10) and every other query ignores an unrecognised named flag, because the pair is appended **after** both positionals and therefore never occupies a positional slot. **The default when the variable is absent is `tolerant`, and that default is deliberate**: two of the four `vault.trace` call sites are mid-lifecycle — `plan:post` runs when no plan has been executed yet, and `execute:wave:post` runs while later waves are still pending — so at those points an unpaired plan is the normal state of a correct run, not a fault. A `strict` default would turn a forgotten token at either of them into a continuous halt on every project that has the capability on. The two points that DO set `strict` are `ship:pre` and `verify:post`, which is the same claim from the other side: those are the two points at which every plan must already have an executed counterpart, so an unpaired plan there is a real defect. `verify:post` qualifies that with the run mode — it sets `strict` only when the host's `WAVE_FILTER` is unset, because a `--wave N` run is the third mid-lifecycle case (04-12, CR-04). |
+| `GATE_DIRECT_QUERY` | no | Direct-query mode (see below) for build entry points that declare no loop-host frontmatter. Only consulted when `GATE_HOOKS_JSON` is empty. |
+
+`GATE_POSITIONAL_ARG` may also name one `*-PLAN.md` file: `check vault.trace` then judges that plan's
+records alone (16-05, D-38), and every other query refuses a file. `execute-plan.md`'s `plan:post`
+row below is the caller that passes one.
+
+## Producer audit — every declared `check.query` in the repo
+
+Enumerated from `capabilities/*/capability.json` (`grep -rho '"query": *"[^"]*"' capabilities/*/capability.json | sort -u`)
+and traced to its handler branch in `src/check-command-router.cts`. The router normalises dots to
+hyphens, so `verify.schema-drift` routes to the `verify-schema-drift` branch.
+
+**D-08-30 — the citations stay line numbers, and that is a decision rather than an inheritance.**
+Every row below rots on ANY line change to the router, and this phase watched it happen twice inside
+a single plan (08-02) and three more times across the wave. Two alternatives were weighed: citing the
+emitting *expressions* instead (unstable in a different way — the same literal `block: true,` appears
+five times in `cmdVaultTrace` alone, so a citation could not name one), and dropping the column
+(which is what the rows were BEFORE 04-16, and is exactly how one of them came to claim a handler
+emitted a constant `false` for three plans after it stopped doing so). Line numbers are kept because
+the probe at `tests/vault-trace.integration.test.cjs:9235,9258` (`handlerRange`, `emitsBlock`) is TWO-DIRECTIONAL: a rotted citation is a
+loud red on the next run, never a silent lie, and the completeness half also forbids a row that names
+a convenient subset. The rot is real; it is now the cheapest kind — a mechanically re-derivable one.
+Re-derive with the probe's own `handlerRange`/`emitsBlock` predicates; never by arithmetic on the
+old numbers, which is how 05-13 shifted three rows ~200 lines into a different function.
+
+| Query | Handler branch / function | Emits boolean `block` on every path? | Emission site(s) |
+|-------|---------------------------|--------------------------------------|------------------|
+| `gap-analysis.plan-post` | `gap-analysis-plan-post` branch (`cmdGapAnalysisPlanPost`) | yes — always `false` (advisory by design) | `src/check-command-router.cts:1067` |
+| `ship.platform-drift` | `ship-platform-drift` branch (`cmdShipPlatformDrift`) | yes — the only producer that can emit `block: true` from a threshold comparison | `src/check-command-router.cts:1169,1179,1188,1205,1247,1256,1270` |
+| `tdd.review-checkpoint` | `tdd-review-checkpoint` branch | yes — `block = violations > 0`, advisory in the capability | `src/check-command-router.cts:928,1022` |
+| `ui.plan-gate` | `ui-plan-gate` branch (`computeUiPlanGate`) | yes — `block = frontend && !hasUiSpec` | `src/check-command-router.cts:703` (emitted at `:727`) |
+| `ui.safety-gate` | `ui-safety-gate` branch (`computeUiSafetyGate`) | yes — `block = frontend && hasUiFiles && !hasUiSpec` | `src/check-command-router.cts:830` (emitted at `:856`) |
+| `vault.status` | `vault-status` branch (`cmdVaultStatus`) | yes — COMPUTED, not constant: `block` is the `vault.required` policy applied to the shared tier-keyed verdict leaf (`computeVaultVerdict`, GATE-01 / D-VH-4). It is `false` with the policy off (STRICT-01's byte-identical promise), on the inert path (`.platform-bindings.json` absent — that branch runs FIRST by requirement, T-02-28, because `tier !== 'client'` is true of `undefined` and would otherwise block every non-Pareto project), and for a present, fresh, client-tier vault; it is `true` on a required miss, on a fallback-tier load, on a stale client vault whatever its source (D-08-01; the block skips staleness only when `vault.cache_ttl_hours` is 0, D-08-28), and on a client cache fetched from a ref the project no longer configures (D-08-23). The attributed override (`applyVaultOverride`, GATE-07) then gets the last word on every blocking path, and that overwrite is the last emission site cited; and on a passing required-on verdict the envelope now carries a `message` (the success line, D-08-20) — the enforcer's every-run passthrough prints it. | `src/check-command-router.cts:1626,1641,1680,1707,1768` (02-11: CHECKED by the same two-directional probe as the other rows — every cited line lies inside `cmdVaultStatus` and emits a block, and every emission site is cited. This was the one row the probe did NOT cover, so it is the row that rotted: wave 1 wrote the claim before 02-06 computed the block, and 05-13 shifted the citations arithmetically into the manifest-sanitiser, ~200 lines outside the handler) 14-06: + the envelope always carries `reason`, `status` may be `degraded` (index missing / unparseable / empty / unresolvable / unchecked, D-12), the flat index fields follow the override keys, and the healthy message is the one-line standards card (D-15); a degraded index blocks exactly when `vault.required` is on, through the same override (D-13), so it adds no emission site of its own. |
+| `vault.trace` | `vault-trace` branch (`cmdVaultTrace`) — declared by the `vault` capability (`when: vault.enabled`) at **four** points, `plan:post`, `execute:post`, `ship:pre` and `verify:post`, all `blocking: true` / `onError: halt`, and once more at `ship:pre` as a seal gate (`onRecordedArtifacts: true`) that renders with `vault.enabled` off over a phase holding vault records (16-08). It judges each PLAN's `<vault_standards>` block and each SUMMARY's `## Standards Consulted` section through `src/vault-standards.cts` and fails closed on the `standards_*` kinds (`standards_block_absent`, `standards_block_duplicate`, `standards_block_unterminated`, `standards_block_malformed`, `standards_reason_invalid`, `standards_document_duplicate`, `standards_degraded_mixed`, `standards_none_without_reason`, `standards_path_not_resolved`, `standards_pin_mismatch`, `standards_cache_unreadable`, `standards_degraded_untrue`, `standards_consulted_absent`, `standards_consulted_mismatch`, `standards_plan_id_mismatch`, `standards_pair_missing`, `standards_orphan_summary`, `standards_anchor_malformed`). Reads `--stage` (04-03) and `--unpaired` (04-07, D-10); `ship:pre` sets `GATE_UNPAIRED=strict` unconditionally, `verify:post` sets it only on a full-phase run and leaves it unset when **either** partial-execution mode is active — the host's `WAVE_FILTER` set, or `--gaps-only` (04-12, CR-04; 04-18, WR-01) — and the other two leave the tolerant default | yes — `false` before any policy is read (inert), `false` with status `inactive` when `vault.enabled` is off and the phase holds no vault records, `true` once a standards record fails to validate; an agreeing degraded record with `vault.required` off is `false` with a message (D-29), and a recorded override is `false` at the tolerant points and `true` at the strict ones; `true` with status `disabled_with_artifacts` when `vault.enabled` is off and the positional's phase (or plan file) holds engine-written vault records (16-09, SEAL-02, D-21) — the answer the `ship:pre` seal gate dispatches for | `src/check-command-router.cts:2982,2994,2997,3029,3060,3085,3115,3141,3416` (04-16: CHECKED — a test asserts every line cited here lies inside `cmdVaultTrace` and carries a `block` emission, because four plans in this pass moved these numbers and nothing noticed). 16-07 (SEAL-01): at the strict points only, `appendSealProblems` compares the phase's recorded end anchors with `HEAD` through bounded git and adds `uncovered_source_commit` (a source commit after the ends that no record's start-end range covers), `anchor_missing`, `anchor_start_missing`, `anchor_unknown`, `anchor_not_ancestor` and `seal_could_not_check` (all blocking) and the `anchor_backfilled` note; it pushes problems into `checked` and owns no emission site and no status. 16-09 (SEAL-02): + the `disabled_with_artifacts` emission inside the switch-off guard. Standards-only vault: re-derived with the probe's own `handlerRange`/`emitsBlock` after the second record family, the invalid-config refusal and the envelope's mode tag left the handler. |
+| `verify.codebase-drift` | `verify-codebase-drift` branch (`verify.cmdVerifyCodebaseDrift`) | yes — `block = action_required` | `src/verify.cts:2134,2149,2164,2186,2231,2246` |
+| `verify.schema-drift` | `verify-schema-drift` branch (`verify.cmdVerifySchemaDrift`) | yes — `block = !skipped && driftDetected` | `src/verify.cts:2051,2071,2108` |
+
+**Footnote — the missing-field rule.** Every producer above emits a boolean `block` on every
+*successful* path today, but that is an observation, not a guarantee: a producer added later, or an
+`error()` early-return on a missing positional argument, can reach a caller with no `block` field at
+all. Therefore the verdict read below (in step 1's fence, printed for step 2) treats a **missing or
+non-boolean `block` as `false` (advisory)**. An
+absent field must never be coerced into a halt — a gate that stops the build because a producer
+forgot a key is a worse failure than the one it was trying to prevent. Producers that reach the
+enforcer through `error()` are *command* errors and are handled by step 1, never by step 2.
+
+## Guard — inactive capability, zero work
+
+Write this branch first, because it is what makes an inactive capability **structurally inert**:
+
+- If `GATE_HOOKS_JSON` is empty, unset, or its `activeHooks` array is missing or empty **and**
+  `GATE_DIRECT_QUERY` is unset, **skip silently and return to the caller.** Print nothing.
+
+A project whose capability is off never reaches any of the logic below. That is the whole inertness
+promise — not a suppressed message, an unreached code path.
+
+## The loop
+
+Process each entry of `activeHooks` where `kind == "gate"` **and** a `check.query` is present, in
+array order. Read `activeHooks` in-context; do not pipe it through a shell parser.
+
+A caller that handles a specific predicate itself — `ship.md` handles a `security` predicate branch
+above its generic loop — is expected to have handled or skipped that entry **before** Reading this
+file. This enforcer never sees it.
+
+For each hook, bind `GATE_QUERY` to `hook.check.query`, `GATE_BLOCKING` to `hook.blocking`, and
+`GATE_ONERROR` to `hook.onError` (absent means `skip`).
+
+## Step 1 — did the check COMMAND succeed?
+
+```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
+GATE_RESULT=$(pp_run check "${GATE_QUERY}" ${GATE_POSITIONAL_ARG:+"${GATE_POSITIONAL_ARG}"} ${GATE_POSITIONAL_ARG_2:+"${GATE_POSITIONAL_ARG_2}"} ${GATE_WS:+--ws} ${GATE_WS:+"${GATE_WS}"} ${GATE_STAGE:+--stage} ${GATE_STAGE:+"${GATE_STAGE}"} ${GATE_UNPAIRED:+--unpaired} ${GATE_UNPAIRED:+"${GATE_UNPAIRED}"} --raw)
+CHECK_EXIT=$?
+if [ "$CHECK_EXIT" -ne 0 ] || [ -z "$GATE_RESULT" ] || ! printf '%s' "$GATE_RESULT" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf-8'));if(j===null||typeof j!=='object')process.exit(1)" 2>/dev/null; then
+  echo "GATE_CHECK=failed"
+else
+  GATE_BLOCK=$(printf '%s' "$GATE_RESULT" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(String(JSON.parse(d).block===true));}catch{process.stdout.write('true');}")
+  GATE_MESSAGE=$(printf '%s' "$GATE_RESULT" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const m=JSON.parse(d).message;process.stdout.write(typeof m==='string'?m.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u0084\u0086-\u009F]/g,' ').replace(/\r\n|[\r\n\u0085\u2028\u2029]/g,'\n  '):'');}catch{process.stdout.write('');}")
+  echo "GATE_CHECK=ok"
+  echo "GATE_BLOCK=$GATE_BLOCK"
+  if [ -n "$GATE_MESSAGE" ]; then printf 'GATE_MESSAGE=%s\n' "$GATE_MESSAGE"; fi
+fi
+```
+
+Capture `$?` on the line immediately after the assignment — any command in between overwrites it.
+
+**This one fence runs the check AND reads its verdict, and it prints everything the prose below
+routes on** (16 review W-1, D-97). It prints exactly one of two shapes:
+
+- `GATE_CHECK=failed` — a **command** error (see below). Nothing else: no verdict is read.
+- `GATE_CHECK=ok`, then `GATE_BLOCK=true` or `GATE_BLOCK=false`, then — only when the envelope
+  carries a non-empty `message` — `GATE_MESSAGE=` followed by that message. The message is printed
+  last, so everything after `GATE_MESSAGE=` to the end of the output is the message, however many
+  lines it has. Every line of it after the first is indented by two spaces (each line break, `\r`
+  and Unicode line separator included, becomes a newline plus two spaces, and other control
+  characters become spaces), so no message line can begin with `GATE_` or with the halt token: the
+  verdict is the one `GATE_BLOCK=` line at column 0, and a message cannot print a second one (16
+  review iteration 3 WR-01).
+
+The verdict is computed here, in the shell that ran the check, for two measured reasons. **The
+engine:** this is the only fence in this file that carries the launcher preamble (the launcher
+generator keeps ONE preamble per file, in its first `pp_run` fence, and strips any other), so a
+`pp_run` in any later fence of this file, run as its own call, resolves whatever `pp_run` is on
+`PATH` — measured on a host with a global 1.14.0 engine there: the repo engine answered
+`disabled_with_artifacts, block: true`, the PATH engine answered `inactive`, and a blocking gate
+passed. **The parameters:** a second check call depends on the agent re-binding every `GATE_*`
+parameter for it; one that drops `GATE_UNPAIRED=strict` at `ship:pre` or `verify:post` re-runs a
+tolerant check, which skips SEAL-01, and the gate passes having checked less than step 1 did. Step 2
+therefore runs no command at all; it reads what this fence printed.
+
+Both positionals use the **conditional-expansion** idiom `${VAR:+"${VAR}"}` deliberately: an unset or
+empty variable expands to *no word at all*, not to an empty string. A bare `"${GATE_POSITIONAL_ARG_2}"`
+would hand every caller that leaves it unset an extra empty argument, which the router would read as a
+present-but-blank slot. The two must stay identical in form for that reason.
+
+`GATE_WS` uses the same idiom for the same reason, and it is a **flag pair** rather than a positional.
+A flag pair must be written as **two separate expansions** — `${GATE_WS:+--ws} ${GATE_WS:+"${GATE_WS}"}`
+— so that it emits both words or neither.
+
+**Do NOT collapse it to `${GATE_WS:+--ws "${GATE_WS}"}`.** That single-expansion form is bash-specific
+and fails SILENTLY elsewhere. POSIX and bash word-split the unquoted expansion into two arguments;
+**zsh does not**, so the whole thing arrives as one argument `--ws demo-ws`, which the router does not
+recognise as `--ws` and ignores. The gate then answers `status: unresolved / block: true /
+phase_unresolved` on a partitioned project — the exact symptom of the omitted-`--ws` defect this
+parameter exists to prevent, reintroduced at execution time rather than at authoring time. Reproduce
+with `set -- ${V:+--ws "$V"}`: bash reports `argc=2`, zsh reports `argc=1`.
+
+This matters because the shell that runs this line is the *dispatching agent's* shell, not this
+document's fence. Several runtimes (macOS Claude Code among them) execute tool commands under zsh.
+The two-expansion form is byte-identical in both shells, so it removes the dependency entirely.
+
+Written correctly, flat mode still produces a byte-identical
+command line to the one that shipped before this parameter existed. It is appended after the
+positionals so it can never occupy a positional slot — the router reads `--ws` by name, and a phase
+argument shifted into the wrong slot is the failure mode the two positionals above already warn about.
+
+`GATE_STAGE` is the third use of that idiom, and it carries the same two properties for the same two
+reasons: written as the two-expansion pair `${GATE_STAGE:+--stage} ${GATE_STAGE:+"${GATE_STAGE}"}` it
+emits both words or neither, so a caller that sets
+no stage produces a command line byte-identical to the one that shipped before this parameter
+existed — and it carries the same zsh hazard described above, where collapsing it to one expansion
+makes `--stage plan` arrive as a single ignored argument and silently reinstates the stage-blind
+collection defect; and it too is appended after both positionals, so it reaches every gate declared at the
+point without ever displacing a phase argument. A query with no `--stage` handling ignores an
+unrecognised named flag — which is what makes it safe to append to an invocation line that is shared
+by every gate at a loop point, not owned by the one that wanted it.
+
+`GATE_UNPAIRED` is the fourth use of that idiom and carries all three of the same properties, for
+the same three reasons: written as `${GATE_UNPAIRED:+--unpaired} ${GATE_UNPAIRED:+"${GATE_UNPAIRED}"}`
+it emits both words or neither, so a caller that sets no strictness produces a command line
+byte-identical to the one that shipped before this parameter existed; collapsing it to the single
+expansion `${GATE_UNPAIRED:+--unpaired "${GATE_UNPAIRED}"}` makes `--unpaired strict` arrive as one
+argument under zsh, which the router does not recognise, so the strict call sites would silently
+degrade to the tolerant default — a gate that reports success because its own flag was dropped; and
+it is appended after both positionals and after both other pairs, so it can never displace a phase
+argument at the three points that pass one.
+
+The command has failed when **any** of these holds: `CHECK_EXIT` is non-zero, `GATE_RESULT` is
+empty, or `GATE_RESULT` does not parse as a JSON object. The fence tests exactly that and prints
+`GATE_CHECK=failed`. That is a **command** error and *only* a command error — and so is a run that
+printed **no** `GATE_CHECK=` line at all (the fence died before it, e.g. the launcher found no
+engine): with nothing printed there is no verdict to read. Route it by the hook's `onError`:
+
+- `onError == "halt"` → fatal. Print
+  `⚠ Gate check command failed (${GATE_POINT} / ${GATE_QUERY}): command error. Resolve before continuing.`,
+  run the halt block below, and stop the host workflow.
+- `onError == "skip"` (or absent) → print
+  `⚠ Gate check skipped (${GATE_POINT} / ${GATE_QUERY}): check command error.`, move to the next
+  hook, and — this is an imperative, not a preference — **do NOT read a verdict.** The fence
+  prints none on this path, and none may be inferred.
+
+Merging these two steps is the fail-open this gate exists to close: if a non-zero exit were read as
+a verdict, `onError: skip` would swallow a genuine block as a command warning.
+
+## Step 2 — read the verdict
+
+Reached **only** when step 1 passed — that is, when it printed `GATE_CHECK=ok`. **Step 2 runs no
+command** — in particular it
+never runs `pp_run check` again. It reads the `GATE_BLOCK=` line and, when present, the
+`GATE_MESSAGE=` text that step 1's fence printed, and nothing else (step 1 explains why: a second
+check call would answer from whatever engine is on `PATH`, with whatever parameters were re-bound).
+The verdict therefore survives the agent's Bash tool starting a fresh shell for every call: what
+crosses from step 1 to step 2 is printed text, never a shell variable.
+
+Step 1 extracts the verdict with the same JSON round-trip idiom the sibling `vault-load-gate.md`
+uses. It deliberately uses `node -e` rather than a JSON command-line filter, because no such filter
+is a declared dependency of this project. The `.block === true` comparison **is** the missing-field
+rule from the audit footnote: a missing, null, string or numeric `block` all evaluate to `false`, so
+the fence prints `GATE_BLOCK=false` for them. (Its `catch` arm, which prints `true`, is unreachable
+behind the command-error test; it exists so that a future edit which removes that test fails closed.)
+
+- **`GATE_BLOCKING` is `true` AND `GATE_BLOCK` is `true` → HALT.** Print
+  `⚠ Gate blocked at ${GATE_POINT} (${GATE_QUERY}). Resolve before continuing.` and run the halt
+  block below.
+
+  **This halt is never bypassed by `onError`.** `onError` governs command errors from step 1 and
+  nothing else; it has no authority over the gate's own decision. A gate that reports a real block
+  and is then waved through by an error policy is not a gate.
+
+- **`GATE_BLOCKING` is `false` → never halt.** If `GATE_BLOCK` is `true`, print one advisory line:
+  `ℹ Gate advisory at ${GATE_POINT} (${GATE_QUERY}). Continuing.` Then continue to the next hook.
+
+- **`GATE_BLOCK` is `false` → continue.** No status line.
+
+**Output-independence rule (a later plan's byte-identical regression pin depends on this).** On
+every NON-halting path, the enforcer's printed output must be **identical** whether `GATE_BLOCKING`
+is `true` or `false`. `blocking` decides one thing only: whether a `true` block halts. It must never
+change what a passing or advisory verdict prints. Otherwise flipping a gate declaration from
+advisory to blocking would change output for projects whose policy key is off — exactly what the
+byte-identical-when-off promise forbids.
+
+## The halt mechanism (D-VH-7, option A — the workflow owns the exit)
+
+There are two halves and both ship, because they serve two different observers.
+
+**Half one — the named token, for the agent.** Print, on its own line:
+
+```
+PARETO_GATE_BLOCKED:${GATE_QUERY}
+```
+
+On seeing that token the agent stops the host workflow immediately, runs no further step, and
+reports the block to the user.
+
+**Half two — the process exit, for the runner.** In the *same* bash block:
+
+```bash
+echo "PARETO_GATE_BLOCKED:${GATE_QUERY}"
+exit 1
+```
+
+An unattended runner or CI job cannot honour a sentence; it can only observe an exit code. Without
+half two a blocked build reports success to the pipeline.
+
+`pp_run check` itself still **exits 0 on every path**, by design (`output()` in `src/io.cts` writes
+to fd 1 and returns; it never sets a non-zero code). That is deliberate and must not be "fixed":
+making the check command exit non-zero would turn every block into a step-1 command error, which
+`onError: skip` would then swallow. The exit code belongs to the workflow, not to the check.
+
+## Message passthrough
+
+Independently of status, and on **every** run including passes: if step 1 printed a
+`GATE_MESSAGE=` line, print it verbatim — the message is the text after `GATE_MESSAGE=`, to the end
+of step 1's output, its later lines indented by two spaces — it is already operator-ready, possibly
+multi-line text. A gate that has
+something to tell the operator says it on every run, not only when its verdict is bad. This rule is
+preserved word-for-word in effect from the ship.md loop this file replaced; a later plan makes both
+the vault gate's actionable block text and its success-path observability ride on it.
+
+## Direct-query mode
+
+Two entry points — the build entry point `fast` and the discovery sprint's
+`discovery-sprint/vault-context.md` subflow — declare no `gsd:loop-host` frontmatter at all. They
+have no rendered hooks, and adding points to them would bump the twelve-point loop-host contract.
+They are supported here rather than in a third copy of the halt logic. The count in this sentence is
+pinned against the `direct` rows of the Caller contract below, so a third caller must update both.
+(`execute-plan` left this mode in 16-10 and `quick` in 16-11: each renders its own loop points and
+filters the payload to the vault capability, so they are hook rows below.)
+
+When `GATE_HOOKS_JSON` is empty **and** `GATE_DIRECT_QUERY` is set to a query name, synthesise a
+single in-memory hook entry — that query, `blocking: true`, `onError: skip` — and run the identical
+loop above over it.
+
+**A direct caller must perform its own activation guard before Reading this file.** A synthesised
+hook has not been through the registry's `when` evaluation and therefore carries none of its
+inertness. The two guards such a caller must run first are:
+
+1. the **platform-bindings presence probe** (`pp_run query platform-bindings --pick present`; when
+   not `true`, do not Read this file at all — non-Pareto project, fully inert), and
+2. the **admission verb** (`pp_run vault admission`, D-28; `on` → Read this file, `off` or `inert`
+   → do not, anything else halts with `PARETO_GATE_BLOCKED:vault.admission`, D-05). Both direct
+   callers, `fast` (16-13) and the discovery subflow (16-04), run it.
+
+## Caller contract
+
+| Caller | Mode | Sets |
+|--------|------|------|
+| `pp-core/workflows/ship.md` step 6 | hook | `GATE_POINT=ship:pre`, `GATE_HOOKS_JSON=$SHIP_PRE_HOOKS_JSON`, `GATE_POSITIONAL_ARG="${PHASE_DIR}"`, `GATE_UNPAIRED=strict` — sets **no** `GATE_WS` (a directory carries the partition) and **no** `GATE_STAGE` (this point validates both stages). The positional was empty until 04-09; emptying it again makes a blocking `vault.trace` gate halt every ship on every vault-enabled project |
+| `pp-core/workflows/execute-phase/steps/execute-pre-dispatch.md` (dispatched by the host's execute:pre step) | hook | `GATE_POINT=execute:pre`, `GATE_HOOKS_JSON=$EXECUTE_PRE_HOOKS_JSON`, `GATE_POSITIONAL_ARG="${PHASE_NUMBER}"`, `GATE_WS=<workstream>` |
+| `pp-core/workflows/code-review-fix.md` `vault_admission_gate` (16-15) | hook | `GATE_POINT=execute:pre`, `GATE_HOOKS_JSON=$CRF_EXECUTE_PRE_HOOKS_JSON` (the door's own `execute:pre` render, filtered in the fence to the vault capabilities, D-30), after its own admission fence and before its agent writes source. Sets **no** positional, **no** `GATE_WS` and **no** `GATE_STAGE`: `vault.status` reads project state |
+| `pp-core/workflows/validate-phase.md` § 0.5 (16-15) | hook | `GATE_POINT=execute:pre`, `GATE_HOOKS_JSON=$VP_EXECUTE_PRE_HOOKS_JSON` (the door's own `execute:pre` render, filtered in the fence to the vault capabilities, D-30), after its own admission fence and before its agent writes source. Sets **no** positional, **no** `GATE_WS` and **no** `GATE_STAGE`: `vault.status` reads project state |
+| `pp-core/workflows/add-tests.md` `vault_admission_gate` (16-15) | hook | `GATE_POINT=execute:pre`, `GATE_HOOKS_JSON=$AT_EXECUTE_PRE_HOOKS_JSON` (the door's own `execute:pre` render, filtered in the fence to the vault capabilities, D-30), after its own admission fence and before its agent writes source. Sets **no** positional, **no** `GATE_WS` and **no** `GATE_STAGE`: `vault.status` reads project state |
+| `pp-core/workflows/audit-fix.md` `vault_admission_gate` (16-15) | hook | `GATE_POINT=execute:pre`, `GATE_HOOKS_JSON=$AF_EXECUTE_PRE_HOOKS_JSON` (the door's own `execute:pre` render, filtered in the fence to the vault capabilities, D-30), after its own admission fence and before its agent writes source. Sets **no** positional, **no** `GATE_WS` and **no** `GATE_STAGE`: `vault.status` reads project state |
+| `pp-core/workflows/execute-phase.md` step 5.75 | hook | `GATE_POINT=execute:wave:post`, `GATE_HOOKS_JSON=$WAVE_POST_HOOKS_JSON`, `GATE_POSITIONAL_ARG="${PHASE_NUMBER}"`, `GATE_WS=<workstream>` |
+| `pp-core/workflows/execute-phase.md` execute:post step | hook | `GATE_POINT=execute:post`, `GATE_HOOKS_JSON=$EXECUTE_POST_HOOKS_JSON`, `GATE_POSITIONAL_ARG="${PHASE_NUMBER}"`, `GATE_WS=<workstream>` — sets **no** `GATE_STAGE`, deliberately: this is the point that validates both stages |
+| `pp-core/workflows/execute-phase/steps/verify-post-gate.md` (dispatched by TWO callers: the host's end-of-phase verification step, and `verify-work.md`'s issues-are-zero branch, which exposes no partial-execution mode and is therefore always strict) | hook | `GATE_POINT=verify:post`, `GATE_HOOKS_JSON=$VERIFY_POST_HOOKS_JSON`, `GATE_POSITIONAL_ARG="${PHASE_DIR}"`, and `GATE_UNPAIRED=strict` **only on a full-phase run: when the host's `WAVE_FILTER` is unset AND the invocation carried no `--gaps-only`** — on a `--wave N` or a `--gaps-only` run it leaves `GATE_UNPAIRED` unset so the tolerant default applies, because a partially-executed run legitimately leaves untouched plans unexecuted and this dispatch runs BEFORE the host's `handle_partial_wave_execution` step, so an unconditional strict verdict here halted every partial run on every vault-enabled project (04-12, CR-04; 04-18 WR-01 widened the step file's condition to `--gaps-only`, and this row named `WAVE_FILTER` alone until 260912-kz7 — a stale row is a lie the next author implements). This is the one conditional strictness in the table, and the condition is deliberate: unlike `ship:pre`, whose preflight requires a passed verification and therefore admits no partial run, this point is reachable in a mode where an unpaired plan is the correct state. Sets **no** `GATE_WS` (a directory carries the partition) and **no** `GATE_STAGE`, deliberately, exactly as `execute:post` omits it: this point validates both stages. The body lives in a step file because the host is under a phase-6 ratchet that is never re-baselined (D-05) |
+| `pp-core/workflows/plan-phase.md` §13e | hook | `GATE_POINT=plan:post`, `GATE_HOOKS_JSON=$PLAN_POST_HOOKS_JSON`, `GATE_POSITIONAL_ARG="${PHASE_DIR}"`, `GATE_POSITIONAL_ARG_2="${PHASE_REQ_IDS}"`, `GATE_WS=<workstream>`, `GATE_STAGE=plan` — the only caller using the second positional, and the only one setting a stage |
+| `pp-core/workflows/plan-phase.md` plan:pre vault gate | hook | `GATE_POINT=plan:pre`, `GATE_HOOKS_JSON=$PLAN_PRE_HOOKS_JSON` — skips `ui.plan-gate`, which §5.6 above already ran with its own phase positional and whose outcome it owns. `GATE_POSITIONAL_ARG` is left **empty** deliberately: `vault.status` reads project state, not a phase, and every remaining gate at this point that needs a positional is caller-handled (D-VH-7). Sets **no** `GATE_WS` (there is no phase-number positional to resolve) and **no** `GATE_STAGE`. Handing the whole payload here with no skip made the enforcer issue `check ui.plan-gate` with no argument; `onError: halt` turned that command error into a hard stop on every vault-enabled plan run, before the vault verdict was read (02-09, G-1) |
+| `pp-core/workflows/autonomous.md` §3a.5-iii | hook | `GATE_POINT=plan:pre`, `GATE_HOOKS_JSON=$HOOKS_JSON` — skips `ui.plan-gate`, which §3a.5-ii above owns on every activation set that renders it, the gate-only set (`ui_phase=false` + `ui_safety_gate=true`) included. `GATE_POSITIONAL_ARG` is left **empty** deliberately, for the same reason as the `plan-phase.md` plan:pre row. Sets **no** `GATE_WS` and **no** `GATE_STAGE`. The skip is sound only because §3a.5-ii's run trigger covers the gate-only set — an unconditional skip without that trigger would leave a `blocking: true` gate enforced by nobody under `--auto` (02-09, T-02-41) |
+| `pp-core/workflows/quick.md` Step 2.4 (16-11) | hook | `GATE_POINT=plan:pre`, `GATE_HOOKS_JSON=$QUICK_PLAN_PRE_HOOKS_JSON` (its own `plan:pre` render, filtered in the fence to the `vault` capability, D-30, so no `ui.plan-gate` reaches the enforcer), after its own admission fence. `GATE_POSITIONAL_ARG` is left **empty** deliberately (`vault.status` reads project state); sets **no** `GATE_WS` and **no** `GATE_STAGE`. Quick's `execute:pre` render feeds only the executor prompt's fragments, never a gate |
+| `pp-core/workflows/debug.md` § 0b (16-14) | hook | `GATE_POINT=plan:pre`, `GATE_HOOKS_JSON=$DEBUG_PLAN_PRE_HOOKS_JSON` (its own `plan:pre` render, filtered in the fence to the `vault` capability, D-30), after its own admission fence and before either session-manager spawn. `GATE_POSITIONAL_ARG` is left **empty** deliberately (`vault.status` reads project state); sets **no** `GATE_WS` and **no** `GATE_STAGE` |
+| `pp-core/workflows/quick.md` Step 5.55 (16-11) | hook | `GATE_POINT=plan:post`, `GATE_HOOKS_JSON=$QUICK_PLAN_POST_HOOKS_JSON` (filtered the same way), `GATE_POSITIONAL_ARG="${QUICK_DIR}"`, `GATE_STAGE=plan` — before Step 5.6's plan commit and the executor spawn (D-34). Sets **no** `GATE_WS`: a quick directory carries its partition |
+| `pp-core/workflows/quick.md` Step 6.1 (16-11) | hook | `GATE_POINT=execute:post`, `GATE_HOOKS_JSON=$QUICK_EXECUTE_POST_HOOKS_JSON` (filtered the same way), `GATE_POSITIONAL_ARG="${QUICK_DIR}"`, `GATE_UNPAIRED=strict` (one plan, one SUMMARY, nothing pending, D-03) — before the STATE.md row and the final commit (D-34). Sets **no** `GATE_STAGE` and **no** `GATE_WS` |
+| `pp-core/workflows/fast.md` (plan 02-05; admission on the verb since 16-13) | direct | `GATE_POINT=fast:pre`, `GATE_DIRECT_QUERY=vault.status`, own activation guards (the bindings probe, then `vault admission`); with the vault on, `fast` also refuses edits outside `.planning/` and backstops its commit (D-07) |
+| `pp-core/workflows/execute-plan.md` `vault_admission_gate` (16-10) | hook | `GATE_POINT=execute:pre`, `GATE_HOOKS_JSON=$EXECUTE_PRE_HOOKS_JSON` (its own `execute:pre` render, filtered in the fence to the `vault` capability, D-30), after its own admission fence. Sets **no** positional, **no** `GATE_WS` and **no** `GATE_STAGE`: `vault.status` reads project state |
+| `pp-core/workflows/execute-plan.md` `vault_trace_gate` (16-10) | hook | `GATE_POINT=plan:post`, `GATE_HOOKS_JSON=$PLAN_POST_HOOKS_JSON` (its own `plan:post` render, filtered the same way), `GATE_POSITIONAL_ARG="$PLAN_PATH"` (the ONE `*-PLAN.md` file this run executes, never its phase directory, D-06), `GATE_STAGE=plan`. Sets **no** `GATE_WS`: the file carries its partition |
+| `pp-core/workflows/discovery-sprint/vault-context.md` (plan 11-03) | direct | `GATE_POINT=discovery:pre`, `GATE_DIRECT_QUERY=vault.status`, own activation guards; Read from the discovery sprint's Flow 2 Step 1 and prefill Step 0 only, never from a read-only arm (D-11-12); runs `vault-fetch.md` in direct mode FIRST, so both `plan:pre` halt surfaces are inherited in their order (D-11-11); `discovery:pre` is a message label, not a loop point — `GATE_POINT` never changes control flow, which is what makes a non-canonical label safe here |

package/pp-core/workflows/execute-phase/steps/client-context-gate.md

@@ -10,12 +10,13 @@ out of scope here.
 
 ```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
-CTX_GATE_PRESENT=$(pp_run query platform-bindings --pick present 2>/dev/null || echo false)
+CTX_GATE_PRESENT=$(pp_run query platform-bindings --pick present 2>/dev/null || echo true)
 CTX_BLOCK=$(pp_run query generate-client-context --read 2>/dev/null || echo '{"present":false}')
 CTX_BLOCK_PRESENT=$(printf '%s' "$CTX_BLOCK" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(String((JSON.parse(d).present)||false));}catch{process.stdout.write('false');}")
 ```
 
-**If `CTX_GATE_PRESENT` != `true`:** skip entirely (non-Pareto project — fully inert).
+**If `CTX_GATE_PRESENT` != `true`:** skip entirely (non-Pareto project — fully inert). A probe that
+cannot answer (a malformed bindings file) reads as present, as `hasPlatformBindings` does (D-47 b).
 
 **If `CTX_GATE_PRESENT` == `true` and `CTX_BLOCK_PRESENT` == `true`:** the client-context
 block exists and is on the executor's read path. Surface a one-line confirmation

package/pp-core/workflows/execute-phase/steps/cross-ai-delegation.md

@@ -5,7 +5,7 @@ unchanged; the host now lazily Reads it.
 
 **Why it moved.** Phase 9's W-1 fix gave this step's `portable-timeout.sh` source the same
 resolve-then-check shape the other eight sites use, which grew `execute-phase.md` by 417 bytes to
-94088. That passed `tests/workflow-size-baseline.json` after a conscious re-baseline, but a SECOND
+93943. That passed `tests/workflow-size-baseline.json` after a conscious re-baseline, but a SECOND
 and independent ratchet — `tests/phase6-capstone-conformance.test.cjs:207`, the ADR-857 shrink
 ratchet — asserts `execute-phase.md` stays strictly **under 93600**, and it was never re-baselined
 because it is not supposed to be: its whole purpose is that the host loop body only ever shrinks.

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

@@ -0,0 +1,78 @@
+# `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 record the 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 `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. 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