@pareto4/pp-core 1.13.0 → 1.17.1

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` and `vault-practices`
+capabilities (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'||x.capId==='vault-practices'));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,325 @@
 <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 client-vault practice review of a completed phase. Standalone command that works on
+any completed phase — traced or untraced. Produces `{padded}-VAULT-REVIEW.md` with one verdict per
+practice and counts by verdict. This workflow reports; it gates nothing.
 </purpose>
 
+<required_reading>
+@~/.claude/pp-core/references/verifier-practice-verdicts.md
+</required_reading>
+
 <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 the practice remainder the CLI derivation could not settle
 </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`, `phase_slug`, `padded_phase`, `commit_docs`.
+
+### 0a. The vault-off short-circuit — the first act of this workflow
+
+Run the derive call now, before any input state is detected, and branch on what the arm prints:
+
+```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')}})")
+```
+
+**If `REVIEW_STATUS` is `inert`:** print the payload's `statement` field verbatim and STOP here.
+Nothing below this line runs: no agent is spawned, no template is read, and no `VAULT-REVIEW.md` is
+written. A project with the vault practices capability off is left byte-identical by this command
+(the CLAUDE.md inertness rule).
+
+**If `REVIEW_STATUS` is `not_applicable` or `bad-config`:** print the payload's `statement` field
+verbatim and STOP: nothing below runs, no agent is spawned. `not_applicable` is standards mode
+(`vault.mode = standards`): the practices review is parked, and the consulted documents are recorded
+in each plan's `<vault_standards>` block and its SUMMARY's `Standards Consulted` section.
+`bad-config` is a `vault.mode` the engine cannot read.
+
+Why the branch is on the arm's output rather than on the config: **this workflow never reads
+`vault.enabled` or `practices_enabled` itself.** Policy has one home — the CLI arm resolves both keys
+through the shared reader and answers before it touches the vault, the trace or a git subprocess. The
+arm's inert sentence is proven byte-identical between the two spellings of "off" (the key absent, and
+the key present and explicitly `false`) by plan 06-04's integration suite, which compares the two
+outputs byte for byte. Branching here on the arm's output is what makes that proof this workflow's
+proof too; a second config read would be a second policy home that could disagree with the first.
+
+**Capability-OFF is not the same input as an absent vault.** They are never collapsed:
+
+| Input | What happens |
+|---|---|
+| The capability is off (`status: inert`) | Stop here, inert. The feature does not apply to this project. |
+| Standards mode or an unrecognised mode (`status: not_applicable` / `bad-config`) | Stop here and print the statement. A parked surface must not render as a clean review. |
+| The capability is on but the vault is missing, unreadable or holds no practices | Continue. The review runs and renders **loudly as gaps-only** through the template's not-derived sections. |
+
+The second row is a phase that was reviewed and whose review found gaps; the first is a project the
+feature does not apply to. A review that reported the second as the first would be reporting a gap as
+an absence of gaps.
+
+**If `REVIEW_STATUS` is `usage`, `no-argument` or `unresolved`:** print the payload's `statement`
+verbatim and stop — the arm reviewed nothing and said which argument it could not use. Re-run with
+the phase directory.
+
+Then display the banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ pp-core ► VAULT PRACTICE REVIEW — PHASE {N}: {name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-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.
+## 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)
+PLAN_FILES=$(ls "${PHASE_DIR}"/*-PLAN.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 audit-trail block to the artifact 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 — "Phase {N} not executed. Run
+  `/pp:execute-phase {N}` first." This is the honest refusal, and it is the only one. D-06-14 makes
+  **any completed phase** eligible, traced or not; State C refuses only a phase that was never built,
+  because there is no work to review.
 
-## 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. Provenance — `trace_present_and_loaded`
+
+Read one flag from the payload, and carry it to the spawn:
+
+`trace_present_and_loaded` is the payload's **`trace.loaded`**. The CLI sets it true only when a
+`vault:` trace block exists in this phase's artifacts **and** every parsed block records
+`predicate.vault.state: loaded`. A degraded block sets it **false**, and so does an absent one. Two
+fields beside it say which case this is and why: `trace.state` is `loaded`, `degraded`, or `null`
+when no block was found at all, and `trace.reason` names the artifact that failed and what it
+recorded. Do not recompute the flag here — it is derived once, in the CLI, from data this workflow
+never reads.
+
+A degraded block is a valid record of a **failure**: it says no trusted vault load existed when the
+work was planned. It therefore proves nothing about which practices governed that work, which is why
+it is not allowed to stand in for a loaded one. When the flag is false because a trace was found and
+failed, carry `trace.reason` into §5's RECONSTRUCT constraint so the reviewer records why the trace
+could not stand.
+
+## 3. The three-way short-circuit
+
+`pp-core/workflows/secure-phase.md` states the rule this step copies, in its own words:
+
+> "Empty-by-no-planning must not rubber-stamp a clean SECURITY.md."
+
+Restated for this tier: **an empty or absent trace must never produce a clean review. Reconstruct
+first, then judge.**
+
+| Provenance | What runs |
+|---|---|
+| `trace_present_and_loaded: true`, remainder empty | The derived rows are the whole review. Render them; the agent judges nothing because nothing was left unsettled. |
+| `trace_present_and_loaded: true`, remainder non-empty | Spawn in **verify mode** — judge the supplied remainder only. |
+| `trace_present_and_loaded: false` | Spawn in **RECONSTRUCT mode** — the applicable practice set was rebuilt by the CLI from this phase's real diff crossed with the vault's own practice list, and that reconstructed set is what gets judged. |
+
+**Reconstruct is the primary path, not a degraded one.** A project with no `vault` config key has no
+phase that has or can have a trace, so every review of its own history takes this arm. The payload
+says so in its `statements[]`, and the artifact repeats it.
+
+## 4. The derived payload
+
+`REVIEW_PAYLOAD`, captured in step 0a, is the review's whole factual input and is consumed before the
+spawn. It carries, already computed: `range`, `rangeSource`, `filesConsidered`, the input set, both
+derived-`N-A` populations with their own labels and reasons, the partitioned remainder, the derived
+`derivedCounts` / `derivedRateLine` (what those two describe, and what they are never written as,
+is stated once in the contract block carried into the spawn prompt below),
+`practiceEntries` (each practice's prose already fenced and defanged by the
+shipped renderer), `statements[]`, `notes[]` and `refusesCleanRender`.
+
+**The clean-render refusal is the CLI's, and this workflow honors it rather than reimplementing it.**
+When `refusesCleanRender` is true (the range considered zero files), or when the payload records that
+the vault was absent or unreadable, the review still renders — as a **loud gaps-only artifact**
+through the template's not-derived sections — and never as a clean review. The rule lives in code, in
+the shipped predicate; nothing here restates it as a second copy that could drift.
+
+## 5. 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. The CLI payload is carried **verbatim**, and every practice byte inside it is
+already fenced by the shipped renderer — this workflow opens no vault file of its own:
+
+```markdown
+Read ~/.claude/agents/pp-vault-reviewer.md for instructions.
+
+<objective>
+Retroactive client-vault practice review of Phase {phase_number}: {phase_name}
+</objective>
+
+<constraints>
+{If trace_present_and_loaded: "This phase's trace is present and loaded. Judge the supplied
+remainder only — the derived sets are complete and are reproduced, not recomputed."}
+{If not trace_present_and_loaded: "RECONSTRUCT mode. This phase has no loaded trace, so the
+applicable practice set below was rebuilt from the phase's changed files crossed with the vault's
+practice list. Judge that reconstructed set. A missing trace is itself a finding: record it loudly."}
+Every derived fact below was computed by `pp-tools check vault-review` and is not recomputable by
+you (D-06-09). Copy the range statement and every derived row's supplied reason and arm label
+verbatim; never recount them.
+<!-- gen:practice-arithmetic-contract:start -->
+**TWO COUNT POPULATIONS, and conflating them writes a false section.**
+
+`derivedCounts` and `derivedRateLine` on the `check vault-review` payload describe the **derived rows
+alone** — Arm A plus Arm B — which on the reconstruct path is usually none. They are never written as
+the register's own two lines.
+
+The register's rate and counts lines describe **the rows you write**, derived and judged together.
+`validateReviewArtifact` recomputes them from exactly those rows and rejects a narrated figure with
+`rate-line-arithmetic` or `counts-line-arithmetic`. Copying a supplied `0 of 0 practices judged …`
+into the register states that nothing was judged over a register that judged something.
+
+`judged = total − na`, and INCONCLUSIVE counts *inside* `judged` and is reported separately.
+
+**Where a supplied figure disagrees with your rows, record the disagreement and overwrite neither
+side.** Write it as PROSE that names it as the supplied figure — never as a bare line in the
+register's own shape. A second bare shaped line makes the section contradict itself: two rate lines,
+or two counts lines, stating different figures, with nothing in the register saying which of them the
+rows you wrote support.
+<!-- gen:practice-arithmetic-contract:end -->
+ON THIS TIER the disagreement goes on the `| Disagreements between supplied counts and the rows |`
+row of `## Not Derived`.
+Write exactly one file: {phase_dir}/{padded_phase}-VAULT-REVIEW.md
+</constraints>
+
+<review_payload>
+{REVIEW_PAYLOAD verbatim}
+</review_payload>
+
+<files_to_read>
+- {summary_paths} (Execution summaries)
+- {plan_paths} (Execution plans)
+- {context_path} (User decisions, if it exists)
+</files_to_read>
+
+${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 practice 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.
+
+## 6. Handle Return
+
+The agent returns `## REVIEWED`, `## DEGRADED` or `## ESCALATE`. It reads
+`~/.claude/pp-core/templates/VAULT-REVIEW.md`, fills it, and writes
+`${PHASE_DIR}/${PADDED_PHASE}-VAULT-REVIEW.md` (D-06-16).
+
+On `REVIEWED` or `DEGRADED`, run the deterministic shape check over what was written:
 
 ```bash
-pp_run vault review finalize "${PHASE_DIR}"
+node -e "const m=require((process.env.PP_LIB || './pp-core/bin/lib') + '/vault-review.cjs');const t=require('fs').readFileSync(process.argv[1],'utf8');const r=m.validateReviewArtifact(t);console.log(JSON.stringify(r.problems,null,2));console.log('rate:',r.expectedRateLine);console.log('counts:',r.expectedCountsLine)" "${PHASE_DIR}/${PADDED_PHASE}-VAULT-REVIEW.md"
 ```
 
-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.
+`PP_LIB` defaults to the repo-root layout above. From an installed runtime, set it first —
+`export PP_LIB=~/.claude/pp-core/bin/lib` — because the bare relative path resolves only when the
+cwd is the repo root, and it silently fails everywhere else.
 
-Route the same way whatever the verdicts: `/pp-verify-work {N}` or `/pp-plan-phase {N+1}`. Commit:
+Surface any reported problems to the operator as **repair items**, listed under the artifact's own
+repair heading, and finish with exit 0 either way. A shape complaint is a defect in the artifact to be
+repaired in the artifact — never by editing the validator, and never by deleting the row that produced
+the complaint.
+
+`ESCALATE` means no artifact could be written at all (the phase directory does not exist, or the
+payload could not be obtained). Report what the agent said and stop; still exit 0.
+
+Display the summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ pp-core ► VAULT PRACTICE REVIEW COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase {N}: {Name}** — arm: {traced | reconstruct}
+
+{the artifact's register rate line — the one `validateReviewArtifact` recomputed and accepted}
+{the artifact's register counts line — the one `validateReviewArtifact` recomputed and accepted}
+
+Gaps reported: {none. / the payload's loud statements}
+
+Full review: {path to VAULT-REVIEW.md}
+
+This review reports and does not gate. No verdict above changes a phase status,
+a score, a gap or any deterministic surface — see "Limits of This Review" in the artifact.
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next
+
+`/clear` then one of:
+
+- `/pp:verify-work {N}` — UAT testing
+- `/pp:plan-phase {N+1}` — plan next phase
+
+───────────────────────────────────────────────────────────────
+```
+
+The routing above is offered on **every** path — a review that found `FAIL` rows routes exactly the
+same as one that found none. No step in this workflow reads a verdict, a count or a rate into a halt,
+an exit code, a block or a suppressed route, and nothing here writes to `ROADMAP.md`, `STATE.md`,
+`VERIFICATION.md` or any `SUMMARY.md`. The one file this command produces is the artifact.
+
+## 7. Commit (if configured)
 
 ```bash
 pp_run query commit "docs(${PADDED_PHASE}): vault practice review" --files "${PHASE_DIR}/${PADDED_PHASE}-VAULT-REVIEW.md"
 ```
 
 </process>
+
+<success_criteria>
+- [ ] Step 0a ran first and branched on the arm's own output
+- [ ] Vault-disabled project: inert sentence printed, nothing else run, nothing written
+- [ ] Input state detected (A/B/C) — State C exits cleanly
+- [ ] `trace_present_and_loaded` read from the payload's `trace.loaded`; degraded and absent both false
+- [ ] Reconstruct arm taken whenever the flag is false, and named as such in the artifact
+- [ ] Agent spawned with the CLI payload verbatim and the origin-dependent constraint
+- [ ] `{padded}-VAULT-REVIEW.md` written in the phase directory; shape check run over it
+- [ ] The payload's derived figures are never written as the register's lines; any difference is on the `| Disagreements between supplied counts and the rows |` row
+- [ ] The register's own rate and counts lines agree with `validateReviewArtifact` over the rows written
+- [ ] Routing offered unconditionally; no verdict reached any halt, block or status
+</success_criteria>