@pareto4/pp-core 1.18.0 → 1.20.0

package/pp-core/workflows/review.md

@@ -181,6 +181,7 @@ Write to a temp file: `/tmp/pp-review-prompt-{phase}.md`
 Also write individual section files so the budget tool can re-trim per reviewer:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Write individual section files for per-reviewer budget trimming
 # These are always written so reviewers with a budget can invoke prompt-budget
 cp "$INSTRUCTIONS_BLOCK_FILE" "/tmp/pp-review-${PHASE}-instructions.md"
@@ -257,6 +258,7 @@ fi
 
 **Codex:**
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # $CODEX_BYPASS_FLAG is capability-gated above (#1115). Capture stderr to a .err
 # file (not /dev/null) so a non-zero exit — e.g. a flag the installed codex-cli
 # does not support — is diagnosable instead of a silent empty review.
@@ -353,6 +355,7 @@ Invocation specifics (verified agy 1.0.0, macOS arm64 and Linux amd64):
 - No `-m` / `--model` flag — agy selects the model internally
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Pre-flight: snapshot the transcript watermark before invoking agy.
 # Must run BEFORE agy -p — this is what prevents the fallback from reading a stale prior response.
 _AGY_WS=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
@@ -426,6 +429,7 @@ fi
 Read host and model from config. All three local backends share the same `/v1/chat/completions` endpoint — only host and model differ. Use `jq --rawfile` to safely encode the multi-line prompt as JSON without shell-escaping issues.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Shared helper: apply prompt-budget trimming for local reviewers
 prepare_trimmed_prompt_for_reviewer() {
   REVIEWER_KEY="$1"
@@ -508,6 +512,7 @@ fi
 
 **LM Studio (local, OpenAI-compatible):**
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Resolve prompt budget for LM Studio: per-reviewer override > global default > null
 LM_STUDIO_REVIEWER_BUDGET=$(pp_run query config-get review.max_prompt_tokens_per_reviewer.lm_studio 2>/dev/null | jq -r '.' 2>/dev/null || echo "null")
 if [ -z "$LM_STUDIO_REVIEWER_BUDGET" ] || [ "$LM_STUDIO_REVIEWER_BUDGET" = "null" ]; then
@@ -561,6 +566,7 @@ fi
 
 **llama.cpp (local, OpenAI-compatible):**
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Resolve prompt budget for llama.cpp: per-reviewer override > global default > null
 LLAMA_CPP_REVIEWER_BUDGET=$(pp_run query config-get review.max_prompt_tokens_per_reviewer.llama_cpp 2>/dev/null | jq -r '.' 2>/dev/null || echo "null")
 if [ -z "$LLAMA_CPP_REVIEWER_BUDGET" ] || [ "$LLAMA_CPP_REVIEWER_BUDGET" = "null" ]; then
@@ -728,7 +734,7 @@ trimmed_reviewers:        # only present if at least one reviewer was trimmed
 
 Commit:
 ```bash
-pp_run query commit "docs: cross-AI review for phase {N}" --files {phase_dir}/{padded_phase}-REVIEWS.md
+pp_run query commit "docs(planning): cross-AI review for phase {N}" --phase "{padded_phase}" --files {phase_dir}/{padded_phase}-REVIEWS.md
 ```
 </step>
 

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

@@ -38,6 +38,7 @@ Display banner: `pp-core > SECURE PHASE {N}: {name}`
 ## 1. Detect Input State
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
 PLAN_FILES=$(ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)
 SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
@@ -151,7 +152,7 @@ Do NOT emit next-phase routing. Stop here.
 ## 7. Commit
 
 ```bash
-pp_run query commit "docs(phase-${PHASE}): add/update security threat verification"
+pp_run query commit "docs(planning): add/update security threat verification" --phase "${PADDED_PHASE}"
 ```
 
 ## 8. Results + Routing

package/pp-core/workflows/session-report.md

@@ -34,6 +34,7 @@ Read `.planning/ROADMAP.md` to get milestone name and goals.
 
 Check for existing reports:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls -la .planning/reports/SESSION_REPORT*.md 2>/dev/null || echo "No previous reports"
 ```
 </step>

package/pp-core/workflows/ship.md

@@ -99,6 +99,7 @@ Verify the work is ready to ship:
    ```
 
    ```bash
+   [ -z "${ZSH_VERSION:-}" ] || emulate -R sh
    SHIP_PRE_HOOKS_JSON=$(pp_run loop render-hooks ship:pre --raw)
    printf '%s' "$SHIP_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('SHIP_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
    SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
@@ -173,11 +174,13 @@ Verify the work is ready to ship:
 Push the current branch to remote:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 git push origin ${CURRENT_BRANCH} 2>&1
 ```
 
 If push fails (e.g., no upstream): set upstream:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 git push --set-upstream origin ${CURRENT_BRANCH} 2>&1
 ```
 
@@ -370,6 +373,7 @@ If `REVIEW_CMD` is non-empty and not `"null"`, run the external review:
 
 1. **Generate diff and stats:**
    ```bash
+   [ -z "${ZSH_VERSION:-}" ] || emulate -R sh
    DIFF=$(git diff ${BASE_BRANCH}...HEAD)
    DIFF_STATS=$(git diff --stat ${BASE_BRANCH}...HEAD)
    ```
@@ -382,6 +386,7 @@ If `REVIEW_CMD` is non-empty and not `"null"`, run the external review:
 3. **Build review prompt and pipe to command via stdin:**
    Construct a review prompt containing the diff, diff stats, and phase context, then pipe it to the configured command:
    ```bash
+   [ -z "${ZSH_VERSION:-}" ] || emulate -R sh
    REVIEW_PROMPT="You are reviewing a pull request.\n\nDiff stats:\n${DIFF_STATS}\n\nPhase context:\n${STATE_STATUS}\n\nFull diff:\n${DIFF}\n\nRespond with JSON: { \"verdict\": \"APPROVED\" or \"REVISE\", \"confidence\": 0-100, \"summary\": \"...\", \"issues\": [{\"severity\": \"...\", \"file\": \"...\", \"line_range\": \"...\", \"description\": \"...\", \"suggestion\": \"...\"}] }"
    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
@@ -399,6 +404,7 @@ If `REVIEW_CMD` is non-empty and not `"null"`, run the external review:
    that disagreed. `is_timeout_exit` is not in scope in this block (the wrapper is sourced in
    the block above), so the codes are tested numerically:
    ```bash
+   [ -z "${ZSH_VERSION:-}" ] || emulate -R sh
    if [ "${REVIEW_EXIT}" -eq 124 ] || [ "${REVIEW_EXIT}" -eq 142 ]; then
      echo "⚠ External review timed out after 120s (exit ${REVIEW_EXIT}) — advisory, not a failure"
    elif [ "${REVIEW_EXIT}" -eq 127 ] || [ "${REVIEW_EXIT}" -eq 2 ]; then
@@ -455,6 +461,7 @@ AskUserQuestion:
 
 **If "Request review":**
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 gh pr edit ${PR_NUMBER} --add-reviewer "${REVIEWER}"
 ```
 
@@ -472,7 +479,7 @@ pp_run query state.update "Status" "Phase ${PHASE_NUMBER} shipped — PR #${PR_N
 
 If `commit_docs` is true:
 ```bash
-pp_run query commit "docs(${padded_phase}): ship phase ${PHASE_NUMBER} — PR #${PR_NUMBER}" --files .planning/STATE.md
+pp_run query commit "docs(planning): ship phase ${PHASE_NUMBER} — PR #${PR_NUMBER}" --phase "${padded_phase}" --files .planning/STATE.md
 ```
 </step>
 

package/pp-core/workflows/sketch-wrap-up.md

@@ -233,7 +233,7 @@ If this routing line already exists (append mode), leave it as-is.
 Commit all artifacts (if `COMMIT_DOCS` is true):
 
 ```bash
-pp_run query commit "docs(sketch-wrap-up): package [N] sketch findings into project skill" --files .planning/sketches/WRAP-UP-SUMMARY.md
+pp_run query commit "docs(planning): package [N] sketch findings into project skill" --files .planning/sketches/WRAP-UP-SUMMARY.md
 ```
 </step>
 

package/pp-core/workflows/sketch.md

@@ -94,6 +94,7 @@ mkdir -p .planning/sketches/themes
 
 Check for existing sketches to determine numbering:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls -d .planning/sketches/[0-9][0-9][0-9]-* 2>/dev/null | sort | tail -1
 ```
 
@@ -298,7 +299,7 @@ Iterate until satisfied.
 
 **h.** Commit (if `COMMIT_DOCS` is true):
 ```bash
-pp_run query commit "docs(sketch-NNN): [winning direction] — [key visual insight]" --files .planning/sketches/NNN-descriptive-name/ .planning/sketches/MANIFEST.md
+pp_run query commit "docs(planning): sketch NNN [winning direction] — [key visual insight]" --files .planning/sketches/NNN-descriptive-name/ .planning/sketches/MANIFEST.md
 ```
 
 **i.** Report:
@@ -357,6 +358,6 @@ After all sketches complete:
 - [ ] Winning variant selected and marked for each sketch
 - [ ] All variants preserved (winner marked, not others deleted)
 - [ ] MANIFEST.md is current
-- [ ] Commits use `docs(sketch-NNN): [winner]` format
+- [ ] Commits use `docs(planning): sketch NNN [winner]` format
 - [ ] Summary presented with next-step routing
 </success_criteria>

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

@@ -74,6 +74,7 @@ Exit.
 
 **Check for existing SPEC.md:**
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls ${phase_dir}/*-SPEC.md 2>/dev/null | grep -v AI-SPEC | head -1 || true
 ```
 
@@ -447,7 +448,7 @@ Write to: `{phase_dir}/{padded_phase}-SPEC.md`
 
 ```bash
 git add "${phase_dir}/${padded_phase}-SPEC.md"
-git commit -m "spec(phase-${phase_number}): add SPEC.md for ${phase_name} — ${requirement_count} requirements (#2213)"
+git commit -m "docs(planning): add SPEC.md for ${phase_name} — ${requirement_count} requirements" -m "Phase: ${padded_phase}"
 ```
 
 If `commit_docs` is false: Skip commit. Note that SPEC.md was written but not committed.

package/pp-core/workflows/spike-wrap-up.md

@@ -247,7 +247,7 @@ Patterns and stack choices established across spike sessions. New spikes follow
 Commit all artifacts (if `COMMIT_DOCS` is true):
 
 ```bash
-pp_run query commit "docs(spike-wrap-up): package [N] spike findings into project skill" --files .planning/spikes/WRAP-UP-SUMMARY.md .planning/spikes/CONVENTIONS.md
+pp_run query commit "docs(planning): package [N] spike findings into project skill" --files .planning/spikes/WRAP-UP-SUMMARY.md .planning/spikes/CONVENTIONS.md
 ```
 </step>
 

package/pp-core/workflows/spike.md

@@ -91,6 +91,7 @@ mkdir -p .planning/spikes
 
 Check for existing spikes to determine numbering:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls -d .planning/spikes/[0-9][0-9][0-9]-* 2>/dev/null | sort | tail -1
 ```
 
@@ -335,7 +336,7 @@ tags: [tag1, tag2]
 
 **i.** Commit (if `COMMIT_DOCS` is true):
 ```bash
-pp_run query commit "docs(spike-NNN): [VERDICT] — [key finding]" --files .planning/spikes/NNN-descriptive-name/ .planning/spikes/MANIFEST.md
+pp_run query commit "docs(planning): spike NNN [VERDICT] — [key finding]" --files .planning/spikes/NNN-descriptive-name/ .planning/spikes/MANIFEST.md
 ```
 
 **j.** Report:
@@ -389,7 +390,7 @@ Only include patterns that repeated across 2+ spikes or were explicitly chosen b
 
 Commit (if `COMMIT_DOCS` is true):
 ```bash
-pp_run query commit "docs(spikes): update conventions" --files .planning/spikes/CONVENTIONS.md
+pp_run query commit "docs(planning): update spike conventions" --files .planning/spikes/CONVENTIONS.md
 ```
 </step>
 
@@ -448,6 +449,6 @@ pp_run query commit "docs(spikes): update conventions" --files .planning/spikes/
 - [ ] CONVENTIONS.md created or updated with patterns that emerged
 - [ ] Each spike README has complete frontmatter, Investigation Trail, and Results
 - [ ] MANIFEST.md is current (with Type column and Requirements section)
-- [ ] Commits use `docs(spike-NNN): [VERDICT]` format
+- [ ] Commits use `docs(planning): spike NNN [VERDICT]` format
 - [ ] Consolidated report presented with next-step routing
 </success_criteria>

package/pp-core/workflows/sync-skills.md

@@ -24,20 +24,21 @@ If neither `--dry-run` nor `--apply` is specified, dry-run is the default.
 ## Step 1: Parse Arguments
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 FROM_RUNTIME=""
 TO_RUNTIMES=()
 IS_APPLY=false
 
 # Parse --from
 if [[ "$@" == *"--from"* ]]; then
-  FROM_RUNTIME=$(echo "$@" | grep -oP '(?<=--from )\S+')
+  FROM_RUNTIME=$(echo "$@" | grep -oE -- '--from [^ ]+' | head -1 | sed 's/^--from //')
 fi
 
 # Parse --to
 if [[ "$@" == *"--to all"* ]]; then
   TO_RUNTIMES=(claude codex grok copilot cursor windsurf opencode gemini kilo augment trae qwen codebuddy cline antigravity)
 elif [[ "$@" == *"--to"* ]]; then
-  TO_RUNTIMES=( $(echo "$@" | grep -oP '(?<=--to )\S+') )
+  TO_RUNTIMES=( $(echo "$@" | grep -oE -- '--to [^ ]+' | sed 's/^--to //') )
 fi
 
 # Parse --apply
@@ -58,6 +59,7 @@ fi
 Use `install.js --skills-root` to resolve paths — this reuses the single authoritative path table rather than duplicating it:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 INSTALL_JS="$(dirname "$0")/../pp-core/bin/install.js"
 # If running from a global install, resolve relative to the pp-core package
 INSTALL_JS_GLOBAL="$HOME/.claude/pp-core/bin/install.js"
@@ -142,6 +144,7 @@ If `--dry-run` (or no flag): skip this step entirely and exit after printing the
 For each destination with changes:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 mkdir -p "$DEST_ROOT"
 
 for SKILL in $CREATE_LIST $UPDATE_LIST; do

package/pp-core/workflows/thread.md

@@ -22,6 +22,7 @@ Create, list, close, or resume persistent context threads for cross-session work
 **LIST / LIST-OPEN / LIST-RESOLVED mode:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls .planning/threads/*.md 2>/dev/null
 ```
 
@@ -74,7 +75,7 @@ When SUBCMD=close and SLUG is set (already sanitized):
 
 3. Commit:
    ```bash
-   pp_run query commit "docs: resolve thread — {SLUG}" --files ".planning/threads/{SLUG}.md"
+   pp_run query commit "docs(planning): resolve thread — {SLUG}" --files ".planning/threads/{SLUG}.md"
    ```
 
 4. Print:
@@ -186,7 +187,7 @@ updated: {today ISO date}
 
 5. Commit:
    ```bash
-   pp_run query commit "docs: create thread — ${ARGUMENTS}" --files ".planning/threads/${SLUG}.md"
+   pp_run query commit "docs(planning): create thread — ${ARGUMENTS}" --files ".planning/threads/${SLUG}.md"
    ```
 
 6. Report:

package/pp-core/workflows/transition.md

@@ -59,6 +59,7 @@ Note accumulated context that may need updating after transition.
 Check current phase has all plan summaries:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 (ls .planning/phases/XX-current/*-PLAN.md 2>/dev/null || true) | sort
 (ls .planning/phases/XX-current/*-SUMMARY.md 2>/dev/null || true) | sort
 ```
@@ -81,6 +82,7 @@ cat .planning/config.json 2>/dev/null || true
 **Check for verification debt in this phase:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Count outstanding items in current phase
 OUTSTANDING=""
 for f in .planning/phases/XX-current/*-UAT.md .planning/phases/XX-current/*-VERIFICATION.md; do
@@ -155,6 +157,7 @@ Wait for user decision.
 Check for lingering handoffs:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls .planning/phases/XX-current/.continue-here*.md 2>/dev/null || true
 ```
 
@@ -196,6 +199,7 @@ Evolve PROJECT.md to reflect learnings from completed phase.
 **Read phase summaries:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 cat .planning/phases/XX-current/*-SUMMARY.md
 ```
 
@@ -385,6 +389,7 @@ After (if database indexing was addressed in Phase 2):
 Record the transition in STATE.md's Session Continuity through the state verb, never by hand: it writes the `Stopped at:` line, the `Last session` timestamp and the frontmatter `stopped_at` together. A hand edit leaves the stored `stopped_at` behind, and `state json`, `state-snapshot` and later writes keep the older value.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 pp_run query state.record-session --stopped-at "Phase [X] complete, ready to plan Phase [X+1]" --resume-file "None" ${GSD_WS}
 ```
 
@@ -452,6 +457,7 @@ Read ROADMAP.md to get the next phase's name and goal.
 **Check if next phase has CONTEXT.md:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls .planning/phases/*[X+1]*/*-CONTEXT.md 2>/dev/null || true
 ```
 

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

@@ -32,6 +32,7 @@ Parse JSON for: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded
 
 Detect sketch findings:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 SKETCH_FINDINGS_PATH=$(ls ./.claude/skills/sketch-findings-*/SKILL.md 2>/dev/null | head -1 || true)
 ```
 
@@ -113,6 +114,7 @@ Continue (non-blocking).
 ## 4. Check Existing UI-SPEC
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 ```
 
@@ -320,7 +322,7 @@ Dimensions: 6/6 passed
 ## 11. Commit (if configured)
 
 ```bash
-pp_run query commit "docs(${padded_phase}): UI design contract" --files "${PHASE_DIR}/${PADDED_PHASE}-UI-SPEC.md"
+pp_run query commit "docs(planning): UI design contract" --phase "${padded_phase}" --files "${PHASE_DIR}/${PADDED_PHASE}-UI-SPEC.md"
 ```
 
 ## 12. Update State

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

@@ -38,6 +38,7 @@ Display banner:
 ## 1. Detect Input State
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 UI_REVIEW_FILE=$(ls "${PHASE_DIR}"/*-UI-REVIEW.md 2>/dev/null | head -1)
@@ -177,7 +178,7 @@ tools is detected at runtime.
 ## 5. Commit (if configured)
 
 ```bash
-pp_run query commit "docs(${padded_phase}): UI audit review" --files "${PHASE_DIR}/${PADDED_PHASE}-UI-REVIEW.md"
+pp_run query commit "docs(planning): UI audit review" --phase "${padded_phase}" --files "${PHASE_DIR}/${PADDED_PHASE}-UI-REVIEW.md"
 ```
 
 </process>

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

@@ -29,6 +29,7 @@ Use /pp:plan-phase for stable local planning.
 Check that the session is running inside Claude Code:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ "$CLAUDECODE" = "1" ] || [ -n "$CLAUDE_CODE_ENTRYPOINT" ]; then
   CC_VERSION="$(claude --version 2>/dev/null | grep -Eo '[0-9]+\.[0-9]+\.[0-9]+' | head -n1)"
   if [ -n "$CC_VERSION" ] && [ "$(printf '%s\n' "2.1.91" "$CC_VERSION" | sort -V | head -n1)" = "2.1.91" ]; then

package/pp-core/workflows/undo.md

@@ -50,17 +50,18 @@ Based on MODE, gather candidate commits.
 
 Run:
 ```bash
-git log --oneline --no-merges -${COUNT}
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
+git log --no-merges -${COUNT} --format='%h %s [Phase: %(trailers:key=Phase,valueonly,separator=%x2C)]'
 ```
 
-Filter for pp-core conventional commits matching `type(scope): message` pattern (e.g., `feat(04-01):`, `docs(03):`, `fix(02-03):`).
+Filter for conventional commits matching `type(scope): message` or `type: message` (e.g., `feat(auth):`, `docs(planning):`, `fix:`). The scope names a part of the codebase; the phase or plan a commit belongs to is its `Phase:` trailer, shown in brackets (empty when the commit has none).
 
 Display a numbered list of matching commits:
 ```
 Recent pp-core commits:
-  1. abc1234 feat(04-01): implement auth endpoint
-  2. def5678 docs(03-02): complete plan summary
-  3. ghi9012 fix(02-03): correct validation logic
+  1. abc1234 feat(auth): implement auth endpoint [Phase: 04-01]
+  2. def5678 docs(planning): complete plan summary [Phase: 03-02]
+  3. ghi9012 fix(validation): correct validation logic [Phase: 02-03]
 ```
 
 
@@ -82,9 +83,10 @@ If the file exists and `manifest.phases?.[TARGET_PHASE]?.commits` is a non-empty
 
 If the file does not exist, or `manifest.phases?.[TARGET_PHASE]` is missing:
   - Display: "Manifest has no entry for phase ${TARGET_PHASE} (or file missing), falling back to git log search"
-  - Fallback: run git log and filter for the target phase scope:
+  - Fallback: run git log and filter for commits whose `Phase:` trailer is the target phase or one of its plans (a `type(<phase>):` subject from before the trailer convention also matches):
     ```bash
-    git log --oneline --no-merges --all | grep -E "\(0*${TARGET_PHASE}(-[0-9]+)?\):" | head -50
+    git log --no-merges --all --format='%h %s [Phase: %(trailers:key=Phase,valueonly,separator=%x2C)]' \
+      | grep -E "\[Phase: 0*${TARGET_PHASE}(-[0-9]+)?\]|\(0*${TARGET_PHASE}(-[0-9]+)?\):" | head -50
     ```
   - Use matching commits as COMMITS
 
@@ -94,7 +96,8 @@ If the file does not exist, or `manifest.phases?.[TARGET_PHASE]` is missing:
 
 Run:
 ```bash
-git log --oneline --no-merges --all | grep -E "\(${TARGET_PLAN}\)" | head -50
+git log --no-merges --all --format='%h %s [Phase: %(trailers:key=Phase,valueonly,separator=%x2C)]' \
+  | grep -E "\[Phase: ${TARGET_PLAN}\]|\(${TARGET_PLAN}\):" | head -50
 ```
 
 Use matching commits as COMMITS.
@@ -214,6 +217,7 @@ Sort COMMITS in reverse chronological order (newest first). If commits came from
 
 For each commit hash in COMMITS:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 git revert --no-commit ${HASH}
 ```
 
@@ -246,12 +250,12 @@ After all reverts are staged successfully, create a single commit:
 
 For MODE=phase:
 ```bash
-git commit -m "revert(${TARGET_PHASE}): undo phase ${TARGET_PHASE} — ${REVERT_REASON}"
+git commit -m "revert: undo phase ${TARGET_PHASE} — ${REVERT_REASON}" -m "Phase: ${TARGET_PHASE}"
 ```
 
 For MODE=plan:
 ```bash
-git commit -m "revert(${TARGET_PLAN}): undo plan ${TARGET_PLAN} — ${REVERT_REASON}"
+git commit -m "revert: undo plan ${TARGET_PLAN} — ${REVERT_REASON}" -m "Phase: ${TARGET_PLAN}"
 ```
 
 For MODE=last:

package/pp-core/workflows/update.md

@@ -18,6 +18,7 @@ First, derive `PREFERRED_CONFIG_DIR` and `PREFERRED_RUNTIME` from the invoking p
 Then resolve the install context via the deterministic projection (#498). **Do NOT re-derive scope, runtime, or version by hand** — `update-context` owns that cascade in tested code (`pp-core/bin/lib/update-context.cjs`), the same way `check-latest-version` owns the package name (#2992):
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Resolve pp-tools.cjs WITHOUT yet knowing GSD_DIR. The running workflow lives
 # at <PREFERRED_CONFIG_DIR>/pp-core/workflows/update.md, so its sibling
 # bin/pp-tools.cjs is the authoritative tool for THIS install. Fall back to a
@@ -79,6 +80,7 @@ If multiple runtime installs are detected and the invoking runtime cannot be det
 Determine the release channel from `$ARGUMENTS`. This selects which npm dist-tag the entire update flow targets — `latest` (stable) by default, or `next` (the RC channel established by ADR #660) when the user opts in with `--next`/`--rc`:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 case " $ARGUMENTS " in
   *" --next "*|*" --rc "*)
     TAG="next"
@@ -102,6 +104,7 @@ The `GSD_DIR` value emitted by `get_installed_version` (line 4) resolves to the
 `LATEST_RESULT` is a JSON document with the documented shape `{ ok: bool, version: string, reason: string, detail?: string }`. Parse via `jq` ONLY when the script actually ran. When `GSD_DIR` is empty (scope `UNKNOWN`), skip the check entirely and seed the parsed fields with their no-op values so downstream logic does not mistake an unset `LATEST_RESULT` for a failed network check (#2993 CR feedback):
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ -z "$GSD_DIR" ]; then
   # No install detected — fall through to install step; version-check is skipped.
   LATEST_RESULT=""
@@ -312,6 +315,7 @@ Back up each custom file to `$RUNTIME_DIR/pp-user-files-backup/` before the
 installer wipes the directories:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 BACKUP_DIR="$RUNTIME_DIR/pp-user-files-backup"
 mkdir -p "$BACKUP_DIR"
 
@@ -377,6 +381,7 @@ Capture output. If install fails, show error and exit.
 Clear the update cache so statusline indicator disappears:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 expand_home() {
   case "$1" in
     "~/"*) printf '%s/%s\n' "$HOME" "${1#~/}" ;;

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

@@ -57,6 +57,7 @@ gate on the `execute:pre` payload, filtered in the fence to the `vault`
 capability (D-30):
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 VP_EXECUTE_PRE_HOOKS_JSON=$(pp_run loop render-hooks execute:pre --raw | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const j=JSON.parse(d);j.activeHooks=(j.activeHooks||[]).filter((x)=>x&&x.capId==='vault');process.stdout.write(JSON.stringify(j));}catch{process.stdout.write('');}")
 printf '%s' "$VP_EXECUTE_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('VP_EXECUTE_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 ```
@@ -72,6 +73,7 @@ it owns the halt.
 ## 1. Detect Input State
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 VALIDATION_FILE=$(ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null | head -1)
 SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
 ```
@@ -188,9 +190,10 @@ Handle return:
 
 ```bash
 git add {test_files}
-git commit -m "test(phase-${PHASE}): add Nyquist validation tests"
+# {area}: the part of the codebase the tests cover; drop "({area})" when no single area fits
+git commit -m "test({area}): add Nyquist validation tests" -m "Phase: ${PADDED_PHASE}"
 
-pp_run query commit "docs(phase-${PHASE}): add/update validation strategy"
+pp_run query commit "docs(planning): add/update validation strategy" --phase "${PADDED_PHASE}"
 ```
 
 Vault door record (D-12), only when Step 5 ran: after the door's last source commit, set `DOOR_DIR="${PHASE_DIR}"`,
@@ -205,7 +208,7 @@ The verb writes a `## Vault Door Record` (mode, vault ref and sha, governing pha
 recorded and the end commit; the agent never types a sha) into a fresh per-run artifact, because it refuses a second record
 in one file (D-57) and a rewritten report would drop the earlier run's coverage (D-79). It prints
 nothing and writes nothing unless `vault admission` answers `on`. When it wrote the file and
-`commit_docs` is true, commit the `artifact` path it printed: `pp_run query commit "docs(phase-${PHASE}): vault door record for validate-phase" --files "<that artifact>"`.
+`commit_docs` is true, commit the `artifact` path it printed: `pp_run query commit "docs(planning): vault door record for validate-phase" --phase "${PADDED_PHASE}" --files "<that artifact>"`.
 
 (A per-run `-VALIDATION.md` name would be read as the phase's validation strategy by the `*-VALIDATION.md`
 globs, so validate-phase's record uses the `-ADD-TESTS.md` suffix: what it records is the tests it added.)

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

@@ -51,6 +51,7 @@ Then display the banner:
 ## 1. Detect Input State
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
 VAULT_REVIEW_FILE=$(ls "${PHASE_DIR}"/*-VAULT-REVIEW.md 2>/dev/null | head -1)
 ```
@@ -84,6 +85,11 @@ reinterpret it.
   range (`filesTruncated` when the list was capped).
 - `gaps[]`: facts the CLI could not establish. Every gap goes into the artifact's `## Not Derived`
   section; a gap is never silently dropped and never turned into a verdict.
+- `deviations[]`: the rows of `.planning/discovery/_deviations.md` when the project ran the
+  Discovery Sprint (`id`, `standard`, `status`, `decision`, `approver`); empty otherwise. An
+  `Approved` deviation that covers a clause turns that document's `FAIL` into `N-A` with the reason
+  `deviation on file: …` — the agent's rule, in `agents/pp-vault-reviewer.md`
+  (`references/discovery-build-consumption.md` § `_deviations.md` read contract).
 
 ## 3. Spawn pp-vault-reviewer
 
@@ -188,7 +194,7 @@ step reads a verdict into a halt, an exit code or a block, and nothing here writ
 ## 5. Commit (if configured)
 
 ```bash
-pp_run query commit "docs(${PADDED_PHASE}): vault standards review" --files "${PHASE_DIR}/${PADDED_PHASE}-VAULT-REVIEW.md"
+pp_run query commit "docs(planning): vault standards review" --phase "${PADDED_PHASE}" --files "${PHASE_DIR}/${PADDED_PHASE}-VAULT-REVIEW.md"
 ```
 
 </process>

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

@@ -40,6 +40,7 @@ Do not compose, rewrite or reformat the document at this or any later step. What
 disk at that path are exactly the bytes that will be previewed and, if approved, pushed.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 DOC_FILE="<the resolved path>"
 PROMOTE_ARGS=()   # add --path, --entry and --section with their values, as given
 ```
@@ -52,6 +53,7 @@ writes the change there, and reports the diff.
 
 ```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
 PROMOTE_PREVIEW_OUT=$(mktemp)
 PROMOTE_PREVIEW_ERR=$(mktemp)
 pp_run vault standards promote "$DOC_FILE" "${PROMOTE_ARGS[@]}" --raw >"$PROMOTE_PREVIEW_OUT" 2>"$PROMOTE_PREVIEW_ERR"
@@ -71,6 +73,7 @@ its own file and read back with `$(cat …)`, whose result bash does not re-scan
 destination path containing `$(...)` or backticks is shown, never executed.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 PROMOTE_FIELDS=$(mktemp -d)
 node -e "
 const fs = require('fs');
@@ -137,6 +140,7 @@ Only inside this approved branch, run the verb again with the same arguments, `-
 expect token carried verbatim from the preview.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 PROMOTE_PUSH_OUT=$(mktemp)
 PROMOTE_PUSH_ERR=$(mktemp)
 pp_run vault standards promote "$DOC_FILE" "${PROMOTE_ARGS[@]}" --confirmed --expect "$PROMOTE_EXPECT" --raw >"$PROMOTE_PUSH_OUT" 2>"$PROMOTE_PUSH_ERR"
@@ -156,6 +160,7 @@ refresh did not succeed, say so plainly: the next vault fetch picks the change u
 succeeded.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 node -e "
 const fs = require('fs');
 const v = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));