@pareto4/pp-core 1.13.0 → 1.18.0

package/pp-core/workflows/ship.md

@@ -89,16 +89,22 @@ Verify the work is ready to ship:
 
    Resolve active `ship:pre` gate hooks from the capability registry — the registry evaluates each hook's `when` condition, so do **not** read `workflow.security_enforcement` directly:
 
+   Admission first (D-28, D-05): a config the gate cannot read renders no ship:pre vault gate at all, so this runs before the render; without bindings it is inert.
+
    ```bash
-   SHIP_PRE_HOOKS_JSON=$(pp_run loop render-hooks ship:pre --raw --phase "${phase_number}") || exit 1
-   TRACE_GATE_JSON=$(pp_run loop run-gates ship:pre --phase "${phase_number}" --query vault.trace) || exit 1
-   AUDIT_GATE_JSON=$(pp_run loop run-gates ship:pre --phase "${phase_number}" --query vault.audit) || exit 1
-   SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
+   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
    ```
 
-   The `run-gates` lines run the blocking `vault.trace` and `vault.audit` gates and own their halt: exit 1 (a `⛔` line) stops the ship — relay it verbatim; do not push or open the PR.
+   ```bash
+   SHIP_PRE_HOOKS_JSON=$(pp_run loop render-hooks ship:pre --raw)
+   printf '%s' "$SHIP_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('SHIP_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
+   SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
+   ```
 
-   Read the `activeHooks` array from `SHIP_PRE_HOOKS_JSON` in-context (do NOT pipe it through a shell parser).
+   Read the `activeHooks` array from the `SHIP_PRE_HOOKS_JSON=` line the fence printed, in-context (do NOT pipe it through a shell parser).
 
    If an active entry exists with `kind == "gate"`, `capId == "security"`, and `blocking == true`, enforce its predicate (`SECURITY.md` frontmatter `threats_open == 0`) before shipping:
 
@@ -117,27 +123,50 @@ Verify the work is ready to ship:
 
    **Generic `check.query` gate enforcement (capability-driven).**
 
-   For each active entry in `activeHooks` where `kind == "gate"` and a `check.query` is present (covers any capability-registered query gate, e.g. the `pareto-stack` platform-drift gates — skip entries already handled by the `security` predicate branch above, and `vault.trace` and `vault.audit`, run above):
-
-   ```bash
-   GATE_RESULT=$(pp_run check ${hook.check.query} --raw)
-   CHECK_EXIT=$?
-   ```
-
-   - If `CHECK_EXIT` is non-zero or output is unparseable: if `hook.onError == "skip"` (the default for all capability-registered query gates), log a warning and continue to the next hook.
-   - Read `status` from `GATE_RESULT`:
-     - If `hook.blocking == true` and `status == "block"` → halt the ship with `PARETO_DRIFT_SHIP_GATE_BLOCKED`:
-       ```
-       ⚠ Ship gate blocked: {hook.check.query} reports a drift condition that exceeds the configured threshold.
-       Pinned: {GATE_RESULT.pinned} — Latest: {GATE_RESULT.latest}
-       Update .platform-bindings.json or adjust the block threshold before shipping.
-       ```
-     - If `hook.blocking == false`, or `status` is `warn`, `pass`, or `inert` → emit an advisory line for non-trivial statuses (`warn` only) and continue:
-       ```
-       ℹ Ship gate advisory ({hook.check.query}): {status}{GATE_RESULT.severity ? ` — ${GATE_RESULT.severity} drift detected` : ''} (non-blocking or below blocking threshold). Continuing.
-       ```
-     - If `status` is `pass` or `inert`: continue silently.
-     - Independently of the status arms above, if `GATE_RESULT.message` is a non-empty string, print it verbatim — it is already operator-ready, possibly multi-line text — then continue: a gate that has something to tell the operator says it on every run, not only when its status is a warning.
+   > **Two behaviour changes landed here (GATE-02).** (1) Ship's gate enforcement now reads the
+   > boolean `block` field instead of `status == "block"`; every declared `check.query` producer in
+   > the repo was audited for that field and the audit table lives in the enforcer sub-file.
+   > (2) `onError: halt` now actually works at `ship:pre` — it was declared-but-unimplemented here
+   > before.
+
+   The `security` predicate branch above is handled *before* this generic loop, so the enforcer
+   never sees that entry.
+
+   For every remaining active entry in `activeHooks` where `kind == "gate"` and a `check.query` is
+   present (covers any capability-registered query gate, e.g. the `pareto-stack` platform-drift
+   gates), set `GATE_POINT=ship:pre`, `GATE_HOOKS_JSON=$SHIP_PRE_HOOKS_JSON`,
+   `GATE_POSITIONAL_ARG="${PHASE_DIR}"` and `GATE_UNPAIRED=strict`, 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 two-step contract (did the command succeed? → then
+   read the boolean `block`), the halt, and the unconditional `message` passthrough. Do not restate
+   its loop here.
+
+   **The positional is `${PHASE_DIR}`, and emptying it again is an outage.** It was empty until
+   04-09. A gate declared `blocking: true` and handed no positional answers its `no-argument`
+   verdict with `block: true`, so an empty positional halts EVERY ship on EVERY vault-enabled
+   project, unconditionally and for every phase — the denial of service the gate exists to prevent,
+   shipped by the gate itself. `PHASE_DIR` is already parsed from `INIT` above and already used
+   twice before this loop, which is why the correction costs one token.
+
+   Set **no** `GATE_WS` here. A phase **directory** already carries the workstream partition — the
+   enforcer's own parameter table says so — so adding a workstream flag would not make this call
+   safer; it would add a fifth opportunity for the omitted-workstream defect this project has
+   already shipped four times. `GATE_UNPAIRED=strict` because ship is one of the two points at
+   which every plan must have an executed counterpart; mid-wave points stay tolerant.
+
+   **After the gate loop, certify the phase's end anchors.** The enforcer halts on a blocking
+   verdict, so this is reached only when it let the ship go on; nothing here assumes the phase is
+   clean from that. Run `pp_run vault anchor certify "${PHASE_DIR}" --raw` with the same
+   `${PHASE_DIR}` positional the gate loop used, print its one-line result, and continue regardless.
+   A ship run is a full-phase run by construction (see above), so there is no partial-run condition
+   here. The verb re-runs `check vault.trace "${PHASE_DIR}" --unpaired strict` itself and records
+   each SUMMARY's end anchor in the directory's `.vault-certificates.json` only when that check
+   answers clean with no override, so this step can never certify what the gate did not pass
+   (D-107, D-108). A skipped or failed step certifies nothing, which only widens the next phase's
+   SEAL-01 reach and never hides a commit (D-110). The verb prints nothing unless `vault admission`
+   answers `on`, so print nothing yourself then either. Every result (a certificate, `kept`, or a
+   refusal such as `not-clean` or `overridden`) is printed, never retried, and never halts the ship.
+   No bash fence.
 </step>
 
 <step name="push_branch">
@@ -452,7 +481,7 @@ pp_run query commit "docs(${padded_phase}): ship phase ${PHASE_NUMBER} — PR #$
 > Capability-driven dispatch. Resolves active `ship:post` hooks via the capability registry; each hook's `when` is evaluated by the registry — no inline `config-get`. All `ship:post` hooks are post-ship and additive (`onError: skip`); a failure here never affects the already-created PR.
 
 ```bash
-SHIP_POST_HOOKS_JSON=$(pp_run loop render-hooks ship:post --raw) || exit 1
+SHIP_POST_HOOKS_JSON=$(pp_run loop render-hooks ship:post --raw)
 ```
 
 Read the `activeHooks` array directly from `SHIP_POST_HOOKS_JSON` in-context (do NOT pipe it through a shell parser).

package/pp-core/workflows/undo.md

@@ -75,7 +75,7 @@ Parse the user's selection into COMMITS list.
 
 **MODE=phase:**
 
-Read `.planning/.phase-manifest.json` if it exists (execute-phase writes it with `pp_run phase manifest start|record`).
+Read `.planning/.phase-manifest.json` if it exists.
 
 If the file exists and `manifest.phases?.[TARGET_PHASE]?.commits` is a non-empty array:
   - Use `manifest.phases[TARGET_PHASE].commits` entries as COMMITS (each entry is a commit hash)

package/pp-core/workflows/update.md

@@ -192,8 +192,8 @@ Exit.
 
 ```bash
 CHANGELOG_TMP="/tmp/pp-changelog-$$.md"
-curl -fsSL "https://gitlab.com/pareto4/pp-core/-/raw/main/CHANGELOG.md" -o "$CHANGELOG_TMP" 2>/dev/null \
-  || wget -qO "$CHANGELOG_TMP" "https://gitlab.com/pareto4/pp-core/-/raw/main/CHANGELOG.md" 2>/dev/null
+curl -fsSL "https://raw.githubusercontent.com/pareto000/pp-core/main/CHANGELOG.md" -o "$CHANGELOG_TMP" 2>/dev/null \
+  || wget -qO "$CHANGELOG_TMP" "https://raw.githubusercontent.com/pareto000/pp-core/main/CHANGELOG.md" 2>/dev/null
 
 GSD_CHANGESET_CLI="$GSD_DIR/scripts/changeset/cli.cjs"
 if [ ! -f "$GSD_CHANGESET_CLI" ]; then
@@ -468,7 +468,7 @@ Format completion message (changelog was already shown in confirmation step):
 
 ⚠️  Restart your runtime to pick up the new commands.
 
-[View full changelog](https://gitlab.com/pareto4/pp-core/-/blob/main/CHANGELOG.md)
+[View full changelog](https://github.com/pareto000/pp-core/blob/main/CHANGELOG.md)
 ```
 </step>
 

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

@@ -30,7 +30,7 @@ Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
 
 ```bash
 AUDITOR_MODEL=$(pp_run query resolve-model pp-nyquist-auditor --raw)
-VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw) || exit 1
+VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw)
 ```
 
 Resolve active step hooks from `VERIFY_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "validate-phase"`.
@@ -39,6 +39,36 @@ If no active validate-phase step hook exists: exit with "Nyquist validation is d
 
 Display banner: `pp-core > VALIDATE PHASE {N}: {name}`
 
+## 0.5 Vault admission and load gate
+
+Vault admission and load gate (D-11, D-12, D-28): runs before the auditor writes or commits a test. A config the gate cannot
+read halts here with the bindings present (D-05); without bindings, or with `vault.enabled` false,
+nothing below prints or writes anything (D-13).
+
+```bash
+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 the fence printed no `VAULT_ADMIT=on` line** (`off` and `inert` print nothing): skip the rest of this block silently. Otherwise run the load
+gate on the `execute:pre` payload, filtered in the fence to the `vault`
+capability (D-30):
+
+```bash
+VP_EXECUTE_PRE_HOOKS_JSON=$(pp_run loop render-hooks execute:pre --raw | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const j=JSON.parse(d);j.activeHooks=(j.activeHooks||[]).filter((x)=>x&&x.capId==='vault');process.stdout.write(JSON.stringify(j));}catch{process.stdout.write('');}")
+printf '%s' "$VP_EXECUTE_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('VP_EXECUTE_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
+```
+
+Set `VAULT_FETCH_HOOKS_JSON=$VP_EXECUTE_PRE_HOOKS_JSON`, then Read and execute
+`pp-core/workflows/execute-phase/steps/vault-fetch.md` (hook mode). Then, in the
+`VP_EXECUTE_PRE_HOOKS_JSON=` line that fence printed, find active entries where `kind == "gate"` and `check.query ==
+"vault.status"`; if none, skip silently. Otherwise set `GATE_POINT=execute:pre` and
+`GATE_HOOKS_JSON=$VP_EXECUTE_PRE_HOOKS_JSON`, leave `GATE_POSITIONAL_ARG`, `GATE_WS` and
+`GATE_STAGE` empty, then Read and follow `pp-core/workflows/execute-phase/steps/check-query-gate.md`;
+it owns the halt.
+
 ## 1. Detect Input State
 
 ```bash
@@ -97,9 +127,17 @@ Call AskUserQuestion with gap table and options:
 2. "Skip — mark manual-only" → add to Manual-Only, Step 6
 3. "Cancel" → exit
 
-## 4b. Vault door gate
+### Door START anchor (before the auditor spawn)
 
-Before the auditor writes tests, Read and execute `pp-core/workflows/execute-phase/steps/vault-door-gate.md`; a stop ends validation with no test written.
+Then record the door's START anchor, before the `pp-nyquist-auditor` spawn (D-31):
+
+```bash
+pp_run vault door-record --begin --door validate-phase --raw
+```
+
+It records HEAD in `.planning/.vault-door-starts.json`, where the record step reads it back: a shell
+variable would not survive into that later step, and the agent never types a sha. It prints nothing
+and writes nothing unless `vault admission` answers `on`.
 
 ## 5. Spawn pp-nyquist-auditor
 
@@ -155,6 +193,23 @@ git commit -m "test(phase-${PHASE}): add Nyquist validation tests"
 pp_run query commit "docs(phase-${PHASE}): add/update validation strategy"
 ```
 
+Vault door record (D-12), only when Step 5 ran: after the door's last source commit, set `DOOR_DIR="${PHASE_DIR}"`,
+`DOOR_PADDED="${PADDED_PHASE}"` and `DOOR_PHASE="${PHASE}"`, then run:
+
+```bash
+DOOR_RUN=$(date -u +%Y%m%dT%H%M%SZ)
+pp_run vault door-record --door validate-phase --artifact "${DOOR_DIR}/${DOOR_PADDED}-door-${DOOR_RUN}-ADD-TESTS.md" --phase "$DOOR_PHASE" --raw
+```
+
+The verb writes a `## Vault Door Record` (mode, vault ref and sha, governing phase, the start `--begin`
+recorded and the end commit; the agent never types a sha) into a fresh per-run artifact, because it refuses a second record
+in one file (D-57) and a rewritten report would drop the earlier run's coverage (D-79). It prints
+nothing and writes nothing unless `vault admission` answers `on`. When it wrote the file and
+`commit_docs` is true, commit the `artifact` path it printed: `pp_run query commit "docs(phase-${PHASE}): vault door record for validate-phase" --files "<that artifact>"`.
+
+(A per-run `-VALIDATION.md` name would be read as the phase's validation strategy by the `*-VALIDATION.md`
+globs, so validate-phase's record uses the `-ADD-TESTS.md` suffix: what it records is the tests it added.)
+
 ## 8. Results + Routing
 
 **Compliant:**

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

@@ -1,65 +1,203 @@
 <purpose>
-Retroactive client-vault practice review of a built phase: one agent-judged verdict (PASS / FAIL /
-N-A / INCONCLUSIVE) per practice the vault audit cannot check, in `{padded}-VAULT-REVIEW.md`. It
-reports and never gates: no verdict changes a status, a score, a route or a ship.
+Retroactive review of a completed phase against the client vault's standards documents. Works on
+any phase whose plans carry a `<vault_standards>` block. Produces `{padded}-VAULT-REVIEW.md` with one
+verdict per standards document that governed the phase, and counts by verdict. This workflow
+reports; it gates nothing.
 </purpose>
 
 <available_agent_types>
 Valid pp-core subagent types (use exact names — do not fall back to 'general-purpose'):
-- pp-vault-reviewer — judges the practices the CLI could not settle
+- pp-vault-reviewer — Judges whether the phase's changes conform to each governing standards document
 </available_agent_types>
 
 <process>
 
-## 1. Scaffold
+## 0. Initialize
 
 ```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
 INIT=$(pp_run query init.phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+AGENT_SKILLS_VAULT_REVIEWER=$(pp_run query agent-skills pp-vault-reviewer)
 ```
 
-Parse `phase_dir`, `phase_number`, `phase_name`, `padded_phase`, `text_mode`. A phase with no
-`*-SUMMARY.md` is not built: say "Phase {N} not executed — run /pp-execute-phase {N} first." and stop.
+Parse: `phase_dir`, `phase_number`, `phase_name`, `padded_phase`, `commit_docs`.
+
+### 0a. Derive first, and stop when there is nothing to review
+
+```bash
+REVIEW_PAYLOAD=$(pp_run check vault-review "${PHASE_DIR}" --raw)
+REVIEW_STATUS=$(printf '%s' "${REVIEW_PAYLOAD}" | node -e "let s='';process.stdin.on('data',d=>{s+=d}).on('end',()=>{try{console.log(JSON.parse(s).status||'')}catch{console.log('unparseable')}})")
+```
+
+| `REVIEW_STATUS` | What happens |
+|---|---|
+| `inert` | The vault is off for this project. Print the payload's `statement` and stop. Nothing is written. |
+| `no-argument`, `usage`, `unresolved` | Print the `statement` and stop: the CLI could not use the phase argument. Re-run with the phase directory. |
+| `no-records` | Print the `statement` and stop: no plan in this phase was governed by a standards document. |
+| `ok` | Continue. |
+
+This workflow never reads `vault.enabled` itself; the CLI is the one place that decides whether the
+vault applies.
+
+Then display the banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ pp-core ► VAULT STANDARDS REVIEW — PHASE {N}: {name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 1. Detect Input State
 
 ```bash
-SCAFFOLD=$(pp_run vault review scaffold "${PHASE_DIR}" ${FORCE:+--force} --raw)
+SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
+VAULT_REVIEW_FILE=$(ls "${PHASE_DIR}"/*-VAULT-REVIEW.md 2>/dev/null | head -1)
 ```
 
-Branch on its `status`:
-- `inert`, `usage`, `no-argument`, `unresolved` — print its `statement` and stop; nothing is written.
-- `exists` — ask "Re-review" (set `FORCE=1`, scaffold again) or "View" (show the file, stop), with
-  AskUserQuestion, or as a numbered list when `--text` is in `$ARGUMENTS` or `text_mode` is true.
-- `written` — continue. With `toJudge` 0 there is nothing to judge: go to step 3.
+- **State A** (`VAULT_REVIEW_FILE` non-empty): a review already exists. Re-review, and append a dated
+  block to the artifact's Audit Trail rather than discarding the previous one.
+- **State B** (`SUMMARY_FILES` non-empty): the phase is completed. Run the review.
+- **State C** (`SUMMARY_FILES` empty): exit cleanly with "Phase {N} not executed. Run
+  `/pp:execute-phase {N}` first."
 
-## 2. Judge
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+
+**In State A**, use AskUserQuestion:
+- header: "Existing Vault Review"
+- question: "VAULT-REVIEW.md already exists for Phase {N}."
+- options:
+  - "Re-review — run a fresh review and append to the audit trail"
+  - "View — display the current review and exit"
+
+If "View": display the file, exit. If "Re-review": continue.
+
+## 2. What the payload gives the reviewer
+
+The payload is the CLI's derivation and is passed to the agent verbatim; this workflow does not
+reinterpret it.
+
+- `documents[]`: every standards document that governed a plan in this phase, with `cachePath` (the
+  cached copy to read; `null` when it is not cached) and `governed[]` (each plan it governed, the
+  planner's `reason`, and the executor's `consulted` status).
+- `plans[]`: each plan's record files, its commit `range`, and the source `files` changed in that
+  range (`filesTruncated` when the list was capped).
+- `gaps[]`: facts the CLI could not establish. Every gap goes into the artifact's `## Not Derived`
+  section; a gap is never silently dropped and never turned into a verdict.
+
+## 3. Spawn pp-vault-reviewer
+
+```bash
+REVIEWER_MODEL=$(pp_run query resolve-model pp-vault-reviewer --raw)
+```
 
 ```
 ◆ Spawning vault reviewer... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 ```
 
+Build the prompt:
+
+```
+<objective>
+Review Phase {N}: {phase_name} against the client vault's standards documents. Give exactly one
+verdict per document in the payload's documents[]: PASS, FAIL, N-A or INCONCLUSIVE, each non-PASS
+verdict with a stated reason, and evidence as file:line references into the phase's changed files.
+Write exactly one file: {phase_dir}/{padded_phase}-VAULT-REVIEW.md
+</objective>
+
+<review_payload>
+{REVIEW_PAYLOAD verbatim}
+</review_payload>
+
+<required_reading>
+- {summary_paths} (Execution summaries)
+- {plan_paths} (Execution plans)
+- {context_path} (User decisions, if it exists)
+</required_reading>
+
+${AGENT_SKILLS_VAULT_REVIEWER}
+
+<config>
+phase_dir: {phase_dir}
+padded_phase: {padded_phase}
+</config>
+```
+
+Omit null file paths.
+
 ```
 Agent(
+  prompt=vault_review_prompt,
   subagent_type="pp-vault-reviewer",
-  model="{pp_run query resolve-model pp-vault-reviewer --raw}",
-  description="Vault practice review Phase {phase_number}",
-  prompt="Fill the TODO rows of {phase_dir}/{padded_phase}-VAULT-REVIEW.md (Phase {phase_number}: {phase_name})."
+  model="{REVIEWER_MODEL}",
+  description="Vault standards review Phase {N}"
 )
 ```
 
-## 3. Finalize
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
+
+## 4. Handle Return
+
+The agent returns `## REVIEWED` or `## ESCALATE`. On `REVIEWED`, check what it wrote:
 
 ```bash
-pp_run vault review finalize "${PHASE_DIR}"
+pp_run check vault-review "${PHASE_DIR}" --validate "${PHASE_DIR}/${PADDED_PHASE}-VAULT-REVIEW.md" --raw
+```
+
+`valid: true` means every governing document has exactly one verdict row, each verdict is one of the
+four, every non-PASS verdict states its reason, and the counts line agrees with the table. Otherwise
+list each entry of `problems[]` to the operator as a repair item. A problem is repaired in the
+artifact, never by deleting the row that produced it. Exit 0 either way.
+
+`ESCALATE` means no artifact could be written. Report what the agent said and stop; still exit 0.
+
+Display the summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ pp-core ► VAULT STANDARDS REVIEW COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase {N}: {Name}**
+
+{the artifact's counts line}
+
+Gaps reported: {none. / the payload's gaps}
+
+Full review: {path to VAULT-REVIEW.md}
+
+This review reports and does not gate. No verdict above changes a phase status,
+a gap or any gate.
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next
+
+`/clear` then one of:
+
+- `/pp:verify-work {N}` — UAT testing
+- `/pp:plan-phase {N+1}` — plan next phase
+
+───────────────────────────────────────────────────────────────
 ```
 
-Print its output. If it lists repair items, send them to the reviewer once ("Fix these repair items
-in {file}: …") and finalize again. Never clear an item by editing a computed line or a derived row.
+The routing is offered on every path; a review with FAIL rows routes exactly like one without. No
+step reads a verdict into a halt, an exit code or a block, and nothing here writes `ROADMAP.md`,
+`STATE.md`, `VERIFICATION.md` or a `SUMMARY.md`. The one file this command produces is the artifact.
 
-Route the same way whatever the verdicts: `/pp-verify-work {N}` or `/pp-plan-phase {N+1}`. Commit:
+## 5. Commit (if configured)
 
 ```bash
-pp_run query commit "docs(${PADDED_PHASE}): vault practice review" --files "${PHASE_DIR}/${PADDED_PHASE}-VAULT-REVIEW.md"
+pp_run query commit "docs(${PADDED_PHASE}): vault standards review" --files "${PHASE_DIR}/${PADDED_PHASE}-VAULT-REVIEW.md"
 ```
 
 </process>
+
+<success_criteria>
+- [ ] Step 0a ran first and stopped on every status other than `ok`
+- [ ] Input state detected (A/B/C); State C exits cleanly
+- [ ] Agent spawned with the CLI payload verbatim
+- [ ] `{padded}-VAULT-REVIEW.md` written in the phase directory and validated with `check vault-review --validate`
+- [ ] Every payload gap appears under Not Derived
+- [ ] Routing offered unconditionally; no verdict reached any halt, block or status
+</success_criteria>