@pareto4/pp-core 1.12.1 → 1.13.0

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

@@ -7,20 +7,22 @@ card verbatim and reads one field; it never re-derives any part of the verdict.
 
 ```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_CARD=$(pp_run check vault.status --card --point "${VAULT_GATE_POINT:-plan}")
-VAULT_ACTION=$(pp_run check vault.status --pick action)
+VAULT_CARD=$(pp_run check vault.status --card --point "${VAULT_GATE_POINT:-plan}") || exit 1
+VAULT_ACTION=$(pp_run check vault.status --pick action) || exit 1
+[ -n "$VAULT_ACTION" ] || exit 1
+[ -z "$VAULT_CARD" ] || printf '%s\n' "$VAULT_CARD"
+echo "VAULT_ACTION=$VAULT_ACTION"
+[ "$VAULT_ACTION" != stop ] || exit 1
 ```
 
-**If either command fails** (non-zero exit, or `VAULT_ACTION` is empty): the gate is
-declared `onError: halt` — STOP and report that the vault gate could not be evaluated. A pure
-read that crashed is never treated as a pass.
+**If the fence exits non-zero** (a command failed, the action is empty, or it is `stop`): STOP —
+do not plan or build, in any mode. The gate is `onError: halt`: a read that crashed is never a pass.
 
-**Otherwise relay `VAULT_CARD` to the user verbatim** (when non-empty), then act on
-`VAULT_ACTION` only:
+**Otherwise relay the printed card to the user verbatim**, then act on `VAULT_ACTION` only:
 
 | `VAULT_ACTION` | What to do |
 |---|---|
 | `none` | The vault is disabled — continue silently. |
 | `proceed` | The client vault is loaded — show the card and continue. |
 | `confirm` | Degraded and `vault.required` is false. Interactive: ask for an explicit `confirmed` (`AskUserQuestion`; in TEXT_MODE — `--text` in `$ARGUMENTS` — a plain-text prompt accepting a typed `confirmed`), then continue. With `--auto` / `--chain` in `$ARGUMENTS`: log the card and continue without prompting. |
-| `stop` | `vault.required` is true and the client vault is not loaded. **STOP** — do not plan or build, in any mode (including `--auto` / `--chain`). The card names the remedy; the operator re-runs the command after fixing it. |
+| `stop` | The fence already exited non-zero: `vault.required` is true and the client vault is not loaded. **STOP** in every mode (including `--auto` / `--chain`); the operator fixes what the card names and re-runs. |

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

@@ -35,6 +35,8 @@ Orchestrator coordinates, not executes. Each subagent loads the full execute-pla
 the orchestrator never receives the completion signal, treat it as successful based on spot-checks
 and continue to the next wave/plan. Never block indefinitely waiting for a signal — always verify
 via filesystem and git state.
+
+**Executor contributions (execute:pre `into: executor`):** every spawn injects its dispatch-plan `contributions[].fragment` verbatim after `${AGENT_SKILLS}`. Every inline path (interactive, Copilot, no `Agent`, a stalled executor switched to inline) follows `pp_run loop render-hooks execute:pre --into executor --phase "${PHASE_NUMBER}" ${TIER_FLAG}` the same way.
 </runtime_compatibility>
 
 <required_reading>
@@ -348,6 +350,8 @@ Read and execute `pp-core/workflows/execute-phase/steps/client-context-gate.md`
 
 <step name="execute_pre_vault">
 Before any executor: `EXECUTE_PRE_HOOKS_JSON=$(pp_run loop render-hooks execute:pre --raw) || exit 1`. For an active `capId == "vault"` step, Read and execute `pp-core/workflows/execute-phase/steps/vault-fetch.md`; then, for an active `vault.status` gate, set `VAULT_GATE_POINT=execute` and Read and execute `pp-core/workflows/execute-phase/steps/vault-load-gate.md`. None active → skip.
+
+Then anchor the phase for `/pp-undo --phase`: `pp_run phase manifest start "${PHASE_NUMBER}" --raw` — print its line and continue whatever it says (write-once; a refusal leaves undo on its git-log fallback).
 </step>
 
 <step name="discover_and_group_plans">
@@ -424,7 +428,7 @@ cd "$ORCHESTRATOR_WT" || { echo "FATAL: cannot cd to orchestrator worktree '$ORC
 DISPATCH_PLAN=$(pp_run query phase.dispatch-plan "${PHASE_NUMBER}" --use-worktrees "${USE_WORKTREES:-true}" ${WAVE_FILTER:+--wave "$WAVE_FILTER"} ${GAPS_ONLY:+--gaps-only} ${TIER_FLAG})
 ```
 
-`stages.execute.waves[]` in order, each with `spawns[]` (`kind` `serial-group`|`plan`, `plans[]` in run order with `id`, `title`, `build`, `touched_tests`; `isolation` `main-checkout`|`worktree`; `build`; `checkpoint`), `run`, `merge`, `build`, `suite_runs` (1), `tracking_commits` (1), `tracking.requirements`, `defects[]`. Report `totals` (spawns, suite runs, tracking commits). Non-empty `filters.lower_wave_incomplete` → STOP: finish the earlier waves first.
+`stages.execute.waves[]` in order, each with `spawns[]` (`kind` `serial-group`|`plan`, `plans[]` in run order with `id`, `title`, `build`, `touched_tests`; `isolation` `main-checkout`|`worktree`; `build`; `checkpoint`; `contributions`), `run`, `merge`, `build`, `suite_runs` (1), `tracking_commits` (1), `tracking.requirements`, `defects[]`. Report `totals` (spawns, suite runs, tracking commits). Non-empty `filters.lower_wave_incomplete` → STOP: finish the earlier waves first.
 
 **Stream-idle-timeout prevention — checkpoint heartbeats (#2410):**
 
@@ -607,6 +611,7 @@ increases monotonically across waves. `{status}` is `complete` (success),
        </files_to_read>
 
        ${AGENT_SKILLS}
+       {spawn.contributions[].fragment — each verbatim, blank-line separated; nothing when empty}
 
        <mcp_tools>
        If CLAUDE.md or project instructions reference MCP tools (e.g. jCodeMunch, context7,
@@ -844,6 +849,7 @@ increases monotonically across waves. `{status}` is `complete` (success),
    else
      echo "⚠ Skipping tracking update — post-merge tests failed (exit ${TEST_EXIT}). Plans remain in-progress until tests pass."
    fi
+   pp_run phase manifest record "${PHASE_NUMBER}" --raw  # .phase-manifest.json for /pp-undo --phase; never stops the run
    ```
 
 5.75. **Execute:wave:post capability dispatch:**
@@ -1067,10 +1073,16 @@ Selected wave finished successfully. This phase still has incomplete plans, so p
 **If no incomplete plans remain after the selected wave finishes:**
 - continue with the normal phase-level verification and completion flow below
 - this means the selected wave happened to be the last remaining work in the phase
+
+**verify:post gates** — every run that reaches this point (a partial run stopped above, so no planned plan is still waiting):
+```bash
+VERIFY_POST_GATES_JSON=$(pp_run loop run-gates verify:post --phase "${PHASE_NUMBER}" ${TIER_FLAG}) || exit 1
+```
+`loop run-gates` runs every active `verify:post` gate and owns the halt: exit 1 (a `⛔` line) stops the phase here — relay it; do not verify or mark the phase complete. `⚠` advisories: relay, continue.
 </step>
 
 <step name="code_review_gate" required="true">
-**This step is REQUIRED to evaluate the capability hook.** When the code-review capability is active, auto-invoke code review on the phase's source changes. Advisory only — never blocks execution flow. Also dispatches advisory execute:post gate hooks (e.g. tdd.review-checkpoint).
+**This step is REQUIRED to evaluate the capability hook.** When the code-review capability is active, auto-invoke code review on the phase's source changes. The review is advisory — it never blocks execution flow. Also dispatches the execute:post gate hooks: advisory ones (e.g. tdd.review-checkpoint) and the blocking `vault.trace` gate.
 
 **Capability gate:**
 ```bash
@@ -1101,9 +1113,13 @@ Code review found issues. Consider running:
 
 **Error handling:** If the Skill invocation fails or throws, catch the error, display "Code review encountered an error (non-blocking): {error}" and proceed to gate dispatch. Review failures must never block execution.
 
-**Execute:post gate hook dispatch.** After code review, dispatch all active gate hooks from `EXECUTE_POST_HOOKS_JSON` where `kind == "gate"`:
+**Execute:post gate hook dispatch.** After code review, run the blocking trace gate in code — exit 1 (a `⛔` line) stops the phase here; relay it and do not proceed:
+```bash
+TRACE_GATE_JSON=$(pp_run loop run-gates execute:post --phase "${PHASE_NUMBER}" ${TIER_FLAG} --query vault.trace) || exit 1
+```
+Then dispatch every other active gate hook from `EXECUTE_POST_HOOKS_JSON` where `kind == "gate"` (skip `check.query == "vault.trace"`):
 
-For each active gate hook:
+For each such gate hook:
 ```bash
 GATE_RESULT=$(pp_run check ${hook.check.query} "${PHASE_NUMBER}" --raw)
 CHECK_EXIT=$?
@@ -1243,7 +1259,7 @@ If `TEXT_MODE` is true, present as a plain-text numbered list and ask the user t
 <step name="verify_phase_goal">
 Verify phase achieved its GOAL, not just completed tasks.
 
-**Tier gate:** spawn the verifier only when `DISPATCH_PLAN.stages.verify` lists `pp-verifier` (= `verifier_enabled`). Otherwise print `Verifier skipped (tier {phase_tier.tier})`, treat the phase as `passed` and go to `update_roadmap`. When it lists `verify-install` (heavy tier), first Read and execute `pp-core/workflows/execute-phase/steps/install-run.md`: the installed-product run the verifier judges on.
+**Tier gate:** spawn the verifier only when `DISPATCH_PLAN.stages.verify` lists `pp-verifier` (= `verifier_enabled`). Otherwise print `Verifier skipped (tier {phase_tier.tier})`, treat the phase as `passed` and go to `update_roadmap`. When it lists `verify-install` (heavy tier), first Read and execute `pp-core/workflows/execute-phase/steps/install-run.md`: the installed-product run the verifier judges on. When it lists `verify-vault-review` (heavy tier, vault practices on), after the verifier returns, set `FORCE=1` and Read and execute `pp-core/workflows/vault-review.md` for this phase: it reports and never changes the route.
 
 ```bash
 VERIFIER_SKILLS=$(pp_run query agent-skills pp-verifier)
@@ -1416,6 +1432,7 @@ These items are tracked and will appear in `/pp:progress` and `/pp:audit-uat`.
 
 ```bash
 pp_run query commit "docs(phase-{X}): complete phase execution" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md {phase_dir}/*-VERIFICATION.md
+pp_run phase manifest record "${PHASE_NUMBER}" --raw  # the completion commit joins the /pp-undo --phase list
 ```
 </step>
 

package/pp-core/workflows/execute-plan.md

@@ -57,6 +57,10 @@ Extract from init JSON: `executor_model`, `commit_docs`, `sub_repos`, `phase_dir
 If `.planning/` missing: error.
 </step>
 
+<step name="vault_door_gate">
+Skipped under the `<dispatch>` tag: execute-phase gated execute:pre before spawning. Otherwise, before any task runs, Read and execute `pp-core/workflows/execute-phase/steps/vault-door-gate.md`; a stop ends this run with nothing executed.
+</step>
+
 <step name="identify_plan">
 ```bash
 # Use plans/summaries from INIT JSON, or list files

package/pp-core/workflows/fast.md

@@ -41,6 +41,10 @@ This looks like it needs planning. Use /pp:quick instead:
 And stop.
 </step>
 
+<step name="vault_door_gate">
+Before any edit, Read and execute `pp-core/workflows/execute-phase/steps/vault-door-gate.md`. A stop ends this task: nothing is edited or committed.
+</step>
+
 <step name="execute_inline">
 Do the work directly:
 

package/pp-core/workflows/help/modes/full.md

@@ -263,7 +263,7 @@ Modes:
 - **default** — progress report + intelligent routing
 - **`--next`** — auto-advance to the next logical step (use `--next --force` to bypass safety gates)
 - **`--next --auto`** — like `--next`, but chains steps automatically until milestone completion or a blocking decision
-- **`--next --converge`** — when the next action is planning, route it through `/pp:plan-review-convergence` instead of `/pp:plan-phase`; requires `workflow.plan_review_convergence=true`. `--cross-ai` is an alias. Reviewer flags (`--codex`, `--gemini`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--all`) and `--max-cycles N` forward to the convergence loop.
+- **`--next --converge`** — when the next action is planning, route it through `/pp:plan-review-convergence` instead of `/pp:plan-phase`; requires `workflow.plan_review_convergence=true`. `--cross-ai` is an alias. Reviewer flags and `--max-cycles N` pass through to it.
 - **`--forensic`** — append a 6-check integrity audit after the progress report
 - **`--do "<text>"`** — smart router: dispatch freeform intent to the matching `/pp-*` command (see *Smart Router* above)
 
@@ -592,7 +592,7 @@ The commands above cover the most common day-to-day flows. Every command listed
 
 - **`/pp:mvp-phase <phase-number>`** — Plan a phase as a vertical MVP slice (user story + SPIDR splitting) before handing off to plan-phase. Same end-state as `/pp:plan-phase --mvp`, with a guided MVP-shaping intro.
 - **`/pp:ultraplan-phase [phase]`** — [BETA] Offload plan phase to Claude Code's ultraplan cloud; review in browser and import back.
-- **`/pp:plan-review-convergence <phase> [--codex] [--gemini] [--claude] [--opencode] [--ollama] [--lm-studio] [--llama-cpp] [--all] [--text] [--ws <name>] [--max-cycles N]`** — Cross-AI plan convergence loop — replan with review feedback until no HIGH concerns remain. Supports both cloud reviewers (Codex/Gemini/Claude/OpenCode) and local model runtimes (Ollama, LM Studio, llama.cpp).
+- **`/pp:plan-review-convergence <phase> [--codex] [--gemini] [--claude] [--opencode] [--ollama] [--lm-studio] [--llama-cpp] [--all] [--text] [--ws <name>] [--max-cycles N]`** — Cross-AI plan convergence loop — replan with review feedback until no HIGH concerns remain.
 - **`/pp:autonomous [--from N] [--to N] [--only N] [--supervised] [--interactive] [--converge]`** — Run the next incomplete phase autonomously (discuss → plan → execute), best-effort with decisions recorded; `--from`/`--to` for a range, `--supervised` restores prompts. `--converge` routes planning through plan-review convergence; `--cross-ai` is an alias.
 
 ### Quality, Review & Verification
@@ -602,6 +602,7 @@ The commands above cover the most common day-to-day flows. Every command listed
 - **`/pp:validate-phase [phase]`** — Retroactively audit and fill Nyquist validation gaps for a completed phase.
 - **`/pp:ui-review [phase]`** — Retroactive 6-pillar visual audit of implemented frontend code.
 - **`/pp:eval-review [phase]`** — Audit an executed AI phase's evaluation coverage and produce an EVAL-REVIEW.md remediation plan.
+- **`/pp:vault-review [phase]`** — Retroactive per-practice client-vault review of a phase; counts by verdict, never gates.
 - **`/pp:audit-fix --source <audit-uat> [--severity medium|high|all] [--max N] [--dry-run]`** — Autonomous audit-to-fix pipeline: find issues, classify, fix, test, commit.
 - **`/pp:add-tests <phase> [additional instructions]`** — Generate tests for a completed phase based on UAT criteria and implementation.
 

package/pp-core/workflows/init.md

@@ -174,8 +174,8 @@ pp_run query init-contract --arm-vault
 pp_run vault probe
 ```
 
-Show both outputs verbatim. `--arm-vault` sets `vault.enabled: true` only where the key is
-absent (an explicit `false` is kept); `ok:false` means no client vault is bound — re-run
+Show both outputs verbatim. `--arm-vault` sets `vault.enabled: true`, and then `vault.required:
+true` and `vault.practices_enabled: true`, each only where the key is absent (an explicit value is kept); `ok:false` means no client vault is bound — re-run
 `pp-tools init`. The probe line says whether the client vault is reachable at its pinned ref;
 it prints nothing when the vault is disabled. Neither ever blocks this step.
 

package/pp-core/workflows/new-project.md

@@ -107,7 +107,7 @@ hard-block initiation on an unreachable remote. For non-Pareto repos the block i
 a no-op and this step is skipped entirely.
 
 When the bindings file is present, also run `pp_run query init-contract --arm-vault`
-(sets `vault.enabled: true` only where absent; `ok:false` = no client vault bound — run
+(sets `vault.enabled` and `vault.required` to true, each only where absent; `ok:false` = no client vault bound — run
 `/pp-init`) and `pp_run vault probe` (one reachability line; empty when the vault is
 disabled). Show both outputs verbatim; neither blocks.
 

package/pp-core/workflows/plan-phase/steps/phase-tier.md

@@ -25,6 +25,15 @@ Spawn nothing the stage does not list. The explicit flags still apply on top: `-
 
 ## After planning (§9, `## PLANNING COMPLETE`)
 
+Threat-model presence gate first (active only when the tier resolves `security_enforcement` on, i.e. the step 5.55 banner showed):
+
+```bash
+TM_BLOCK=$(pp_run check threat-model-presence "$PHASE" $TIER_FLAG --pick block) || exit 1
+[ "$TM_BLOCK" != "true" ] || exit 1   # stderr names each new plan without <threat_model>
+```
+
+If it stops: do not go on to step 10 or 13; re-spawn the planner (step 8) requiring the block in each plan named, then return here.
+
 Plans now exist, so re-propose from their `files_modified`:
 
 ```bash

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

@@ -686,6 +686,7 @@ Output this markdown directly (not as a code block):
 ───────────────────────────────────────────────
 Also available:
 - `/pp:plan-phase {N} --skip-ui ${GSD_WS}` — plan without UI-SPEC (not recommended for frontend phases)
+- Not a UI phase? Matched: {GATE.tokens}. Add `**UI:** none` on its own line in the ROADMAP phase section.
 ```
 
 **Exit the plan-phase workflow. Do not continue.**
@@ -815,6 +816,7 @@ Continue to step 8.
 Run this Bash command to emit the branded Plan stage banner (renders on stderr, auto-degrades on non-TTY — do NOT print an inline ASCII banner, that would double-print):
 ```bash
 pp_run banner plan "PLANNING PHASE {X}"
+touch "${PHASE_DIR}/.planner-run-mark"   # the threat-model gate examines only newer plans
 ```
 
 Then announce the spawn:
@@ -1325,7 +1327,7 @@ After plans pass the checker (or checker is skipped), verify that all phase requ
 **Step 1: Extract requirement IDs claimed by plans**
 ```bash
 # Collect all requirement IDs from plan frontmatter
-PLAN_REQS=$(grep -h "requirements_addressed\|requirements:" ${PHASE_DIR}/*-PLAN.md 2>/dev/null | tr -d '[]' | tr ',' '\n' | sed 's/^[[:space:]]*//' | sort -u)
+PLAN_REQS=$(grep -h "^requirements_addressed\|^requirements:" ${PHASE_DIR}/*-PLAN.md 2>/dev/null | tr -d '[]' | tr ',' '\n' | sed 's/^[[:space:]]*//' | sort -u)
 ```
 
 **Step 2: Compare against phase requirements from ROADMAP**
@@ -1476,13 +1478,14 @@ Proactive, non-blocking coverage report gated on `workflow.post_planning_gaps`
 
 ```bash
 PLAN_POST_HOOKS_JSON=$(pp_run loop render-hooks plan:post --raw --phase "$PHASE" $TIER_FLAG) || exit 1
+TRACE_GATE_JSON=$(pp_run loop run-gates plan:post --phase "$PHASE" $TIER_FLAG --query vault.trace) || exit 1
 PHASE_REQ_IDS=$(pp_run query init.plan-phase "$PHASE" --pick phase_req_ids 2>/dev/null || echo TBD)
 ```
 
-Read the `activeHooks` array from `PLAN_POST_HOOKS_JSON` in-context. If the
-`gap-analysis` gate hook is absent (capability inactive), skip this step.
+The `run-gates` line runs the blocking `vault.trace` gate (vault practices on) and owns its halt: exit 1 (a `⛔` line) stops planning here — relay it verbatim and do not present the plans as ready. Read the `activeHooks` array from `PLAN_POST_HOOKS_JSON` in-context. If the
+`gap-analysis` gate hook is absent (capability inactive), skip the rest of this step.
 
-**For each active entry where `kind == "gate"`** (process in array order):
+**For each active entry where `kind == "gate"`** except `check.query == "vault.trace"` (run above), in array order:
 
 ```bash
 GATE_RESULT=$(pp_run check ${hook.check.query} "${PHASE_DIR}" "${PHASE_REQ_IDS}" --raw)

package/pp-core/workflows/quick.md

@@ -176,6 +176,10 @@ Quick tasks can run mid-phase - validation only checks ROADMAP.md exists, not ph
 
 ---
 
+**Step 2.4: Vault door gate** — Step 2.5 is the first write. Read and execute `pp-core/workflows/execute-phase/steps/vault-door-gate.md` now; a stop ends the quick task before anything is written.
+
+---
+
 **Step 2.5: Handle quick-task branching**
 
 **If `branch_name` is empty/null:** Skip and continue on the current branch.

package/pp-core/workflows/ship.md

@@ -91,9 +91,13 @@ Verify the work is ready to ship:
 
    ```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)
    ```
 
+   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.
+
    Read the `activeHooks` array from `SHIP_PRE_HOOKS_JSON` 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:
@@ -113,7 +117,7 @@ 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):
+   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)

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.
+Read `.planning/.phase-manifest.json` if it exists (execute-phase writes it with `pp_run phase manifest start|record`).
 
 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/validate-phase.md

@@ -97,6 +97,10 @@ 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
+
+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.
+
 ## 5. Spawn pp-nyquist-auditor
 
 Print: `◆ Spawning nyquist auditor... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)`

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

@@ -0,0 +1,65 @@
+<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.
+</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
+</available_agent_types>
+
+<process>
+
+## 1. Scaffold
+
+```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
+```
+
+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.
+
+```bash
+SCAFFOLD=$(pp_run vault review scaffold "${PHASE_DIR}" ${FORCE:+--force} --raw)
+```
+
+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.
+
+## 2. Judge
+
+```
+◆ Spawning vault reviewer... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
+```
+
+```
+Agent(
+  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})."
+)
+```
+
+## 3. Finalize
+
+```bash
+pp_run vault review finalize "${PHASE_DIR}"
+```
+
+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.
+
+Route the same way whatever the verdicts: `/pp-verify-work {N}` or `/pp-plan-phase {N+1}`. Commit:
+
+```bash
+pp_run query commit "docs(${PADDED_PHASE}): vault practice review" --files "${PHASE_DIR}/${PADDED_PHASE}-VAULT-REVIEW.md"
+```
+
+</process>

package/pp-core/workflows/verify-work.md

@@ -461,9 +461,12 @@ Present summary:
 
 ```bash
 VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw --phase "${phase_number}" ${GSD_WS} ${TIER_FLAG}) || exit 1
+VERIFY_POST_GATES_JSON=$(pp_run loop run-gates verify:post --phase "${phase_number}" ${GSD_WS} ${TIER_FLAG}) || exit 1
 SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
 ```
 
+`loop run-gates` runs every active `verify:post` gate and owns the halt: exit 1 (a `⛔` line) means a blocking gate blocked — stop, relay it, do not mark the phase complete. `⚠` lines are advisories: relay and continue.
+
 Resolve active step hooks from `VERIFY_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "secure-phase"`.
 
 If an active secure-phase step hook exists AND `SECURITY_FILE` is empty, dispatch the registry-provided skill stem:

package/scripts/gen-capability-registry.cjs

@@ -1204,6 +1204,17 @@ function validateGate(gate, prefix) {
     if (count !== 1) {
       errors.push(prefix + '.check must have exactly one of: query, predicate, agentVerdict');
     }
+    // check.args: literal tokens `loop run-gates` appends after the phase — query gates only,
+    // at most 8, each a flag or a plain word (the runner refuses anything else at run time too).
+    if (Object.prototype.hasOwnProperty.call(gate.check, 'args')) {
+      const a = gate.check.args;
+      if (!hasQuery) {
+        errors.push(prefix + '.check.args is only valid beside check.query');
+      } else if (!Array.isArray(a) || a.length > 8
+        || !a.every((t) => typeof t === 'string' && /^(?:--[a-z][a-z0-9-]*|[a-z0-9][a-z0-9._-]*)$/i.test(t))) {
+        errors.push(prefix + '.check.args must be an array of at most 8 flags (--name) or plain words');
+      }
+    }
     // agentVerdict forces blocking: false (advisory only)
     if (hasAgentVerdict && gate.blocking === true) {
       errors.push(

package/scripts/lint-test-file-count.allowlist.json

@@ -187,13 +187,22 @@
       ],
       "issue": "v1.7.0 Client Vault Load — four distinct concerns: vault.test (fetch/status/summary unit), vault-security (VSEC-02/03 write-guard + secret/fence), vault-read-path (VGATE-03 SUMMARY pointer), vault-status-check (VGATE-02 gate-query handler). Phase 24-02 added vault-practices.property.test.cjs (fast-check fuzz of the practices glob-fallback compiler + a practices-frontmatter round-trip, PRAC-02) — it is grouped under this bucket rather than \"vault-practices\" because the test-file-count lint's hyphen-prefix matcher treats \"vault-practices.property\" (period before \"property\") as starting with \"vault-\" before it can match the more specific \"vault-practices-\" prefix; the module it actually tests is pp-core/bin/lib/vault-practices.cjs, not vault.cjs."
     },
+    "vault-review": {
+      "files": [
+        "vault-review.integration.test.cjs",
+        "vault-review.security.test.cjs",
+        "vault-review.test.cjs"
+      ],
+      "issue": "Agent practice review (vault assurance R5) — three distinct concerns for pp-core/bin/lib/vault-review.cjs: vault-review.test (the pure derivations — vocabularies, both derived-N-A arms, the counts, the range, the clean-render refusal, the scaffold renderer and the line stamper — plus the require-graph barrier), vault-review.integration.test (the seams: the artifact validator and the check vault-review / vault review scaffold|finalize arms driven through the real pp-tools.cjs, where the exit-0 / no-block-key contract is proved), and vault-review.security.test (adversarial practice bodies: a spoofed fence marker, directive-shaped text, a client table inside the fence, an option-shaped base branch). The .security marker is what identifies the adversarial lane to scripts/run-tests.cjs; consolidating would blur three different questions into one file."
+    },
     "vault-practices": {
       "files": [
         "vault-practices-examples.test.cjs",
         "vault-practices-matcher.test.cjs",
+        "vault-practices.slow.test.cjs",
         "vault-practices.test.cjs"
       ],
-      "issue": "Phase 24 (24-01/24-02/24-04) — three distinct concerns for pp-core/bin/lib/vault-practices.cjs: vault-practices.test (24-01 parser/validation/discovery unit tests), vault-practices-matcher.test (24-02 glob matcher + two-bucket result + report unit tests), vault-practices-examples.test (24-04 shipped-example drift guard + minimal-comments global-bucket smoke case, PRAC-03 Success Criterion 3). All three test the same production module and are each independently load-bearing; consolidating would blur distinct plan-level verification gates."
+      "issue": "Phase 24 (24-01/24-02/24-04) — three distinct concerns for pp-core/bin/lib/vault-practices.cjs: vault-practices.test (24-01 parser/validation/discovery unit tests), vault-practices-matcher.test (24-02 glob matcher + two-bucket result + report unit tests), vault-practices-examples.test (24-04 shipped-example drift guard + minimal-comments global-bucket smoke case, PRAC-03 Success Criterion 3). All three test the same production module and are each independently load-bearing; consolidating would blur distinct plan-level verification gates. The practice-file contract extensions added vault-practices.slow.test.cjs — the >5 s worst-case matcher corpus behind the matching cost bound, split out per the .slow suffix convention so the default suite stays fast."
     }
   }
 }

package/scripts/prompt-injection-scan.sh

@@ -89,6 +89,8 @@ ALLOWLIST=(
   'tests/security.test.cjs::the adversarial suite for the library sanitisers, whose fixtures are real override and role-manipulation strings asserted to be neutralised; measured 54 pattern hits at HEAD on 2026-10-11'
   'tests/prompt-injection-scan.security.test.cjs::drives scanForInjection in the compiled security library with crafted payloads, and carries a second allowlist of its own for that separate scanner; measured 11 pattern hits at HEAD on 2026-10-11'
   'tests/vault-security.test.cjs::the vault fencing suite plants an instruction-override heading in a fixture vault file and asserts SUMMARY.md fences and defangs it rather than passing it to the agent as instructions; measured 1 pattern hit at HEAD on 2026-10-11'
+  'tests/vault-practices-matcher.test.cjs::the vault practices matcher suite plants an instruction-override line inside a fixture practice body and a spoofed fence end, and asserts the matcher keeps both inside the untrusted fenced region, so the fixtures must carry a real injection phrase'
+  'tests/vault-review.security.test.cjs::the adversarial suite of the agent practice review seeds a practice body with directive-shaped text aimed at the practice judge (the DIRECTIVE_TEXT constant) and asserts the rendered review entry carries it only between the fence markers, after the reference-data preamble, so the judge reads it as data; the text must be a literal for that assertion to mean anything; measured 1 pattern hit at HEAD on 2026-10-12'
   'tests/verify.test.cjs::the verification suite plants an instruction-override line in a phase artifact and asserts it is rejected, so the line is present as a negative fixture; measured 1 pattern hit at HEAD on 2026-10-11'
   'pp-core/bin/lib/security.cjs::gitignored build output compiled from src/security.cts per .gitignore line 117, so it is unreachable in diff mode and matters only to a local dir-mode run; it carries the library injection patterns inline; measured 8 pattern hits at HEAD on 2026-10-11'
   'tests/read-injection-scanner.security.test.cjs::exercises the read-time injection scanner hook with the payloads a hostile file would carry, each asserted to be blocked rather than obeyed; measured 14 pattern hits at HEAD on 2026-10-11'