@pareto4/pp-core 1.18.0 → 1.20.0

package/pp-core/workflows/init.md

@@ -11,8 +11,8 @@ D-13 (gate on .platform-bindings.json via the Phase 7 reader — Step 2 now comp
 writes this file too, not only reads it, Phase 34 INIT-01).
 
 Provisioning is provider-aware (Phase 34 D-11/D-13): `resolveProvider` is the sole
-authority for which provisioning path runs. The gated GitLab `glab` recipe (G-2…G-5) runs
-only when it resolves to `gitlab`; under any other provider (`azure` today) it is
+authority for which provisioning path runs. The gated create recipe runs only when it
+resolves to `gitlab` (`glab`, G-2…G-5) or `github` (`gh`, H-2…H-5); under any other provider (`azure` today) it is
 **skipped, not failed**, and the run falls through to this same generic remote-wiring
 path so the user still leaves with a wired remote (Phase 34 INIT-03).
 
@@ -31,13 +31,6 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 <process>
 
-## Shim hoist
-
-Resolve `pp_run` before any step — required for the platform-bindings preflight (D-13).
-
-```bash
-```
-
 ## Text mode (resolve before any prompt — WR-02)
 
 Resolve `TEXT_MODE` here, **before Step 0**, because the Step 0 drift prompt is the first
@@ -91,13 +84,13 @@ step is skipped entirely.
 
 ## 1. Worktree-aware git init
 
-Parse the init signals by running the query below. `init.execute-phase` is reused here
-deliberately (IN-02): it is the shared verb that emits the generic git-state signals
-(`has_git`, `in_nested_subdir`, `git_worktree_root`) this step needs — no phase work is
-triggered when called with an empty phase argument.
+Parse the init signals by running the query below. `init.ingest-docs` takes no argument
+and emits the git-state signals this step needs (`has_git`, `in_nested_subdir`,
+`git_worktree_root`) from the same #3491 reader `init.new-project` uses. Never use
+`init.execute-phase ""`: it refuses an empty phase, and the `{}` fallback would disable the guard.
 
 ```bash
-INIT=$(pp_run query init.execute-phase "" 2>/dev/null || echo '{}')
+INIT=$(pp_run query init.ingest-docs 2>/dev/null || echo '{}')
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -177,7 +170,12 @@ its booleans, never in `$?`, and its `error` prose is never echoed (D-07-07). Th
 runs only *after* a clean probe, so a project that cannot reach its vault never ends up
 with a half-populated cache (D-07-05).
 
+The verdict is the client vault's. The platform repo is probed and shown, but a client
+project may have no access to it, so an unreachable platform repo reads `(not required)`
+and does not fail the proof.
+
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # D-07-01 + OD-1 + INIT-01: three signals, all read through the resolvers every other path
 # uses. Anything but the literal "true" is a fail-inert default.
 PP_INIT_PROBE=""
@@ -219,26 +217,25 @@ if [ "$VAULT_ON" = "true" ] && [ "$PROFILE_RESOLVED" = "true" ]; then
     PROBE=$(pp_run query vault probe --raw 2>/dev/null || echo '{"targets":[]}')
     # R3-CR-02 + R3-WR-02: ONE evaluation of the target set, read by every arm
     # below. FOUR hand-copied de-dup pipelines stood here and had already
-    # diverged; the one that mattered inverted the proof. 07-18 excluded the
-    # fallback tier AFTER the de-dup, and targets arrive in the fixed order
-    # client, shared, platform — so a platform sharing a coordinate with the
-    # fallback survived under the FALLBACK'S NAME, the exclusion deleted the
-    # only representative of a REQUIRED tier, and Step 2.6 printed and durably
-    # recorded a platform reachable line for a target measured unreachable. The
-    # exclusion now runs BEFORE the de-dup; the DISPLAY de-dup keeps the REQUIRED
-    # tier's identity when two tiers name one coordinate (a fallback identical to
-    # the client is still one remote, not two). OD-5 Option A unchanged: the
-    # fallback tier stays out of the verdict and out of the note's sick list and
-    # keeps its "(fallback tier, not required)" line when its coordinate is its
-    # own. The all-down flag counts EVERY distinct remote, fallback included, ON
-    # PURPOSE: it drives the offline candidate below, and a fallback that answered
-    # is evidence the network is up. CR-02: a REQUIRED target with no coordinate
-    # gets its own "missing" line — without it the D-07-02 case printed a card
-    # whose every line read healthy under a fail verdict; measured, not a
-    # diagnosis (D-07-07). EMITS: line 1 verdict, 2 all-down, 3 note, 4+ card; a
-    # card line can never carry a newline of its own (redactCloneTarget collapses
-    # the control class at the source, R2-WR-03), so the split below is safe.
-    PROBE_EVAL=$(printf '%s' "$PROBE" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const t=(JSON.parse(d).targets||[]).filter(x=>x&&x.configured===true);const key=x=>[x.repo,x.ref,x.host].join('|');const names=new Set(t.map(x=>x.name));const seen=new Set();const req=t.filter(x=>x.name!=='shared'&&!seen.has(key(x))&&seen.add(key(x)));const pick=new Map();for(const x of t){const k=key(x);const p=pick.get(k);if(!p||(p.name==='shared'&&x.name!=='shared'))pick.set(k,x);}const shown=t.filter(x=>pick.get(key(x))===x);const cfg={client:'client.vaultRepo',platform:'platform.repo'};const gone=Object.keys(cfg).filter(n=>!names.has(n));const ok=names.has('client')&&names.has('platform')&&req.length>0&&req.every(x=>x.reachable===true&&x.refFound===true);const sick=req.filter(x=>!(x.reachable===true&&x.refFound===true)).map(x=>String(x.name)+' '+String(x.repoSafe)+' @ '+String(x.ref)+' '+(x.reachable===true?'ref not found':'unreachable'));const all=gone.map(n=>n+' not configured').concat(sick);const lines=shown.map(x=>'  '+String(x.name).padEnd(9)+String(x.repoSafe)+' @ '+((x.name==='platform'&&x.ref==='HEAD')?'(unpinned)':String(x.ref))+'  '+(x.reachable===true?(x.refFound===true?'reachable, ref found':'ref not found'):'unreachable')+(x.name==='shared'?'  (fallback tier, not required)':'')).concat(gone.map(n=>'  '+n.padEnd(9)+'(not configured)  missing — '+cfg[n]+' is absent from .platform-bindings.json'));process.stdout.write([ok?'pass':'fail',String(shown.length>0&&shown.every(x=>x.reachable!==true)),'failed='+(all.length?all.join('; '):'probe payload unreadable')].concat(lines).join('\n'));}catch{process.stdout.write('fail\nfalse\nfailed=probe payload unreadable');}")
+    # diverged, so every arm reads this one line. Only the CLIENT vault decides
+    # the verdict: it is what the fetch below lands. The platform repo is shown
+    # and recorded but not required (a client project may have no access to
+    # it), so an unreachable platform line carries "(not required)", like the
+    # fallback tier (OD-5 Option A: shared is probed and shown, out of the
+    # verdict and out of the note's sick list). A binding with no platform.repo
+    # at all still fails as "not configured". The DISPLAY de-dup keeps a
+    # non-shared tier's identity when two tiers name one coordinate, so a
+    # platform colliding with the fallback is still shown as platform. The
+    # all-down flag counts EVERY distinct remote, fallback included, ON
+    # PURPOSE: it drives the offline candidate below, and a remote that
+    # answered is evidence the network is up. CR-02: a target with no
+    # coordinate gets its own "missing" line — without it the D-07-02 case
+    # printed a card whose every line read healthy under a fail verdict;
+    # measured, not a diagnosis (D-07-07). EMITS: line 1 verdict, 2 all-down,
+    # 3 note, 4+ card; a card line can never carry a newline of its own
+    # (redactCloneTarget collapses the control class at the source, R2-WR-03),
+    # so the split below is safe.
+    PROBE_EVAL=$(printf '%s' "$PROBE" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const t=(JSON.parse(d).targets||[]).filter(x=>x&&x.configured===true);const key=x=>[x.repo,x.ref,x.host].join('|');const names=new Set(t.map(x=>x.name));const healthy=x=>x.reachable===true&&x.refFound===true;const req=t.filter(x=>x.name==='client');const pick=new Map();for(const x of t){const k=key(x);const p=pick.get(k);if(!p||(p.name==='shared'&&x.name!=='shared'))pick.set(k,x);}const shown=t.filter(x=>pick.get(key(x))===x);const cfg={client:'client.vaultRepo',platform:'platform.repo'};const gone=Object.keys(cfg).filter(n=>!names.has(n));const ok=names.has('client')&&names.has('platform')&&req.length>0&&req.every(healthy);const sick=req.filter(x=>!healthy(x)).map(x=>String(x.name)+' '+String(x.repoSafe)+' @ '+String(x.ref)+' '+(x.reachable===true?'ref not found':'unreachable'));const all=gone.map(n=>n+' not configured').concat(sick);const lines=shown.map(x=>'  '+String(x.name).padEnd(9)+String(x.repoSafe)+' @ '+((x.name==='platform'&&x.ref==='HEAD')?'(unpinned)':String(x.ref))+'  '+(x.reachable===true?(x.refFound===true?'reachable, ref found':'ref not found'):'unreachable')+(x.name==='shared'?'  (fallback tier, not required)':(x.name==='platform'&&!healthy(x)?'  (not required)':''))).concat(gone.map(n=>'  '+n.padEnd(9)+'(not configured)  missing — '+cfg[n]+' is absent from .platform-bindings.json'));process.stdout.write([ok?'pass':'fail',String(shown.length>0&&shown.every(x=>x.reachable!==true)),'failed='+(all.length?all.join('; '):'probe payload unreadable')].concat(lines).join('\n'));}catch{process.stdout.write('fail\nfalse\nfailed=probe payload unreadable');}")
     PROBE_VERDICT=$(printf '%s' "$PROBE_EVAL" | sed -n '1p')
     PROBE_ALL_DOWN=$(printf '%s' "$PROBE_EVAL" | sed -n '2p')
     PROBE_NOTE=$(printf '%s' "$PROBE_EVAL" | sed -n '3p')
@@ -257,6 +254,9 @@ if [ "$VAULT_ON" = "true" ] && [ "$PROFILE_RESOLVED" = "true" ]; then
       FETCH_COUNT=$(printf '%s' "$FETCH" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(String((JSON.parse(d).files||[]).length));}catch{process.stdout.write('0');}")
       FETCH_SUMMARY=$(printf '%s' "$FETCH" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(String(JSON.parse(d).summaryWritten===true));}catch{process.stdout.write('false');}")
       PLATFORM_REPO=$(printf '%s' "$PROBE" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const x=(JSON.parse(d).targets||[]).find(y=>y&&y.name==='platform');process.stdout.write(String((x&&x.repoSafe)||''));}catch{process.stdout.write('');}")
+      # The platform repo is not required (a client may have no access to it): its measured
+      # state goes on the card and into the record, it never decides the verdict.
+      PLATFORM_STATE=$(printf '%s' "$PROBE" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const x=(JSON.parse(d).targets||[]).find(y=>y&&y.name==='platform');process.stdout.write(x&&x.reachable===true?(x.refFound===true?'reachable':'ref not found (not required)'):'unreachable (not required)');}catch{process.stdout.write('unreachable (not required)');}")
       # Never the probe's internal HEAD placeholder — an unpinned platform says so.
       PLATFORM_TAG=$(pp_run query platform-bindings --pick platform.tag 2>/dev/null)
       if [ "$FETCH_TIER" = "client" ] && [ "$FETCH_SUMMARY" = "true" ] && { [ "$FETCH_SOURCE" = "fetched" ] || [ "$FETCH_SOURCE" = "cache" ]; }; then
@@ -264,13 +264,13 @@ if [ "$VAULT_ON" = "true" ] && [ "$PROFILE_RESOLVED" = "true" ]; then
         # card prints. A refused write used to be a warning under a PASSED card, and PASSED
         # routes to "continue to Step 3" — so "unrecorded" was defined to continue. It is a
         # failure of the step, kind FAIL_KIND=record. Markers unchanged: pass/unbound/fail.
-        if pp_run query init-contract --record-probe "passed=platform ${PLATFORM_REPO} @ ${PLATFORM_TAG:-(unpinned)}; vault ${FETCH_REPO} @ ${FETCH_REF} tier ${FETCH_TIER} ${FETCH_COUNT} files" >/dev/null 2>&1; then
+        if pp_run query init-contract --record-probe "passed=platform ${PLATFORM_REPO} @ ${PLATFORM_TAG:-(unpinned)} ${PLATFORM_STATE}; vault ${FETCH_REPO} @ ${FETCH_REF} tier ${FETCH_TIER} ${FETCH_COUNT} files" >/dev/null 2>&1; then
           PP_INIT_PROBE=pass
           echo "Reachability proof: PASSED"
           # OD-3 + CR-01: the DISPLAY-SAFE coordinate (repoSafe), ref, tier and booleans
           # only. Credentials are stripped at the source, so a PAT in the binding reaches
           # neither this card nor the record. Never url, never error.
-          printf '%s\n' "  platform  ${PLATFORM_REPO} @ ${PLATFORM_TAG:-(unpinned)}  reachable"
+          printf '%s\n' "  platform  ${PLATFORM_REPO} @ ${PLATFORM_TAG:-(unpinned)}  ${PLATFORM_STATE}"
           printf '%s\n' "  vault     ${FETCH_REPO} @ ${FETCH_REF}  reachable, ref found — tier ${FETCH_TIER}, sha ${FETCH_SHA}, ${FETCH_COUNT} files, SUMMARY.md written (${FETCH_SOURCE})"
           printf '%s\n' "$PROBE_LINES" | grep '^  shared ' || true
           echo "PP_INIT_PROBE=pass"
@@ -353,7 +353,7 @@ outright. Take THIS generic sub-path when
 bindings ARE present, take the gated GitLab/Azure sub-path below instead — that section is
 still part of Step 3, not a separate optional step. **The provider answer never decides
 whether Step 3 runs** — inside the gated sub-path it only decides whether the
-GitLab-specific `glab` recipe fires or falls through to this same generic code below.
+`glab` or `gh` create recipe fires or falls through to this same generic code below.
 
 On the generic path:
 
@@ -393,14 +393,14 @@ gets its own per-action confirmation immediately before it fires — nothing bat
 step makes **ZERO `gh`/`glab`/provider-API calls**. The push target is the user-supplied
 URL only.
 
-### Gated GitLab/Azure provisioning (Step 3's other sub-path — bindings present)
+### Gated GitLab/GitHub provisioning (Step 3's other sub-path — bindings present)
 
 This is Step 3's other sub-path, not a separate step. It runs **instead of** the generic
 remote-wiring path above when
 `pp_run query platform-bindings --pick present 2>/dev/null` equals `"true"`. Within it,
-G-1 always runs first to source coordinates and apply the two guards below; the
-GitLab-specific create recipe (G-2…G-5) runs **only when the resolved provider is
-`gitlab`** — under any other provider (`azure` today) it is skipped, not failed, and the
+G-1 always runs first to source coordinates and apply the two guards below; a create
+recipe runs **only when the resolved provider is `gitlab` or `github`** — under any
+other provider (`azure` today) it is skipped, not failed, and the
 run falls through to Step 3's generic remote-wiring path above instead (D-11, D-13).
 Implements D-05 (per-action confirmation), D-09 (existence probe → adopt-if-exists), D-10
 (private by default), D-11 (auth verify-only; gated on provider), D-12 (adopt-if-exists
@@ -442,8 +442,9 @@ comes from, skip G-2 through G-5 entirely, and fall through to Step 3's generic
 wiring:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ -z "$GROUP" ] || [ -z "$SLUG" ]; then
-  echo "Skipping GitLab provisioning: $( [ -z "$GROUP" ] && echo "GROUP (org profile seed provisioning group)" || echo "SLUG (project.slug)" ) is empty — falling through to Step 3's generic remote wiring."
+  echo "Skipping repository provisioning: $( [ -z "$GROUP" ] && echo "GROUP (org profile seed provisioning group)" || echo "SLUG (project.slug)" ) is empty — falling through to Step 3's generic remote wiring."
 fi
 ```
 
@@ -452,35 +453,24 @@ fi
 
 ```bash
 PROVIDER=$(pp_run query compose-bindings --offline --pick provider 2>/dev/null)
-if [ "$PROVIDER" != "gitlab" ]; then
-  echo "Skipping GitLab-specific provisioning for provider \"$PROVIDER\" — falling through to Step 3's generic remote wiring instead."
+if [ "$PROVIDER" != "gitlab" ] && [ "$PROVIDER" != "github" ]; then
+  echo "Skipping repository provisioning for provider \"$PROVIDER\" — falling through to Step 3's generic remote wiring instead."
 fi
 ```
 
-Continue to G-2 only when the empty-group guard above did not skip **and** `PROVIDER`
-equals `gitlab`. Otherwise stop here and go to Step 3's generic remote wiring (`:283-312`)
+Continue only when the empty-group guard above did not skip **and** `PROVIDER`
+is `gitlab` or `github`. Otherwise stop here and go to Step 3's generic remote wiring (`:283-312`)
 instead — do not fail, do not error, do not prompt for a missing CLI. "Skipped, not
 failed" is satisfied *and* the user still leaves with a wired remote, which a bare skip
 would not give them; pp-core makes zero provider-API calls it has no client for.
 
-When both conditions hold, **Read `pp-core/workflows/init/steps/gitlab-provisioning.md` and
-follow it.** That file owns G-2 (auth verify-only), G-3 (existence probe →
-adopt-if-exists), G-4 (per-action confirmation, then the locked `--private` create) and G-5
-(post-create reconciliation). Under any other provider do not read it at all — fall through
-to Step 3's generic remote wiring above.
-
-**Security invariants — landmine guards:**
-- Always use the group-qualified `$GROUP/$SLUG` path — never a bare slug (T-08-04, D-09).
-  A bare slug creates under the user's personal namespace, not the client group. G-1's
-  empty-group guard above is what actually enforces this before any create attempt.
-- Always pass `--private` explicitly — never inherit `glab`'s default `--internal`
-  visibility (T-08-05, D-10). The `--internal` flag is what makes this dangerous; the
-  locked recipe must carry `--private` and must NOT emit `--internal`.
-- Always confirm immediately before each outward action — nothing batched (T-08-06, D-05).
-- Verify-only auth via `glab auth status` — never run `glab auth login`, never read
-  or write the user's token (T-08-08, D-11). Bindings hold only non-secret routing data.
-- Always reconcile create with a `glab repo view` probe — a non-zero create exit does
-  NOT mean nothing happened (T-08-09, D-09).
+When both conditions hold, **Read `pp-core/workflows/init/steps/gitlab-provisioning.md`
+(provider `gitlab`) or `pp-core/workflows/init/steps/github-provisioning.md` (provider
+`github`) and follow it.** Each owns, for its
+CLI, auth verify-only, the existence probe → adopt-if-exists, per-action confirmation then
+the locked `--private` create, post-create reconciliation, and its security invariants
+(landmine guards: group-qualified path, explicit `--private`, verify-only auth). Under any
+other provider read neither — fall through to Step 3's generic remote wiring above.
 
 ### Gated client-context capture (Pareto projects — bindings present)
 
@@ -555,9 +545,9 @@ legitimately not exist — the session declines or composes nothing on the inert
 
 ```bash
 if [ -f .platform-bindings.json ]; then
-  pp_run query commit "docs: initialize project" --files .planning/config.json .platform-bindings.json
+  pp_run query commit "docs(planning): initialize project" --files .planning/config.json .platform-bindings.json
 else
-  pp_run query commit "docs: initialize project" --files .planning/config.json
+  pp_run query commit "docs(planning): initialize project" --files .planning/config.json
 fi
 ```
 

package/pp-core/workflows/map-codebase.md

@@ -327,6 +327,7 @@ Continue to verify_output.
 Verify all documents created successfully:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls -la .planning/codebase/
 wc -l .planning/codebase/*.md
 ```
@@ -346,6 +347,7 @@ Continue to scan_for_secrets.
 Run secret pattern detection:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Check for common API key patterns in generated docs
 grep -E '(sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]+|sk_test_[a-zA-Z0-9]+|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9_-]+|AKIA[A-Z0-9]{16}|xox[baprs]-[a-zA-Z0-9-]+|-----BEGIN.*PRIVATE KEY|eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.)' .planning/codebase/*.md 2>/dev/null && SECRETS_FOUND=true || SECRETS_FOUND=false
 ```
@@ -379,7 +381,8 @@ Continue to commit_codebase_map.
 Commit the codebase map:
 
 ```bash
-pp_run query commit "docs: map existing codebase" --files .planning/codebase/*.md
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
+pp_run query commit "docs(planning): map existing codebase" --files .planning/codebase/*.md
 ```
 
 Continue to offer_next.
@@ -390,6 +393,7 @@ Present completion summary and next steps.
 
 **Get line counts:**
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 wc -l .planning/codebase/*.md
 ```
 

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

@@ -78,6 +78,7 @@ git tag -l "v${VERSION}" | head -1
 ```
 If the tag exists:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 git log v${VERSION} --oneline | wc -l
 git diff --stat $(git log --format=%H --reverse v${VERSION} | head -1)..v${VERSION}
 ```
@@ -190,7 +191,7 @@ mkdir -p .planning/reports
 
 Write the summary, then commit:
 ```bash
-pp_run query commit "docs(v${VERSION}): generate milestone summary for onboarding" --files \
+pp_run query commit "docs(planning): generate v${VERSION} milestone summary for onboarding" --files \
   ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md"
 ```
 

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

@@ -99,6 +99,7 @@ If any of the three answers is empty or whitespace-only, error and re-prompt tha
 **Validate via the centralized User Story validator.** The verb owns the canonical regex `/^As a .+, I want to .+, so that .+\.$/` and surfaces per-error guidance:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 USER_STORY_RESULT=$(pp_run query user-story.validate --story "$USER_STORY")
 if [ "$(echo "$USER_STORY_RESULT" | jq -r '.valid')" != "true" ]; then
   echo "$USER_STORY_RESULT" | jq -r '.errors[]' >&2

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

@@ -55,6 +55,7 @@ If the flag is absent, keep the current behavior of continuing phase numbering f
 Check `.planning/seeds/` for seed files that match the milestone goals gathered in step 2.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls .planning/seeds/SEED-*.md 2>/dev/null
 ```
 
@@ -217,7 +218,7 @@ pp_run query phases.clear --confirm
 ```
 
 ```bash
-pp_run query commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
+pp_run query commit "docs(planning): start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
 ```
 
 ## 7. Load Context and Resolve Models
@@ -256,6 +257,7 @@ If `--reset-phase-numbers` is active:
 If `phase_dir_count > 0`, let the engine archive what the closed milestones name — never move phase directories by hand:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ARCHIVED=$(pp_run query phases.archive-closed ${GSD_WS})
 ```
 
@@ -368,7 +370,7 @@ Commit after writing.
 **Synthesizer output self-heal (#222) — verify SUMMARY.md materialized:** The synthesizer's canonical output is `.planning/research/SUMMARY.md` on disk; its brief structured return (`## SYNTHESIS COMPLETE` plus a few `###` confirmation lines) is NOT the file content. A known LLM false-refusal (issue #222) sometimes makes the agent return the full SUMMARY.md document inline — fabricating a write restriction (e.g. "the runtime is blocking file writes") — instead of writing the file. Prompt hardening alone does not fully eliminate it, so the orchestrator MUST absorb the failure deterministically before spawning `pp-roadmapper`:
 
 1. Verify `.planning/research/SUMMARY.md` exists AND is substantive — non-empty, and free of any leftover `<!-- gsd:write-continue -->` continuation sentinel (which marks a truncated/incomplete write). You may validate with `pp-tools verify-summary .planning/research/SUMMARY.md` — it exits 0 regardless, so check its JSON `passed` field (`"passed": false` means missing or invalid), not the process exit code. If it passes, continue normally.
-2. If it is MISSING or invalid AND the synthesizer's return message contains the FULL SUMMARY.md document — recognizable by the template's top-level markers `# Project Research Summary`, `## Key Findings`, `## Implications for Roadmap`, and `## Sources`, not merely the brief `## SYNTHESIS COMPLETE` confirmation — the false-refusal fired: write that returned document to `.planning/research/SUMMARY.md` with the Write tool, then commit ALL research artifacts the synthesizer owns (it commits on behalf of the four researchers) with `pp-tools query commit "docs: complete project research" --files .planning/research/` unless they are already committed. Log `⚠ #222 self-heal: synthesizer returned SUMMARY.md inline without writing it; orchestrator persisted the file.`
+2. If it is MISSING or invalid AND the synthesizer's return message contains the FULL SUMMARY.md document — recognizable by the template's top-level markers `# Project Research Summary`, `## Key Findings`, `## Implications for Roadmap`, and `## Sources`, not merely the brief `## SYNTHESIS COMPLETE` confirmation — the false-refusal fired: write that returned document to `.planning/research/SUMMARY.md` with the Write tool, then commit ALL research artifacts the synthesizer owns (it commits on behalf of the four researchers) with `pp_run query commit "docs(planning): complete project research" --files .planning/research/` unless they are already committed. Log `⚠ #222 self-heal: synthesizer returned SUMMARY.md inline without writing it; orchestrator persisted the file.`
 3. If it is MISSING or invalid AND the return is only a brief confirmation (no full SUMMARY document to recover), the synthesizer genuinely failed — surface the error and stop; do NOT spawn `pp-roadmapper` against a missing or incomplete SUMMARY.md.
 
 This guarantees `pp-roadmapper` (which lists SUMMARY.md as required reading) never runs against a missing or truncated SUMMARY.md.
@@ -456,7 +458,7 @@ If "adjust": Return to scoping.
 
 **Commit requirements:**
 ```bash
-pp_run query commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
+pp_run query commit "docs(planning): define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
 ```
 
 ## 10. Create Roadmap
@@ -542,7 +544,7 @@ Success criteria:
 
 **Commit roadmap** (after approval):
 ```bash
-pp_run query commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+pp_run query commit "docs(planning): create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
 ```
 
 ## 10.5. Link Pending Todos to Roadmap Phases
@@ -551,6 +553,7 @@ After roadmap approval, scan pending todos against the newly approved phases. Fo
 
 **Check for pending todos:**
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 PENDING_TODOS=$(ls .planning/todos/pending/*.md 2>/dev/null | head -50)
 ```
 
@@ -585,7 +588,8 @@ files: [existing]
 
 **If any todos were linked:**
 ```bash
-pp_run query commit "docs: tag [count] pending todos with resolves_phase after milestone v[X.Y] roadmap" --files .planning/todos/pending/*.md
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
+pp_run query commit "docs(planning): tag [count] pending todos with resolves_phase after milestone v[X.Y] roadmap" --files .planning/todos/pending/*.md
 ```
 
 Print a summary:

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

@@ -323,7 +323,7 @@ pp_run query config-new-project '{"mode":"yolo","granularity":"[selected]","para
 
 ```bash
 mkdir -p .planning
-pp_run query commit "chore: add project config" --files .planning/config.json
+pp_run query commit "chore(planning): add project config" --files .planning/config.json
 ```
 
 **Persist auto-advance chain flag to config (survives context compaction):**
@@ -339,6 +339,7 @@ Proceed to Step 4 (skip Steps 3 and 5).
 Check for existing spike and sketch work that should inform project setup:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Check for spike findings skill (project-local)
 SPIKE_SKILL=$(ls ./.claude/skills/spike-findings-*/SKILL.md 2>/dev/null | head -1 || true)
 
@@ -500,9 +501,9 @@ Initialize with any decisions made during questioning:
 ```markdown
 ## Key Decisions
 
-| Decision | Rationale | Outcome |
-|----------|-----------|---------|
-| [Choice from questioning] | [Why] | — Pending |
+| ID | Decision | Rationale | Outcome |
+|----|----------|-----------|---------|
+| — | [Choice from questioning] | [Why] | — Pending |
 ```
 
 **Last updated footer:**
@@ -539,7 +540,7 @@ Do not compress. Capture everything gathered.
 
 ```bash
 mkdir -p .planning
-pp_run query commit "docs: initialize project" --files .planning/PROJECT.md
+pp_run query commit "docs(planning): initialize project" --files .planning/PROJECT.md
 ```
 
 ## 5. Workflow Preferences
@@ -836,7 +837,7 @@ pp_run query config-new-project '{"mode":"[yolo|interactive]","granularity":"[se
 **Commit config.json:**
 
 ```bash
-pp_run query commit "chore: add project config" --files .planning/config.json
+pp_run query commit "chore(planning): add project config" --files .planning/config.json
 ```
 
 ## 5.1. Sub-Repo Detection
@@ -884,9 +885,9 @@ echo "$ARM"
 ARMED=$(printf '%s' "$ARM" | node -e 'let s="";process.stdin.on("data",d=>{s+=d}).on("end",()=>{try{process.stdout.write(String(JSON.parse(s).armed===true))}catch{process.stdout.write("false")}})')
 if [ "$ARM_EXIT" -eq 0 ] && [ "$ARMED" = "true" ]; then
   if [ -f .platform-bindings.json ]; then
-    pp_run query commit "chore: arm client vault from org profile" --files .planning/config.json .platform-bindings.json
+    pp_run query commit "chore(planning): arm client vault from org profile" --files .planning/config.json .platform-bindings.json
   else
-    pp_run query commit "chore: arm client vault from org profile" --files .planning/config.json
+    pp_run query commit "chore(planning): arm client vault from org profile" --files .planning/config.json
   fi
 fi
 ```
@@ -1138,7 +1139,7 @@ Commit after writing.
 **Synthesizer output self-heal (#222) — verify SUMMARY.md materialized:** The synthesizer's canonical output is `.planning/research/SUMMARY.md` on disk; its brief structured return (`## SYNTHESIS COMPLETE` plus a few `###` confirmation lines) is NOT the file content. A known LLM false-refusal (issue #222) sometimes makes the agent return the full SUMMARY.md document inline — fabricating a write restriction (e.g. "the runtime is blocking file writes") — instead of writing the file. Prompt hardening alone does not fully eliminate it, so the orchestrator MUST absorb the failure deterministically before spawning `pp-roadmapper`:
 
 1. Verify `.planning/research/SUMMARY.md` exists AND is substantive — non-empty, and free of any leftover `<!-- gsd:write-continue -->` continuation sentinel (which marks a truncated/incomplete write). You may validate with `pp-tools verify-summary .planning/research/SUMMARY.md` — it exits 0 regardless, so check its JSON `passed` field (`"passed": false` means missing or invalid), not the process exit code. If it passes, continue normally.
-2. If it is MISSING or invalid AND the synthesizer's return message contains the FULL SUMMARY.md document — recognizable by the template's top-level markers `# Project Research Summary`, `## Key Findings`, `## Implications for Roadmap`, and `## Sources`, not merely the brief `## SYNTHESIS COMPLETE` confirmation — the false-refusal fired: write that returned document to `.planning/research/SUMMARY.md` with the Write tool, then commit ALL research artifacts the synthesizer owns (it commits on behalf of the four researchers) with `pp-tools query commit "docs: complete project research" --files .planning/research/` unless they are already committed. Log `⚠ #222 self-heal: synthesizer returned SUMMARY.md inline without writing it; orchestrator persisted the file.`
+2. If it is MISSING or invalid AND the synthesizer's return message contains the FULL SUMMARY.md document — recognizable by the template's top-level markers `# Project Research Summary`, `## Key Findings`, `## Implications for Roadmap`, and `## Sources`, not merely the brief `## SYNTHESIS COMPLETE` confirmation — the false-refusal fired: write that returned document to `.planning/research/SUMMARY.md` with the Write tool, then commit ALL research artifacts the synthesizer owns (it commits on behalf of the four researchers) with `pp_run query commit "docs(planning): complete project research" --files .planning/research/` unless they are already committed. Log `⚠ #222 self-heal: synthesizer returned SUMMARY.md inline without writing it; orchestrator persisted the file.`
 3. If it is MISSING or invalid AND the return is only a brief confirmation (no full SUMMARY document to recover), the synthesizer genuinely failed — surface the error and stop; do NOT spawn `pp-roadmapper` against a missing or incomplete SUMMARY.md.
 
 This guarantees `pp-roadmapper` (which lists SUMMARY.md as required reading) never runs against a missing or truncated SUMMARY.md.
@@ -1312,7 +1313,7 @@ If "adjust": Return to scoping.
 **Commit requirements:**
 
 ```bash
-pp_run query commit "docs: define v1 requirements" --files .planning/REQUIREMENTS.md
+pp_run query commit "docs(planning): define v1 requirements" --files .planning/REQUIREMENTS.md
 ```
 
 ## 7.5. Project Structure Mode
@@ -1496,7 +1497,7 @@ This ensures new projects get the default pp-core workflow-enforcement guidance
 **Commit roadmap (after approval or auto mode):**
 
 ```bash
-pp_run query commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md "$INSTRUCTION_FILE"
+pp_run query commit "docs(planning): create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md "$INSTRUCTION_FILE"
 ```
 
 ## 9. Done

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

@@ -110,6 +110,7 @@ Before creating anything, validate:
 
 1. **Target path** — must not exist or must be empty:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ -d "$TARGET_PATH" ] && [ "$(ls -A "$TARGET_PATH" 2>/dev/null)" ]; then
   echo "Error: Target path already exists and is not empty: $TARGET_PATH"
   echo "Choose a different --name or --path."

package/pp-core/workflows/next.md

@@ -187,7 +187,7 @@ Choice [S]:
 ```
 2. Commit the deferral record:
 ```bash
-pp_run query commit "docs: defer incomplete Phase {src} items to backlog"
+pp_run query commit "docs(planning): defer incomplete Phase {src} items to backlog"
 ```
 3. Continue routing to `determine_next_action` immediately — no second prompt.
 
@@ -198,6 +198,7 @@ pp_run query commit "docs: defer incomplete Phase {src} items to backlog"
 Check for pending spike/sketch work and surface a notice (does not change routing):
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Check for pending spikes (verdict: PENDING in any README)
 PENDING_SPIKES=$(grep -rl 'verdict: PENDING' .planning/spikes/*/README.md 2>/dev/null | wc -l | tr -d ' ')
 

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

@@ -14,14 +14,15 @@ Read all files referenced by the invoking prompt's execution_context before star
 Determine what kind of work is being paused and set the handoff destination accordingly:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Check for active phase
-phase=$(( ls -lt .planning/phases/*/PLAN.md 2>/dev/null || true ) | head -1 | grep -oP 'phases/\K[^/]+' || true)
+phase=$(( ls -lt .planning/phases/*/PLAN.md 2>/dev/null || true ) | head -1 | sed -n 's|.*phases/\([^/]*\)/.*|\1|p')
 
 # Check for active spike
-spike=$(( ls -lt .planning/spikes/*/SPIKE.md .planning/spikes/*/DESIGN.md .planning/spikes/*/README.md 2>/dev/null || true ) | head -1 | grep -oP 'spikes/\K[^/]+' || true)
+spike=$(( ls -lt .planning/spikes/*/SPIKE.md .planning/spikes/*/DESIGN.md .planning/spikes/*/README.md 2>/dev/null || true ) | head -1 | sed -n 's|.*spikes/\([^/]*\)/.*|\1|p')
 
 # Check for active sketch
-sketch=$(( ls -lt .planning/sketches/*/README.md .planning/sketches/*/index.html 2>/dev/null || true ) | head -1 | grep -oP 'sketches/\K[^/]+' || true)
+sketch=$(( ls -lt .planning/sketches/*/README.md .planning/sketches/*/index.html 2>/dev/null || true ) | head -1 | sed -n 's|.*sketches/\([^/]*\)/.*|\1|p')
 
 # Check for active deliberation
 deliberation=$(ls .planning/deliberations/*.md 2>/dev/null | head -1 || true)
@@ -57,6 +58,7 @@ Ask user for clarifications if needed via conversational questions.
 
 **Also inspect SUMMARY.md files for false completions:**
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Check for placeholder content in existing summaries
 grep -l "To be filled\|placeholder\|TBD" .planning/phases/*/*.md 2>/dev/null || true
 ```
@@ -214,7 +216,7 @@ timestamp=$(pp_run query current-timestamp full --raw)
 
 <step name="commit">
 ```bash
-pp_run query commit "wip: [context-name] paused at [X]/[Y]" --files [handoff-path] .planning/HANDOFF.json
+pp_run query commit "docs(planning): pause [context-name] at [X]/[Y]" --files [handoff-path] .planning/HANDOFF.json
 ```
 </step>
 

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

@@ -11,6 +11,7 @@ Read all files referenced by the invoking prompt's execution_context before star
 ## 1. Load Audit Results
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Find the most recent audit file
 (ls -t .planning/v*-MILESTONE-AUDIT.md 2>/dev/null || true) | head -1
 ```
@@ -65,6 +66,7 @@ Gap: Flow "View dashboard" broken at data fetch
 Find highest existing phase:
 ```bash
 _PP_SHIM_NAME="pp-tools.cjs"; _pp_root() { ( for _v in $(env | sed -n 's/^\(GIT_[A-Za-z0-9_]*\)=.*/\1/p'); do unset "$_v"; done; _c=$(git rev-parse --git-common-dir 2>/dev/null); if [ "${_c##*/}" = .git ] && cd "$_c/.." 2>/dev/null; then pwd -P; else git rev-parse --show-toplevel 2>/dev/null || pwd; fi ); }; pp_run() { case "$PP_TOOLS" in *.cjs) node "$PP_TOOLS" "$@";; *) "$PP_TOOLS" "$@";; esac; }; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(_pp_root)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then :; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Get sorted phase list, extract last one
 HIGHEST=$(pp_run query phases.list --pick directories[-1])
 ```
@@ -154,7 +156,7 @@ Repeat for each gap-closure phase number. This produces `{CODE}-{NN}-{slug}/` wh
 ## 9. Commit Roadmap and Requirements Update
 
 ```bash
-pp_run query commit "docs(roadmap): add gap closure phases {N}-{M}" --files .planning/ROADMAP.md .planning/REQUIREMENTS.md
+pp_run query commit "docs(planning): add gap closure phases {N}-{M}" --files .planning/ROADMAP.md .planning/REQUIREMENTS.md
 ```
 
 ## 10. Offer Next Steps

package/pp-core/workflows/plan-phase/steps/chunked-planning.md

@@ -104,7 +104,7 @@ For each plan entry extracted from `PLAN-OUTLINE.md`:
 5. **Commit per-plan:**
    ```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(${PADDED_PHASE}): plan ${plan_id} (chunked)" --files "${PHASE_DIR}/${plan_id}-PLAN.md"
+   pp_run query commit "docs(planning): plan ${plan_id} (chunked)" --phase "${PADDED_PHASE}" --files "${PHASE_DIR}/${plan_id}-PLAN.md"
    ```
 
 After all N plans are written and committed, treat this as `## PLANNING COMPLETE` and continue