@pareto4/pp-core 1.13.0 → 1.17.1

package/pp-core/workflows/add-tests.md

@@ -67,6 +67,47 @@ Present banner:
 ```
 </step>
 
+<step name="vault_admission_gate">
+Vault admission and load gate (D-11, D-12, D-28): runs before a test is written or committed. 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
+AT_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' "$AT_EXECUTE_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('AT_EXECUTE_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
+```
+
+Set `VAULT_FETCH_HOOKS_JSON=$AT_EXECUTE_PRE_HOOKS_JSON`, then Read and execute
+`pp-core/workflows/execute-phase/steps/vault-fetch.md` (hook mode). Then, in the
+`AT_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=$AT_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.
+
+Then record the door's START anchor, before the first test file is written (`execute_tdd_generation`) (D-31):
+
+```bash
+pp_run vault door-record --begin --door add-tests --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`.
+Take `padded_phase` from the same init JSON for the record below.
+</step>
+
 <step name="analyze_implementation">
 Extract the list of files modified by the phase from SUMMARY.md ("Files Changed" or equivalent section).
 
@@ -212,10 +253,6 @@ If "Cherry-pick": ask user which tests to include.
 If "Adjust plan": apply changes and re-present.
 </step>
 
-<step name="vault_door_gate">
-Before any test file is written, Read and execute `pp-core/workflows/execute-phase/steps/vault-door-gate.md`; a stop ends this run with no test written.
-</step>
-
 <step name="execute_tdd_generation">
 For each approved TDD test:
 
@@ -315,6 +352,20 @@ git add {test files}
 git commit -m "test(phase-${phase_number}): add unit and E2E tests from add-tests command"
 ```
 
+Vault door record (D-12): after the door's last source commit, set `DOOR_DIR="${phase_dir}"`,
+`DOOR_PADDED="${padded_phase}"` and `DOOR_PHASE="${phase_number}"`, then run:
+
+```bash
+DOOR_RUN=$(date -u +%Y%m%dT%H%M%SZ)
+pp_run vault door-record --door add-tests --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_number}): vault door record for add-tests" --files "<that artifact>"`.
+
 Present next steps:
 
 ```

package/pp-core/workflows/audit-fix.md

@@ -91,9 +91,49 @@ If `--dry-run` was specified, **stop here and exit**. The classification table i
 final output — do not proceed to fixing.
 </step>
 
-<step name="fix-loop">
-Before the first fix, Read and execute `pp-core/workflows/execute-phase/steps/vault-door-gate.md`; a stop ends this run with no fix applied.
+<step name="vault_admission_gate">
+Skipped under `--dry-run` (nothing is fixed).
+
+Vault admission and load gate (D-11, D-12, D-28): runs before any finding is fixed. 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
+AF_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' "$AF_EXECUTE_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('AF_EXECUTE_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
+```
+
+Set `VAULT_FETCH_HOOKS_JSON=$AF_EXECUTE_PRE_HOOKS_JSON`, then Read and execute
+`pp-core/workflows/execute-phase/steps/vault-fetch.md` (hook mode). Then, in the
+`AF_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=$AF_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.
+
+Then record the door's START anchor, before the first `pp-executor` spawn of the fix loop (D-31):
+
+```bash
+pp_run vault door-record --begin --door audit-fix --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`.
+</step>
 
+<step name="fix-loop">
 For each **auto-fixable** finding (up to `--max`, ordered by severity desc):
 
 **a. Spawn executor agent** (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)**:**
@@ -142,6 +182,27 @@ must halt to avoid cascading issues. Remaining auto-fixable findings will appear
 report as `not-attempted`.
 </step>
 
+<step name="vault_door_record">
+After the loop, once for EACH phase directory whose findings were fixed in this run (the directory of
+the UAT or VERIFICATION file the finding came from): the record's range, from the start captured
+before the loop to HEAD now, covers every finding commit, and it lands in each fixed phase so that
+phase's gate sees it.
+
+Vault door record (D-12): after the door's last source commit, set `DOOR_DIR="<that phase directory>"`,
+`DOOR_PADDED="<its padded phase>"` and `DOOR_PHASE="<that phase directory>"`, then run:
+
+```bash
+DOOR_RUN=$(date -u +%Y%m%dT%H%M%SZ)
+pp_run vault door-record --door audit-fix --artifact "${DOOR_DIR}/${DOOR_PADDED}-door-${DOOR_RUN}-AUDIT-FIX.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: vault door record for audit-fix" --files "<that artifact>"`.
+</step>
+
 <step name="report">
 Present the final summary:
 

package/pp-core/workflows/audit-milestone.md

@@ -146,7 +146,7 @@ For each REQ-ID, determine status using all three sources:
 Skip if the Nyquist capability is inactive.
 
 ```bash
-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"`.

package/pp-core/workflows/autonomous.md

@@ -267,18 +267,65 @@ PHASE_STATE=$(pp_run query init.phase-op ${PHASE_NUM})
 
 Check `has_context`. If false → go to handle_blocker: "Discuss for phase ${PHASE_NUM} did not produce CONTEXT.md."
 
-**3a.5. UI Design Contract (Frontend Phases)**
+**3a.5. plan:pre dispatch — fetch, design contract, then gate**
+
+Admission first (D-28): a config the gate cannot read renders no vault hook, so this runs before the render.
+
+```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
+```
 
 Resolve active `plan:pre` hooks:
 
 ```bash
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
-HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw --phase "${PHASE_NUM}") || exit 1
+HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw)
+printf '%s' "$HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 ```
 
-Read the `activeHooks` array directly from `HOOKS_JSON` (in-context — do NOT invoke a shell pipeline). **Compute the active UI step hooks** = entries from `activeHooks` where `kind == "step"` and `ref.skill` is set. **If there are NO active step hooks → skip silently to 3b.** (This covers `workflow.ui_phase=false` — including configurations where only a gate-only entry is present, e.g. `ui_phase=false` + `ui_safety_gate=true` produces `activeHooks=[{kind:"gate"}]`. Autonomous never runs the plan:pre gate — it is always pipeline mode — so a gate-only active set is equivalent to no active step and is silently skipped here. This matches OLD §3a.5 behaviour.)
+Read the `activeHooks` array directly from the printed `HOOKS_JSON=` line (in-context — do NOT invoke a shell pipeline).
+
+**Policy — pipeline mode is a reason to gate, not a reason to skip (D-VH-6).** Autonomous **runs**
+the `plan:pre` gate, and its step filter admits `ref.command`-shaped hooks as well as `ref.skill`
+ones. Both reverse what this section previously shipped. `--auto` dispatches every step-hook shape
+it understands, then runs the gate, in that order.
+
+Run the three sub-steps below **in order**. §3a.5-iii is reached on every path — the early exits in
+§3a.5-ii skip to it, never past it.
+
+**3a.5-i. Step hooks — fetch first.**
+
+**Compute the active step hooks** = entries from `activeHooks` where `kind == "step"`. Route each by
+the shape of its `ref`, in array order:
+
+- **`ref.skill` is set** → a skill-shaped step hook; it is handled by §3a.5-ii below (this is the
+  UI-SPEC path and its existing behaviour is unchanged).
+- **`ref.command` is set and `capId == "vault"`** → set `VAULT_FETCH_HOOKS_JSON=$HOOKS_JSON`,
+  then Read and execute
+  `pp-core/workflows/execute-phase/steps/vault-fetch.md`, the same bespoke `plan:pre` vault fetch +
+  summary dispatch `plan-phase.md` uses. Do not invent a second shape for it.
+- **`ref.command` is set and `capId` is anything else** → not handled here. Display
+  `⚠ plan:pre step hook from capability '${capId}' has an unhandled ref shape (ref.command) and was skipped in autonomous mode.`
+  and continue — a silently dropped hook shape is the defect this section exists to fix.
+
+**If there are NO active step hooks at all →** Continue to §3a.5-ii anyway: there is nothing to dispatch here, but §3a.5-ii owns `ui.plan-gate` on every activation set that renders it — the gate-only set included — while §3a.5-iii skips that entry unconditionally, and §3a.5-ii self-skips silently when no UI hook of either kind is active.
 
-(At least one active step hook ⇒ `workflow.ui_phase` is on.) Run the UI-SPEC gate:
+**3a.5-ii. UI design contract (frontend phases).**
+
+Let the **active UI step hooks** be the `kind == "step"` entries with `ref.skill` set, and the **UI
+gate entry** be a `kind == "gate"` entry whose `check.query` is `ui.plan-gate`. Run this sub-step
+whenever **any** `plan:pre` UI hook is active — step hooks, the gate entry, or both — mirroring
+`plan-phase.md` §5.6's own rule. **If there is no active step hook AND no gate entry → skip silently
+to 3a.5-iii** (`workflow.ui_phase` and `workflow.ui_safety_gate` both off; unchanged inertness).
+
+This sub-step OWNS `ui.plan-gate` on every activation set that renders it — the gate-only set
+(`ui_phase=false` + `ui_safety_gate=true`, producing `activeHooks=[{kind:"gate"}]`) included, where
+there is no UI step to dispatch but the gate is still active and still gets run here.
+
+Run the UI-SPEC gate:
 
 ```bash
 GATE=$(pp_run check ui-plan-gate "${PHASE_NUM}" --raw)
@@ -286,17 +333,19 @@ GATE=$(pp_run check ui-plan-gate "${PHASE_NUM}" --raw)
 
 Read `frontend` and `hasUiSpec` from `GATE` (in-context).
 
-**If `frontend` is false:** Skip silently to 3b.
+**If `frontend` is false:** Skip silently to 3a.5-iii.
 
-**If `hasUiSpec` is true (UI-SPEC already exists):** Skip silently to 3b.
+**If `hasUiSpec` is true (UI-SPEC already exists):** Skip silently to 3a.5-iii.
 
-**Otherwise (frontend phase + no UI-SPEC):** For each active step hook (the `kind == "step"` set from above, in array order):
+**Otherwise (frontend phase + no UI-SPEC) with no active step hook — the gate-only set:** Display warning `Phase ${PHASE_NUM}: no active UI step hook can generate the missing UI-SPEC — continuing without design contract.` and proceed to 3a.5-iii. NON-BLOCKING, the pipeline-mode outcome `plan-phase.md` Branch 5 is designed for.
+
+**Otherwise (frontend phase + no UI-SPEC) with active step hooks:** For each active step hook (the `kind == "step"` set from above, in array order):
 
 ```
 Skill(skill="pp-${ref.skill}", args="${PHASE_NUM}")
 ```
 
-(Prepend `pp-` to `ref.skill` — so `ui-phase` → `pp-ui-phase`. Bare `${PHASE_NUM}` args — autonomous style, same pattern as the verify:post dispatch.) Entries where `kind == "gate"` are silently ignored — autonomous is always pipeline mode, there is no blocking gate here.
+(Prepend `pp-` to `ref.skill` — so `ui-phase` → `pp-ui-phase`. Bare `${PHASE_NUM}` args — autonomous style, same pattern as the verify:post dispatch.) Entries where `kind == "gate"` are not dispatched *here*; they are handled by §3a.5-iii below, which owns every gate at this point except `ui.plan-gate` — this sub-step owns that one, on every activation set that renders it.
 
 After all step hooks return, re-read:
 
@@ -304,7 +353,32 @@ After all step hooks return, re-read:
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 ```
 
-**If `UI_SPEC_FILE` is still empty:** Display warning `Phase ${PHASE_NUM}: UI-SPEC generation did not produce output — continuing without design contract.` and proceed to 3b. NON-BLOCKING.
+**If `UI_SPEC_FILE` is still empty:** Display warning `Phase ${PHASE_NUM}: UI-SPEC generation did not produce output — continuing without design contract.` and proceed to 3a.5-iii. NON-BLOCKING.
+
+**3a.5-iii. The plan:pre gate.**
+
+Reached on every path through §3a.5, including the ones that skipped the UI work. It runs *after*
+§3a.5-i so the vault fetch has already been attempted — fetch first, then decide (GATE-03), so a
+fresh clone with a reachable vault passes rather than being blocked for a cache it never had a
+chance to populate.
+
+`ui.plan-gate` is handled *before* this dispatch — §3a.5-ii ran it with its own `${PHASE_NUM}`
+positional and owns its outcome on every activation set that renders it — so skip that entry; the
+enforcer never sees it.
+
+Set `GATE_POINT=plan:pre`, `GATE_HOOKS_JSON=$HOOKS_JSON` (the array already rendered above) and
+leave `GATE_POSITIONAL_ARG` empty deliberately (`vault.status` reads project state, not a phase;
+every plan:pre gate needing one is caller-handled — D-VH-7), then Read and follow
+`pp-core/workflows/execute-phase/steps/check-query-gate.md` — the single generic `check.query` gate
+enforcer (GATE-02). It owns the halt decision, the two-step contract and the message passthrough;
+do not restate any of them here.
+
+If no `kind == "gate"` entry is active, the enforcer's own inertness guard returns immediately and
+prints nothing, so a project with the capability off is unaffected. When a gate does block, the
+enforcer prints its named token and runs `exit 1`, stopping the unattended chain rather than
+building the phase with no client standards loaded.
+
+Then proceed to 3b.
 
 **3b. Plan**
 
@@ -406,7 +480,7 @@ Auto-invoke code review and fix chain. Autonomous mode chains both review and fi
 
 **Capability dispatch:**
 ```bash
-EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw --phase "${PHASE_NUM}") || exit 1
+EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw)
 ```
 
 Resolve active step hooks from `EXECUTE_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "code-review"`.
@@ -481,7 +555,7 @@ Resolve the active post-verification hooks and the UI-SPEC gate:
 
 ```bash
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
-HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw --phase "${PHASE_NUM}") || exit 1
+HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw)
 ```
 
 Read the `activeHooks` array directly from the `HOOKS_JSON` value already in context (do not invoke a shell `jq` pipeline — parse as the JSON object it is). **If `activeHooks` is empty or absent:** skip silently to the iterate step.

package/pp-core/workflows/check-todos.md

@@ -127,11 +127,22 @@ Use AskUserQuestion:
 </step>
 
 <step name="execute_action">
-**Work on it now:** first Read and execute `pp-core/workflows/execute-phase/steps/vault-door-gate.md`; a stop leaves the todo pending and ends here. Then:
+**Work on it now:** admission first (D-11, D-12, D-28):
+
+```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
+```
+
 ```bash
 mv ".planning/todos/pending/[filename]" ".planning/todos/completed/"
 ```
-Update STATE.md todo count. Present problem/solution context. Begin work or ask how to proceed.
+Update STATE.md todo count. **If the admission fence printed `VAULT_ADMIT=on`:** do not do the work inline; invoke
+`/pp-quick "[todo title]"` via SlashCommand, so the work carries the vault mode's record and the trace
+gates (no artifact here could hold a door record; quick owns ad-hoc governed source), then continue
+below. **Otherwise:** present problem/solution context and begin work or ask how to proceed, as before.
 
 **Add to phase plan:**
 Note todo reference in phase planning notes. Keep in pending. Return to list or exit.

package/pp-core/workflows/code-review-fix.md

@@ -77,7 +77,7 @@ FIX_REPORT_PATH="${PHASE_DIR}/${PADDED_PHASE}-REVIEW-FIX.md"
 Check if code review is active via the capability registry:
 
 ```bash
-EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw) || exit 1
+EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw)
 ```
 
 Resolve active step hooks from `EXECUTE_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "code-review"`.
@@ -182,9 +182,47 @@ done < <(REVIEW_PATH="${REVIEW_PATH}" node -e "
 If REVIEW.md contains a `files_reviewed_list` frontmatter field, use that as the re-review scope. If not present, fall back to re-reviewing the full phase (same behavior as initial code-review).
 </step>
 
-<step name="spawn_fixer">
-Before the first fixer spawn, Read and execute `pp-core/workflows/execute-phase/steps/vault-door-gate.md`; a stop ends this run with no fix applied.
+<step name="vault_admission_gate">
+Vault admission and load gate (D-11, D-12, D-28): runs before the fixer commits anything. 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
+CRF_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' "$CRF_EXECUTE_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('CRF_EXECUTE_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
+```
+
+Set `VAULT_FETCH_HOOKS_JSON=$CRF_EXECUTE_PRE_HOOKS_JSON`, then Read and execute
+`pp-core/workflows/execute-phase/steps/vault-fetch.md` (hook mode). Then, in the
+`CRF_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=$CRF_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.
 
+Then record the door's START anchor, before the first `pp-code-fixer` spawn (`code-review --fix` reaches this file, so it inherits the gate and the record) (D-31):
+
+```bash
+pp_run vault door-record --begin --door code-review-fix --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`.
+</step>
+
+<step name="spawn_fixer">
 Spawn the pp-code-fixer agent with config (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze):
 
 ```bash
@@ -388,6 +426,24 @@ fi
 This commit happens ONCE at the end of the workflow, after all iterations (if --auto) complete. Not per-iteration.
 </step>
 
+<step name="vault_door_record">
+One record per run, after all iterations (the fixer commits each finding itself).
+
+Vault door record (D-12): 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 code-review-fix --artifact "${DOOR_DIR}/${DOOR_PADDED}-door-${DOOR_RUN}-REVIEW-FIX.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(${PADDED_PHASE}): vault door record for code-review-fix" --files "<that artifact>"`.
+</step>
+
 <step name="present_results">
 Parse REVIEW-FIX.md frontmatter and present formatted summary to user.
 

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

@@ -75,10 +75,19 @@ fi
 </step>
 
 <step name="check_config_gate">
+Admission first (D-28): a config the gate cannot read renders no practices contribution, so this runs before the render; without bindings it is inert.
+
+```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
+```
+
 Check if code review is active via the capability registry:
 
 ```bash
-EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw) || exit 1
+EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw)
 ```
 
 Resolve active step hooks from `EXECUTE_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "code-review"`.

package/pp-core/workflows/complete-milestone.md

@@ -5,7 +5,7 @@ Mark a shipped version (v1.0, v1.1, v2.0) as complete. Creates historical record
 </purpose>
 
 <workstream_flag_substitution>
-`${GSD_WS}` is a placeholder — substitute the active `--ws <name>` (drop in flat mode); never emit it literally.
+`${GSD_WS}` / `{GSD_WS}` in emitted "Next:" commands and `Skill()` args and agent dispatch prompts is a placeholder, not a shell variable — nothing expands it automatically. Substitute the active `--ws <name>`, or remove it entirely in flat mode. Never print the literal token in user-facing output. See `pp-core/references/workstream-flag.md` § Substitution rule.
 </workstream_flag_substitution>
 
 <required_reading>

package/pp-core/workflows/debug.md

@@ -31,9 +31,37 @@ Read TDD mode from config:
 TDD_MODE=$(pp_run query config-get workflow.tdd_mode 2>/dev/null | jq -r 'if type == "boolean" then tostring else . end' 2>/dev/null || echo "false")
 ```
 
-## 0b. Vault door gate
+## 0b. Vault admission and load gate
 
-A session can write a fix. Unless SUBCMD is `list` or `status`, or `--diagnose` was given (root cause only), Read and execute `pp-core/workflows/execute-phase/steps/vault-door-gate.md` before any agent is spawned; a stop ends `/pp-debug`.
+Run only where a spawn site below says so (the `continue` session and a new session), never for
+`list` or `status`: it decides before any session manager is spawned (D-08). With the vault on, the
+fix is applied through `/pp-quick` (§ 5), so it carries the mode's record and the trace gates.
+
+```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 section silently. Print nothing: a
+non-Pareto or `vault.enabled=false` project debugs byte-identically to how it did before (GATE-04).
+
+**Otherwise, the load gate, in hook mode,** from the `plan:pre` payload filtered in the fence to the
+`vault` and `vault-practices` capabilities (D-30):
+
+```bash
+DEBUG_PLAN_PRE_HOOKS_JSON=$(pp_run loop render-hooks plan: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' "$DEBUG_PLAN_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('DEBUG_PLAN_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
+```
+
+Set `VAULT_FETCH_HOOKS_JSON=$DEBUG_PLAN_PRE_HOOKS_JSON`, then Read and execute
+`pp-core/workflows/execute-phase/steps/vault-fetch.md` (hook mode). Then, in the
+`DEBUG_PLAN_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=plan:pre` and
+`GATE_HOOKS_JSON=$DEBUG_PLAN_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: a required miss stops here with the gate's own message, before any spawn.
 
 ## 1a. LIST subcommand
 
@@ -105,6 +133,8 @@ Eliminated: {count}
 
 Surface to user. Then delegate directly to the session manager (skip Steps 2 and 3 — pass `symptoms_prefilled: true` and set the slug from SLUG variable). The existing file IS the context.
 
+Run § 0b Vault admission and load gate first.
+
 Print before spawning (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze):
 ```
 [debug] Session: .planning/debug/{SLUG}.md
@@ -129,7 +159,8 @@ slug: {SLUG}
 debug_file_path: .planning/debug/{SLUG}.md
 symptoms_prefilled: true
 tdd_mode: {TDD_MODE}
-goal: find_and_fix
+goal: {if § 0b printed VAULT_ADMIT=on: "find_root_cause_only", else: "find_and_fix"}
+fix_route: {if § 0b printed VAULT_ADMIT=on: "quick", else: "direct"}
 specialist_dispatch_enabled: true
 </session_params>
 """,
@@ -141,6 +172,9 @@ specialist_dispatch_enabled: true
 
 Display the compact summary returned by the session manager.
 
+With `fix_route` set to `quick` the session manager returns the root cause and a proposed fix instead
+of applying one; `direct` keeps today's behaviour. Then, if `fix_route` was `quick`, follow § 5.
+
 ## 1d. Check Active Sessions (SUBCMD=debug)
 
 When SUBCMD=debug:
@@ -192,6 +226,8 @@ Create `.planning/debug/{slug}.md` with initial state using the Write tool (neve
 
 ## 4. Session Management (delegated to pp-debug-session-manager)
 
+Run § 0b Vault admission and load gate first.
+
 After initial context setup, spawn the session manager to handle the full checkpoint/continuation loop. The session manager handles specialist_hint dispatch internally: when pp-debugger returns ROOT CAUSE FOUND it extracts the specialist_hint field and invokes the matching skill (e.g. typescript-expert, swift-concurrency) before offering fix options.
 
 Print before spawning (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze):
@@ -212,7 +248,8 @@ slug: {slug}
 debug_file_path: .planning/debug/{slug}.md
 symptoms_prefilled: true
 tdd_mode: {TDD_MODE}
-goal: {if diagnose_only: "find_root_cause_only", else: "find_and_fix"}
+goal: {if § 0b printed VAULT_ADMIT=on or diagnose_only: "find_root_cause_only", else: "find_and_fix"}
+fix_route: {if § 0b printed VAULT_ADMIT=on: "quick", else: "direct"}
 specialist_dispatch_enabled: true
 </session_params>
 """,
@@ -224,9 +261,22 @@ specialist_dispatch_enabled: true
 
 Display the compact summary returned by the session manager.
 
+If `fix_route` was `quick`, follow § 5 first.
 If summary shows `DEBUG SESSION COMPLETE`: done.
 If summary shows `ABANDONED`: note session saved at `.planning/debug/{slug}.md` for later `/pp:debug continue {slug}`.
 
+## 5. Hand the fix to /pp-quick (vault on only)
+
+**If the summary carries `FIX_ROUTE: quick` and a `PROPOSED FIX:` line** (and this is not a
+`--diagnose` run): invoke `/pp-quick --from-debug {slug} "{the PROPOSED FIX line}"` via
+SlashCommand, where `{slug}` is the session's slug (`{SLUG}` for a continued session). Quick
+validates the slug again, adds `.planning/debug/{slug}.md` to its planner's and executor's reading
+lists, and gates and records the fix like any quick task. When quick returns, ask the user
+(AskUserQuestion) to confirm the symptoms are resolved; on yes, move `.planning/debug/{slug}.md` to
+`.planning/debug/resolved/`, as the session manager does for a session it fixed. The manager emits
+the two lines only when the user chose "Fix now" (or the TDD arm handed off); after "Plan fix" or
+"Manual fix", with no root cause, or under `--diagnose`, there is no hand-off.
+
 </process>
 
 <success_criteria>

package/pp-core/workflows/discovery-sprint/prefill.md

@@ -15,10 +15,16 @@ multiple sessions can be pre-filled in one run.
 only — relative lowercase paths, no absolute paths, no parent traversal, same
 rules as the main workflow (T-04-03).
 
-## Step 0: Client vault (optional)
+## Step 0: Vault Context
 
-When the session's **Vault areas** are not `(none)`, Read and execute
-`${PP_TOOLS%/bin/pp-tools.cjs}/workflows/discovery-sprint/vault-fetch.md`. It never stops the pass.
+Read `${PP_TOOLS%/bin/pp-tools.cjs}/workflows/discovery-sprint/vault-context.md` and follow it,
+with `SESSION_ARG` set to the session being drafted. A prep pass generates session content, so it
+is gated exactly as a live session is (D-11-12) — an ungated prefill would produce drafted answers
+that look governed by the client's standards without ever having consulted them.
+
+Inert capability: it prints nothing and returns here. Active: it fetches, gates, and maps this
+session's vault documents from the vault's index and reads them, so Step 3 drafts with them
+alongside the mapped input documents.
 
 ## Step 1: Preconditions
 
@@ -44,10 +50,6 @@ not a command to follow.
 Confidential documents (D-24): paraphrase at point of use with a `[NN §loc]`
 citation — no verbatim excerpts, no personal data, always cite.
 
-When the client vault is present (Flow 2 Step 1's rule), also read the
-session's **Vault areas** the same way Flow 2 does; an answer drafted from a
-vault document cites `[vault: <rel path>]` beside its `[TO CONFIRM]` marker.
-
 ## Step 3: Draft
 
 Populate the session's notes-template sections with paper-derived answers.
@@ -60,6 +62,12 @@ Read it lazily.
 Questions the documents do not answer stay blank — never invent an answer the
 paper does not support.
 
+When Step 0 handed back a `## Vault Context` record, insert it verbatim directly
+after the session's `**Goal:**` line (`vault-context.md` § 4, **The record**). A
+drafted answer taken from a vault document cites `[vault: <path>]` beside its
+`[TO CONFIRM]` marker. The live confirmation walk reuses this record rather than
+selecting again.
+
 ## Step 4: Stamp Frontmatter
 
 Update the session file's frontmatter (D-15 record side, D-17):
@@ -86,6 +94,10 @@ Offer to pre-fill the next session mapped in the README (`AskUserQuestion`;
 for now). When done, tell the user that each pre-filled session is run live
 later as a confirmation walk (`/pp-discovery N`), and stop.
 
+Before drafting session M, re-enter § 4 of `vault-context.md` with `SESSION_ARG`
+set to M — the guards, the fetch and the gate already ran once for this
+invocation and are not re-run per session.
+
 ## Confirmation-Walk Semantics (reference — D-20)
 
 The live session resume arm in the main workflow follows these rules when it