@pareto4/pp-core 1.18.0 → 1.20.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pp-core",
   "displayName": "PP Core",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "description": "PP Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "author": {
     "name": "pareto4",

package/agents/pp-code-fixer.md

@@ -217,6 +217,7 @@ This agent runs as a background process that makes commits. Operating on the mai
 The cleanup tail (commit fixes -> remove worktree -> drop recovery sentinel) MUST be **transactional**: either all of (worktree, branch advance, sentinel) end in a clean state, or — if the process is interrupted (system restart, OOM kill) between the last commit and `git worktree remove` — a discoverable recovery sentinel is left behind so a future run, `/pp:resume-work`, or `/pp:progress` can complete the cleanup. The bug fixed by #2839 was that the cleanup tail was non-transactional and silently left orphan worktrees + unmerged branches with no resume marker.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Derive worktree path from padded_phase (parsed from config in next step,
 # but the shell snippet below is illustrative — adapt once config is parsed).
 # In practice: parse padded_phase from config first, then run:
@@ -458,18 +459,21 @@ Use `pp_run query commit` with conventional format (message first, then every st
 ```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 commit \
-  "fix({padded_phase}): {finding_id} {short_description}" \
+  "fix({area}): {finding_id} {short_description}" \
+  --phase "{padded_phase}" \
   --files \
   {all_modified_files}
 ```
 
+`{area}` names the part of the codebase the fix touches (omit `({area})` when no single area fits); the phase goes in the `Phase:` trailer that `--phase` adds, never in the scope.
+
 Examples:
-- `fix(02): CR-01 fix SQL injection in auth.py`
-- `fix(03): WR-05 add null check before array access`
+- `fix(auth): CR-01 fix SQL injection in auth.py` with trailer `Phase: 02`
+- `fix(dashboard): WR-05 add null check before array access` with trailer `Phase: 03`
 
 **Multiple files:** List ALL modified files after the message (space-separated):
 ```bash
-pp_run query commit "fix(02): CR-01 ..." --files \
+pp_run query commit "fix(auth): CR-01 ..." --phase "02" --files \
   src/api/auth.ts src/types/user.ts tests/auth.test.ts
 ```
 
@@ -656,7 +660,7 @@ Fixes are committed **per-finding**. This has operational implications:
 <success_criteria>
 
 - [ ] All in-scope findings attempted (either fixed or skipped with reason)
-- [ ] Each fix committed atomically with `fix({padded_phase}): {id} {description}` format
+- [ ] Each fix committed atomically as `fix({area}): {id} {description}` with `--phase "{padded_phase}"` (trailer `Phase: {padded_phase}`)
 - [ ] All modified files listed after each commit message (multi-file fix support)
 - [ ] REVIEW-FIX.md created with accurate counts, status, and iteration number
 - [ ] No source files left in broken state (failed fixes rolled back via git checkout)

package/agents/pp-code-reviewer.md

@@ -133,6 +133,7 @@ Do NOT invent a heuristic (e.g., HEAD~5) — silent mis-scoping is worse than fa
 
 If DIFF_BASE is set, run:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 git diff --name-only ${DIFF_BASE}..HEAD -- . ':!.planning/' ':!ROADMAP.md' ':!STATE.md' ':!*-SUMMARY.md' ':!*-VERIFICATION.md' ':!*-PLAN.md' ':!package-lock.json' ':!yarn.lock' ':!Gemfile.lock' ':!poetry.lock'
 ```
 

package/agents/pp-codebase-mapper.md

@@ -114,6 +114,7 @@ Explore the codebase thoroughly for your focus area.
 
 **For tech focus:**
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Package manifests
 ls package.json requirements.txt Cargo.toml go.mod pyproject.toml 2>/dev/null
 cat package.json 2>/dev/null | head -100
@@ -128,6 +129,7 @@ grep -r "import.*stripe\|import.*supabase\|import.*aws\|import.*@" src/ --includ
 
 **For arch focus:**
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Directory structure
 find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | head -50
 
@@ -140,6 +142,7 @@ grep -r "^import" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -10
 
 **For quality focus:**
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Linting/formatting config
 ls .eslintrc* .prettierrc* eslint.config.* biome.json 2>/dev/null
 cat .prettierrc 2>/dev/null

package/agents/pp-debugger.md

@@ -912,6 +912,7 @@ The file IS the debugging brain.
 **First:** Check for active debug sessions.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls .planning/debug/*.md 2>/dev/null | grep -v resolved
 ```
 
@@ -1169,7 +1170,7 @@ Root cause: {root_cause}"
 
 Then commit planning docs via CLI (respects `commit_docs` config automatically):
 ```bash
-pp_run query commit "docs: resolve debug {slug}" --files .planning/debug/resolved/{slug}.md
+pp_run query commit "docs(planning): resolve debug {slug}" --files .planning/debug/resolved/{slug}.md
 ```
 
 **Append to knowledge base:**
@@ -1200,7 +1201,7 @@ Then append the entry:
 
 Commit the knowledge base update alongside the resolved session:
 ```bash
-pp_run query commit "docs: update debug knowledge base with {slug}" --files .planning/debug/knowledge-base.md
+pp_run query commit "docs(planning): update debug knowledge base with {slug}" --files .planning/debug/knowledge-base.md
 ```
 
 Report completion and offer next steps.

package/agents/pp-executor.md

@@ -18,6 +18,8 @@ Spawned by `/pp:execute-phase` orchestrator.
 
 Your job: Execute the plan completely, commit each task, create SUMMARY.md, update STATE.md.
 
+Shell you compose yourself may run under zsh on macOS: start every multi-line command with `[ -z "${ZSH_VERSION:-}" ] || emulate -R sh` and use no GNU-only flags (`grep -P`). Details: `~/.claude/pp-core/references/shell-portability.md`.
+
 @~/.claude/pp-core/references/mandatory-initial-read.md
 </role>
 
@@ -381,11 +383,11 @@ When executing task with `tdd="true"`:
 
 **1. Check test infrastructure** (if first TDD task): detect project type, install test framework if needed.
 
-**2. RED:** Read `<behavior>`, create test file, write failing tests, run (MUST fail), commit: `test({phase}-{plan}): add failing test for [feature]`
+**2. RED:** Read `<behavior>`, create test file, write failing tests, run (MUST fail), commit: `test({area}): add failing test for [feature]` with the trailer `Phase: {phase}-{plan}`
 
-**3. GREEN:** Read `<implementation>`, write minimal code to pass, run (MUST pass), commit: `feat({phase}-{plan}): implement [feature]`
+**3. GREEN:** Read `<implementation>`, write minimal code to pass, run (MUST pass), commit: `feat({area}): implement [feature]` with the trailer `Phase: {phase}-{plan}`
 
-**4. REFACTOR (if needed):** Clean up, run tests (MUST still pass), commit only if changes: `refactor({phase}-{plan}): clean up [feature]`
+**4. REFACTOR (if needed):** Clean up, run tests (MUST still pass), commit only if changes: `refactor({area}): clean up [feature]` with the trailer `Phase: {phase}-{plan}`
 
 **Error handling:** RED doesn't fail ��� investigate. GREEN doesn't pass → debug/iterate. REFACTOR breaks → undo.
 
@@ -395,7 +397,7 @@ When the plan frontmatter has `type: tdd`, the entire plan follows the RED/GREEN
 
 **Fail-fast rule:** If a test passes unexpectedly during the RED phase (before any implementation), STOP. The feature may already exist or the test is not testing what you think. Investigate and fix the test before proceeding to GREEN. Do NOT skip RED by proceeding with a passing test.
 
-**Gate sequence validation:** After completing the plan, verify in git log:
+**Gate sequence validation:** After completing the plan, verify in git log (each commit carrying the trailer `Phase: {phase}-{plan}`):
 1. A `test(...)` commit exists (RED gate)
 2. A `feat(...)` commit exists after it (GREEN gate)
 3. Optionally a `refactor(...)` commit exists after GREEN (REFACTOR gate)
@@ -442,6 +444,7 @@ A prior Bash call may have `cd`'d out of the worktree into the main repo. When t
 `[ -f .git ]` is false (main repo's `.git` is a directory), silently skipping all worktree guards.
 Capture the spawn-time toplevel via a sentinel on first commit, then verify on every subsequent commit:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 WT_GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
 case "$WT_GIT_DIR" in
   *.git/worktrees/*)
@@ -525,18 +528,22 @@ git add src/types/user.ts
 
 **4. Commit:**
 
+The subject is `{type}({area}): {concise task description}`. `{area}` is a noun naming the part of the codebase the staged files belong to (`auth`, `billing`, `api`), picked from the files you touched; omit `({area})` when no single area fits. Never put the phase or plan number in the scope: the plan goes in the trailer `Phase: {phase}-{plan}`, the last paragraph of the message.
+
 **If `sub_repos` is configured (non-empty array from init context):** Use `commit-to-subrepo` to route files to their correct sub-repo:
 ```bash
-pp_run query commit-to-subrepo "{type}({phase}-{plan}): {concise task description}" --files file1 file2 ...
+pp_run query commit-to-subrepo "{type}({area}): {concise task description}" --phase "{phase}-{plan}" --files file1 file2 ...
 ```
 Returns JSON with per-repo commit hashes: `{ committed: true, repos: { "backend": { hash: "abc", files: [...] }, ... } }`. Record all hashes for SUMMARY.
 
 **Otherwise (standard single-repo):**
 ```bash
-git commit -m "{type}({phase}-{plan}): {concise task description}
+git commit -m "{type}({area}): {concise task description}
 
 - {key change 1}
 - {key change 2}
+
+Phase: {phase}-{plan}
 "
 ```
 
@@ -707,6 +714,7 @@ Do NOT skip. Do NOT proceed to state updates if self-check fails.
 After SUMMARY.md, update STATE.md using `pp-tools query` state handlers (arguments by name; see `sdk/src/query/QUERY-HANDLERS.md`):
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Advance plan counter (handles edge cases automatically)
 pp_run query state.advance-plan
 
@@ -728,6 +736,7 @@ pp_run query state.record-session \
 ```
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Update ROADMAP.md progress for this phase (plan counts, status)
 pp_run query roadmap.update-plan-progress "${PHASE_NUMBER}"
 
@@ -757,7 +766,7 @@ pp_run query state.add-blocker --text "Blocker description"
 
 <final_commit>
 ```bash
-pp_run query commit "docs({phase}-{plan}): complete [plan-name] plan" --files \
+pp_run query commit "docs(planning): complete [plan-name] plan" --phase "{phase}-{plan}" --files \
   .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
 ```
 

package/agents/pp-integration-checker.md

@@ -92,6 +92,7 @@ For each phase, extract what it provides and what it should consume.
 **From SUMMARYs, extract:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Key exports from each phase
 for summary in .planning/phases/*/*-SUMMARY.md; do
   echo "=== $summary ==="

package/agents/pp-phase-researcher.md

@@ -61,6 +61,12 @@ Before researching, discover project context:
 | `## Deferred Ideas` | Out of scope — ignore completely |
 
 If CONTEXT.md exists, it constrains your research scope. Don't explore alternatives to locked decisions.
+
+**`{padded}-DISCOVERY-EXTRACT.md`** (if listed in your files to read) — the Discovery registers' rows
+that cite this phase's requirement IDs. Required reading; Read
+`pp-core/references/planner-discovery-extract.md` § Researcher and follow it. **Never open
+`.planning/discovery/session-NN.md`**: the session files are the facilitation record, not a
+source. Absent file → nothing here applies.
 </upstream_input>
 
 <downstream_consumer>
@@ -531,6 +537,7 @@ Also read `.planning/config.json` — include Validation Architecture section in
 
 Then read CONTEXT.md if exists:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 cat "$phase_dir"/*-CONTEXT.md 2>/dev/null
 ```
 
@@ -547,6 +554,10 @@ cat "$phase_dir"/*-CONTEXT.md 2>/dev/null
 - User decided "simple UI, no animations" → don't research animation libraries
 - Marked as Claude's discretion → research options and recommend
 
+Then read `$phase_dir`/*-DISCOVERY-EXTRACT.md if it exists (see `<upstream_input>`): list the
+entities, integrations and rules it names under `## User Constraints` as "Discovery facts (by row
+ID)" so the planner sees them beside the locked decisions. Do not open any `session-NN.md`.
+
 ## Step 1.3: Load Graph Context
 
 Check for knowledge graph:
@@ -652,6 +663,7 @@ Plans that assume a tool is available without checking lead to silent failures a
 2. **Probe availability** for each dependency:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # CLI tools — check if command exists and get version
 command -v $TOOL 2>/dev/null && $TOOL --version 2>/dev/null | head -1
 
@@ -781,7 +793,7 @@ Write to: `$PHASE_DIR/$PADDED_PHASE-RESEARCH.md`
 ## Step 7: Commit Research (optional)
 
 ```bash
-pp_run query commit "docs($PHASE): research phase domain" --files "$PHASE_DIR/$PADDED_PHASE-RESEARCH.md"
+pp_run query commit "docs(planning): research phase domain" --phase "$PHASE" --files "$PHASE_DIR/$PADDED_PHASE-RESEARCH.md"
 ```
 
 ## Step 8: Return Structured Result

package/agents/pp-plan-checker.md

@@ -453,6 +453,7 @@ Skip if: `workflow.nyquist_validation` is explicitly set to `false` in config.js
 Before running checks 8a-8d, verify VALIDATION.md exists:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null
 ```
 
@@ -679,6 +680,7 @@ pp_run query phase.list-artifacts "$phase_number" --type summary
 Use `pp-tools query` to validate plan structure:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 for plan in "$PHASE_DIR"/*-PLAN.md; do
   echo "=== $plan ==="
   PLAN_STRUCTURE=$(pp_run query verify.plan-structure "$plan")
@@ -764,6 +766,7 @@ Inspect `tasks` in the JSON; open the PLAN in the editor for prose-level review.
 ## Step 6: Verify Dependency Graph
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 for plan in "$PHASE_DIR"/*-PLAN.md; do
   grep "depends_on:" "$plan"
 done

package/agents/pp-planner.md

@@ -362,6 +362,11 @@ Output: [Artifacts created]
 Its exact shape comes from `pp_run vault standards block`, per `pp-core/references/planner-vault-standards.md`.]
 </vault_standards>
 
+<discovery_extract>
+[Present ONLY when a `*-DISCOVERY-EXTRACT.md` is in your files to read — omitted entirely otherwise.
+The file's content verbatim, `<!-- discovery:auto -->` markers included; see <discovery_mode>.]
+</discovery_extract>
+
 <tasks>
 
 <task type="auto">
@@ -577,6 +582,13 @@ start of execution when the injected `plan:pre -> into: planner` fragment for
 the vault capability is present in your context.
 </vault_standards_mode>
 
+<discovery_mode>
+See `pp-core/references/planner-discovery-extract.md`. Load this file at the
+start of execution when a `*-DISCOVERY-EXTRACT.md` is listed in your files to
+read: it is required reading, embedded verbatim as `<discovery_extract>`, and
+you never open a `.planning/discovery/session-NN.md`.
+</discovery_mode>
+
 <execution_flow>
 
 <step name="load_project_state" priority="first">
@@ -604,6 +616,7 @@ Check the invocation mode and load the relevant reference file:
 - If `<revision_context>` provided by orchestrator: Read `pp-core/references/planner-revision.md`
 - If `--reviews` flag present or reviews mode active: Read `pp-core/references/planner-reviews.md`
 - If the vault capability's `plan:pre` fragment is present: Read `pp-core/references/planner-vault-standards.md`
+- If a `*-DISCOVERY-EXTRACT.md` is in your files to read: Read `pp-core/references/planner-discovery-extract.md`
 - If task_breakdown identifies TDD candidates or TDD mode is active: Read `pp-core/references/planner-tdd.md`
 - Standard planning mode: no additional file to read
 
@@ -615,6 +628,7 @@ instructions for operating in that mode.
 Check for codebase map:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls .planning/codebase/*.md 2>/dev/null
 ```
 
@@ -676,6 +690,7 @@ Select top 2-4 phases. Skip phases with no relevance signal.
 
 **Step 3 — Read full SUMMARYs for selected phases:**
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 cat .planning/phases/{selected-phase}/*-SUMMARY.md
 ```
 
@@ -713,6 +728,7 @@ If `features.global_learnings` is `true`: run `pp-tools query learnings.query --
 Use `phase_dir` from init context (already loaded in load_project_state).
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 cat "$phase_dir"/*-CONTEXT.md 2>/dev/null   # From /pp:discuss-phase
 cat "$phase_dir"/*-RESEARCH.md 2>/dev/null   # Research output
 cat "$phase_dir"/*-DISCOVERY.md 2>/dev/null  # From mandatory discovery
@@ -809,6 +825,8 @@ Use template structure for each PLAN.md.
 
 When the fragment IS present, follow `pp-core/references/planner-vault-standards.md` in full — select documents from the INDEX, read each in full, obtain the block from `pp_run vault standards block` once `files_modified` settles, embed it verbatim after `<context>` and before `<tasks>`, fill only the reason slots, and re-run it on revision.
 
+**Discovery extract block (only when a `*-DISCOVERY-EXTRACT.md` is in your files to read):** embed the file verbatim as `<discovery_extract>` after `<context>` (and after `<vault_standards>` when present), before `<tasks>`, per `<discovery_mode>`. Absent file → write no block.
+
 **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
 
 **Write contract (hard rules — must follow):**
@@ -906,7 +924,8 @@ Plans:
 
 <step name="git_commit">
 ```bash
-pp_run query commit "docs($PHASE): create phase plan" --files \
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
+pp_run query commit "docs(planning): create phase plan" --phase "$PHASE" --files \
   .planning/phases/$PHASE-*/$PHASE-*-PLAN.md .planning/ROADMAP.md
 ```
 </step>

package/agents/pp-research-synthesizer.md

@@ -152,7 +152,7 @@ The 4 parallel researcher agents write files but do NOT commit. You commit every
 
 ```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 commit "docs: complete project research" --files .planning/research/
+pp_run query commit "docs(planning): complete project research" --files .planning/research/
 ```
 
 ## Step 8: Return Summary

package/agents/pp-ui-auditor.md

@@ -79,6 +79,7 @@ If no UI-SPEC exists: audit against abstract 6-pillar standards.
 **MUST run before any screenshot capture.** Prevents binary files from reaching git history.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Ensure directory exists
 mkdir -p .planning/ui-reviews
 

package/agents/pp-ui-researcher.md

@@ -102,6 +102,7 @@ Your UI-SPEC.md is consumed by:
 **Codebase first:** Always scan the project for existing design decisions before asking.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Detect design system
 ls components.json tailwind.config.* postcss.config.* 2>/dev/null
 
@@ -236,6 +237,7 @@ Read all files from `<required_reading>` block. Parse:
 ## Step 2: Scout Existing UI
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Design system detection
 ls components.json tailwind.config.* postcss.config.* 2>/dev/null
 
@@ -287,7 +289,7 @@ This file is the canonical output of this agent. The orchestrator reads `$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
-pp_run query commit "docs($PHASE): UI design contract" --files "$PHASE_DIR/$PADDED_PHASE-UI-SPEC.md"
+pp_run query commit "docs(planning): UI design contract" --phase "$PHASE" --files "$PHASE_DIR/$PADDED_PHASE-UI-SPEC.md"
 ```
 
 ## Step 7: Return Structured Result

package/agents/pp-vault-reviewer.md

@@ -56,6 +56,8 @@ Forbidden, without exception, even when a finding seems to demand it:
 **Counts, never a score.** Report counts by verdict in the exact counts line the template shows. A ratio, percentage, letter grade or compliance number is prohibited anywhere in the artifact.
 
 A document the executor marked `not read: …` is still judged against the code; record the executor's reason in the row's evidence, because a standard nobody read is worth a reader's attention.
+
+**Deviations on file (`deviations[]` in the payload).** A Discovery Sprint records the client's agreed departures from the vault in `.planning/discovery/_deviations.md`; the CLI copies them into the payload (`pp-core/references/discovery-build-consumption.md` § `_deviations.md` read contract). Before writing `FAIL`, check the list: when a deviation whose `standard` names the document and whose `status` is `Approved` covers the clause the code breaks, the verdict is `N-A` with the reason `deviation on file: <id> (<decision>)` — the sponsor chose this departure and the document does not govern that clause here. A deviation in any other status (`Proposed`, `Rejected`, empty) leaves the `FAIL` standing; name the deviation and its status in the reason so the reader sees the gap between what was asked and what was approved. Never coin a verdict for it; `N-A` with that reason is the whole mechanism. An empty `deviations[]` changes nothing.
 </verdicts>
 
 <adversarial_stance>

package/agents/pp-verifier.md

@@ -14,7 +14,7 @@ color: green
 <role>
 A completed phase has been submitted for goal-backward verification. Verify that the phase goal is actually achieved in the codebase — SUMMARY.md claims are not evidence.
 
-Goal-backward verification. Start from what the phase SHOULD deliver, verify it actually exists and works in the codebase.
+Goal-backward verification. Start from what the phase SHOULD deliver; verify it exists and works in the codebase.
 
 @~/.claude/pp-core/references/mandatory-initial-read.md
 
@@ -79,6 +79,7 @@ At verification decision points, reference calibration examples:
 ## Step 0: Check for Previous Verification
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 cat "$PHASE_DIR"/*-VERIFICATION.md 2>/dev/null
 ```
 
@@ -100,6 +101,7 @@ Set `is_re_verification = false`, proceed with Step 1.
 
 ```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
 ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
 pp_run query roadmap.get-phase "$PHASE_NUM"
@@ -123,6 +125,7 @@ Parse the `success_criteria` array from the JSON output. These are the **roadmap
 **Step 2b: Load PLAN frontmatter must-haves (if present)**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 grep -l "must_haves:" "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 ```
 
@@ -185,7 +188,7 @@ For each truth, determine if codebase enables it.
 - ✗ FAILED: One or more artifacts missing, stub, or unwired
 - ? UNCERTAIN: Can't verify programmatically (needs human)
 
-**Behavior-dependent truths.** A truth is *behavior-dependent* when its correctness hinges on runtime behavior grep/presence checks cannot see — a **state transition** or a **cancellation / cleanup / ordering invariant** (e.g. "cancels the in-flight task and bumps the generation counter", "resets the busy flag on abort", "rolls back on failure"). For these, symbol presence + wiring is *necessary but not sufficient*: the code can be present and wired yet still leak state on the very path the invariant covers.
+**Behavior-dependent truths.** A truth is *behavior-dependent* when its correctness hinges on runtime behavior grep/presence checks cannot see — a **state transition** or a **cancellation / cleanup / ordering invariant** (e.g. "cancels the in-flight task and bumps the generation counter", "rolls back on failure"). For these, symbol presence + wiring is *necessary but not sufficient*: code can be present and wired yet leak state on the very path the invariant covers.
 
 For each truth:
 
@@ -397,6 +400,7 @@ Status: WIRED (state displayed) | NOT_WIRED (state exists, not rendered)
 **6a. Extract requirement IDs from PLAN frontmatter:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 grep -A5 "^requirements:" "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 ```
 
@@ -420,11 +424,14 @@ grep -E "Phase $PHASE_NUM" .planning/REQUIREMENTS.md 2>/dev/null
 
 If REQUIREMENTS.md maps additional IDs to this phase that don't appear in ANY plan's `requirements` field, flag as **ORPHANED** — these requirements were expected but no plan claimed them. ORPHANED requirements MUST appear in the verification report.
 
+**6d. Discovery conformance (R3):** if `.planning/discovery/` exists, Read and follow `~/.claude/pp-core/references/verifier-discovery-conformance.md`; a `missed` row is a gap.
+
 ## Step 7: Scan for Anti-Patterns
 
 Identify files modified in this phase from SUMMARY.md key-files section, or extract commits and verify:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Option 1: Extract from SUMMARY frontmatter
 SUMMARY_FILES=$(pp_run query summary-extract "$PHASE_DIR"/*-SUMMARY.md --fields key-files)
 
@@ -468,13 +475,14 @@ Anti-pattern scanning (Step 7) checks for code smells. Behavioral spot-checks go
 
 **When to run:** For phases that produce runnable code (APIs, CLI tools, build scripts, data pipelines). Skip for documentation-only or config-only phases.
 
-**Behavioral evidence for behavior-dependent truths (Step 3).** When a truth asserts a state transition or a cancellation/cleanup/ordering invariant, the single named test below is what upgrades it from ⚠️ PRESENT_BEHAVIOR_UNVERIFIED to ✓ VERIFIED. Run only the one named test that exercises the transition/invariant — never the full suite (per #25/#753). If no such test exists, leave the truth ⚠️ PRESENT_BEHAVIOR_UNVERIFIED and route it to human verification (Step 8); do not mark it VERIFIED on presence.
+**Behavioral evidence for behavior-dependent truths (Step 3).** For a state transition or a cancellation/cleanup/ordering invariant, the single named test below is what upgrades the truth from ⚠️ PRESENT_BEHAVIOR_UNVERIFIED to ✓ VERIFIED. Run only that one test — never the full suite (per #25/#753). No such test → leave it ⚠️ PRESENT_BEHAVIOR_UNVERIFIED and route it to human verification (Step 8); never VERIFIED on presence.
 
 **How:**
 
 1. **Identify checkable behaviors** from must-haves truths. Select 2-4 that can be tested with a single command:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # API endpoint returns non-empty data
 curl -s http://localhost:$PORT/api/$ENDPOINT 2>/dev/null | node -e "let b='';process.stdin.setEncoding('utf8');process.stdin.on('data',c=>b+=c);process.stdin.on('end',()=>{const d=JSON.parse(b);process.exit(Array.isArray(d)?(d.length>0?0:1):(Object.keys(d).length>0?0:1))})"
 
@@ -523,6 +531,7 @@ SUMMARY.md probe pass claims are not evidence. If a phase declares or implies pr
 **Probe discovery:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Conventional project probes
 find scripts -path '*/tests/probe-*.sh' -type f 2>/dev/null | sort
 
@@ -537,6 +546,7 @@ grep -R -n -E 'probe-[^[:space:]]+\.sh|scripts/.*/tests/probe-.*\.sh' "$PHASE_DI
 3. Run each probe from the built `PROBES` list (declared + conventional) from the repository root:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 PP_GATE_BIN=$(printf '%s\n' "${PP_TOOLS:+${PP_TOOLS%/*}:}$PATH" | tr : '\n' | while IFS= read -r d; do if [ -r "$d/portable-timeout.sh" ]; then printf %s "$d"; break; fi; done)
 if [ ! -r "$PP_GATE_BIN/portable-timeout.sh" ]; then echo "✗ probes NEVER RAN — portable-timeout.sh not found beside pp-tools"; else . "$PP_GATE_BIN/portable-timeout.sh"; fi
 for probe in "${PROBES[@]}"; do
@@ -559,7 +569,7 @@ done
 
 **Needs human if uncertain:** Complex wiring grep can't trace, dynamic state behavior, edge cases.
 
-**Behavior-unverified truths (Step 3):** Every truth left ⚠️ PRESENT_BEHAVIOR_UNVERIFIED is recorded in the `behavior_unverified_items` frontmatter list (emitted whenever the count > 0, regardless of overall status, so it survives a gaps_found phase) and surfaces for human verification; when the overall status is human_needed it also appears in the human_verification section. Phrase each item around the invariant: what to trigger, what state must hold afterward, and why presence checks can't see it.
+**Behavior-unverified truths (Step 3):** every ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truth is recorded in the `behavior_unverified_items` frontmatter list (emitted whenever the count > 0, regardless of overall status, so it survives a gaps_found phase) and surfaces for human verification — also in the human_verification section when the status is human_needed. Phrase each item around the invariant: what to trigger, what state must hold afterward, why presence checks can't see it.
 
 **Harvest deferred items from PLAN.md (#3309 / `workflow.human_verify_mode = end-of-phase`):** Scan every PLAN file in the phase for `<verify><human-check>` blocks on `auto` tasks. These are verification items the planner deliberately deferred from `checkpoint:human-verify` to end-of-phase to avoid the executor cold-start cost. Each block has the same shape used by the planner:
 
@@ -573,7 +583,7 @@ done
 </verify>
 ```
 
-Merge those harvested items into the same human verification list as your own analysis. Deduplicate when the planner-deferred item and your own analysis describe the same check. The downstream `human_needed` → `{phase_num}-UAT.md` path in `workflows/execute-phase.md` is the single sink — no separate file is created.
+Merge the harvested items into your own human verification list, deduplicating items that describe the same check. The downstream `human_needed` → `{phase_num}-UAT.md` path in `workflows/execute-phase.md` is the single sink — no separate file is created.
 
 **Format:**
 
@@ -589,7 +599,7 @@ Merge those harvested items into the same human verification list as your own an
 
 Classify status using this decision tree IN ORDER (most restrictive first):
 
-1. IF any truth FAILED, artifact MISSING/STUB, key link NOT_WIRED, or blocker anti-pattern found:
+1. IF any truth FAILED, artifact MISSING/STUB, key link NOT_WIRED, blocker anti-pattern found, or Discovery conformance row `missed` (Step 6d):
    → **status: gaps_found**
 
 2. IF Step 8 produced ANY human verification items (section is non-empty) — this includes every ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truth from Step 3:
@@ -599,11 +609,11 @@ Classify status using this decision tree IN ORDER (most restrictive first):
 3. IF all truths VERIFIED, all artifacts pass, all links WIRED, no blockers, AND no human verification items:
    → **status: passed**
 
-**passed is ONLY valid when the human verification section is empty.** If Step 8 produced any items — including any truth left ⚠️ PRESENT_BEHAVIOR_UNVERIFIED — the status is not `passed`: it is `human_needed`, or `gaps_found` when rule 1 also fires (the ordered tree keeps gaps_found's precedence).
+**passed is ONLY valid when the human verification section is empty.** If Step 8 produced any items — including any ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truth — the status is not `passed`: it is `human_needed`, or `gaps_found` when rule 1 also fires (gaps_found keeps precedence).
 
-**A ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truth is never FAILED and never VERIFIED.** It does not trigger gaps_found (the code is present and wired) and is not counted as verified (behavior unexercised). On its own it routes to human_needed; when a higher-precedence gaps_found also applies, the status stays gaps_found and the item is preserved in the always-on `behavior_unverified_items` list so it is never lost. Either way it stays a *per-truth* state — the overall-status vocabulary is unchanged, with no new status value.
+**A ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truth is never FAILED and never VERIFIED.** It does not trigger gaps_found (present and wired) and is not counted as verified (behavior unexercised). Alone it routes to human_needed; under a higher-precedence gaps_found the status stays gaps_found and the item is preserved in the always-on `behavior_unverified_items` list. It stays a *per-truth* state — the overall-status vocabulary is unchanged, with no new status value.
 
-> **Shared status seam**: the status vocabulary (`passed`, `gaps_found`, `human_needed`) and the per-status routing (next action and next command for each value) are owned by `src/verification.cts` via `pp-tools query verification.status`. This agent is the single emitter of the frontmatter status field; consumers (ship.md, execute-phase.md) read routing from that query instead of re-deriving it.
+> **Shared status seam**: the status vocabulary (`passed`, `gaps_found`, `human_needed`) and the per-status routing are owned by `src/verification.cts` via `pp-tools query verification.status`. This agent is the single emitter of the frontmatter status field; consumers (ship.md, execute-phase.md) read routing from that query instead of re-deriving it.
 
 **Score (presence- vs behavior-verified split):**
 
@@ -821,6 +831,8 @@ Only include this section if deferred items exist (from Step 9b).
 | Requirement | Source Plan | Description | Status | Evidence |
 | ----------- | ---------- | ----------- | ------ | -------- |
 
+{Step 6d block, when produced: `### Discovery conformance` + the filled `<!-- discovery:conformance -->` block}
+
 ### Anti-Patterns Found
 
 | File | Line | Pattern | Severity | Impact |
@@ -877,7 +889,7 @@ Automated checks passed. Awaiting human verification.
 
 <critical_rules>
 
-**DO NOT trust SUMMARY claims.** Verify the component actually renders messages, not a placeholder.
+**DO NOT trust SUMMARY claims.** Verify the component renders messages, not a placeholder.
 
 **DO NOT assume existence = implementation.** Need level 2 (substantive), level 3 (wired), and level 4 (data flowing) for artifacts that render dynamic data.
 

package/commands/pp-add-tests.md

@@ -22,7 +22,7 @@ Generate unit and E2E tests for a completed phase, using its SUMMARY.md, CONTEXT
 
 Analyzes implementation files, classifies them into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
 
-Output: Test files committed with message `test(phase-{N}): add unit and E2E tests from add-tests command`
+Output: Test files committed with message `test({area}): add unit and E2E tests from add-tests command` and the trailer `Phase: {N}`
 </objective>
 
 <execution_context>