@pareto4/pp-core 1.9.0 → 1.11.0

package/pp-core/workflows/init.md

@@ -7,7 +7,23 @@ Implements decisions: D-02 (no Obsidian/board scaffolding), D-03 (no discovery s
 scaffolding here — /pp-discovery self-generates them), D-04 (ASK handoff with smart
 default), D-06 (generic remote wiring: prompt URL → git remote add → confirmed push,
 zero provider API), D-07 (minimal identity only — no CLAUDE.md client-context block),
-D-13 (gate on .platform-bindings.json via the Phase 7 reader).
+D-13 (gate on .platform-bindings.json via the Phase 7 reader — Step 2 now composes and
+writes this file too, not only reads it, Phase 34 INIT-01).
+
+Provisioning is provider-aware (Phase 34 D-11/D-13): `resolveProvider` is the sole
+authority for which provisioning path runs. The gated GitLab `glab` recipe (G-2…G-5) runs
+only when it resolves to `gitlab`; under any other provider (`azure` today) it is
+**skipped, not failed**, and the run falls through to this same generic remote-wiring
+path so the user still leaves with a wired remote (Phase 34 INIT-03).
+
+Step 2 is a single instruction to run `pp-tools init` in a real terminal, not a prose
+questionnaire and not a relay this document drives (Phase 34-09 gap closure). Four prior
+UAT walks — plain prose, hardened prose, a tested CLI arm, and a session state machine the
+agent was still handed one step at a time — all failed at the identical point: the agent's
+own model of which steps exist overrode this document and it substituted its own
+`AskUserQuestion` wizard for the question set (`34-VALIDATION.md`). The interaction now
+lives entirely inside `pp-tools init` itself — a human types answers directly into the
+process that acts on them — so this document has nothing left to compress, reorder or drop.
 
 Inert of all Pareto/GitLab behavior when no .platform-bindings.json is present.
 </purpose>
@@ -119,61 +135,51 @@ Step 0). Continue honoring it for every `AskUserQuestion` call in this and later
 
 ---
 
-## 2. Minimal identity capture (D-07)
+## 2. Identity, provider and binding — run `pp-tools init` (D-05, D-07, INIT-01, INIT-02, INIT-03)
 
-Capture ONLY the five identity fields below. Persist them as a stub in
-`.planning/config.json` under a top-level `"project"` key, merged with any existing
-config. These fields are used by the gated GitLab provisioning path (Plan 02) for
-`group/repo-slug` and `visibility`; they do NOT produce a `CLAUDE.md` client-context
-block — that is Phase 9 (CTX-01..03) territory. Do NOT write a coding-standards,
-architecture, or DoD block here; executor and Phase 9 must not double-capture these.
-
-Ask the user with `AskUserQuestion` (or plain-text prompts in TEXT_MODE):
-
-```text
-1. Project name (human-readable, e.g. "Acme Dashboard")
-2. Project slug (kebab-case, e.g. "acme-dashboard")
-3. Client name (company / team, e.g. "Acme Corp") — type "internal" if none
-4. Client slug (kebab-case, e.g. "acme") — type "internal" if none
-5. One-line description (what this project does)
-```
-
-Also ask — used only by the gated GitLab path (D-13, Plan 02):
+Tell the user to run this in their own terminal, then **stop** and wait for them to confirm
+they are done before continuing to Step 3:
 
 ```text
-6. Provider (gitlab / github / other / none)
-7. Visibility (private / public / internal)
-```
-
-Write these to `.planning/config.json`:
-
-```json
-{
-  "project": {
-    "name": "<value>",
-    "slug": "<value>",
-    "client_name": "<value>",
-    "client_slug": "<value>",
-    "description": "<value>",
-    "provider": "<value>",
-    "visibility": "<value>"
-  }
-}
+pp-tools init
 ```
 
-`mkdir -p .planning` before writing if the directory does not exist.
-
-**Scope boundary:** this step writes identity only. All coding-standards, architecture
-context, client-engagement CLAUDE.md blocks, and discovery-session scaffolding are out of
-scope here. Phase 9 owns those; /pp-discovery self-generates its own session files (D-03).
+**Do not ask the identity questions yourself. Do not describe the question set, the
+provider options, or the compose confirmation. Do not attempt to drive the `init-contract`
+session on the user's behalf — not even one step of it, even via `--session-next` /
+`--session-answer`.** Four dated UAT walks (`34-VALIDATION.md` § Manual-Only Verifications)
+found the IDENTICAL failure at exactly this boundary, across four escalating strategies —
+plain prose, hardened prose, a data-supplying CLI arm, and a session state machine the
+agent was still handed one step at a time. Every pure-bash step ran reliably every time;
+the one step whose job is to ask a structured question set was always overridden by the
+agent's own `AskUserQuestion` wizard instead. The only strategy left is to remove the
+interaction from this document entirely: `pp-tools init` prompts on a real terminal, reads
+the answers itself, and performs every write (`.planning/config.json`, `vault.provider`,
+`.platform-bindings.json`) — a human types answers directly into the process that acts on
+them, with nothing in between. It refuses to run when stdin is not a TTY.
+
+**If this step is skipped, `/pp-init` has not completed** — no identity config, no
+`vault.provider`, and no binding are produced without it. `pp_run query init-contract
+--verify` reports exactly what is still missing if the operator wants to confirm before
+continuing.
+
+**Scope boundary:** this step writes identity, provider and the platform binding only. All
+coding-standards, architecture context, client-engagement CLAUDE.md blocks, and
+discovery-session scaffolding are out of scope here. Phase 9 owns those; /pp-discovery
+self-generates its own session files (D-03).
 
 ---
 
 ## 3. Remote wiring — provider-agnostic (non-Pareto / no bindings)
 
-**Gate (D-06, D-13):** this step is the active path when
-`pp_run query platform-bindings --pick present 2>/dev/null` does NOT equal `"true"`.
-When bindings ARE present, see the gated GitLab provisioning section below instead.
+**Gate (D-06, D-13) — bindings presence ONLY, never the provider answer.** Step 3 always
+runs exactly one of its two sub-paths on every `/pp-init` invocation; it is never skipped
+outright. Take THIS generic sub-path when
+`pp_run query platform-bindings --pick present 2>/dev/null` does NOT equal `"true"`. When
+bindings ARE present, take the gated GitLab/Azure sub-path below instead — that section is
+still part of Step 3, not a separate optional step. **The provider answer never decides
+whether Step 3 runs** — inside the gated sub-path it only decides whether the
+GitLab-specific `glab` recipe fires or falls through to this same generic code below.
 
 On the generic path:
 
@@ -213,17 +219,80 @@ gets its own per-action confirmation immediately before it fires — nothing bat
 step makes **ZERO `gh`/`glab`/provider-API calls**. The push target is the user-supplied
 URL only.
 
-### Gated GitLab provisioning (Pareto projects — bindings present)
+### Gated GitLab/Azure provisioning (Step 3's other sub-path — bindings present)
+
+This is Step 3's other sub-path, not a separate step. It runs **instead of** the generic
+remote-wiring path above when
+`pp_run query platform-bindings --pick present 2>/dev/null` equals `"true"`. Within it,
+G-1 always runs first to source coordinates and apply the two guards below; the
+GitLab-specific create recipe (G-2…G-5) runs **only when the resolved provider is
+`gitlab`** — under any other provider (`azure` today) it is skipped, not failed, and the
+run falls through to Step 3's generic remote-wiring path above instead (D-11, D-13).
+Implements D-05 (per-action confirmation), D-09 (existence probe → adopt-if-exists), D-10
+(private by default), D-11 (auth verify-only; gated on provider), D-12 (adopt-if-exists
+reconciliation; coordinates sourced one-per-value, no phantom `gitlab.*` binding reads),
+D-13 (bindings gate; `resolveProvider` is the sole authority for which path runs).
+Covers INIT-02, INIT-03, and the cross-cutting SAFE-01 invariant.
+
+#### G-1. Config reads — one source per value (D-12)
+
+Per-project values (repo slug, visibility, description) come from the `project.*` block
+Step 2 already writes to `.planning/config.json`; the org-wide group root comes from the
+org profile's init-only seed section, read through the composer's own offline probe; the
+host comes from the composed binding. **No `gitlab` namespace exists in the schema**
+(`additionalProperties: false` at the top level, no such block) or will be declared —
+declaring one would put the same value in both the binding and `.planning/config.json`, a
+fresh instance of the two-sources-of-truth class this repo has already paid for twice.
+One source per value:
+
+```bash
+GROUP=$(pp_run query compose-bindings --offline --pick seed.provisioningGroup 2>/dev/null)
+SLUG=$(pp_run query config-get project.slug --raw 2>/dev/null)
+VIS_RAW=$(pp_run query config-get project.visibility --raw 2>/dev/null)
+HOST=$(pp_run query platform-bindings --pick platform.host 2>/dev/null)
+# D-10: hard-default to private when field is absent or empty
+VIS="${VIS_RAW:-private}"
+DESC=$(pp_run query config-get project.description --raw 2>/dev/null || echo "")
+```
+
+`HOST` still defaults to `gitlab.com` in remote URLs below when empty (the existing
+`${HOST:-gitlab.com}` fallback below, unchanged). `DESC` now carries `--raw`: without it
+`config-get` returns a JSON-quoted string, so the create step's `--description "$DESC"`
+would pass the surrounding quotes through into the created project's description.
+
+**Empty-group guard (closes T-34-41).** A bare or half-empty group/slug pair is the
+personal-namespace landmine named in the security invariants below: creating with an
+empty group lands under the user's personal namespace, not the client group. When
+`GROUP` or `SLUG` is empty, print a clear line naming which one is missing and where it
+comes from, skip G-2 through G-5 entirely, and fall through to Step 3's generic remote
+wiring:
+
+```bash
+if [ -z "$GROUP" ] || [ -z "$SLUG" ]; then
+  echo "Skipping GitLab provisioning: $( [ -z "$GROUP" ] && echo "GROUP (org profile seed provisioning group)" || echo "SLUG (project.slug)" ) is empty — falling through to Step 3's generic remote wiring."
+fi
+```
 
-This path runs **instead of** the generic remote-wiring path above when
-`pp_run query platform-bindings --pick present 2>/dev/null` equals `"true"`. Implements
-D-05 (per-action confirmation), D-09 (existence probe → adopt-if-exists), D-10 (private
-by default), D-11 (auth verify-only), D-12 (adopt-if-exists reconciliation), D-13
-(bindings gate). Covers INIT-02 and the cross-cutting SAFE-01 invariant.
+**Provider gate (D-11, D-13).** Read the one authority for which provisioning path runs —
+`--offline` so this never touches the network:
+
+```bash
+PROVIDER=$(pp_run query compose-bindings --offline --pick provider 2>/dev/null)
+if [ "$PROVIDER" != "gitlab" ]; then
+  echo "Skipping GitLab-specific provisioning for provider \"$PROVIDER\" — falling through to Step 3's generic remote wiring instead."
+fi
+```
+
+Continue to G-2 only when the empty-group guard above did not skip **and** `PROVIDER`
+equals `gitlab`. Otherwise stop here and go to Step 3's generic remote wiring (`:283-312`)
+instead — do not fail, do not error, do not prompt for a missing CLI. "Skipped, not
+failed" is satisfied *and* the user still leaves with a wired remote, which a bare skip
+would not give them; pp-core makes zero provider-API calls it has no client for.
 
 **Security invariants — landmine guards:**
 - Always use the group-qualified `$GROUP/$SLUG` path — never a bare slug (T-08-04, D-09).
-  A bare slug creates under the user's personal namespace, not the client group.
+  A bare slug creates under the user's personal namespace, not the client group. G-1's
+  empty-group guard above is what actually enforces this before any create attempt.
 - Always pass `--private` explicitly — never inherit `glab`'s default `--internal`
   visibility (T-08-05, D-10). The `--internal` flag is what makes this dangerous; the
   locked recipe must carry `--private` and must NOT emit `--internal`.
@@ -233,25 +302,6 @@ by default), D-11 (auth verify-only), D-12 (adopt-if-exists reconciliation), D-1
 - Always reconcile create with a `glab repo view` probe — a non-zero create exit does
   NOT mean nothing happened (T-08-09, D-09).
 
-#### G-1. Config reads from the bindings reader (Pattern C, D-09, D-13)
-
-All values come from the Phase 7 bindings reader. **Never hardcoded.**
-
-```bash
-GROUP=$(pp_run query platform-bindings --pick gitlab.group 2>/dev/null)
-SLUG=$(pp_run query platform-bindings --pick gitlab.repo_slug 2>/dev/null)
-VIS_RAW=$(pp_run query platform-bindings --pick gitlab.visibility 2>/dev/null)
-HOST=$(pp_run query platform-bindings --pick gitlab.host 2>/dev/null)
-# D-10: hard-default to private when field is absent or empty
-VIS="${VIS_RAW:-private}"
-DESC=$(pp_run query config-get project.description 2>/dev/null || echo "")
-```
-
-The `gitlab.*` namespace is provisional — the bindings reader is lenient on unknown fields
-(it only hard-validates `schemaVersion`, `platform.repo`, and `platform.tag`). Treat any
-absent `gitlab.*` field gracefully: fall back to safe defaults, never fail hard on a
-missing key. `HOST` defaults to `gitlab.com` in remote URLs when empty.
-
 #### G-2. Auth verify-only (D-11)
 
 `/pp-init` **never establishes auth and never reads or writes the user's token.**
@@ -518,13 +568,24 @@ chosen command or stop cleanly.
 
 ## 5. Commit
 
-Commit the `.planning/config.json` identity stub created in Step 2:
+Commit the `.planning/config.json` identity stub created in Step 2. When the Step 2 session
+composed and wrote a binding (the `compose_confirm` approval), commit `.platform-bindings.json`
+in this same commit rather than a second one (D-09): being committed is what makes the
+binding outrank the profile on every later run, and leaving it untracked would leave the
+precedence story half-built while still tripping every presence gate. The file may
+legitimately not exist — the session declines or composes nothing on the inert path
+(INIT-02) — so branch explicitly rather than word-splitting an unquoted variable into
+`--files`:
 
 ```bash
-pp_run query commit "docs: initialize project" --files .planning/config.json
+if [ -f .platform-bindings.json ]; then
+  pp_run query commit "docs: initialize project" --files .planning/config.json .platform-bindings.json
+else
+  pp_run query commit "docs: initialize project" --files .planning/config.json
+fi
 ```
 
-If `.planning/config.json` is the only new file, stage only that file. If other planning
-artifacts were created (e.g. `.planning/` directory structure), include them.
+If other planning artifacts were created (e.g. `.planning/` directory structure), include
+them too.
 
 </process>

package/pp-core/workflows/ship.md

@@ -133,6 +133,7 @@ Verify the work is ready to ship:
        ℹ Ship gate advisory ({hook.check.query}): {status}{GATE_RESULT.severity ? ` — ${GATE_RESULT.severity} drift detected` : ''} (non-blocking or below blocking threshold). Continuing.
        ```
      - If `status` is `pass` or `inert`: continue silently.
+     - Independently of the status arms above, if `GATE_RESULT.message` is a non-empty string, print it verbatim — it is already operator-ready, possibly multi-line text — then continue: a gate that has something to tell the operator says it on every run, not only when its status is a warning.
 </step>
 
 <step name="push_branch">

package/pp-core/workflows/vault-write-back.md

@@ -0,0 +1,213 @@
+<purpose>
+Take one local practice file from preview to a confirmed, pushed promotion into the client
+vault — and nothing more. This workflow is the single human gate in front of an
+irreversible outward action: it shows the operator the complete preview, asks once whether
+to proceed, and only on explicit approval re-invokes the same guarded CLI arm in confirmed
+mode. It never authors, edits, or reformats the practice file, and it performs no direct git
+operation of its own — every outward action happens inside the promote verb, which this
+workflow only calls.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="text_mode">
+Resolve `TEXT_MODE` here, before the first question, mirroring the same resolution `init.md`
+does before its own first prompt. Set `TEXT_MODE=true` if `--text` is present in
+`$ARGUMENTS`. When `TEXT_MODE` is active, replace every `AskUserQuestion` call in this
+workflow — including the gate in Step 4 — with a plain-text numbered list, and ask the
+operator to type their choice number. This is required because non-Claude runtimes have no
+interactive question tool, and the confirmation in Step 4 is the entire point of this
+workflow — it must degrade to plain text, never disappear.
+</step>
+
+<step name="resolve_launcher">
+Resolve the `pp_run` launcher shim before any other step, so every call below goes through
+the repo-local or installed `pp-tools` binary rather than assuming a global install:
+
+```bash
+_PP_SHIM_NAME="pp-tools.cjs"; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; pp_run() { "$PP_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$PP_TOOLS" "$@"; }; 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}"; pp_run() { node "$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
+```
+</step>
+
+<step name="resolve_input">
+Take the practice file path from `$ARGUMENTS` (the first token that is not `--text`). When
+none was given, ask the operator for one with a plain prompt:
+
+```text
+Path to the local practice file to promote (e.g. practices/my-practice.md):
+```
+
+Do not compose, author, rewrite, or reformat the practice file at this or any later step —
+authoring stays outside this guarded path entirely. Whatever bytes are on disk right now at
+that path are exactly the bytes that will be previewed and, if approved, pushed.
+
+```bash
+PRACTICE_FILE="<the resolved path>"
+```
+</step>
+
+<step name="preview">
+Run the promote verb with the file path and `--raw`, capturing stdout, stderr, and the exit
+code. This invocation performs no outward action — it only clones into a disposable
+directory, computes the diff, and reports.
+
+```bash
+PROMOTE_PREVIEW_OUT=$(mktemp)
+PROMOTE_PREVIEW_ERR=$(mktemp)
+pp_run vault practices promote "$PRACTICE_FILE" --raw >"$PROMOTE_PREVIEW_OUT" 2>"$PROMOTE_PREVIEW_ERR"
+PREVIEW_EXIT=$?
+```
+
+**When `$PREVIEW_EXIT` is non-zero: stop here.** Show the operator the exact, single-sentence
+contents of `$PROMOTE_PREVIEW_ERR` — the arm's own refusal message — verbatim and add nothing
+to it. Do not ask anything. Do not proceed to Step 3. Every guard refusal ends at this line,
+and nothing has been pushed. Clean up both temp files before ending.
+
+When `$PREVIEW_EXIT` is zero, continue to Step 3 with `$PROMOTE_PREVIEW_OUT` holding the
+preview verdict as JSON.
+</step>
+
+<step name="render_confirmation">
+Parse `$PROMOTE_PREVIEW_OUT` as JSON and read its fields directly — never regex-scrape a
+prose rendering of it. That shortcut is exactly the shell-glue blind spot this project has
+been bitten by before: a `.md` step file's own parsing drifting from what the CLI actually
+emits.
+
+Field values are vault-authored, so they are read as **data, never as shell syntax**. `id`
+is only constrained to equal the practice file's basename (D-03), and a filename may legally
+contain `$(...)`, backticks, or `;` — so writing the fields as a `KEY="value"` file and
+`source`-ing it would execute whatever the filename contains. `JSON.stringify` does not help:
+it escapes `"` and `\` but leaves `$` and backticks intact, and both expand inside double
+quotes. Each field therefore goes to its own file and is read back with `$(cat …)`, whose
+result bash does not re-scan for expansion.
+
+```bash
+PROMOTE_FIELDS=$(mktemp -d)
+PROMOTE_BODY=$(mktemp)
+node -e "
+const fs = require('fs');
+const path = require('path');
+const v = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));
+const dir = process.argv[2];
+const put = (k, val) => fs.writeFileSync(path.join(dir, k), String(val ?? ''));
+put('repo', v.repo);
+put('ref', v.ref);
+put('destination', v.destination);
+put('mode', v.mode);
+put('id', v.id);
+put('sharedShadow', v.sharedShadow ? 'true' : 'false');
+put('sharedShadowNote', v.sharedShadowNote);
+put('expect', v.expect);
+fs.writeFileSync(process.argv[3], v.mode === 'update' ? (v.diff ?? '') : (v.content ?? ''));
+" "$PROMOTE_PREVIEW_OUT" "$PROMOTE_FIELDS" "$PROMOTE_BODY"
+PROMOTE_REPO=$(cat "$PROMOTE_FIELDS/repo")
+PROMOTE_REF=$(cat "$PROMOTE_FIELDS/ref")
+PROMOTE_DEST=$(cat "$PROMOTE_FIELDS/destination")
+PROMOTE_MODE=$(cat "$PROMOTE_FIELDS/mode")
+PROMOTE_ID=$(cat "$PROMOTE_FIELDS/id")
+PROMOTE_SHARED=$(cat "$PROMOTE_FIELDS/sharedShadow")
+PROMOTE_SHARED_NOTE=$(cat "$PROMOTE_FIELDS/sharedShadowNote")
+PROMOTE_EXPECT=$(cat "$PROMOTE_FIELDS/expect")
+```
+
+Show the operator, in this exact order, reading every value from the parsed fields above —
+never truncated, summarized, or collapsed to "the first N lines":
+
+1. The target vault repository (`$PROMOTE_REPO`) and ref (`$PROMOTE_REF`).
+2. The destination path inside that repository (`$PROMOTE_DEST`).
+3. Whether this **creates** a new practice or **updates** an existing one
+   (`$PROMOTE_MODE`, for id `$PROMOTE_ID`).
+4. When `$PROMOTE_SHARED` is `true`, the shared-vault disclosure sentence verbatim from
+   `$PROMOTE_SHARED_NOTE` — this id also exists in the shared Pareto vault, and promoting it
+   here makes the client's version the one that applies for this client.
+5. One line stating plainly that the secret scan already run inside the promote verb found
+   nothing in this file — a file that failed that scan would have refused before a preview
+   was ever produced, so reaching this line already proves the scan passed.
+6. The complete contents of `$PROMOTE_BODY` — the full diff when `$PROMOTE_MODE` is
+   `update`, or the full new-file content when it is `create`. Show every byte; the operator
+   is about to approve exactly these bytes, so nothing here may be shortened.
+</step>
+
+<step name="gate">
+Ask the operator with `AskUserQuestion` (or a numbered plain-text prompt when `TEXT_MODE` is
+active) whether to push this to the client vault. Offer exactly two outcomes — there is no
+default, no timeout, and no auto-advance, because this is an irreversible outward action and
+this confirmation is the whole review step:
+
+```text
+AskUserQuestion([
+  {
+    header: "Push to client vault",
+    question: "Push this practice to the client vault now?",
+    multiSelect: false,
+    options: [
+      { label: "Push it", description: "Push exactly the diff/content shown above" },
+      { label: "Stop", description: "Do not push anything — the vault stays unchanged" }
+    ]
+  }
+])
+```
+
+**When the operator chooses to stop:** print one sentence saying nothing was pushed and the
+client vault is unchanged, clean up the temp files, and end the workflow here.
+
+**When the operator chooses to push:** continue to Step 5.
+</step>
+
+<step name="push">
+Only inside this approved branch, run the promote verb again with the same file path, the
+confirmed flag, the expect token carried verbatim from the preview verdict, and `--raw`. This
+workflow never runs an outward git operation itself — the only thing it does here is invoke
+this verb a second time; every push, every commit, and every other outward action happens
+inside the verb, not in this shell block.
+
+```bash
+PROMOTE_PUSH_OUT=$(mktemp)
+PROMOTE_PUSH_ERR=$(mktemp)
+pp_run vault practices promote "$PRACTICE_FILE" --confirmed --expect "$PROMOTE_EXPECT" --raw >"$PROMOTE_PUSH_OUT" 2>"$PROMOTE_PUSH_ERR"
+PUSH_EXIT=$?
+```
+
+**When `$PUSH_EXIT` is non-zero:** show the arm's own single-sentence refusal from
+`$PROMOTE_PUSH_ERR` verbatim and end — the arm has already guaranteed nothing was pushed on a
+refusal. A concurrent-edit refusal here is expected, ordinary behavior: it means someone else
+changed this same practice in the client vault between the preview in Step 2 and this push.
+The remedy is simply to run this workflow again from the top — the new preview will diff
+against their current version. Clean up all temp files before ending.
+
+When `$PUSH_EXIT` is zero, continue to Step 6 with `$PROMOTE_PUSH_OUT` holding the push
+verdict as JSON.
+</step>
+
+<step name="report">
+Parse `$PROMOTE_PUSH_OUT` the same way Step 3 parsed the preview verdict — direct field
+reads, never a prose scrape:
+
+```bash
+node -e "
+const fs = require('fs');
+const v = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));
+process.stdout.write(
+  'repo=' + (v.repo ?? '') + '\n' +
+  'destination=' + (v.destination ?? '') + '\n' +
+  'commit=' + (v.commit ?? '') + '\n' +
+  'cacheRefreshed=' + String(!!v.cacheRefreshed) + '\n'
+);
+" "$PROMOTE_PUSH_OUT"
+```
+
+Show the operator: the repository, the destination path, the new commit the push produced,
+and whether the local read cache of the vault was refreshed. When the local cache refresh did
+not succeed, say so plainly and note that the next vault fetch will pick up the change — this
+is a cosmetic staleness in the local cache only, not a sign the push failed.
+
+Clean up every temp path created in this workflow (`$PROMOTE_PREVIEW_OUT`,
+`$PROMOTE_PREVIEW_ERR`, `$PROMOTE_BODY`, `$PROMOTE_PUSH_OUT`, `$PROMOTE_PUSH_ERR`, and the
+`$PROMOTE_FIELDS` **directory**, which needs `rm -rf`) before ending.
+</step>
+
+</process>

package/scripts/gen-capability-registry.cjs

@@ -1232,29 +1232,40 @@ function validateGate(gate, prefix) {
 /**
  * Validate per-capability contract constraints against the Loop Host Contract.
  * This covers:
- *   - contribution.into ∈ step's agentRoles
+ *   - contribution.into ∈ step's agentRoles, OR contribution.into names an agent
+ *     already registered by some capability's own `agents` array (a non-pipeline
+ *     consumer of the same loop point, e.g. code-review.md reading execute:post
+ *     alongside execute-phase.md — see capabilities/vault-practices's
+ *     execute:post -> pp-code-reviewer contribution)
  *   - when references a config key in cap.config
  *
  * NOTE: step.consumes satisfiability is NOT checked here — it requires the full
  * set of validated capabilities (cross-capability produces). It runs in
  * validateConsumesGlobal() after loadAndValidate builds capMap.
  *
- * @param {object} cap         Validated capability object
- * @param {string} capId       Capability id (for error messages)
+ * @param {object} cap                  Validated capability object
+ * @param {string} capId                Capability id (for error messages)
+ * @param {Set<string>} [knownAgentIds] Every agent id declared by any capability's
+ *   `agents` array, precomputed once across the whole capabilities/ tree
+ *   (order-independent — does not require the target capability to have
+ *   already passed validation). Defaults to an empty set so existing callers
+ *   that validate a single in-memory fixture are unaffected.
  */
-function validateAgainstContract(cap, capId) {
+function validateAgainstContract(cap, capId, knownAgentIds) {
   if (cap.role !== 'feature') return [];
   const errors = [];
   const prefix = 'capability "' + capId + '"';
+  const agentIds = knownAgentIds instanceof Set ? knownAgentIds : new Set();
 
-  // contribution.into must be in the step's agentRoles
+  // contribution.into must be in the step's agentRoles, or name a registered agent
   for (const contrib of cap.contributions) {
     if (!VALID_LOOP_POINTS.has(contrib.point)) continue; // already reported
     const contract = POINT_TO_CONTRACT.get(contrib.point);
-    if (contract && !contract.agentRoles.includes(contrib.into)) {
+    if (contract && !contract.agentRoles.includes(contrib.into) && !agentIds.has(contrib.into)) {
       errors.push(
         prefix + ' contribution.into "' + contrib.into + '" at point "' + contrib.point +
-        '" is not in the step\'s agentRoles [' + contract.agentRoles.join(', ') + ']',
+        '" is not in the step\'s agentRoles [' + contract.agentRoles.join(', ') +
+        '] and is not a registered agent id',
       );
     }
   }
@@ -2055,6 +2066,49 @@ function validateHooksWired(cap, wiredSet) {
 
 // ─── Registry builder ─────────────────────────────────────────────────────────
 
+/**
+ * Best-effort, order-independent pre-scan of every capability.json's `agents`
+ * array, across the whole capabilities/ tree. Used by validateAgainstContract
+ * to recognize a contribution.into target that names an agent registered by
+ * some OTHER capability (not just the roles of the point's own owning step
+ * workflow) — e.g. code-review.md is a non-pipeline consumer of the same
+ * execute:post loop point execute-phase.md owns, and pp-code-reviewer is
+ * registered as an agent by capabilities/code-review, not by an agent-role in
+ * execute-phase.md's <!-- gsd:loop-host --> marker.
+ *
+ * Deliberately tolerant of malformed/missing files here — real validation
+ * errors for those files are reported by the main loadAndValidate loop; this
+ * pre-scan only needs the `agents` array, never blocks on anything else.
+ *
+ * @param {string} capabilitiesDir
+ * @returns {Set<string>}
+ */
+function collectDeclaredAgentIds(capabilitiesDir) {
+  const agentIds = new Set();
+  if (!fs.existsSync(capabilitiesDir)) return agentIds;
+
+  const folderEntries = fs.readdirSync(capabilitiesDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name);
+
+  for (const folderId of folderEntries) {
+    const capPath = path.join(capabilitiesDir, folderId, 'capability.json');
+    if (!fs.existsSync(capPath)) continue;
+    let cap;
+    try {
+      cap = JSON.parse(fs.readFileSync(capPath, 'utf8'));
+    } catch {
+      continue; // malformed JSON reported elsewhere
+    }
+    if (Array.isArray(cap.agents)) {
+      for (const agent of cap.agents) {
+        if (typeof agent === 'string' && agent.length > 0) agentIds.add(agent);
+      }
+    }
+  }
+  return agentIds;
+}
+
 /**
  * Read + validate all capabilities/<id>/capability.json files.
  * Returns { capMap, errors } where capMap is Map<id, cap>.
@@ -2078,6 +2132,12 @@ function loadAndValidate(centralKeys, capabilitiesDir) {
   // scan is not repeated per-capability. ROOT is the repo root (defined at top of file).
   const wiredSet = getWiredLoopPoints(ROOT);
 
+  // Pre-scan every capability's `agents` array ONCE, order-independent, so
+  // validateAgainstContract can recognize a contribution.into target that
+  // names a registered agent even when that agent's owning capability sorts
+  // after the current one alphabetically.
+  const knownAgentIds = collectDeclaredAgentIds(resolvedCapDir);
+
   const folderEntries = fs.readdirSync(resolvedCapDir, { withFileTypes: true })
     .filter((e) => e.isDirectory())
     .map((e) => e.name)
@@ -2101,7 +2161,7 @@ function loadAndValidate(centralKeys, capabilitiesDir) {
       continue; // skip cross-validation if basic schema fails
     }
 
-    const contractErrors = validateAgainstContract(cap, cap.id);
+    const contractErrors = validateAgainstContract(cap, cap.id, knownAgentIds);
     if (contractErrors.length > 0) {
       for (const e of contractErrors) errors.push(folderId + '/capability.json: ' + e);
       // Fix #6: do NOT add contract-invalid caps to capMap — validateCrossCapability should