@pareto4/pp-core 1.18.0 → 1.19.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pp-core",
   "displayName": "PP Core",
-  "version": "1.18.0",
+  "version": "1.19.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

@@ -531,6 +531,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
 ```
 
@@ -652,6 +653,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 +783,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

@@ -615,6 +615,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 +677,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 +715,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
@@ -906,7 +909,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-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
 ```
 
@@ -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
 ```
 
@@ -425,6 +429,7 @@ If REQUIREMENTS.md maps additional IDs to this phase that don't appear in ANY pl
 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)
 
@@ -475,6 +480,7 @@ Anti-pattern scanning (Step 7) checks for code smells. Behavioral spot-checks go
 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 +529,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 +544,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
@@ -877,7 +885,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>

package/commands/pp-debug.md

@@ -43,6 +43,7 @@ Parse subcommands and flags from $ARGUMENTS BEFORE the active-session check:
 
 Check for active sessions (used for non-list/status/continue flows):
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
 ```
 </context>

package/commands/pp-init.md

@@ -18,9 +18,10 @@ Universal project entry point. Takes any directory — empty or with existing co
 to: git-initialized, minimal identity captured, remote wired, and handed off to the next
 workflow.
 
-Works for every project regardless of provider. The gated GitLab provisioning path
-(Pareto satellite repos with `.platform-bindings.json`) is added in Plan 02 and slots
-into the structural anchor already present in the workflow.
+Works for every project regardless of provider. On a Pareto project (one with
+`.platform-bindings.json`) whose provider is GitLab or GitHub, it creates the repository
+under the org profile's provisioning group — or adopts it if it already exists — after
+confirming, always private; any other provider gets the generic remote-URL prompt.
 
 **After this command:** You will be asked whether to continue with `/pp-discovery`
 (client/Pareto projects) or `/pp-new-project` (greenfield planning).

package/commands/pp-quick.md

@@ -65,6 +65,7 @@ Context files are resolved inside the workflow (`init quick`) and delegated via
 When SUBCMD=list:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls -d .planning/quick/*/  2>/dev/null
 ```
 
@@ -105,6 +106,7 @@ When SUBCMD=status and SLUG is set (already sanitized):
 
 Find directory matching `*-{SLUG}` pattern:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 dir=$(ls -d .planning/quick/*-{SLUG}/ 2>/dev/null | head -1)
 ```
 
@@ -130,6 +132,7 @@ When SUBCMD=resume and SLUG is set (already sanitized):
 
 1. Find the directory matching `*-{SLUG}` pattern:
    ```bash
+   [ -z "${ZSH_VERSION:-}" ] || emulate -R sh
    dir=$(ls -d .planning/quick/*-{SLUG}/ 2>/dev/null | head -1)
    ```
 2. If no directory found, print `No quick task found with slug: {SLUG}` and stop.

package/commands/pp-review-backlog.md

@@ -18,6 +18,7 @@ milestone sequence or remove stale entries.
 
 1. **List backlog items:**
    ```bash
+   [ -z "${ZSH_VERSION:-}" ] || emulate -R sh
    ls -d .planning/phases/999* 2>/dev/null || echo "No backlog items found"
    ```
 
@@ -48,7 +49,7 @@ milestone sequence or remove stale entries.
 
 6. **Commit changes:**
    ```bash
-   pp_run query commit "docs: review backlog — promoted N, removed M" --files .planning/ROADMAP.md
+   pp_run query commit "docs(planning): review backlog — promoted N, removed M" --files .planning/ROADMAP.md
    ```
 
 7. **Report summary:**

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "pp-core",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "PP Core — a meta-prompting, context engineering, and spec-driven development system for AI coding agents. Loads pp-core's operating context into every Gemini CLI session.",
   "contextFileName": "GEMINI.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pareto4/pp-core",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Pareto pp-core — The Pareto Project's AI-assisted engineering framework: meta-prompting, context engineering, and spec-driven development for AI coding agents.",
   "bin": {
     "pp-core": "bin/install.js",

package/pp-core/bin/lib/capability-registry.cjs

@@ -1967,7 +1967,7 @@ const capabilities = {
       },
       "vault.fallback_repo": {
         "type": "string",
-        "default": "pareto000/Pareto-Vault",
+        "default": "pareto-ooo/pareto-vault-releases",
         "description": "Shared org-wide vault repo used when no client.vaultRepo is configured, or when the client vault is unreachable. Set to '' to disable fallback."
       },
       "vault.fallback_ref": {
@@ -3178,7 +3178,7 @@ const configSchema = {
   "vault.fallback_repo": {
     "owner": "vault",
     "type": "string",
-    "default": "pareto000/Pareto-Vault",
+    "default": "pareto-ooo/pareto-vault-releases",
     "description": "Shared org-wide vault repo used when no client.vaultRepo is configured, or when the client vault is unreachable. Set to '' to disable fallback."
   },
   "vault.fallback_ref": {