@pareto4/pp-core 1.9.0 → 1.10.0

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

@@ -88,6 +88,14 @@ Code review skipped (code-review capability inactive)
 Exit workflow.
 
 Default is active through the Capability Registry schema — only skip when the registry resolves no active code-review step hook. This check runs AFTER phase validation so invalid phase errors are shown first.
+
+Resolve the practices contribution independently, from the SAME `EXECUTE_POST_HOOKS_JSON` variable already fetched above — do not add a second `pp_run loop render-hooks` call:
+
+```bash
+PRACTICES_CONTRIBUTION_FRAGMENT=""
+```
+
+Resolve active entries in `EXECUTE_POST_HOOKS_JSON` where `kind == "contribution"` and `into == "pp-code-reviewer"`, and capture that entry's `fragment.inline` verbatim into `PRACTICES_CONTRIBUTION_FRAGMENT`. When no such entry is active, `PRACTICES_CONTRIBUTION_FRAGMENT` stays empty and the review runs exactly as it does today — the practices dimension is inert, not degraded.
 </step>
 
 <step name="resolve_depth">
@@ -359,9 +367,9 @@ if (resolved) process.stdout.write(resolved);
 
 2) If binary is missing, fail with actionable message:
 ```bash
-if [ -z \"$FALLOW_BIN\" ]; then
-  echo \"Error: fallow is enabled but no binary was found.\"
-  echo \"Install fallow via \`npm install -D fallow\` or \`cargo install fallow\`.\"
+if [ -z "$FALLOW_BIN" ]; then
+  echo "Error: fallow is enabled but no binary was found."
+  echo "Install fallow via \`npm install -D fallow\` or \`cargo install fallow\`."
   # Exit workflow
 fi
 ```
@@ -375,36 +383,36 @@ FALLOW_STDERR_TMP=$(mktemp)
 # Derive the phase base commit; if none is found, fall back to repo scope (fallow
 # auto-detects the base branch).
 FALLOW_SCOPE_ARGS=()
-if [ \"$FALLOW_SCOPE\" = \"phase\" ]; then
-  FALLOW_PHASE_COMMITS=$(git log --oneline --all --grep=\"${PADDED_PHASE}\" --format=\"%H\" 2>/dev/null)
-  if [ -n \"$FALLOW_PHASE_COMMITS\" ]; then
-    FALLOW_BASE=$(echo \"$FALLOW_PHASE_COMMITS\" | tail -1)^
-    FALLOW_SCOPE_ARGS=(--changed-since \"$FALLOW_BASE\")
+if [ "$FALLOW_SCOPE" = "phase" ]; then
+  FALLOW_PHASE_COMMITS=$(git log --oneline --all --grep="${PADDED_PHASE}" --format="%H" 2>/dev/null)
+  if [ -n "$FALLOW_PHASE_COMMITS" ]; then
+    FALLOW_BASE=$(echo "$FALLOW_PHASE_COMMITS" | tail -1)^
+    FALLOW_SCOPE_ARGS=(--changed-since "$FALLOW_BASE")
   fi
 fi
 
-timeout 120 \"$FALLOW_BIN\" audit --format json --quiet --max-crap \"$FALLOW_MAX_CRAP\" \"${FALLOW_SCOPE_ARGS[@]+\"${FALLOW_SCOPE_ARGS[@]}\"}\" > \"${FALLOW_JSON_PATH}.tmp\" 2>\"$FALLOW_STDERR_TMP\"
+timeout 120 "$FALLOW_BIN" audit --format json --quiet --max-crap "$FALLOW_MAX_CRAP" "${FALLOW_SCOPE_ARGS[@]+"${FALLOW_SCOPE_ARGS[@]}"}" > "${FALLOW_JSON_PATH}.tmp" 2>"$FALLOW_STDERR_TMP"
 FALLOW_EXIT=$?
 
 # fallow exits 0 (clean) or 1 (issues found) — BOTH are successful runs that produce a
 # valid JSON report. Only a timeout (124), usage error (2), or crash yields no usable JSON.
 # Decide success by whether the output parses as a fallow report, not by exit code.
-FALLOW_OK=$(FALLOW_TMP=\"${FALLOW_JSON_PATH}.tmp\" node -e \"
+FALLOW_OK=$(FALLOW_TMP="${FALLOW_JSON_PATH}.tmp" node -e "
   try {
     const fs = require('fs');
     const txt = fs.readFileSync(process.env.FALLOW_TMP, 'utf8');
     const o = JSON.parse(txt);
     process.stdout.write(o && typeof o === 'object' && 'verdict' in o ? '1' : '0');
   } catch { process.stdout.write('0'); }
-\")
-if [ \"$FALLOW_OK\" != \"1\" ]; then
-  FALLOW_STDERR_SUMMARY=$(head -5 \"$FALLOW_STDERR_TMP\")
-  rm -f \"${FALLOW_JSON_PATH}.tmp\" \"$FALLOW_STDERR_TMP\"
-  echo \"WARNING: fallow structural pre-pass failed (exit ${FALLOW_EXIT}): ${FALLOW_STDERR_SUMMARY}\"
-  FALLOW_JSON_PATH=\"\"
+")
+if [ "$FALLOW_OK" != "1" ]; then
+  FALLOW_STDERR_SUMMARY=$(head -5 "$FALLOW_STDERR_TMP")
+  rm -f "${FALLOW_JSON_PATH}.tmp" "$FALLOW_STDERR_TMP"
+  echo "WARNING: fallow structural pre-pass failed (exit ${FALLOW_EXIT}): ${FALLOW_STDERR_SUMMARY}"
+  FALLOW_JSON_PATH=""
 else
-  mv \"${FALLOW_JSON_PATH}.tmp\" \"$FALLOW_JSON_PATH\"
-  rm -f \"$FALLOW_STDERR_TMP\"
+  mv "${FALLOW_JSON_PATH}.tmp" "$FALLOW_JSON_PATH"
+  rm -f "$FALLOW_STDERR_TMP"
 fi
 ```
 
@@ -477,6 +485,16 @@ if [ -n "$FALLOW_JSON_PATH" ] && [ -f "$FALLOW_JSON_PATH" ]; then
 fi
 ```
 
+Build practices contribution block for agent:
+```bash
+PRACTICES_CONTRIBUTION_BLOCK=""
+if [ -n "$PRACTICES_CONTRIBUTION_FRAGMENT" ]; then
+  # Escape any literal closing tag before embedding; the closing tag literal is escaped so text arriving from outside this workflow cannot end the block early and steer the reviewer.
+  SAFE_PRACTICES_FRAGMENT=$(echo "$PRACTICES_CONTRIBUTION_FRAGMENT" | sed 's#</practices_contribution>#<\/practices_contribution>#g')
+  PRACTICES_CONTRIBUTION_BLOCK=$(printf '<practices_contribution>\n%s\n</practices_contribution>\n' "$SAFE_PRACTICES_FRAGMENT")
+fi
+```
+
 Spawn the pp-code-reviewer agent:
 
 Print: `◆ Spawning code reviewer... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)`
@@ -489,6 +507,8 @@ ${FILES_TO_READ}
 
 ${STRUCTURAL_FINDINGS_BLOCK}
 
+${PRACTICES_CONTRIBUTION_BLOCK}
+
 <config>
 depth: ${REVIEW_DEPTH}
 phase_dir: ${PHASE_DIR}
@@ -549,6 +569,30 @@ fi
 ```
 </step>
 
+<step name="check_practice_boundaries">
+This is a safety report about untrusted client vault text already written to `${REVIEW_PATH}`, ahead of `dispatch_fix`, and never skipped when `--fix` short-circuits `present_results`. A boundary shortfall is a defect in the report, not the reviewed code, so this check never changes an exit status — failing the review would punish the wrong artifact. The detection logic lives in `src/practices-review-check.cts`, a compiled module whose own test suite (`tests/practices-review-check.test.cjs`) pins the property that a malformed finding can only ever change its own verdict, never a sibling's.
+
+```bash
+pp_run check practices-review --review "${REVIEW_PATH}" --boundaries 2>/dev/null || true
+```
+</step>
+
+<step name="check_unfenced_vault_quotes">
+Safety report about client vault text already in `${REVIEW_PATH}`, scoped to the WHOLE file — the sibling above cannot see a verbatim client quote unfenced in narrative prose. The comparison corpus is the client's own words from inside the boundary lines only, never the fixed reference-data sentences the check itself prepends to every excerpt. Reports findings only and never changes an exit status — a quote shortfall is a defect in the review, not the reviewed code. The detection logic lives in the same compiled `src/practices-review-check.cts` module as the sibling step above, with its own pinned regression tests.
+
+**Resolve and compare in one block**, deliberately: the block resolves and consumes the corpus in one invocation AND decides whether to attempt the resolution from inside that same invocation, because a gate read from another fenced block is the identical failure the merge exists to prevent. `REVIEW_FILES` and `REVIEW_PATH` are still read from earlier in the workflow — they are this step's actual inputs, not its gate — and both now degrade visibly rather than silently: an empty `REVIEW_PATH` produces an operator-visible usage line instead of a byte-identical clean result (the CLI seam's empty-value guard, T-27-R8-05), and an empty or unset `REVIEW_FILES` produces its own one-line notice from inside this same block, before the corpus is ever resolved — an unresolved comparison corpus is never mistaken for a clean result. A test harness can supply both `REVIEW_PATH` and `VAULT_QUOTE_CORPUS` directly, no vault/matcher/model:
+
+```bash
+VAULT_QUOTE_CORPUS=""
+if [ -z "${REVIEW_FILES[@]+x}" ]; then
+  echo "practices quote check: no review files in scope — corpus not resolved"
+elif ! VAULT_QUOTE_CORPUS=$(pp_run vault practices match "${REVIEW_FILES[@]}" --raw 2>/dev/null); then
+  VAULT_QUOTE_CORPUS=""
+fi
+VAULT_QUOTE_CORPUS="${VAULT_QUOTE_CORPUS}" pp_run check practices-review --review "${REVIEW_PATH}" --quotes 2>/dev/null || true
+```
+</step>
+
 <step name="dispatch_fix">
 If the `--fix` flag was passed (`FIX_FLAG=true`), delegate to the `code-review-fix.md` workflow
 to auto-apply findings from the REVIEW.md that was just written (or that already existed).
@@ -612,6 +656,15 @@ INFO=$(echo "$FRONTMATTER" | grep "info:" | head -1 | cut -d: -f2 | xargs)
 TOTAL=$(echo "$FRONTMATTER" | grep "total:" | head -1 | cut -d: -f2 | xargs)
 ```
 
+The six lines above take the first match over the whole frontmatter and therefore read the bugs/security numbers only — this is why the practices key below is read from its own slice and written after the existing counts (D-07):
+
+```bash
+# Scoped read: the practices: block only, so its total: line can never collide with
+# the bugs/security first-match extraction above.
+PRACTICES_FRONTMATTER_BLOCK=$(printf '%s\n' "$FRONTMATTER" | sed -n -e '/^practices:/,/^[^[:space:]]/{' -e '/^practices:/p' -e '/^[[:space:]]/p' -e '}')
+PRACTICES_TOTAL=$(echo "$PRACTICES_FRONTMATTER_BLOCK" | grep -E "^[[:space:]]*total:" | head -1 | cut -d: -f2 | xargs)
+```
+
 Display inline summary to user:
 
 ```
@@ -630,10 +683,13 @@ Display inline summary to user:
     Info:      ${INFO}
     ──────────
     Total:     ${TOTAL}
+${PRACTICES_TOTAL:+  Practices (advisory): ${PRACTICES_TOTAL}}
 
 ───────────────────────────────────────────────────────────────
 ```
 
+When `PRACTICES_TOTAL` is empty, omit the Practices line entirely — the block renders exactly as it did before this phase, with no blank line left in its place.
+
 If status is "clean":
 ```
 ✓ No issues found. All ${FILES_REVIEWED} files pass review at ${REVIEW_DEPTH} depth.

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

package/scripts/lint-allow-test-rule-refs.allowlist.json

@@ -326,5 +326,12 @@
   "tests/workflow-size-budget.test.cjs :: source-text-is-the-product",
   "tests/workspace.test.cjs :: source-text-is-the-product",
   "tests/worktree-cleanup.test.cjs :: source-text-is-the-product",
-  "tests/worktree.test.cjs :: source-text-is-the-product"
+  "tests/worktree.test.cjs :: source-text-is-the-product",
+  "tests/comp-01-provider-off-by-default.test.cjs :: validates runtime CLI stdout/stderr/on-disk-config behavior, not source grep",
+  "tests/discovery-annotations.test.cjs :: source-text-is-the-product",
+  "tests/discovery-architecture-deliverables.test.cjs :: source-text-is-the-product",
+  "tests/discovery-to-build-canonical-refs.test.cjs :: source-text-is-the-product",
+  "tests/discovery-to-build-fixture.test.cjs :: source-text-is-the-product",
+  "tests/discovery-to-build-path-contract.test.cjs :: source-text-is-the-product",
+  "tests/release-smoke-discuss-plan-execute.install.test.cjs :: integration-test-input"
 ]

package/scripts/lint-descriptions.cjs

@@ -18,7 +18,9 @@ const path = require('path');
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 
 const MAX_LENGTH = 100;
-const COMMANDS_DIR = path.join(__dirname, '..', 'commands', 'gsd');
+// D-12 flat-hyphen rename (05-04): command files live flat at commands/pp-<cmd>.md,
+// no longer under a legacy nested subdirectory (mirrors lint-command-contract.cjs's COMMANDS_DIR).
+const COMMANDS_DIR = path.join(__dirname, '..', 'commands');
 
 /**
  * Parse the description field from frontmatter in a .md file.

package/scripts/lint-legacy-dir-name.cjs

@@ -53,6 +53,11 @@ const ALLOWLIST_FILES = new Set([
   'README.ko-KR.md',
   'README.pt-BR.md',
   'README.zh-CN.md',
+  // Generated snapshot of every grandfathered legacy-token reference in the tree,
+  // so it quotes those lines by construction — including this file's own comment
+  // above. Scanning it here is circular: the baseline cannot carry per-line allow
+  // markers without breaking its byte-for-byte match against the real sources.
+  'tests/rename-guard-baseline.json',
 ]);
 
 const ALLOWLIST_DIR_PREFIXES = [

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

@@ -179,12 +179,21 @@
     },
     "vault": {
       "files": [
+        "vault-practices.property.test.cjs",
         "vault-read-path.test.cjs",
         "vault-security.test.cjs",
         "vault-status-check.test.cjs",
         "vault.test.cjs"
       ],
-      "issue": "v1.7.0 Client Vault Load — four distinct concerns: vault.test (fetch/status/summary unit), vault-security (VSEC-02/03 write-guard + secret/fence), vault-read-path (VGATE-03 SUMMARY pointer), vault-status-check (VGATE-02 gate-query handler)"
+      "issue": "v1.7.0 Client Vault Load — four distinct concerns: vault.test (fetch/status/summary unit), vault-security (VSEC-02/03 write-guard + secret/fence), vault-read-path (VGATE-03 SUMMARY pointer), vault-status-check (VGATE-02 gate-query handler). Phase 24-02 added vault-practices.property.test.cjs (fast-check fuzz of the practices glob-fallback compiler + a practices-frontmatter round-trip, PRAC-02) — it is grouped under this bucket rather than \"vault-practices\" because the test-file-count lint's hyphen-prefix matcher treats \"vault-practices.property\" (period before \"property\") as starting with \"vault-\" before it can match the more specific \"vault-practices-\" prefix; the module it actually tests is pp-core/bin/lib/vault-practices.cjs, not vault.cjs."
+    },
+    "vault-practices": {
+      "files": [
+        "vault-practices-examples.test.cjs",
+        "vault-practices-matcher.test.cjs",
+        "vault-practices.test.cjs"
+      ],
+      "issue": "Phase 24 (24-01/24-02/24-04) — three distinct concerns for pp-core/bin/lib/vault-practices.cjs: vault-practices.test (24-01 parser/validation/discovery unit tests), vault-practices-matcher.test (24-02 glob matcher + two-bucket result + report unit tests), vault-practices-examples.test (24-04 shipped-example drift guard + minimal-comments global-bucket smoke case, PRAC-03 Success Criterion 3). All three test the same production module and are each independently load-bearing; consolidating would blur distinct plan-level verification gates."
     }
   }
 }