@pareto4/pp-core 1.18.0 → 1.20.0

package/pp-core/workflows/add-tests.md

@@ -84,6 +84,7 @@ gate on the `execute:pre` payload, filtered in the fence to the `vault`
 capability (D-30):
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 AT_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' "$AT_EXECUTE_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('AT_EXECUTE_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 ```
@@ -186,6 +187,7 @@ If user selects "Cancel": exit gracefully.
 Before generating the test plan, discover the project's existing test structure:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Find existing test directories
 find . -type d -name "*test*" -o -name "*spec*" -o -name "*__tests__*" 2>/dev/null | head -20
 # Find existing test files for convention matching
@@ -349,7 +351,8 @@ If there are passing tests to commit:
 
 ```bash
 git add {test files}
-git commit -m "test(phase-${phase_number}): add unit and E2E tests from add-tests command"
+# {area}: the part of the codebase the tests cover; drop "({area})" when no single area fits
+git commit -m "test({area}): add unit and E2E tests from add-tests command" -m "Phase: ${padded_phase}"
 ```
 
 Vault door record (D-12): after the door's last source commit, set `DOOR_DIR="${phase_dir}"`,
@@ -364,7 +367,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_number}): vault door record for add-tests" --files "<that artifact>"`.
+`commit_docs` is true, commit the `artifact` path it printed: `pp_run query commit "docs(planning): vault door record for add-tests" --phase "${padded_phase}" --files "<that artifact>"`.
 
 Present next steps:
 

package/pp-core/workflows/add-todo.md

@@ -63,6 +63,7 @@ Use existing area from step 2 if similar match exists.
 
 <step name="check_duplicates">
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Search for key words from title in existing todos
 grep -l -i "[key words from title]" .planning/todos/pending/*.md 2>/dev/null || true
 ```
@@ -122,7 +123,8 @@ If `.planning/STATE.md` exists:
 Commit the todo and any updated state:
 
 ```bash
-pp_run query commit "docs: capture todo - [title]" --files .planning/todos/pending/[filename] .planning/STATE.md
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
+pp_run query commit "docs(planning): capture todo - [title]" --files .planning/todos/pending/[filename] .planning/STATE.md
 ```
 
 Tool respects `commit_docs` config and gitignore automatically.

package/pp-core/workflows/ai-integration-phase.md

@@ -73,6 +73,7 @@ Continue (non-blocking).
 ## 4. Check Existing AI-SPEC
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 AI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-AI-SPEC.md 2>/dev/null | head -1)
 ```
 
@@ -259,7 +260,7 @@ Read the completed AI-SPEC.md. Check that:
 **If `commit_docs` is true:**
 ```bash
 git add "${AI_SPEC_FILE}"
-git commit -m "docs({phase_slug}): generate AI-SPEC.md — {primary_framework} + domain context + eval strategy"
+git commit -m "docs(planning): generate AI-SPEC.md — {primary_framework} + domain context + eval strategy" -m "Phase: {padded_phase}"
 ```
 
 ## 12. Display Completion

package/pp-core/workflows/audit-fix.md

@@ -110,6 +110,7 @@ gate on the `execute:pre` payload, filtered in the fence to the `vault`
 capability (D-30):
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 AF_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' "$AF_EXECUTE_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('AF_EXECUTE_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 ```
@@ -168,9 +169,9 @@ fi
 **c. If tests pass** — commit atomically:
 ```bash
 git add {changed_files}
-git commit -m "fix({scope}): resolve {ID} — {description}"
+git commit -m "fix({area}): resolve {ID} — {description}"
 ```
-The commit message **must** include the finding ID (e.g., F-01) for traceability.
+`{area}` names the part of the codebase the fix touches (`auth`, `billing`); omit `({area})` when no single area fits. The commit message **must** include the finding ID (e.g., F-01) for traceability.
 
 **d. If tests fail** — revert changes, mark finding as `fix-failed`, and **stop the pipeline**:
 ```bash
@@ -200,7 +201,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: vault door record for audit-fix" --files "<that artifact>"`.
+`commit_docs` is true, commit the `artifact` path it printed: `pp_run query commit "docs(planning): vault door record for audit-fix" --files "<that artifact>"`.
 </step>
 
 <step name="report">

package/pp-core/workflows/audit-milestone.md

@@ -116,6 +116,7 @@ For each phase's VERIFICATION.md, extract the expanded requirements table:
 
 For each phase's SUMMARY.md, extract `requirements-completed` from YAML frontmatter:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 for summary in .planning/phases/*-*/*-SUMMARY.md; do
   [ -e "$summary" ] || continue
   pp_run query summary-extract "$summary" --fields requirements_completed --pick requirements_completed

package/pp-core/workflows/autonomous.md

@@ -189,6 +189,7 @@ Set `FIRST_PHASE` to the first remaining phase's number, derive `RUN_STATE` per
 **Fetch details for each phase:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 DETAIL=$(pp_run query roadmap.get-phase ${PHASE_NUM})
 ```
 
@@ -217,6 +218,7 @@ Banner math (N, T, P and the N > T fallback): reference § Banner math.
 Check if CONTEXT.md already exists for this phase:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 PHASE_STATE=$(pp_run query init.phase-op ${PHASE_NUM})
 ```
 
@@ -262,6 +264,7 @@ Skill(skill="pp-discuss-phase", args="${PHASE_NUM}")
 After discuss completes (either mode), verify context was written:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 PHASE_STATE=$(pp_run query init.phase-op ${PHASE_NUM})
 ```
 
@@ -281,6 +284,7 @@ case "$VAULT_ADMIT" in on) echo "VAULT_ADMIT=on" ;; off|inert) : ;; *) pp_run va
 Resolve active `plan:pre` hooks:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw)
 printf '%s' "$HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
@@ -350,6 +354,7 @@ Skill(skill="pp-${ref.skill}", args="${PHASE_NUM}")
 After all step hooks return, re-read:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 ```
 
@@ -554,6 +559,7 @@ Route the new status through A-3 (passed → `OUTCOME=passed`; human_needed →
 Resolve the active post-verification hooks and the UI-SPEC gate:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw)
 ```

package/pp-core/workflows/check-todos.md

@@ -168,8 +168,9 @@ Re-run `init todos` to get updated count, then update STATE.md "### Pending Todo
 If todo was moved to done/, commit the change:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 git rm --cached .planning/todos/pending/[filename] 2>/dev/null || true
-pp_run query commit "docs: start work on todo - [title]" --files .planning/todos/completed/[filename] .planning/STATE.md
+pp_run query commit "docs(planning): start work on todo - [title]" --files .planning/todos/completed/[filename] .planning/STATE.md
 ```
 
 Tool respects `commit_docs` config and gitignore automatically.

package/pp-core/workflows/cleanup.md

@@ -27,6 +27,7 @@ Extract each milestone version (e.g., v1.0, v1.1, v2.0).
 Check which milestone archive dirs already exist:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls -d .planning/milestones/v*-phases 2>/dev/null || true
 ```
 
@@ -55,6 +56,7 @@ Extract phase numbers and names from the archived roadmap (e.g., Phase 1: Founda
 Check which of those phase directories still exist in `.planning/phases/`:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls -d .planning/phases/*/ 2>/dev/null || true
 ```
 
@@ -162,7 +164,7 @@ Commit the changes:
 
 ```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 "chore: archive phase directories from completed milestones" --files .planning/milestones/ .planning/phases/
+pp_run query commit "chore(planning): archive phase directories from completed milestones" --files .planning/milestones/ .planning/phases/
 ```
 
 </step>

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

@@ -110,6 +110,7 @@ Do NOT auto-run code-review. Require explicit user action to ensure review inten
 Parse REVIEW.md frontmatter to check status and extract context for --auto loop:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Parse status field
 REVIEW_STATUS=$(REVIEW_PATH="${REVIEW_PATH}" node -e "
   const fs = require('fs');
@@ -137,6 +138,7 @@ Warning: Could not parse REVIEW.md status. Proceeding with fix attempt.
 Extract review depth for --auto re-review:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 REVIEW_DEPTH=$(REVIEW_PATH="${REVIEW_PATH}" node -e "
   const fs = require('fs');
   const content = fs.readFileSync(process.env.REVIEW_PATH, 'utf-8');
@@ -152,6 +154,7 @@ REVIEW_DEPTH=$(REVIEW_PATH="${REVIEW_PATH}" node -e "
 Extract original review file list for --auto re-review scope persistence:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Extract review file list — portable bash 3.2+ (no mapfile, handles spaces in paths)
 REVIEW_FILES_ARRAY=()
 while IFS= read -r line; do
@@ -199,6 +202,7 @@ gate on the `execute:pre` payload, filtered in the fence to the `vault`
 capability (D-30):
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 CRF_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' "$CRF_EXECUTE_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('CRF_EXECUTE_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 ```
@@ -267,7 +271,7 @@ Check if FIX_REPORT_PATH exists:
 
 Either way:
 ```
-Some fix commits may already exist in git history — check git log for fix(${PADDED_PHASE}) commits.
+Some fix commits may already exist in git history — check git log --grep="^Phase: ${PADDED_PHASE}$" for fix commits.
 You can retry with /pp:code-review ${PHASE_ARG} --fix.
 ```
 
@@ -278,6 +282,7 @@ Exit workflow (skip auto loop).
 Only runs if AUTO_MODE is true. If AUTO_MODE is false, skip this step entirely.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ "$AUTO_MODE" = "true" ]; then
   # Iteration semantics: the initial fix pass (step 5) is iteration 1.
   # This loop runs iterations 2..MAX_ITERATIONS (re-review + re-fix cycles).
@@ -395,6 +400,7 @@ Key design decisions for --auto (addresses ALL review HIGH concerns):
 After ALL iterations complete (or single pass in non-auto mode), validate and commit REVIEW-FIX.md:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ -f "${FIX_REPORT_PATH}" ]; then
   # Validate REVIEW-FIX.md has valid YAML frontmatter with status field
   HAS_STATUS=$(REVIEW_PATH="${REVIEW_PATH}" node -e "
@@ -409,7 +415,7 @@ if [ -f "${FIX_REPORT_PATH}" ]; then
     
     if [ "$COMMIT_DOCS" = "true" ]; then
       pp_run query commit \
-        "docs(${PADDED_PHASE}): add code review fix report" \
+        "docs(planning): add code review fix report" --phase "${PADDED_PHASE}" \
         --files "${FIX_REPORT_PATH}"
     fi
   else
@@ -419,7 +425,7 @@ if [ -f "${FIX_REPORT_PATH}" ]; then
 else
   echo "Warning: REVIEW-FIX.md not found at ${FIX_REPORT_PATH}."
   echo "Agent may have failed before writing report."
-  echo "Check git log for any fix(${PADDED_PHASE}) commits that were applied."
+  echo "Check git log --grep='^Phase: ${PADDED_PHASE}\$' for any fix commits that were applied."
 fi
 ```
 
@@ -441,7 +447,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(${PADDED_PHASE}): vault door record for code-review-fix" --files "<that artifact>"`.
+`commit_docs` is true, commit the `artifact` path it printed: `pp_run query commit "docs(planning): vault door record for code-review-fix" --phase "${PADDED_PHASE}" --files "<that artifact>"`.
 </step>
 
 <step name="present_results">
@@ -459,7 +465,7 @@ if [ ! -f "${FIX_REPORT_PATH}" ]; then
   echo "───────────────────────────────────────────────────────────────"
   echo ""
   echo "The fixer agent may have failed before completing."
-  echo "Check git log for any fix(${PADDED_PHASE}) commits."
+  echo "Check git log --grep='^Phase: ${PADDED_PHASE}\$' for any fix commits."
   echo ""
   echo "Retry: /pp:code-review ${PHASE_ARG} --fix"
   echo ""
@@ -471,6 +477,7 @@ fi
 Extract frontmatter fields:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Extract only the YAML frontmatter block (between first two --- lines)
 FIX_FRONTMATTER=$(REVIEW_PATH="${REVIEW_PATH}" node -e "
   const fs = require('fs');

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

@@ -18,6 +18,7 @@ Parse arguments and load project state:
 
 ```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
 PHASE_ARG="${1}"
 INIT=$(pp_run query init.phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
@@ -138,6 +139,7 @@ Three-tier scoping with explicit precedence:
 
 If FILES_OVERRIDE is set (from --files flag):
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ -n "$FILES_OVERRIDE" ]; then
   REVIEW_FILES=()
   REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
@@ -168,6 +170,7 @@ Skip SUMMARY/git scoping entirely when --files is provided.
 
 If --files NOT provided:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ -z "$FILES_OVERRIDE" ]; then
   SUMMARIES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
   REVIEW_FILES=()
@@ -222,6 +225,7 @@ fi
 
 If no SUMMARY.md files found OR no files extracted from them:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ ${#REVIEW_FILES[@]} -eq 0 ]; then
   # Compute diff base from phase commits — fail closed if no reliable base found
   PHASE_COMMITS=$(git log --oneline --all --grep="${PADDED_PHASE}" --format="%H" 2>/dev/null)
@@ -257,6 +261,7 @@ fi
 
 1. **Apply exclusions (per D-03):** Remove paths matching planning artifacts
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 FILTERED_FILES=()
 for file in "${REVIEW_FILES[@]}"; do
   # Skip planning directory and specific artifacts
@@ -275,6 +280,7 @@ REVIEW_FILES=("${FILTERED_FILES[@]}")
 
 2. **Filter deleted files:** Remove paths that don't exist on disk
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 EXISTING_FILES=()
 DELETED_COUNT=0
 for file in "${REVIEW_FILES[@]}"; do
@@ -293,6 +299,7 @@ fi
 
 3. **Deduplicate:** Remove duplicate paths (portable — bash 3.2+ compatible, handles spaces in paths)
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 DEDUPED=()
 while IFS= read -r line; do
   [ -n "$line" ] && DEDUPED+=("$line")
@@ -304,6 +311,7 @@ REVIEW_FILES=("${DEDUPED[@]}")
 
 **Log final scope and warn if large:**
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ -n "$FILES_OVERRIDE" ]; then
   TIER="--files override"
 elif [ -n "$SUMMARIES" ] && [ ${#REVIEW_FILES[@]} -gt 0 ]; then
@@ -379,6 +387,7 @@ fi
 
 3) Execute structural pass and persist JSON (bounded at 120s). Note: `fallow audit` exits 0 when clean and 1 when issues are found — BOTH are successful runs. Only a timeout (124), usage error (2), or crash yields no usable JSON; success is decided by whether the output parses as a valid fallow report, not by exit code:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 FALLOW_JSON_PATH="${PHASE_DIR}/FALLOW.json"
 FALLOW_STDERR_TMP=$(mktemp)
 
@@ -459,6 +468,7 @@ fi
 
 Build files_to_read block for agent:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 FILES_TO_READ=""
 for file in "${REVIEW_FILES[@]}"; do
   FILES_TO_READ+="- ${file}\n"
@@ -467,6 +477,7 @@ done
 
 Build config block for agent:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 CONFIG_FILES=""
 for file in "${REVIEW_FILES[@]}"; do
   CONFIG_FILES+="  - ${file}\n"
@@ -475,6 +486,7 @@ done
 
 Build structural findings block for agent:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 STRUCTURAL_FINDINGS_BLOCK=""
 MAX_FINDINGS_SIZE=50000
 if [ -n "$FALLOW_JSON_PATH" ] && [ -f "$FALLOW_JSON_PATH" ]; then
@@ -542,6 +554,7 @@ Do NOT proceed to commit_review step. Do NOT create a partial or empty REVIEW.md
 After agent completes successfully, verify REVIEW.md was created and has valid structure:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ -f "${REVIEW_PATH}" ]; then
   # Validate REVIEW.md has valid YAML frontmatter with status field
   HAS_STATUS=$(REVIEW_PATH="${REVIEW_PATH}" node -e "
@@ -556,7 +569,7 @@ if [ -f "${REVIEW_PATH}" ]; then
     
     if [ "$COMMIT_DOCS" = "true" ]; then
       pp_run query commit \
-        "docs(${PADDED_PHASE}): add code review report" \
+        "docs(planning): add code review report" --phase "${PADDED_PHASE}" \
         --files "${REVIEW_PATH}"
     fi
   else
@@ -616,6 +629,7 @@ Read the REVIEW.md YAML frontmatter to extract finding counts.
 Extract frontmatter between `---` delimiters first to avoid matching values in the review body:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Extract only the YAML frontmatter block (between first two --- lines)
 FRONTMATTER=$(REVIEW_PATH="${REVIEW_PATH}" node -e "
   const fs = require('fs');

package/pp-core/workflows/complete-milestone.md

@@ -201,6 +201,7 @@ Milestone Stats:
 Extract one-liners from SUMMARY.md files using summary-extract:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # For each phase in milestone, extract one-liner
 for summary in .planning/phases/*-*/*-SUMMARY.md; do
   [ -e "$summary" ] || continue
@@ -236,6 +237,7 @@ Full PROJECT.md evolution review at milestone completion.
 Read all phase summaries:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 cat .planning/phases/*-*/*-SUMMARY.md
 ```
 
@@ -385,11 +387,13 @@ AskUserQuestion(header="Archive Phases", question="Archive phase directories to
 
 If "Yes":
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ARCHIVE=$(pp_run query milestone.complete "v[X.Y]" --name "[Milestone Name]" --archive-phases ${GSD_WS})
 ```
 
 If "Skip":
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ARCHIVE=$(pp_run query milestone.complete "v[X.Y]" --name "[Milestone Name]" ${GSD_WS})
 ```
 
@@ -482,7 +486,8 @@ Append the extracted Backlog content verbatim to the end of the newly written RO
 **Safety commit — commit archive files BEFORE deleting any originals:**
 
 ```bash
-pp_run query commit "chore: archive v[X.Y] milestone files" --files .planning/milestones/v[X.Y]-ROADMAP.md .planning/milestones/v[X.Y]-REQUIREMENTS.md .planning/milestones/v[X.Y]-MILESTONE-AUDIT.md .planning/MILESTONES.md .planning/PROJECT.md .planning/STATE.md .planning/ROADMAP.md
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
+pp_run query commit "chore(planning): archive v[X.Y] milestone files" --files .planning/milestones/v[X.Y]-ROADMAP.md .planning/milestones/v[X.Y]-REQUIREMENTS.md .planning/milestones/v[X.Y]-MILESTONE-AUDIT.md .planning/MILESTONES.md .planning/PROJECT.md .planning/STATE.md .planning/ROADMAP.md
 ```
 
 This creates a durable checkpoint in git history. If anything fails after this point, the working tree can be reconstructed from git.
@@ -551,7 +556,7 @@ If the "## Cross-Milestone Trends" section exists, update the tables with new da
 
 **Commit:**
 ```bash
-pp_run query commit "docs: update retrospective for v${VERSION}" --files .planning/RETROSPECTIVE.md
+pp_run query commit "docs(planning): update retrospective for v${VERSION}" --files .planning/RETROSPECTIVE.md
 ```
 
 </step>
@@ -633,6 +638,7 @@ AskUserQuestion with options: Squash merge (Recommended), Merge with history, De
 **Squash merge:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 CURRENT_BRANCH=$(git branch --show-current)
 git checkout ${BASE_BRANCH}
 
@@ -662,6 +668,7 @@ git checkout "$CURRENT_BRANCH"
 **Merge with history:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 CURRENT_BRANCH=$(git branch --show-current)
 git checkout ${BASE_BRANCH}
 
@@ -691,6 +698,7 @@ git checkout "$CURRENT_BRANCH"
 **Delete without merging:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ "$BRANCHING_STRATEGY" = "phase" ]; then
   for branch in $PHASE_BRANCHES; do
     git branch -d "$branch" 2>/dev/null || git branch -D "$branch"
@@ -716,6 +724,7 @@ If the result is `false` → skip this step entirely and proceed to `git_commit_
 Create git tag:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Pre-check: skip if tag already exists (prevents silent failure on retry)
 if git rev-parse "v[X.Y]" >/dev/null 2>&1; then echo "Tag v[X.Y] already exists, skipping"; exit 0; fi
 git tag -a v[X.Y] -m "v[X.Y] [Name]
@@ -736,6 +745,7 @@ Ask: "Push tag to remote? (y/n)"
 
 If yes:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 git push origin v[X.Y]
 ```
 
@@ -746,7 +756,7 @@ git push origin v[X.Y]
 Commit the REQUIREMENTS.md deletion (archive files and ROADMAP.md were already committed in the safety commit in `reorganize_roadmap_and_delete_originals`).
 
 ```bash
-git commit -m "chore: remove REQUIREMENTS.md for v[X.Y] milestone"
+git commit -m "chore(planning): remove REQUIREMENTS.md for v[X.Y] milestone"
 ```
 
 Confirm: "Committed: chore: remove REQUIREMENTS.md for v[X.Y] milestone"

package/pp-core/workflows/debug.md

@@ -51,6 +51,7 @@ non-Pareto or `vault.enabled=false` project debugs byte-identically to how it di
 `vault` capability (D-30):
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 DEBUG_PLAN_PRE_HOOKS_JSON=$(pp_run loop render-hooks plan: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' "$DEBUG_PLAN_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('DEBUG_PLAN_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 ```
@@ -68,6 +69,7 @@ It owns the halt: a required miss stops here with the gate's own message, before
 When SUBCMD=list:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls .planning/debug/*.md 2>/dev/null | grep -v resolved
 ```
 

package/pp-core/workflows/diagnose-issues.md

@@ -184,7 +184,7 @@ Update status in frontmatter to "diagnosed".
 
 Commit the updated UAT.md:
 ```bash
-pp_run query commit "docs({phase_num}): add root causes from diagnosis" --files ".planning/phases/XX-name/{phase_num}-UAT.md"
+pp_run query commit "docs(planning): add root causes from diagnosis" --phase "{phase_num}" --files ".planning/phases/XX-name/{phase_num}-UAT.md"
 ```
 </step>