@pareto4/pp-core 1.18.0 → 1.20.0

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

@@ -179,6 +179,7 @@ fi
 
 Resolve `MVP_MODE` once via the centralized `phase.mvp-mode` query verb (precedence chain: CLI flag → ROADMAP `**Mode:** mvp` → `workflow.mvp_mode` config → false):
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 MVP_FLAG_ARG=""
 if [[ "$ARGUMENTS" =~ (^|[[:space:]])--mvp([[:space:]]|$) ]]; then MVP_FLAG_ARG="--cli-flag"; fi
 MVP_MODE=$(pp_run query phase.mvp-mode "${PHASE_NUMBER}" $MVP_FLAG_ARG --pick active)
@@ -218,7 +219,10 @@ Offer these recovery options:
 if [ "$MVP_MODE" = "true" ] && [ "$TDD_MODE" = "true" ]; then
   IS_BEHAVIOR_ADDING=$(pp_run query task.is-behavior-adding "$TASK_FILE" --pick is_behavior_adding)
   if [ "$IS_BEHAVIOR_ADDING" = "true" ]; then
-    RED_COMMIT=$(git log --oneline --grep="^test(${PHASE_NUMBER}-${PLAN_ID}):" -- "**/*.test.*" "**/*.spec.*" "tests/" | head -1)
+    # A `test` commit (any scope) whose `Phase:` trailer is this plan; a `test(<plan>):`
+    # subject from before the trailer convention still counts.
+    RED_COMMIT=$(git log --format='%h%x09%s%x09%(trailers:key=Phase,valueonly,separator=%x2C)' -- "**/*.test.*" "**/*.spec.*" "tests/" \
+      | awk -F'\t' -v id="${PHASE_NUMBER}-${PLAN_ID}" '$2 ~ /^test(\([^)]*\))?!?:/ && ($3 == id || index($2, "(" id "):") > 0) { print; exit }')
     if [ -z "$RED_COMMIT" ]; then
       pp_run query state.update last_gate_trip "${PLAN_ID}/${TASK_ID}" || true
       echo "MVP+TDD GATE TRIPPED: missing RED commit for ${PLAN_ID}/${TASK_ID}"
@@ -236,6 +240,7 @@ Pure doc-only / config-only / test-only tasks return `is_behavior_adding=false`
 Look for a `.continue-here.md` in the current phase directory:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls ${phase_dir}/.continue-here.md 2>/dev/null || true
 ```
 
@@ -755,6 +760,7 @@ increases monotonically across waves. `{status}` is `complete` (success),
    rerun the same command. Do not fall back to broad worktree discovery.
 
    ```bash
+   [ -z "${ZSH_VERSION:-}" ] || emulate -R sh
    [ -n "${WAVE_WORKTREE_MANIFEST:-}" ] && [ -f "$WAVE_WORKTREE_MANIFEST" ] || {
      echo "BLOCKED: missing WAVE_WORKTREE_MANIFEST; refusing broad worktree cleanup (#3384)." >&2
      exit 1
@@ -784,6 +790,7 @@ increases monotonically across waves. `{status}` is `complete` (success),
    If the orchestrator deviated from the standard wave merge path (e.g., custom inter-worktree base-update merges with `merge: bring …` style messages), run this snippet after the custom merges are complete. It reads only `WAVE_WORKTREE_MANIFEST`; do not discover unrelated `worktree-agent-*` worktrees.
 
    ```bash
+   [ -z "${ZSH_VERSION:-}" ] || emulate -R sh
    # Cleanup-tail: pin orchestrator CWD to its OWN worktree before cleanup-tail (#3174, #630).
    # Same fix as the templated path: resolve the dispatch-time orchestrator root from the manifest,
    # not `git worktree list`'s first entry (always the main checkout — wrong for a lane orchestrator).
@@ -858,7 +865,7 @@ increases monotonically across waves. `{status}` is `complete` (success),
 
      # Only commit tracking files if they actually changed
      if ! git diff --quiet .planning/ROADMAP.md .planning/STATE.md 2>/dev/null; then
-       pp_run query commit "docs(phase-${PHASE_NUMBER}): update tracking after wave ${N}" --files .planning/ROADMAP.md .planning/STATE.md
+       pp_run query commit "docs(planning): update tracking after wave ${N}" --phase "${PHASE_NUMBER}" --files .planning/ROADMAP.md .planning/STATE.md
      fi
    elif [ "${TEST_EXIT}" -eq 124 ]; then
      echo "⚠ Skipping tracking update — test suite timed out. Plans remain in-progress. Run tests manually to confirm."
@@ -1062,6 +1069,7 @@ After all waves:
 
 **Security gate check:**
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw)
 printf '%s' "$VERIFY_POST_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('VERIFY_POST_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
@@ -1213,7 +1221,8 @@ mv .planning/debug/{slug}.md .planning/debug/resolved/
 
 **6. Commit updated artifacts:**
 ```bash
-pp_run query commit "docs(phase-${PARENT_PHASE}): resolve UAT gaps and debug sessions after ${PHASE_NUMBER} gap closure" --files .planning/phases/*${PARENT_PHASE}*/*-UAT.md .planning/debug/resolved/*.md
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
+pp_run query commit "docs(planning): resolve UAT gaps and debug sessions after ${PHASE_NUMBER} gap closure" --phase "${PARENT_PHASE}" --files .planning/phases/*${PARENT_PHASE}*/*-UAT.md .planning/debug/resolved/*.md
 ```
 </step>
 
@@ -1376,7 +1385,7 @@ blocked: 0
 
 Commit the file:
 ```bash
-pp_run query commit "test({phase_num}): persist human verification items as UAT" --files "{phase_dir}/{phase_num}-UAT.md"
+pp_run query commit "docs(planning): persist human verification items as UAT" --phase "{phase_num}" --files "{phase_dir}/{phase_num}-UAT.md"
 ```
 
 **Step B: Present to user:**
@@ -1456,7 +1465,8 @@ These items are tracked and will appear in `/pp:progress` and `/pp:audit-uat`.
 ```
 
 ```bash
-pp_run query commit "docs(phase-{X}): complete phase execution" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md {phase_dir}/*-VERIFICATION.md
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
+pp_run query commit "docs(planning): complete phase execution" --phase "{X}" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md {phase_dir}/*-VERIFICATION.md
 ```
 </step>
 
@@ -1489,6 +1499,7 @@ Copy failure must NOT block phase completion.
 This step runs AFTER `update_roadmap` marks the phase complete. It moves any pending todos that carry `resolves_phase: <current-phase-number>` to the completed directory.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 PHASE_NUM="${PHASE_NUMBER}"
 PENDING_DIR=".planning/todos/pending"
 COMPLETED_DIR=".planning/todos/completed"
@@ -1506,7 +1517,7 @@ for TODO_FILE in "$PENDING_DIR"/*.md; do
 done
 
 if [ ${#CLOSED[@]} -gt 0 ]; then
-  pp_run query commit "docs(phase-${PHASE_NUMBER}): auto-close ${#CLOSED[@]} todo(s) resolved by this phase" --files .planning/todos/completed/ .planning/STATE.md|| true
+  pp_run query commit "docs(planning): auto-close ${#CLOSED[@]} todo(s) resolved by this phase" --phase "${PHASE_NUMBER}" --files .planning/todos/completed/ .planning/STATE.md|| true
   echo "◆ Closed ${#CLOSED[@]} todo(s) resolved by Phase ${PHASE_NUMBER}:"
   for f in "${CLOSED[@]}"; do echo "  ✓ $f"; done
 fi
@@ -1531,7 +1542,7 @@ PROJECT.md falls behind silently over multiple phases.
 5. Commit the change:
 
 ```bash
-pp_run query commit "docs(phase-{X}): evolve PROJECT.md after phase completion" --files .planning/PROJECT.md
+pp_run query commit "docs(planning): evolve PROJECT.md after phase completion" --phase "{X}" --files .planning/PROJECT.md
 ```
 
 **Skip this step if** `.planning/PROJECT.md` does not exist.
@@ -1594,6 +1605,7 @@ Read and follow `~/.claude/pp-core/workflows/transition.md`, passing through the
 Check whether CONTEXT.md already exists for the next phase:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls .planning/phases/*{next}*/{next}-CONTEXT.md 2>/dev/null || echo "no-context"
 ```
 

package/pp-core/workflows/execute-plan.md

@@ -77,6 +77,7 @@ hooks, mechanically in the fence (D-30): no other capability's hook is run or
 injected here, because execute-phase's dispatcher owns those for its own run.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 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' "$EXECUTE_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('EXECUTE_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 ```
@@ -91,6 +92,7 @@ the two-step contract, the halt and the message passthrough; none of them are re
 
 <step name="identify_plan">
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Use plans/summaries from INIT JSON, or list files
 (ls .planning/phases/XX-name/*-PLAN.md 2>/dev/null || true) | sort
 (ls .planning/phases/XX-name/*-SUMMARY.md 2>/dev/null || true) | sort
@@ -122,6 +124,7 @@ positional is the plan file, not its phase directory: sibling plans mid-wave are
 business, and `check vault.trace <plan file> --stage plan` by hand gives this gate's verdict.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 PLAN_POST_HOOKS_JSON=$(pp_run loop render-hooks plan:post --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' "$PLAN_POST_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('PLAN_POST_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 ```
@@ -312,9 +315,11 @@ End with: **Total deviations:** N auto-fixed (breakdown). **Impact:** assessment
 For `type: tdd` plans — RED-GREEN-REFACTOR:
 
 1. **Infrastructure** (first TDD plan only): detect project, install framework, config, verify empty suite
-2. **RED:** Read `<behavior>` → failing test(s) → run (MUST fail) → commit: `test({phase}-{plan}): add failing test for [feature]`
-3. **GREEN:** Read `<implementation>` → minimal code → run (MUST pass) → commit: `feat({phase}-{plan}): implement [feature]`
-4. **REFACTOR:** Clean up → tests MUST pass → commit: `refactor({phase}-{plan}): clean up [feature]`
+2. **RED:** Read `<behavior>` → failing test(s) → run (MUST fail) → commit: `test({area}): add failing test for [feature]`
+3. **GREEN:** Read `<implementation>` → minimal code → run (MUST pass) → commit: `feat({area}): implement [feature]`
+4. **REFACTOR:** Clean up → tests MUST pass → commit: `refactor({area}): clean up [feature]`
+
+`{area}` names the part of the codebase (`auth`, `billing`), never the plan; every one of these commits ends with the trailer `Phase: {phase}-{plan}` after a blank line.
 
 Errors: RED doesn't fail → investigate test/existing feature. GREEN doesn't pass → debug, iterate. REFACTOR breaks → undo.
 
@@ -348,7 +353,7 @@ If a commit is BLOCKED by a hook:
 <task_commit>
 ## Task Commit Protocol
 
-Canonical per-task commit rules live in **`agents/pp-executor.md`** (`<task_commit_protocol>`). Follow that section for staging, `{type}({phase}-{plan})` messages, `commit-to-subrepo` when `sub_repos` is set, post-commit checks, and untracked-file handling — do not duplicate or paraphrase the full protocol here (single source of truth).
+Canonical per-task commit rules live in **`agents/pp-executor.md`** (`<task_commit_protocol>`). Follow that section for staging, `{type}({area}): …` messages with the `Phase: {phase}-{plan}` trailer, `commit-to-subrepo` when `sub_repos` is set, post-commit checks, and untracked-file handling — do not duplicate or paraphrase the full protocol here (single source of truth).
 
 **Orchestrator note:** After each task, the spawned executor reports commit hashes; this workflow does not re-specify commit semantics beyond pointing at the executor.
 
@@ -523,6 +528,7 @@ Counts PLAN vs SUMMARY files on disk and updates the progress-table row with the
 Mark completed requirements from the PLAN.md frontmatter `requirements:` field:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 pp_run query requirements.mark-complete ${REQ_IDS}
 ```
 
@@ -543,9 +549,9 @@ IS_WORKTREE=$([ -f .git ] && echo "true" || echo "false")
 
 # In parallel mode: exclude STATE.md and ROADMAP.md (orchestrator commits these)
 if [ "$IS_WORKTREE" = "true" ]; then
-  pp_run query commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/REQUIREMENTS.md
+  pp_run query commit "docs(planning): complete [plan-name] plan" --phase "{phase}-{plan}" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/REQUIREMENTS.md
 else
-  pp_run query commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
+  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
 fi
 ```
 </step>
@@ -554,13 +560,17 @@ fi
 If .planning/codebase/ doesn't exist: skip.
 
 ```bash
-FIRST_TASK=$(git log --oneline --grep="feat({phase}-{plan}):" --grep="fix({phase}-{plan}):" --grep="test({phase}-{plan}):" --reverse | head -1 | cut -d' ' -f1)
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
+# Oldest feat/fix/test commit carrying the plan's `Phase:` trailer (or, from before the trailer, its scope)
+FIRST_TASK=$(git log --reverse --format='%h%x09%s%x09%(trailers:key=Phase,valueonly,separator=%x2C)' \
+  | awk -F'\t' -v id="{phase}-{plan}" '$2 ~ /^(feat|fix|test)(\([^)]*\))?!?:/ && ($3 == id || index($2, "(" id "):") > 0) { print $1; exit }')
 git diff --name-only ${FIRST_TASK}^..HEAD 2>/dev/null || true
 ```
 
 Update only structural changes: new src/ dir → STRUCTURE.md | deps → STACK.md | file pattern → CONVENTIONS.md | API client → INTEGRATIONS.md | config → STACK.md | renamed → update paths. Skip code-only/bugfix/content changes.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 pp_run query commit "" --files .planning/codebase/*.md --amend
 ```
 </step>
@@ -569,6 +579,7 @@ pp_run query commit "" --files .planning/codebase/*.md --amend
 If `USER_SETUP_CREATED=true`: display `⚠️ USER SETUP REQUIRED` with path + env/config tasks at TOP.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 (ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null || true) | wc -l
 (ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null || true) | wc -l
 ```

package/pp-core/workflows/explore.md

@@ -118,7 +118,7 @@ For each selected output, write the file:
 Commit if `commit_docs` is enabled:
 ```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: capture exploration — {topic_slug}" --files {file_list}
+pp_run query commit "docs(planning): capture exploration — {topic_slug}" --files {file_list}
 ```
 
 ## Step 6: Close

package/pp-core/workflows/forensics.md

@@ -64,6 +64,7 @@ Extract:
 For each phase directory in `.planning/phases/*/`:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls .planning/phases/*/
 ```
 
@@ -255,15 +256,16 @@ If actionable anomalies were found (HIGH or MEDIUM confidence):
 
 If confirmed:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Check if "bug" label exists before using it
-BUG_LABEL=$(gh label list --repo open-gsd/pp-core --search "bug" --json name -q '.[0].name' 2>/dev/null)
+BUG_LABEL=$(gh label list --repo pareto000/pp-core --search "bug" --json name -q '.[0].name' 2>/dev/null)
 LABEL_FLAG=""
 if [ -n "$BUG_LABEL" ]; then
   LABEL_FLAG="--label bug"
 fi
 
 gh issue create \
-  --repo open-gsd/pp-core \
+  --repo pareto000/pp-core \
   --title "bug: {concise description from anomaly}" \
   $LABEL_FLAG \
   --body "{formatted findings from report}"

package/pp-core/workflows/health.md

@@ -65,6 +65,7 @@ health output, the two modes are independent diagnostics.
 **Run health validation:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 pp_run query validate.health $REPAIR_FLAG $BACKFILL_FLAG
 ```
 

package/pp-core/workflows/import.md

@@ -42,6 +42,7 @@ Usage: /pp:import --from <path>
 Verify the path does not contain traversal sequences and the file exists:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 case "{FILEPATH}" in
   *..* ) echo "SECURITY_ERROR: path contains traversal sequence"; exit 1 ;;
 esac
@@ -228,7 +229,7 @@ Update `.planning/STATE.md` if appropriate (e.g., increment total plan count).
 
 Commit the imported plan and updated files:
 ```bash
-pp_run query commit "docs({phase}): import plan from {basename FILEPATH}" --files .planning/phases/{phase}/{plan}-PLAN.md .planning/ROADMAP.md
+pp_run query commit "docs(planning): import plan from {basename FILEPATH}" --phase "{phase}" --files .planning/phases/{phase}/{plan}-PLAN.md .planning/ROADMAP.md
 ```
 
 Display completion:

package/pp-core/workflows/ingest-docs.md

@@ -33,6 +33,7 @@ Parse `$ARGUMENTS`:
 **Validate paths:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 case "{SCAN_PATH}" in *..*) echo "SECURITY_ERROR: path contains traversal sequence"; exit 1 ;; esac
 test -d "{SCAN_PATH}" || echo "PATH_NOT_FOUND"
 if [ -n "{MANIFEST_PATH}" ]; then

package/pp-core/workflows/init/steps/client-context-capture.md

@@ -61,6 +61,7 @@ Capture these fields, in this order:
 managed-block writer:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ "$(pp_run query platform-bindings --pick present 2>/dev/null)" = "true" ]; then
   # Write collected values to a temp JSON file using node + JSON.stringify so that
   # multi-line values, embedded quotes, backslashes, and $(...) sequences are encoded

package/pp-core/workflows/init/steps/github-provisioning.md

@@ -0,0 +1,145 @@
+# Gated GitHub provisioning — H-2..H-5 (D-05, D-09, D-10, D-11, D-12, D-13)
+
+Lazily Read by `pp-core/workflows/init.md` § "Gated GitLab/GitHub provisioning" — Step 3's
+other sub-path — and ONLY when BOTH of that section's gates hold: `.platform-bindings.json`
+is present AND `resolveProvider` answers `github`. Both gates, G-1's one-source-per-value
+config reads and the empty-group guard stay in `init.md`; this file is the GitHub create
+recipe those guards protect, the counterpart of `gitlab-provisioning.md` step for step.
+`$GROUP` (the GitHub organization), `$SLUG`, `$VIS`, `$DESC` and `$HOST` are the variables
+G-1 has already set. Every `gh` call names the host through `GH_HOST`, so a GitHub
+Enterprise host in the binding is honored and `github.com` is the default:
+
+```bash
+GH_HOSTNAME="${HOST:-github.com}"
+```
+
+#### H-2. Auth verify-only (D-11)
+
+`/pp-init` **never establishes auth and never reads or writes the user's token.**
+Secrets stay in the environment or OS keyring. Only verify that a session exists:
+
+```bash
+gh auth status --hostname "$GH_HOSTNAME" >/dev/null 2>&1 || {
+  echo "Not authenticated to GitHub ($GH_HOSTNAME). Run: gh auth login --hostname $GH_HOSTNAME"
+  exit 1
+}
+```
+
+If this check fails, stop immediately. Do not proceed to probe or create.
+Never run `gh auth login` from within `/pp-init`.
+
+#### H-3. Existence probe → adopt-if-exists (D-09, D-12)
+
+Pre-check with a read-only probe before any create attempt. The create command is **not
+idempotent** — re-running it against an existing repository fails, and a create whose
+remote-add step fails has still created the repository. The probe avoids this landmine.
+
+This is one self-contained block: it sets `PROJECT_EXISTS` and, on the exists path,
+adopts (links the remote). It NEVER creates — create lives in its own H-4 block, gated
+on `PROJECT_EXISTS=false`, so the create invocation can never fall inside the exists
+branch.
+
+```bash
+if GH_HOST="$GH_HOSTNAME" gh repo view "$GROUP/$SLUG" --json name >/dev/null 2>&1; then
+  # Repository already exists — ADOPT: link remote only, skip create (D-12)
+  PROJECT_EXISTS=true
+  echo "GitHub repository $GROUP/$SLUG already exists — adopting (linking remote, skipping create)."
+  # Match the remote scheme gh itself uses on the create path — honor the user's
+  # `gh config get git_protocol` (https default) instead of hardcoding SSH.
+  GIT_PROTO=$(gh config get git_protocol --host "$GH_HOSTNAME" 2>/dev/null || echo https)
+  if [ "$GIT_PROTO" = "ssh" ]; then
+    ADOPT_URL="git@$GH_HOSTNAME:$GROUP/$SLUG.git"
+  else
+    ADOPT_URL="https://$GH_HOSTNAME/$GROUP/$SLUG.git"
+  fi
+  git remote get-url origin >/dev/null 2>&1 || git remote add origin "$ADOPT_URL"
+  echo "Remote 'origin' → $ADOPT_URL"
+else
+  # Repository not found — defer to H-4 for confirm-then-create
+  PROJECT_EXISTS=false
+  echo "GitHub repository $GROUP/$SLUG not found — will confirm before create."
+fi
+```
+
+If the repository exists (`PROJECT_EXISTS=true`), the remote is already linked above
+(skipping create entirely) — proceed straight to H-5 reconciliation. The adopt path does
+not show a create confirmation — it only links the remote, which is a local-only
+operation and can be undone with `git remote remove origin`.
+
+#### H-4. Per-action confirmation, then create (D-05, D-09, D-10, SAFE-01)
+
+**Only run this step when `PROJECT_EXISTS=false`** (the existence probe in H-3 found no
+repository). If `PROJECT_EXISTS=true`, skip H-4 entirely — the repository was already
+adopted — and go to H-5. When creating, **show the exact command and target before
+firing**. The user must confirm explicitly. Nothing is batched. (D-05)
+
+Present to the user (via `AskUserQuestion` or TEXT_MODE numbered list):
+
+```text
+About to create GitHub repository:
+  Command:        gh repo create "$GROUP/$SLUG"
+  Host:           $GH_HOSTNAME
+  Organization:   $GROUP
+  Repository:     $GROUP/$SLUG
+  Visibility:     private (enforced --private)
+  Requested:      $VIS  (from project.visibility — see note below)
+  Source:         this directory (--source .) — nothing is pushed
+  Remote name:    origin
+
+Proceed? [y/N]
+```
+
+`$VIS` (from G-1) is surfaced in the confirmation so the requested visibility is never
+silently ignored (WR-01). pp-core always **creates private** regardless; a non-private
+repository must be a deliberate, separate post-create change.
+
+Only after the user confirms — and only with `PROJECT_EXISTS=false` — run the locked
+create recipe (D-09, D-10). This is a standalone block: it carries no `if`/`else`/`fi`, so
+it can only ever run as the deliberate, confirmed not-exists path:
+
+```bash
+GH_HOST="$GH_HOSTNAME" gh repo create "$GROUP/$SLUG" \
+  --description "$DESC" \
+  --private \
+  --source . \
+  --remote origin
+```
+
+**Visibility hard-default (D-10):** the create invocation always carries `--private` and
+never `--public` or `--internal`. `VIS` is read in G-1 and **surfaced in the H-4
+confirmation** (WR-01) so a `public`/`internal` request is visible to the user — but
+pp-core still creates the repository **private**. Applying a non-private visibility is a
+deliberate, separate post-create action (e.g. `gh repo edit --visibility …`) the operator
+performs knowingly; `/pp-init` never auto-relaxes visibility. The create pushes nothing
+(no `--push`): the first push is Step 3's own confirmed push, and the repository's default
+branch is whatever that push sends.
+
+#### H-5. Post-create reconciliation (D-09)
+
+After the create (or after the adopt path), re-probe existence. A non-zero exit from
+`gh repo create` does **not** mean the repository was not created — the repository is
+created before `--remote origin` is added, so an `origin` that already exists fails the
+command after the create succeeded. The `repo view` probe is the source of truth, not the
+exit code:
+
+```bash
+if GH_HOST="$GH_HOSTNAME" gh repo view "$GROUP/$SLUG" --json name >/dev/null 2>&1; then
+  echo "Reconciled: GitHub repository $GROUP/$SLUG confirmed."
+else
+  echo "WARN: gh repo view $GROUP/$SLUG returned non-zero — verify the repository was created before continuing."
+fi
+```
+
+If reconciliation warns, do not auto-retry. Prompt the user to check GitHub directly
+before proceeding to Step 4 (handoff routing).
+
+**Security invariants — landmine guards:**
+- Always use the organization-qualified `$GROUP/$SLUG` — never a bare slug (T-08-04, D-09).
+  A bare slug creates under the user's personal account, not the client organization.
+  G-1's empty-group guard is what actually enforces this before any create attempt.
+- Always pass `--private` explicitly — never `--public` or `--internal` (T-08-05, D-10).
+- Always confirm immediately before each outward action — nothing batched (T-08-06, D-05).
+- Verify-only auth via `gh auth status` — never run `gh 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 `gh repo view` probe — a non-zero create exit does NOT
+  mean nothing happened (T-08-09, D-09).

package/pp-core/workflows/init/steps/gitlab-provisioning.md

@@ -1,10 +1,11 @@
 # Gated GitLab provisioning — G-2..G-5 (D-05, D-09, D-10, D-11, D-12, D-13)
 
-Lazily Read by `pp-core/workflows/init.md` § "Gated GitLab/Azure provisioning" — Step 3's
+Lazily Read by `pp-core/workflows/init.md` § "Gated GitLab/GitHub provisioning" — Step 3's
 other sub-path — and ONLY when BOTH of that section's gates hold: `.platform-bindings.json`
 is present AND `resolveProvider` answers `gitlab`. Both gates, G-1's one-source-per-value
-config reads, the empty-group guard and the security-invariant list stay in `init.md`; this
-file is the create recipe those guards protect. Extracted from `init.md` (07-10) so the
+config reads and the empty-group guard stay in `init.md`; this file is the create recipe
+those guards protect, and ends with its security invariants (moved here from `init.md`
+beside `github-provisioning.md`'s own). Extracted from `init.md` (07-10) so the
 always-loaded workflow stays under its DEFAULT size cap — relocation, not deletion: this
 text is the authority for how `/pp-init` provisions a GitLab project, and `$GROUP`, `$SLUG`,
 `$VIS`, `$DESC` and `$HOST` are the variables G-1 has already set.
@@ -26,7 +27,7 @@ Never run `glab auth login` from within `/pp-init`.
 
 #### G-3. Existence probe → adopt-if-exists (D-09, D-12)
 
-Pre-check with a read-only probe before any create attempt. `glab repo create` is **not
+Pre-check with a read-only probe before any create attempt. The create command is **not
 idempotent** — re-running it against an existing project errors but may still produce side
 effects (the GitLab project is created before the remote-add step that then fails). The
 probe avoids this landmine.
@@ -128,3 +129,16 @@ fi
 
 If reconciliation warns, do not auto-retry. Prompt the user to check GitLab directly
 before proceeding to Step 4 (handoff routing).
+
+**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 in `init.md` 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).

package/pp-core/workflows/init/steps/reachability-outcome.md

@@ -16,7 +16,9 @@ the probe, or this step to the user.
 named ref exists, and the client vault landed with a written `SUMMARY.md` (INIT-02).
 Continue to Step 3. A `shared` line on that card is information about the fallback
 tier (OD-5) — it is probed and shown, never required; an unreachable shared vault does
-not fail the proof and is not in the recorded note.
+not fail the proof and is not in the recorded note. A `platform` line reading
+`unreachable (not required)` is information too: the platform repo is not required, and
+the record states what was measured.
 
 **(c) `PP_INIT_PROBE=unbound` or `PP_INIT_PROBE=fail`** — **STOP. `/pp-init` is not
 complete (INIT-03).** Do not continue to Step 3, and do not re-run the probe hoping for a