@pareto4/pp-core 1.21.1 → 1.23.1

package/pp-core/workflows/plan-milestone-gaps.md

@@ -8,6 +8,13 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 <process>
 
+```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 audience fields
+```
+
+**Audience, before any question:** run the block above. If it prints `pp-tools.cjs not found`, show that error and stop. If it exits non-zero for any other reason, tell the person the audience setting could not be read (show the error) and continue; if it prints JSON, apply the **Audience** line below to it now.
+
 ## 1. Load Audit Results
 
 ```bash
@@ -65,7 +72,6 @@ Gap: Flow "View dashboard" broken at data fetch
 
 Find highest existing phase:
 ```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
 [ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Get sorted phase list, extract last one
 HIGHEST=$(pp_run query phases.list --pick directories[-1])
@@ -145,12 +151,15 @@ grep -c "Pending" .planning/REQUIREMENTS.md
 For each new phase (N, N+1, …), resolve the directory name via `init.phase-op` so the `project_code` prefix is honoured:
 
 ```bash
+command -v pp_run >/dev/null 2>&1 || { echo "ERROR: pp_run is not on PATH; prepend the resolver line from the top block to this block and run it again" >&2; exit 1; }
 INIT=$(pp_run query init.phase-op "{NN}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 expected_phase_dir=$(echo "$INIT" | node -e "process.stdout.write(JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).expected_phase_dir)")
 mkdir -p "${expected_phase_dir}"
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Repeat for each gap-closure phase number. This produces `{CODE}-{NN}-{slug}/` when `project_code` is set in `.planning/config.json`, and `{NN}-{slug}/` otherwise — consistent with all other phase-creation paths.
 
 ## 9. Commit Roadmap and Requirements Update

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

@@ -88,7 +88,7 @@ When `CONTEXT_WINDOW >= 500000`, the planner prompt includes the 3 most recent p
 
 Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `nyquist_validation_enabled`, `commit_docs`, `text_mode`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_reviews`, `has_plans`, `plan_count`, `phase_status` (#3569), `planning_exists`, `roadmap_exists`, `phase_req_ids`, `response_language`, `granularity`.
 
-**If `response_language` is set:** Include `response_language: {value}` in all spawned subagent prompts so any user-facing output stays in the configured language.
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
 
 **File paths (for <files_to_read> blocks):** `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`, `verification_path`, `uat_path`, `reviews_path`. These are null if files don't exist.
 
@@ -1404,6 +1404,7 @@ if [ "$GATE_CFG" != "false" ]; then
   # no trackable decisions). Verify-phase counterpart deliberately omits this exit-1 — that
   # gate is non-blocking by design (review finding F15).
   echo "$GATE_RESULT" | jq -e '(.passed // .data.passed) == true' >/dev/null || {
+    pp_run gate-card decision-coverage --state blocked --details 2>/dev/null || true
     echo "$GATE_RESULT" | jq -r '(.message // .data.message // "Decision coverage gate failed.")'
     exit 1
   }

package/pp-core/workflows/plan-review-convergence.md

@@ -73,7 +73,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 
 Parse JSON for: `phase_dir`, `phase_number`, `padded_phase`, `phase_name`, `has_plans`, `plan_count`, `commit_docs`, `text_mode`, `response_language`.
 
-**If `response_language` is set:** All user-facing output should be in `{response_language}`.
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
 
 Set `TEXT_MODE=true` if `--text` is present in $ARGUMENTS OR `text_mode` from init JSON is `true`. When `TEXT_MODE` is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number.
 

package/pp-core/workflows/progress.md

@@ -21,8 +21,18 @@ INIT=$(pp_run query init.progress)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Extract from init JSON: `project_exists`, `roadmap_exists`, `state_exists`, `phases`, `current_phase`, `next_phase`, `milestone_version`, `completed_count`, `phase_count`, `paused_at`, `state_path`, `roadmap_path`, `project_path`, `config_path`.
 
+**Discovery Sprint only:** if `project_exists` and `roadmap_exists` are both false, run:
+
+```bash
+pp_run query discovery.status --raw
+```
+
+If it prints JSON with `"discovery_only": true`, run `pp_run query discovery.status` and show its output exactly as printed, with nothing before or after it. Then stop: skip the rest of this workflow (the report, the routing and the Route 0 scan) whatever the arguments; `--forensic` adds nothing here. If it prints `"discovery_only": false`, or the command fails, continue below exactly as before.
+
 ```bash
 DISCUSS_MODE=$(pp_run query config-get workflow.discuss_mode --raw 2>/dev/null || echo "discuss")
 ```

package/pp-core/workflows/quick.md

@@ -31,6 +31,14 @@ Valid pp-core subagent types (use exact names — do not fall back to 'general-p
 </available_agent_types>
 
 <process>
+
+```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 audience fields
+```
+
+**Audience, before any question:** run the block above. If it prints `pp-tools.cjs not found`, show that error and stop. If it exits non-zero for any other reason, tell the person the audience setting could not be read (show the error) and continue; if it prints JSON, apply the **Audience** line below to it now.
+
 **Step 1: Parse arguments and get task description**
 
 Parse `$ARGUMENTS` for:
@@ -130,7 +138,7 @@ If `$VALIDATE_MODE` only:
 **Step 2: Initialize**
 
 ```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
+command -v pp_run >/dev/null 2>&1 || { echo "ERROR: pp_run is not on PATH; prepend the resolver line from the top block to this block and run it again" >&2; exit 1; }
 INIT=$(pp_run query init.quick "$DESCRIPTION")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_PLANNER=$(pp_run query agent-skills pp-planner)
@@ -139,6 +147,8 @@ AGENT_SKILLS_CHECKER=$(pp_run query agent-skills pp-plan-checker)
 AGENT_SKILLS_VERIFIER=$(pp_run query agent-skills pp-verifier)
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Parse JSON for: `planner_model`, `executor_model`, `checker_model`, `verifier_model`, `commit_docs`, `branch_name`, `quick_id`, `slug`, `date`, `timestamp`, `quick_dir`, `task_dir`, `roadmap_exists`, `planning_exists`.
 
 ```bash

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

@@ -34,6 +34,8 @@ INIT=$(pp_run query init.phase-op "${target}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Extract: `phase_found`, `phase_dir`, `phase_number`, `commit_docs`, `roadmap_exists`.
 
 Also read STATE.md and ROADMAP.md content for parsing current position.

package/pp-core/workflows/remove-workspace.md

@@ -18,6 +18,8 @@ INIT=$(pp_run query init.remove-workspace "$WORKSPACE_NAME")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Parse JSON for: `workspace_name`, `workspace_path`, `has_manifest`, `strategy`, `repos`, `repo_count`, `dirty_repos`, `has_dirty_repos`.
 
 **If no workspace name provided:**

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

@@ -29,8 +29,33 @@ INIT=$(pp_run query init.resume)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Parse JSON for: `state_exists`, `roadmap_exists`, `project_exists`, `planning_exists`, `has_interrupted_agent`, `interrupted_agent_id`, `commit_docs`.
 
+**Discovery Sprint only (check this first):** if `project_exists` and `roadmap_exists` are both false, whatever `state_exists` says, run:
+
+```bash
+pp_run query discovery.status --raw
+```
+
+If it prints JSON with `"discovery_only": true`:
+
+1. Run `pp_run query discovery.status` and show its output exactly as printed; it already says where the sprint stopped.
+2. Run the block below (check_incomplete_work's scan); if it lists `HANDOFF.json` or a `.continue-here` file, add one line naming it as a note left by an earlier pause. The next step stays the sprint's. Leave the files in place: `HANDOFF.json` is not deleted here, it is left for a later build-mode resume.
+
+   ```bash
+   find .planning -maxdepth 1 -name HANDOFF.json -print 2>/dev/null || true
+   find .planning -maxdepth 3 -name '.continue-here*.md' -print 2>/dev/null || true
+   find . -maxdepth 1 -name '.continue-here*.md' -print 2>/dev/null || true
+   ```
+
+3. Offer three numbered choices in the person's wording: the next step (the JSON's `next.command`, with the reason the view gives); the whole sprint (`/pp-discovery`); Something else. When `next.kind` is `open_sprint`, offer only the last two. Wait for the person's choice.
+4. For the first two, show the chosen command directly, without `/clear` (route_to_workflow's rule). For Something else, ask what they need.
+5. End the workflow there: skip load_state, check_incomplete_work, present_status, determine_next_action, offer_options, route_to_workflow and update_session. On a discovery-only project never rebuild STATE.md and never run `state.record-session`.
+
+If it prints `"discovery_only": false`, or the command fails, continue below exactly as before.
+
 **If `state_exists` is true:** Proceed to load_state
 **If `state_exists` is false but `roadmap_exists` or `project_exists` is true:** Offer to reconstruct STATE.md
 **If `planning_exists` is false:** This is a new project - route to /pp:init

package/pp-core/workflows/review.md

@@ -116,6 +116,8 @@ INIT=$(pp_run query init.phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Read from init: `phase_dir`, `phase_number`, `padded_phase`.
 
 Then read:

package/pp-core/workflows/scan.md

@@ -44,6 +44,8 @@ INIT=$(pp_run query init.map-codebase 2>/dev/null || echo "{}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Look up which documents would be produced for the selected focus (from the mapping table above).
 
 For each target document, check if it already exists in `.planning/codebase/`:

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

@@ -22,6 +22,8 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_AUDITOR=$(pp_run query agent-skills pp-security-auditor)
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
 
 ```bash

package/pp-core/workflows/settings.md

@@ -535,6 +535,45 @@ Write `~/.gsd/defaults.json` with:
 ```
 </step>
 
+<step name="audience">
+This question is about **you**, not this project: it decides how pp-core talks to you in every project. It is saved in your own per-person file `~/.gsd/person.json` — never in this project's config file and never in `~/.gsd/defaults.json`.
+
+Run `pp_run query audience status --raw` and read `audience`, `audience_source`, `language_source` and `language_name`.
+
+If `language_source` is `person_file`, the person chose a language explicitly and every pick below keeps it. Show it before the question, so it is never silent:
+
+```
+Language: {language_name} — your own choice, kept.
+Clear: pp-tools audience set --clear-language
+```
+
+The clear command names no audience on purpose: it removes only the language and never saves `PP_AUDIENCE` or a default as the person's audience (D-12).
+
+```
+AskUserQuestion([
+  {
+    question: "Who are you? This is about you, not this project.",
+    header: "Audience",
+    multiSelect: false,
+    options: [
+      { label: "Business user", description: "Plain words, no technical terms." },
+      { label: "Business engineer", description: "Plain English; you know the technology." },
+      { label: "Developer", description: "As today." },
+      { label: "Keep current", description: "{audience}" }
+    ]
+  }
+])
+```
+
+The labels are the first-run prompt's own (D-09; a test pins them). Mark the option matching the current value with `(current)`.
+
+- `Keep current`: change nothing.
+- Any other answer: run `pp_run query audience set business`, `pp_run query audience set engineer` or `pp_run query audience set developer` (the matching value) and show its output. An explicit pick is saved even when it equals the default, so the first-run question is never asked again.
+- If `audience_source` is `environment`, tell the user that `PP_AUDIENCE` overrides the saved value in this terminal.
+- A change affects only what pp-core shows from now on; files already written (discovery sessions, registers) are never rewritten.
+- Never add `audience` or `language` to the project config write or to the defaults file.
+</step>
+
 <step name="confirm">
 Display:
 
@@ -568,6 +607,7 @@ Display:
 | Skip Discuss         | {On/Off} |
 | Context Warnings     | {On/Off} |
 | Saved as Defaults    | {Yes/No} |
+| Audience (you, not this project) | {business/engineer/developer} |
 
 These settings apply to future /pp:plan-phase and /pp:execute-phase runs.
 
@@ -588,5 +628,6 @@ Quick commands:
 - [ ] User presented with 24 settings (profile + workflow toggles + features + git branching + git tagging + ctx warnings), grouped into six sections: Planning, Execution, Docs & Output, Features, Model & Pipeline, Misc. `code_review_depth` is conditional on `code_review=on`. Model profile uses a two-question split (Q1: Adaptive / Standard tier / Inherit; Q2: Quality / Balanced / Budget — only when Standard tier chosen) to stay within the 4-option AskUserQuestion cap while exposing all 5 valid profiles (#3784). Drift Guard (`plan_review.source_grounding`) is in the Planning section.
 - [ ] Config updated with model_profile, workflow, and git sections
 - [ ] User offered to save as global defaults (~/.gsd/defaults.json)
+- [ ] Audience asked once and saved with pp_run query audience set — never into the project config or the defaults file
 - [ ] Changes confirmed to user
 </success_criteria>

package/pp-core/workflows/ship.md

@@ -33,6 +33,8 @@ INIT=$(pp_run query init.phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Parse from init JSON: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `padded_phase`, `commit_docs`.
 
 Also load config for branching strategy:

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

@@ -63,7 +63,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 
 Parse JSON for: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `state_path`, `requirements_path`, `roadmap_path`, `planning_path`, `response_language`, `commit_docs`.
 
-**If `response_language` is set:** All user-facing text in this workflow MUST be in `{response_language}`. Technical terms, code, and file paths stay in English.
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
 
 **If `phase_found` is false:**
 ```

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

@@ -26,6 +26,8 @@ AGENT_SKILLS_UI=$(pp_run query agent-skills pp-ui-researcher)
 AGENT_SKILLS_UI_CHECKER=$(pp_run query agent-skills pp-ui-checker)
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Parse JSON for: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_context`, `has_research`, `commit_docs`.
 
 **File paths:** `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`.

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

@@ -22,6 +22,8 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_UI_REVIEWER=$(pp_run query agent-skills pp-ui-auditor)
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `commit_docs`.
 
 ```bash

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

@@ -72,6 +72,8 @@ INIT=$(pp_run query init.plan-phase "$PHASE")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Parse JSON for: `phase_found`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`,
 `phase_dir`, `roadmap_path`, `requirements_path`, `research_path`, `planning_exists`.
 

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

@@ -26,6 +26,8 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_AUDITOR=$(pp_run query agent-skills pp-nyquist-auditor)
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
 
 ```bash

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

@@ -21,6 +21,8 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_VAULT_REVIEWER=$(pp_run query agent-skills pp-vault-reviewer)
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Parse: `phase_dir`, `phase_number`, `phase_name`, `padded_phase`, `commit_docs`.
 
 ### 0a. Derive first, and stop when there is nothing to review

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

@@ -34,6 +34,8 @@ INIT=$(pp_run query init.phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `has_plans`, `plan_count`.
 
 Then load phase details and list plans/summaries:

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

@@ -49,6 +49,8 @@ AGENT_SKILLS_PLANNER=$(pp_run query agent-skills pp-planner)
 AGENT_SKILLS_CHECKER=$(pp_run query agent-skills pp-plan-checker)
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Parse JSON for: `planner_model`, `checker_model`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `has_verification`, `uat_path`.
 
 ```bash

package/scripts/affected-tests-lib.cjs

@@ -5,6 +5,7 @@ const { readdirSync, readFileSync, existsSync } = require('node:fs');
 const path = require('node:path');
 
 const { ExitError } = require('./lib/cli-exit.cjs');
+const { prepareSuiteEnv } = require('./test-env.cjs');
 const { suiteOf } = require('./run-tests.cjs');
 
 const CRITICAL_PATHS = [
@@ -405,21 +406,33 @@ function runNodeTestFiles(repoRoot, files) {
   }
   if (current.length > 0) chunks.push(current);
 
+  // D-16 / WR-04: the same isolation `npm test` gets — session variables and
+  // PP_AUDIENCE stripped, GSD_HOME on a throwaway suite home, leak tripwire.
+  const suiteEnv = prepareSuiteEnv({ ...process.env });
   let firstFailure = 0;
-  for (let i = 0; i < chunks.length; i++) {
-    if (chunks.length > 1) {
-      console.error(`affected-tests: chunk ${i + 1}/${chunks.length} (${chunks[i].length} files)`);
+  try {
+    for (let i = 0; i < chunks.length; i++) {
+      if (chunks.length > 1) {
+        console.error(`affected-tests: chunk ${i + 1}/${chunks.length} (${chunks[i].length} files)`);
+      }
+      try {
+        execFileSync(process.execPath, ['--test', concurrency, ...chunks[i]], {
+          cwd: repoRoot,
+          stdio: 'inherit',
+          env: suiteEnv.env,
+        });
+      } catch (error) {
+        const code = error.status || 1;
+        if (firstFailure === 0) firstFailure = code;
+      }
     }
-    try {
-      execFileSync(process.execPath, ['--test', concurrency, ...chunks[i]], {
-        cwd: repoRoot,
-        stdio: 'inherit',
-        env: { ...process.env },
-      });
-    } catch (error) {
-      const code = error.status || 1;
-      if (firstFailure === 0) firstFailure = code;
+    const leak = suiteEnv.leakMessage();
+    if (leak) {
+      console.error(`affected-tests: ${leak}`);
+      if (firstFailure === 0) firstFailure = 1;
     }
+  } finally {
+    suiteEnv.cleanup();
   }
   if (firstFailure !== 0) throw new ExitError(firstFailure);
 }
@@ -548,6 +561,7 @@ module.exports = {
   resolveBaseRef,
   resolveRelativeDependency,
   resolveRunPlan,
+  runNodeTestFiles,
   shouldRunFullSuite,
   toPosixPath,
   runAffectedTests,

package/scripts/ci-release-only.cjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * ci-release-only.cjs — is this PR diff only a release (version bump + CHANGELOG
+ * render)? If so the CI `test` and `smoke` jobs run the release checks instead
+ * of the full suite: the code in a release PR is the code `main` already holds,
+ * and the v* tag run executes the full suite again before `pack` and `publish`,
+ * so a second full run on the release PR proves nothing new (2026-11-10: ~20
+ * billed minutes per release).
+ *
+ * Release-only means EVERY changed path is one of:
+ *   - VERSION or CHANGELOG.md (modified);
+ *   - a `.changeset/*.md` fragment that was DELETED (consumed by the render);
+ *   - a versioned JSON manifest whose content is identical once its version
+ *     field(s) are removed — so a dependency, script or override change in
+ *     package.json / package-lock.json can never pass as a release.
+ * Anything else — a source file, an added or edited fragment, a rename, a new
+ * file — makes the diff a normal one and the full suite runs.
+ *
+ * Usage:
+ *   node scripts/ci-release-only.cjs --base <rev> --head <rev>
+ *       prints {"releaseOnly":bool,"reasons":[...]} and, under GitHub Actions,
+ *       appends `release_only=true|false` to $GITHUB_OUTPUT. Exit 0 either way.
+ *   node scripts/ci-release-only.cjs --list-tests
+ *       prints the release-check test files, one per line.
+ */
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+
+const PLAIN_RELEASE_FILES = new Set(['VERSION', 'CHANGELOG.md']);
+
+// Each versioned manifest and the key paths of the version fields a release
+// bump rewrites (scripts/sync-manifest-versions.cjs + `npm version`).
+const VERSIONED_JSON = new Map([
+  ['package.json', [['version']]],
+  ['package-lock.json', [['version'], ['packages', '', 'version']]],
+  ['.claude-plugin/plugin.json', [['version']]],
+  ['gemini-extension.json', [['version']]],
+]);
+
+// The tests that read what a release PR changes: the fragments, the rendered
+// CHANGELOG and the versioned manifests. tests/ci-release-only.test.cjs fails
+// if one is missing, and if a test file that reads CHANGELOG.md or the
+// .changeset directory is not listed here.
+const RELEASE_CHECK_TESTS = [
+  'tests/changeset-claims.test.cjs',
+  'tests/changeset-cli.test.cjs',
+  'tests/changeset-github-release-notes.test.cjs',
+  'tests/changeset-lint.test.cjs',
+  'tests/changeset-new.test.cjs',
+  'tests/changeset-parse.test.cjs',
+  'tests/changeset-render.test.cjs',
+  'tests/changeset-serialize.test.cjs',
+  'tests/docs-parity-live-registry.test.cjs',
+  'tests/feat-71924-shipped-claims.test.cjs',
+  'tests/feat-71924-tag-gate-steps.test.cjs',
+  'tests/feat-71924-vault-required-gate.test.cjs',
+  'tests/issue-766-plugin-manifest.test.cjs',
+  'tests/issue-775-gemini-extension.test.cjs',
+  'tests/issue-844-manifest-version-sync.test.cjs',
+  'tests/package-manifest.test.cjs',
+  'tests/product-name-purity.test.cjs',
+];
+
+// Test files that mention CHANGELOG.md or .changeset without reading the live
+// release content a release PR rewrites — each with the reason it is safe to
+// leave out of the release checks. The ratchet in tests/ci-release-only.test.cjs
+// makes every other mention a listed release check.
+const RELEASE_CHECK_EXEMPT = new Map([
+  ['tests/bug-3258-no-stale-gsd-intel-references.test.cjs', 'excludes CHANGELOG.md from its scan'], // gsd-allow-legacy-name: names an existing test file
+  ['tests/bug-3810-no-gsd-sdk-runtime-refs.test.cjs', 'excludes .changeset/ from its scan'], // gsd-allow-legacy-name: names an existing test file
+  ['tests/cline-install.test.cjs', 'copies CHANGELOG.md as an install artifact, content unread'],
+  ['tests/copilot-install.test.cjs', 'checks CHANGELOG.md is installed, content unread'],
+  ['tests/install.test.cjs', 'excludes CHANGELOG.md from its tree scan'],
+  ['tests/issue-498-package-identity.test.cjs', 'a CHANGELOG.md URL in a fixture string'],
+  ['tests/issue-607-legacy-cleanup.test.cjs', 'writes its own CHANGELOG.md fixture in a temp dir'],
+  ['tests/lint-docs-required.test.cjs', 'synthetic .changeset paths, no repo read'],
+  ['tests/vault-seal.integration.test.cjs', 'synthetic .changeset paths in a temp repo'],
+  ['tests/vault-seal.test.cjs', 'synthetic CHANGELOG.md / .changeset paths'],
+  ['tests/vault-trace.integration.test.cjs', 'sweeps pp-core/commands/agents; deleting fragments cannot add a dispatcher'],
+]);
+
+function stripVersions(text, keyPaths) {
+  const doc = JSON.parse(text);
+  for (const keyPath of keyPaths) {
+    let node = doc;
+    for (const key of keyPath.slice(0, -1)) {
+      node = node && typeof node === 'object' ? node[key] : undefined;
+    }
+    if (node && typeof node === 'object') delete node[keyPath[keyPath.length - 1]];
+  }
+  return JSON.stringify(doc);
+}
+
+/**
+ * @param {{status: string, path: string}[]} changes  `git diff --name-status` rows
+ * @param {(rev: 'base'|'head', file: string) => string} read  file content at a side
+ * @returns {{releaseOnly: boolean, reasons: string[]}}
+ */
+function classify(changes, read) {
+  const reasons = [];
+  if (changes.length === 0) reasons.push('empty diff');
+  for (const { status, path: file } of changes) {
+    if (PLAIN_RELEASE_FILES.has(file) && status === 'M') continue;
+    if (/^\.changeset\/[^/]+\.md$/.test(file) && file !== '.changeset/README.md' && status === 'D') continue;
+    if (VERSIONED_JSON.has(file) && status === 'M') {
+      let same = false;
+      try {
+        same = stripVersions(read('base', file), VERSIONED_JSON.get(file)) ===
+          stripVersions(read('head', file), VERSIONED_JSON.get(file));
+      } catch (err) {
+        reasons.push(`${file}: unreadable (${err.message})`);
+        continue;
+      }
+      if (same) continue;
+      reasons.push(`${file}: changes beyond the version field`);
+      continue;
+    }
+    reasons.push(`${status} ${file}: not a release file`);
+  }
+  return { releaseOnly: reasons.length === 0, reasons };
+}
+
+function gitDiff(base, head, cwd) {
+  const out = execFileSync('git', ['diff', '--name-status', '--no-renames', base, head], { cwd, encoding: 'utf8' });
+  return out.split('\n').filter(Boolean).map(line => {
+    const [status, file] = line.split('\t');
+    return { status: status[0], path: file };
+  });
+}
+
+function main(argv) {
+  if (argv.includes('--list-tests')) {
+    process.stdout.write(RELEASE_CHECK_TESTS.join('\n') + '\n');
+    return 0;
+  }
+  const base = argv[argv.indexOf('--base') + 1];
+  const head = argv[argv.indexOf('--head') + 1];
+  if (!argv.includes('--base') || !argv.includes('--head') || !base || !head) {
+    process.stderr.write('usage: ci-release-only.cjs --base <rev> --head <rev> | --list-tests\n');
+    return 2;
+  }
+  const cwd = process.cwd();
+  const revs = { base, head };
+  const verdict = classify(gitDiff(base, head, cwd), (side, file) =>
+    execFileSync('git', ['show', `${revs[side]}:${file}`], { cwd, encoding: 'utf8' }));
+  process.stdout.write(JSON.stringify(verdict) + '\n');
+  if (process.env.GITHUB_OUTPUT) {
+    fs.appendFileSync(process.env.GITHUB_OUTPUT, `release_only=${verdict.releaseOnly}\n`);
+  }
+  return 0;
+}
+
+module.exports = { classify, stripVersions, RELEASE_CHECK_TESTS, RELEASE_CHECK_EXEMPT, VERSIONED_JSON };
+
+if (require.main === module) process.exitCode = main(process.argv.slice(2));