@pareto4/pp-core 1.13.0 → 1.17.1

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

@@ -32,10 +32,6 @@ duplicate the external job). The manifest schema is the stability contract in
 a capability (#1164), not core.
 </atomic_close_out_invariant>
 
-<dispatch_scope>
-Under execute-phase every spawn's prompt carries `<dispatch tracking="orchestrator" suite="orchestrator" build="…" />` (rules: `agents/pp-executor.md` `<dispatch_contract>`). Then skip update_current_position, extract_decisions_and_issues, update_session_continuity, update_roadmap and update_requirements; git_commit_metadata commits the SUMMARY.md only; run the plan's touched test files, never the full suite; build only when `build="true"`. The orchestrator advances STATE, ROADMAP and REQUIREMENTS and runs the full suite once per wave. Without the tag (inline execution) every step runs as written.
-</dispatch_scope>
-
 <available_agent_types>
 Valid pp-core subagent types (use exact names — do not fall back to 'general-purpose'):
 - pp-executor — Executes plan tasks, commits, creates SUMMARY.md
@@ -57,8 +53,40 @@ 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 name="vault_admission_gate">
+Runs here because `<step name="execute">` below is the first step that writes a file or spawns an
+agent, and the gate has to decide before code can be written, not after.
+
+Admission first (D-28): `vault admission` checks bindings first, then parses every config file the
+gate reads. A config the gate cannot read would render no vault hook and skip in silence, so with
+bindings present it halts here, naming the file and the repair (D-05).
+
+```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 step and the `vault_trace_gate`
+step silently and continue. Print nothing: a non-Pareto or `vault.enabled=false` project runs this
+workflow byte-identically to how it ran before this gate existed (GATE-04).
+
+**Otherwise, the load gate, in hook mode.** Render `execute:pre` and keep only the `vault` and
+`vault-practices` hooks, mechanically in the fence (D-30): no other capability's hook is run or
+injected here, because execute-phase's dispatcher owns those for its own run.
+
+```bash
+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' "$EXECUTE_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('EXECUTE_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
+```
+
+In the `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=$EXECUTE_PRE_HOOKS_JSON`, leave `GATE_POSITIONAL_ARG`, `GATE_WS` and `GATE_STAGE`
+empty (`vault.status` reads project state, not a phase), then Read and follow
+`pp-core/workflows/execute-phase/steps/check-query-gate.md`. That single enforcer (GATE-02) owns
+the two-step contract, the halt and the message passthrough; none of them are restated here.
 </step>
 
 <step name="identify_plan">
@@ -86,6 +114,26 @@ Present plan identification, wait for confirmation.
 </if>
 </step>
 
+<step name="vault_trace_gate">
+This gate judges the ONE plan this run executes (D-06, D-38): a plan with no `<vault_practices>` /
+`<vault_standards>` record is blocked (`practices_block_absent` / `standards_block_absent`), never
+rendered as nothing. Skip this step silently unless the admission step printed `VAULT_ADMIT=on`. The
+positional is the plan file, not its phase directory: sibling plans mid-wave are not this run's
+business, and `check vault.trace <plan file> --stage plan` by hand gives this gate's verdict.
+
+```bash
+PLAN_POST_HOOKS_JSON=$(pp_run loop render-hooks plan:post --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' "$PLAN_POST_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('PLAN_POST_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
+```
+
+In the `PLAN_POST_HOOKS_JSON=` line that fence printed, find active entries where `kind == "gate"` and `check.query ==
+"vault.trace"`; if none, skip silently. Otherwise set `GATE_POINT=plan:post`,
+`GATE_HOOKS_JSON=$PLAN_POST_HOOKS_JSON`, `GATE_POSITIONAL_ARG="$PLAN_PATH"` and `GATE_STAGE=plan`,
+leave `GATE_WS` empty (a PLAN file carries its own partition) and set no strictness (`plan:post` is
+mid-lifecycle), then Read and follow `pp-core/workflows/execute-phase/steps/check-query-gate.md`; it
+owns the halt.
+</step>
+
 <step name="record_start_time">
 ```bash
 PLAN_START_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
@@ -392,6 +440,8 @@ One-liner SUBSTANTIVE: "JWT auth with refresh rotation using jose library" not "
 Include: duration, start/end times, task count, file count.
 
 Next: more plans → "Ready for {next-plan}" | last → "Phase complete, ready for next step".
+
+**Practices Applied (only when the plan carried a `<vault_practices>` block):** inside the atomic block above and BEFORE the Write, run `pp_run vault trace render` against the execute-stage ledger and include the returned section in that same single Write — no narrative between the render and the Write, for the reason the critical-ordering note already gives. It belongs here and not in the end-of-phase gate: the code reviewer reads this section from every summary in the phase and runs first inside that gate step, so a section produced there would never be visible to it.
 </step>
 
 <step name="update_current_position">

package/pp-core/workflows/fast.md

@@ -21,7 +21,46 @@ What's the quick fix? (one sentence)
 Store as `$TASK`.
 </step>
 
+<step name="vault_admission_gate">
+**This workflow exists to be minimal, and this block is the smallest form that still guards.** An
+entry point that skips the gate is an entry point that launders ungoverned code past it, so "trivial"
+cannot mean "unchecked" — but nothing beyond the admission check and one Read below is added here.
+
+Runs before `scope_check`, because the refusal there needs the admission answer (D-07), and so
+before `execute_inline`, the first step that edits a file.
+
+`fast.md` declares no loop-host frontmatter, renders no hooks and writes no record, so it reaches the
+shared verdict envelope through the enforcer's **direct-query mode** (GATE-06) and, with the vault
+on, refuses source edits instead of recording them. No loop-host contract bump; no second copy of
+the halt. It also has no launcher shim of its own, so the canonical one is resolved here.
+
+Admission first (D-28): bindings first, then every config file the gate reads is parsed. With
+bindings present, a config the gate cannot read halts here, naming the file and the repair (D-05).
+
+```bash
+_PP_SHIM_NAME="pp-tools.cjs"; _pp_root() { ( for _v in $(env | sed -n 's/^\(GIT_[A-Za-z0-9_]*\)=.*/\1/p'); do unset "$_v"; done; _c=$(git rev-parse --git-common-dir 2>/dev/null); if [ "${_c##*/}" = .git ] && cd "$_c/.." 2>/dev/null; then pwd -P; else git rev-parse --show-toplevel 2>/dev/null || pwd; fi ); }; pp_run() { case "$PP_TOOLS" in *.cjs) node "$PP_TOOLS" "$@";; *) "$PP_TOOLS" "$@";; esac; }; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(_pp_root)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then :; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+VAULT_ADMIT_PRESENT=$(pp_run query platform-bindings --pick present 2>/dev/null || echo true)
+VAULT_ADMIT=inert
+if [ "$VAULT_ADMIT_PRESENT" = true ]; then VAULT_ADMIT=$(pp_run vault admission 2>/dev/null || echo unrecognised); fi
+case "$VAULT_ADMIT" in on) echo "VAULT_ADMIT=on" ;; off|inert) : ;; *) pp_run vault admission --explain; echo "PARETO_GATE_BLOCKED:vault.admission"; exit 1 ;; esac
+```
+
+**If the fence printed no `VAULT_ADMIT=on` line** (`off` and `inert` print nothing): skip the rest of this step silently and continue. Print
+nothing: a non-Pareto or `vault.enabled=false` project runs this workflow byte-identically to how it
+ran before this gate existed (GATE-04).
+
+**Otherwise, enforce.** Set `GATE_POINT=fast:pre` and `GATE_DIRECT_QUERY=vault.status`, leave
+`GATE_HOOKS_JSON` and `GATE_POSITIONAL_ARG` empty, then Read and follow
+`pp-core/workflows/execute-phase/steps/check-query-gate.md`. That file owns the two-step contract,
+the halt and the message passthrough — none of them are restated here.
+</step>
+
 <step name="scope_check">
+**If the admission step printed `VAULT_ADMIT=on`:** this vault-enabled project governs source through `/pp-quick`. If the
+task would edit ANY path outside `.planning/` (source, tests, docs, config: the requirement's
+letter, D-07), name the path(s), say `Use /pp-quick "{task description}" — it records and gates
+source changes in this project.`, and stop. A `.planning/`-only task continues below.
+
 **Before doing anything, verify this is actually trivial.**
 
 A task is trivial if it can be completed in:
@@ -41,10 +80,6 @@ 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:
 
@@ -60,9 +95,23 @@ Commit the change atomically:
 
 ```bash
 git add -A
+FAST_ADMIT=$(pp_run vault admission 2>/dev/null || echo unrecognised)
+FAST_OUTSIDE=
+case "$FAST_ADMIT" in off|inert) : ;; *) FAST_OUTSIDE=$(git diff --cached --name-only -- ':!.planning') ;; esac
+if [ -n "$FAST_OUTSIDE" ]; then
+  printf 'Refused: this vault-enabled project governs source through /pp-quick. Paths outside .planning/:\n%s\n' "$FAST_OUTSIDE"
+  git reset -q -- ':!.planning'
+  exit 1
+fi
 git commit -m "fix: {concise description of what changed}"
 ```
 
+The backstop is the mechanical form of the `scope_check` refusal: an agent's judgement cannot be
+tested, a pathspec can. It asks the admission verb again inside this fence (a variable from an
+earlier fence does not survive into this shell, D-77), so it is inert only on `off`/`inert` and
+refuses on anything else. It unstages only the paths outside `.planning/` and never touches the
+working tree, because `git add -A` also staged unrelated user work.
+
 Use conventional commit format: `fix:`, `feat:`, `docs:`, `chore:`, `refactor:` as appropriate.
 </step>
 

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 and `--max-cycles N` pass through to it.
+- **`--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.
 - **`--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.
+- **`/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: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
@@ -601,8 +601,8 @@ The commands above cover the most common day-to-day flows. Every command listed
 - **`/pp:secure-phase [phase]`** — Retroactively verify threat mitigations for a completed phase.
 - **`/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:vault-review [phase]`** — Retroactive per-practice vault review (counts by verdict; reports, never gates).
 - **`/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/steps/client-context-capture.md

@@ -0,0 +1,101 @@
+# Gated client-context capture (Pareto projects — bindings present)
+
+Lazily Read by `pp-core/workflows/init.md` § "Gated client-context capture" only after
+that step's `pp_run query platform-bindings --pick present` gate has already answered
+`"true"`. A non-Pareto project never reads this file, so the capture stays fully inert
+there (D-04, success criterion #4); all capture is offline-only — no Obsidian, no MCP,
+no network (D-05 / T-09-05). Extracted from `init.md` (07-03) so the always-loaded
+workflow stays under its DEFAULT size cap — relocation, not deletion: this file is the
+authority for the five-field capture, the re-run edit path and the managed-block write.
+
+```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
+if [ "$(pp_run query platform-bindings --pick present 2>/dev/null)" = "true" ]; then
+  # ── D-05: edit-on-re-run — read existing block first ──────────────────────────
+  EXISTING=$(pp_run query generate-client-context --read 2>/dev/null || echo '{"present":false}')
+  EXISTING_PRESENT=$(echo "$EXISTING" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const o=JSON.parse(d);process.stdout.write(String(o.present||'false'));}catch{process.stdout.write('false');}")
+
+  if [ "$EXISTING_PRESENT" = "true" ]; then
+    echo ""
+    echo "Existing client-context block found. Press Enter to keep each value, or type to replace it."
+    EXISTING_CLIENT_NAME=$(echo "$EXISTING" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const o=JSON.parse(d);process.stdout.write(o.client_name||'');}catch{}" 2>/dev/null)
+    EXISTING_CLIENT_SLUG=$(echo "$EXISTING" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const o=JSON.parse(d);process.stdout.write(o.client_slug||'');}catch{}" 2>/dev/null)
+    EXISTING_CODING=$(echo "$EXISTING" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const o=JSON.parse(d);process.stdout.write(o.coding_standards||'');}catch{}" 2>/dev/null)
+    EXISTING_ARCH=$(echo "$EXISTING" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const o=JSON.parse(d);process.stdout.write(o.architecture_patterns||'');}catch{}" 2>/dev/null)
+    EXISTING_UI=$(echo "$EXISTING" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const o=JSON.parse(d);process.stdout.write(o.ui_brand_conventions||'');}catch{}" 2>/dev/null)
+    EXISTING_DOD=$(echo "$EXISTING" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const o=JSON.parse(d);process.stdout.write(o.definition_of_done||'');}catch{}" 2>/dev/null)
+  fi
+fi
+```
+
+**Field capture — one field at a time (D-01, D-02):** Prompt the user for each of the five fields
+sequentially. All five are required — **re-prompt on empty input until a non-empty value is given**
+(no skip, no catch-all). Multi-line values are accepted: instruct the user to type or paste, then
+enter a blank line (or a sentinel line such as `EOF`) to signal end-of-field. Do not call any
+network resource during capture.
+
+Capture these fields, in this order:
+
+1. **Client name** — the human-readable client or project name (e.g. "Acme Corp").
+   - On re-run: show the current value (`$EXISTING_CLIENT_NAME`) and let the user keep or replace.
+   - After capturing, derive a URL-safe slug via `pp_run query generate-slug` on the name; present
+     the suggested slug and let the user confirm or override. Store as `CLIENT_SLUG`.
+
+2. **Coding standards** — the conventions and rules the Build agent must follow (e.g. language,
+   style guide, patterns to use/avoid). Multi-line OK.
+   - On re-run: show `$EXISTING_CODING`.
+
+3. **Architecture patterns** — the structural patterns and constraints the Build agent must respect
+   (e.g. layering, module boundaries, framework idioms). Multi-line OK.
+   - On re-run: show `$EXISTING_ARCH`.
+
+4. **UI / brand conventions** — visual and component standards the Build agent must apply (e.g.
+   design system, color tokens, typography rules). Multi-line OK.
+   - On re-run: show `$EXISTING_UI`.
+
+5. **Definition of done** — the quality gates that must pass before any task is marked complete
+   (e.g. tests green, lint clean, accessibility checked). Multi-line OK.
+   - On re-run: show `$EXISTING_DOD`.
+
+**Write block** — after all five fields are captured, write them to a temp file and invoke the
+managed-block writer:
+
+```bash
+if [ "$(pp_run query platform-bindings --pick present 2>/dev/null)" = "true" ]; then
+  # Write collected values to a temp JSON file using node + JSON.stringify so that
+  # multi-line values, embedded quotes, backslashes, and $(...) sequences are encoded
+  # correctly (CR-02: an unquoted heredoc would produce invalid JSON for any multi-line
+  # field, breaking cmdGenerateClientContext with "Failed to parse JSON input").
+  TMP_CTX=$(mktemp /tmp/pp-client-ctx-XXXXXX.json)
+  CLIENT_NAME="$CLIENT_NAME" \
+  CLIENT_SLUG="$CLIENT_SLUG" \
+  CODING_STANDARDS="$CODING_STANDARDS" \
+  ARCHITECTURE_PATTERNS="$ARCHITECTURE_PATTERNS" \
+  UI_BRAND_CONVENTIONS="$UI_BRAND_CONVENTIONS" \
+  DEFINITION_OF_DONE="$DEFINITION_OF_DONE" \
+  node -e "
+const e = process.env;
+const fs = require('fs');
+fs.writeFileSync(process.argv[1], JSON.stringify({
+  client_name: e.CLIENT_NAME,
+  client_slug: e.CLIENT_SLUG,
+  coding_standards: e.CODING_STANDARDS,
+  architecture_patterns: e.ARCHITECTURE_PATTERNS,
+  ui_brand_conventions: e.UI_BRAND_CONVENTIONS,
+  definition_of_done: e.DEFINITION_OF_DONE
+}));
+" "$TMP_CTX"
+
+  # Invoke the Plan 09-01 writer — routes through updateSection, marker-bounded, idempotent
+  pp_run query generate-client-context --from-json "$TMP_CTX"
+  rm -f "$TMP_CTX"
+  echo "Client context written to CLAUDE.md (<!-- PP:client-context-start --> block)."
+fi
+```
+
+This writes a `## Client Context & Patterns` block bounded by
+`<!-- PP:client-context-start -->` … `<!-- PP:client-context-end -->` markers into the local
+CLAUDE.md (config-driven path, default `./.claude/CLAUDE.md`). The write is idempotent —
+re-running `/pp-init` replaces the bounded block, never duplicates it. All values stay local;
+no network or external service is involved.
+

package/pp-core/workflows/init/steps/gitlab-provisioning.md

@@ -0,0 +1,130 @@
+# Gated GitLab provisioning — G-2..G-5 (D-05, D-09, D-10, D-11, D-12, D-13)
+
+Lazily Read by `pp-core/workflows/init.md` § "Gated GitLab/Azure provisioning" — Step 3's
+other sub-path — and ONLY when BOTH of that section's gates hold: `.platform-bindings.json`
+is present AND `resolveProvider` answers `gitlab`. Both gates, G-1's one-source-per-value
+config reads, the empty-group guard and the security-invariant list stay in `init.md`; this
+file is the create recipe those guards protect. Extracted from `init.md` (07-10) so the
+always-loaded workflow stays under its DEFAULT size cap — relocation, not deletion: this
+text is the authority for how `/pp-init` provisions a GitLab project, and `$GROUP`, `$SLUG`,
+`$VIS`, `$DESC` and `$HOST` are the variables G-1 has already set.
+
+#### G-2. Auth verify-only (D-11)
+
+`/pp-init` **never establishes auth and never reads or writes the user's token.**
+Secrets stay in the environment or OS keyring. Only verify that a session exists:
+
+```bash
+glab auth status >/dev/null 2>&1 || {
+  echo "Not authenticated to GitLab. Run: glab auth login"
+  exit 1
+}
+```
+
+If this check fails, stop immediately. Do not proceed to probe or create.
+Never run `glab auth login` from within `/pp-init`.
+
+#### G-3. Existence probe → adopt-if-exists (D-09, D-12)
+
+Pre-check with a read-only probe before any create attempt. `glab repo create` is **not
+idempotent** — re-running it against an existing project errors but may still produce side
+effects (the GitLab project is created before the remote-add step that then fails). The
+probe avoids this landmine.
+
+This is one self-contained block: it sets `PROJECT_EXISTS` and, on the exists path,
+adopts (links the remote). It NEVER creates — create lives in its own G-4 block, gated
+on `PROJECT_EXISTS=false`, so the create invocation can never fall inside the exists
+branch.
+
+```bash
+if glab repo view "$GROUP/$SLUG" -F json >/dev/null 2>&1; then
+  # Project already exists — ADOPT: link remote only, skip create (D-12)
+  PROJECT_EXISTS=true
+  echo "GitLab project $GROUP/$SLUG already exists — adopting (linking remote, skipping create)."
+  # IN-01: match the remote scheme glab itself uses on the create path — honor the
+  # user's `glab config get git_protocol` (https default) instead of hardcoding SSH,
+  # so adopt and create produce a consistent origin URL.
+  GIT_PROTO=$(glab config get git_protocol 2>/dev/null || echo https)
+  if [ "$GIT_PROTO" = "ssh" ]; then
+    ADOPT_URL="git@${HOST:-gitlab.com}:$GROUP/$SLUG.git"
+  else
+    ADOPT_URL="https://${HOST:-gitlab.com}/$GROUP/$SLUG.git"
+  fi
+  git remote get-url origin >/dev/null 2>&1 || git remote add origin "$ADOPT_URL"
+  echo "Remote 'origin' → $ADOPT_URL"
+else
+  # Project not found — defer to G-4 for confirm-then-create
+  PROJECT_EXISTS=false
+  echo "GitLab project $GROUP/$SLUG not found — will confirm before create."
+fi
+```
+
+If the project exists (`PROJECT_EXISTS=true`), the remote is already linked above
+(skipping create entirely) — proceed straight to G-5 reconciliation. The adopt path does
+not show a create confirmation — it only links the remote, which is a local-only
+operation and can be undone with `git remote remove origin`.
+
+#### G-4. Per-action confirmation, then create (D-05, D-09, D-10, SAFE-01)
+
+**Only run this step when `PROJECT_EXISTS=false`** (the existence probe in G-3 found no
+project). If `PROJECT_EXISTS=true`, skip G-4 entirely — the project was already adopted —
+and go to G-5. When creating, **show the exact command and target before firing**. The
+user must confirm explicitly. Nothing is batched. (D-05)
+
+Present to the user (via `AskUserQuestion` or TEXT_MODE numbered list):
+
+```text
+About to create GitLab project:
+  Command:        glab repo create "$GROUP/$SLUG"
+  Group path:     $GROUP/$SLUG
+  Visibility:     private (enforced --private; never the glab default --internal)
+  Requested:      $VIS  (from bindings gitlab.visibility — see note below)
+  Default branch: main
+  Skip git init:  yes  (local repo already initialized — --skipGitInit)
+  Remote name:    origin
+
+Proceed? [y/N]
+```
+
+`$VIS` (from G-1) is surfaced in the confirmation so the binding's requested visibility is
+never silently ignored (WR-01). pp-core always **creates private** regardless; a
+non-private binding must be applied as a deliberate, separate post-create change.
+
+Only after the user confirms — and only with `PROJECT_EXISTS=false` — run the locked
+create recipe (D-09, D-10). This is a standalone block: it carries no `if`/`else`/`fi`, so
+it can only ever run as the deliberate, confirmed not-exists path:
+
+```bash
+glab repo create "$GROUP/$SLUG" \
+  --description "$DESC" \
+  --private \
+  --defaultBranch main \
+  --skipGitInit \
+  --remoteName origin
+```
+
+**Visibility hard-default (D-10):** the create invocation always carries `--private`.
+Never omit it and let `glab` silently apply `--internal`. `VIS` from bindings is read in
+G-1 and **surfaced in the G-4 confirmation** (WR-01) so a `public`/`internal` request is
+visible to the user — but pp-core still creates the project **private**. Applying a
+non-private visibility is a deliberate, separate post-create action (e.g. `glab repo edit
+--visibility …`) the operator performs knowingly; `/pp-init` never auto-relaxes visibility.
+
+#### G-5. Post-create reconciliation (D-09)
+
+After the create (or after the adopt path), re-probe existence. A non-zero exit from
+`glab repo create` does **not** mean the project was not created — `glab` exits non-zero
+(code 3) when the GitLab project was created but the subsequent `git remote add` step
+then failed (e.g., because `origin` already existed). The `repo view` probe is the source
+of truth, not the exit code (research §1 "Remote-add caveat — VERIFIED"):
+
+```bash
+if glab repo view "$GROUP/$SLUG" -F json >/dev/null 2>&1; then
+  echo "Reconciled: GitLab project $GROUP/$SLUG confirmed."
+else
+  echo "WARN: glab repo view $GROUP/$SLUG returned non-zero — verify the project was created before continuing."
+fi
+```
+
+If reconciliation warns, do not auto-retry. Prompt the user to check GitLab directly
+before proceeding to Step 4 (handoff routing).

package/pp-core/workflows/init/steps/project-md-deferral-narration.md

@@ -0,0 +1,66 @@
+# Narrating an init deferral into PROJECT.md (D-07-03, OD-2)
+
+**Read by two callers, immediately before either writes `.planning/PROJECT.md`:**
+`pp-core/workflows/new-project.md` § 4 and `pp-core/workflows/discovery-to-build.md` § 5d.
+
+This file is the **single rendering** of the reachability-proof deferral that `/pp-init`
+Step 2.6 recorded. OD-2 is one source of truth and one rendering: the record lives in
+`.planning/config.json` under the four `init.probe_*` keys, and this block is the only
+place that turns it into prose. Neither caller restates the logic — a second copy would
+be a second rendering, and the two would drift.
+
+Nothing here re-derives who deferred, when, or why. Those three facts were captured by
+`pp-tools init-contract --defer-probe` (07-01), which enforces a stated reason. Re-deriving
+any of them from the git identity, the environment or the clock would invent a fourth fact
+the operator never asserted.
+
+Run the block from the project root. It is **silent** unless a deferral is on file — a
+project whose proof passed, or that never ran the proof at all, prints nothing and adds no
+section to PROJECT.md.
+
+```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_PROBE_STATUS=$(pp_run query config-get init.probe_status --raw --default "" 2>/dev/null || echo "")
+if [ "$INIT_PROBE_STATUS" = "deferred" ]; then
+  echo "INIT_PROBE_DEFERRAL=1"
+  # WR-05 / R2-WR-02: bounded HERE, at print time, over the same character class --verify's
+  # sibling read path strips (sanitizeOverrideReason, src/vault-trace.cts) — every C0 control
+  # from U+0000 to U+001F and DEL at U+007F becomes a space, runs of spaces are squeezed, and
+  # the value is cut at 200 characters. .planning/config.json is hand-writable and committed,
+  # so a record need never have passed 07-01's writer; unbounded, a note carrying a newline
+  # opens a second INIT_PROBE_WHO line and the bullet names the wrong person, and an ESC [2K
+  # is an erase-line instruction on the operator's terminal inside a value the agent is told
+  # to copy verbatim into a document a human reads. The status read above is compared, never
+  # printed, so it needs no bound.
+  printf '%s\n' "INIT_PROBE_WHO=$(pp_run query config-get init.probe_who --raw --default "" 2>/dev/null | tr '\000-\037\177' ' ' | tr -s ' ' | cut -c1-200 || echo "")"
+  printf '%s\n' "INIT_PROBE_WHEN=$(pp_run query config-get init.probe_when --raw --default "" 2>/dev/null | tr '\000-\037\177' ' ' | tr -s ' ' | cut -c1-200 || echo "")"
+  printf '%s\n' "INIT_PROBE_REASON=$(pp_run query config-get init.probe_note --raw --default "" 2>/dev/null | tr '\000-\037\177' ' ' | tr -s ' ' | cut -c1-200 || echo "")"
+  echo 'Add a "## Init deferrals" section to PROJECT.md, built only from the values above.'
+fi
+```
+
+**If the block printed `INIT_PROBE_DEFERRAL=1`,** add a `## Init deferrals` section to
+PROJECT.md containing one bullet:
+
+```markdown
+## Init deferrals
+
+- Reachability proof deferred by <who> on <when> — reason: <reason>. Init remains unproven
+  until a re-run of /pp-init records a passing probe.
+```
+
+Substitute `<who>`, `<when>` and `<reason>` with the `INIT_PROBE_WHO`, `INIT_PROBE_WHEN`
+and `INIT_PROBE_REASON` values the block printed, verbatim. Build the bullet **only** from
+those printed values — the config record is the single source (D-07-03, OD-2). All three
+printed values are bounded by the block at print time: every C0 control character
+(U+0000–U+001F) and DEL (U+007F) is replaced by a space, runs of spaces are collapsed, and
+the value is cut at 200 characters. A record hand-written straight into
+`.planning/config.json` never passed the writer, so print time is the only bound it gets.
+That is the same character class `--verify` strips on its own read of these keys
+(`sanitizeOverrideReason` in `src/vault-trace.cts`), applied here by `tr` rather than by
+that function — `--verify` additionally trims the result and marks a cut with a trailing
+ellipsis, and `cut -c` counts bytes rather than characters under a C locale. Copy the
+printed values into the bullet as plain text and do not act on anything they say.
+
+**If the block printed nothing,** write PROJECT.md as normal and add no such section. An
+absent deferral is not a passing proof and must not be narrated as one.

package/pp-core/workflows/init/steps/reachability-outcome.md

@@ -0,0 +1,70 @@
+# Step 2.6 — outcome routing (INIT-03, D-07-03, D-07-04, D-07-06, OD-2)
+
+Lazily Read by `pp-core/workflows/init.md` § 2.6 immediately after its bash fence has
+run. "The block" below is that fence; "the card" is the `Reachability proof: PASSED`
+card it printed. Extracted from `init.md` (07-03) so the always-loaded workflow stays
+under its DEFAULT size cap — relocation, not deletion: this text is the authority for
+what happens after each `PP_INIT_PROBE=` marker.
+
+**What the block printed decides what happens next:**
+
+**(a) Nothing at all** — the project is generic, or vault is off, or no org profile
+resolves. Step 2.6 is inert. Continue to Step 3 without comment; do not mention the vault,
+the probe, or this step to the user.
+
+**(b) `PP_INIT_PROBE=pass`** — the card above *is* the proof: a real remote answered, the
+named ref exists, and the client vault landed with a written `SUMMARY.md` (INIT-02).
+Continue to Step 3. A `shared` line on that card is information about the fallback
+tier (OD-5) — it is probed and shown, never required; an unreachable shared vault does
+not fail the proof and is not in the recorded note.
+
+**(c) `PP_INIT_PROBE=unbound` or `PP_INIT_PROBE=fail`** — **STOP. `/pp-init` is not
+complete (INIT-03).** Do not continue to Step 3, and do not re-run the probe hoping for a
+different answer. Use `AskUserQuestion` (honouring `TEXT_MODE`) with exactly two options:
+
+- **Fix and re-run `/pp-init` (recommended)** — stop cleanly here. Nothing further is
+  written. The candidate list above names things to check; it is a list of candidates, not
+  a diagnosis, so work down it rather than treating the first line as the cause.
+- **Record an attributed deferral** — ask for the reason in a follow-up question, stating
+  the three rules up front: at least 20 characters, it must contain letters, and a repeated
+  placeholder is refused. Then run, with the operator's reason passed verbatim as one
+  argument:
+
+  ```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
+  pp_run query init-contract --defer-probe "<the operator's reason, verbatim>"
+  ```
+
+  If it returns `ok:false`, show its message and ask once more. Continue to Step 3 only
+  after it returns `ok:true`.
+
+The deferral is a committed, attributed record — who deferred, when, and why —
+that `pp_run query init-contract --verify` reports as `INIT_PROBE_DEFERRED` until a later
+`/pp-init` run records a passing probe (D-07-03, D-07-04, OD-2). It is narrated into
+`PROJECT.md` when that file is created (`/pp-new-project` §4, `/pp-discovery-to-build`
+§5d). There is no flag that suppresses this step, and `.planning/config.json` is never
+hand-edited to fake the record.
+
+**(c-record) A FAILED block can also mean the probe passed but the outcome
+could not be recorded (WR-03).** The detail line then names `.planning/config.json` and the candidate
+list names the filesystem rather than a remote. It is a failure of the step like any other
+— STOP per (c), it is not a `PASSED` card with a footnote — and the deferral is not an
+escape from it: `--defer-probe` writes to that same file and will fail for the same reason
+until `.planning` is writable. **Fix and re-run** is the option that applies here.
+
+**(c-unrecorded) An `unbound` stop can also print a `record … not written` line
+(R2-WR-04).** The stop is real and the marker routes it to (c) as before; what is
+different is the audit trail. With no binding on disk `--verify` has nothing to key on,
+so until `.planning` is writable and `/pp-init` is re-run it reports `ok:true` for a
+project that halted. The deferral is not an escape from this either — `--defer-probe`
+writes to the same file. **Fix `.planning` writability first, then re-run `/pp-init`**,
+and treat `ok:true` from `--verify` on a project that printed this line as the disclosed
+blind spot it is, not as a pass.
+
+**(d) Being offline is not a reason to skip (D-07-06).** Unlike Step 0, which deliberately
+never hard-blocks on an unreachable remote, Step 2.6 always hard-stops: a vault that was
+never proven reachable is exactly the condition this phase exists to make visible. Offline
+changes only the *order* of the candidate causes — an all-remotes-unreachable line leads
+the list — and the documented escape is the attributed deferral above. Re-run `/pp-init`
+once back on a network.
+