@pareto4/pp-core 1.18.0 → 1.19.0

package/pp-core/workflows/autonomous.md

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

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

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

package/pp-core/workflows/cleanup.md

@@ -27,6 +27,7 @@ Extract each milestone version (e.g., v1.0, v1.1, v2.0).
 Check which milestone archive dirs already exist:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls -d .planning/milestones/v*-phases 2>/dev/null || true
 ```
 
@@ -55,6 +56,7 @@ Extract phase numbers and names from the archived roadmap (e.g., Phase 1: Founda
 Check which of those phase directories still exist in `.planning/phases/`:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls -d .planning/phases/*/ 2>/dev/null || true
 ```
 
@@ -162,7 +164,7 @@ Commit the changes:
 
 ```bash
 _PP_SHIM_NAME="pp-tools.cjs"; _pp_root() { ( for _v in $(env | sed -n 's/^\(GIT_[A-Za-z0-9_]*\)=.*/\1/p'); do unset "$_v"; done; _c=$(git rev-parse --git-common-dir 2>/dev/null); if [ "${_c##*/}" = .git ] && cd "$_c/.." 2>/dev/null; then pwd -P; else git rev-parse --show-toplevel 2>/dev/null || pwd; fi ); }; pp_run() { case "$PP_TOOLS" in *.cjs) node "$PP_TOOLS" "$@";; *) "$PP_TOOLS" "$@";; esac; }; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(_pp_root)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then :; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
-pp_run query commit "chore: archive phase directories from completed milestones" --files .planning/milestones/ .planning/phases/
+pp_run query commit "chore(planning): archive phase directories from completed milestones" --files .planning/milestones/ .planning/phases/
 ```
 
 </step>

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

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

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

@@ -18,6 +18,7 @@ Parse arguments and load project state:
 
 ```bash
 _PP_SHIM_NAME="pp-tools.cjs"; _pp_root() { ( for _v in $(env | sed -n 's/^\(GIT_[A-Za-z0-9_]*\)=.*/\1/p'); do unset "$_v"; done; _c=$(git rev-parse --git-common-dir 2>/dev/null); if [ "${_c##*/}" = .git ] && cd "$_c/.." 2>/dev/null; then pwd -P; else git rev-parse --show-toplevel 2>/dev/null || pwd; fi ); }; pp_run() { case "$PP_TOOLS" in *.cjs) node "$PP_TOOLS" "$@";; *) "$PP_TOOLS" "$@";; esac; }; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(_pp_root)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then :; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 PHASE_ARG="${1}"
 INIT=$(pp_run query init.phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
@@ -138,6 +139,7 @@ Three-tier scoping with explicit precedence:
 
 If FILES_OVERRIDE is set (from --files flag):
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ -n "$FILES_OVERRIDE" ]; then
   REVIEW_FILES=()
   REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
@@ -168,6 +170,7 @@ Skip SUMMARY/git scoping entirely when --files is provided.
 
 If --files NOT provided:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ -z "$FILES_OVERRIDE" ]; then
   SUMMARIES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
   REVIEW_FILES=()
@@ -222,6 +225,7 @@ fi
 
 If no SUMMARY.md files found OR no files extracted from them:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ ${#REVIEW_FILES[@]} -eq 0 ]; then
   # Compute diff base from phase commits — fail closed if no reliable base found
   PHASE_COMMITS=$(git log --oneline --all --grep="${PADDED_PHASE}" --format="%H" 2>/dev/null)
@@ -257,6 +261,7 @@ fi
 
 1. **Apply exclusions (per D-03):** Remove paths matching planning artifacts
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 FILTERED_FILES=()
 for file in "${REVIEW_FILES[@]}"; do
   # Skip planning directory and specific artifacts
@@ -275,6 +280,7 @@ REVIEW_FILES=("${FILTERED_FILES[@]}")
 
 2. **Filter deleted files:** Remove paths that don't exist on disk
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 EXISTING_FILES=()
 DELETED_COUNT=0
 for file in "${REVIEW_FILES[@]}"; do
@@ -293,6 +299,7 @@ fi
 
 3. **Deduplicate:** Remove duplicate paths (portable — bash 3.2+ compatible, handles spaces in paths)
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 DEDUPED=()
 while IFS= read -r line; do
   [ -n "$line" ] && DEDUPED+=("$line")
@@ -304,6 +311,7 @@ REVIEW_FILES=("${DEDUPED[@]}")
 
 **Log final scope and warn if large:**
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ -n "$FILES_OVERRIDE" ]; then
   TIER="--files override"
 elif [ -n "$SUMMARIES" ] && [ ${#REVIEW_FILES[@]} -gt 0 ]; then
@@ -379,6 +387,7 @@ fi
 
 3) Execute structural pass and persist JSON (bounded at 120s). Note: `fallow audit` exits 0 when clean and 1 when issues are found — BOTH are successful runs. Only a timeout (124), usage error (2), or crash yields no usable JSON; success is decided by whether the output parses as a valid fallow report, not by exit code:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 FALLOW_JSON_PATH="${PHASE_DIR}/FALLOW.json"
 FALLOW_STDERR_TMP=$(mktemp)
 
@@ -459,6 +468,7 @@ fi
 
 Build files_to_read block for agent:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 FILES_TO_READ=""
 for file in "${REVIEW_FILES[@]}"; do
   FILES_TO_READ+="- ${file}\n"
@@ -467,6 +477,7 @@ done
 
 Build config block for agent:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 CONFIG_FILES=""
 for file in "${REVIEW_FILES[@]}"; do
   CONFIG_FILES+="  - ${file}\n"
@@ -475,6 +486,7 @@ done
 
 Build structural findings block for agent:
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 STRUCTURAL_FINDINGS_BLOCK=""
 MAX_FINDINGS_SIZE=50000
 if [ -n "$FALLOW_JSON_PATH" ] && [ -f "$FALLOW_JSON_PATH" ]; then
@@ -542,6 +554,7 @@ Do NOT proceed to commit_review step. Do NOT create a partial or empty REVIEW.md
 After agent completes successfully, verify REVIEW.md was created and has valid structure:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ -f "${REVIEW_PATH}" ]; then
   # Validate REVIEW.md has valid YAML frontmatter with status field
   HAS_STATUS=$(REVIEW_PATH="${REVIEW_PATH}" node -e "
@@ -556,7 +569,7 @@ if [ -f "${REVIEW_PATH}" ]; then
     
     if [ "$COMMIT_DOCS" = "true" ]; then
       pp_run query commit \
-        "docs(${PADDED_PHASE}): add code review report" \
+        "docs(planning): add code review report" --phase "${PADDED_PHASE}" \
         --files "${REVIEW_PATH}"
     fi
   else
@@ -616,6 +629,7 @@ Read the REVIEW.md YAML frontmatter to extract finding counts.
 Extract frontmatter between `---` delimiters first to avoid matching values in the review body:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Extract only the YAML frontmatter block (between first two --- lines)
 FRONTMATTER=$(REVIEW_PATH="${REVIEW_PATH}" node -e "
   const fs = require('fs');

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

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

package/pp-core/workflows/debug.md

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

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

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

package/pp-core/workflows/discovery-sprint/session-13-gates.md

@@ -19,7 +19,7 @@ documented absent-artifact arm — before the cross-reference analysis begins.
 
 **Element-sweep gate:** run `pp_run query discovery.element-sweep --check`. Exit 0 → proceed. Non-zero → a functional prototype element has no id, a tag names an unknown requirement, or `_sweep.md` leaves an element of the current pages undecided, decides one twice, or cites a reference that does not fit its outcome — finish the sweep with `/pp-discovery prototype` Step 8 and re-run. Without a prototype the check exits 0 by itself.
 
-**Vault-context gate (PBI 75336):** for each of sessions 1–12 whose `.planning/discovery/session-NN.md` carries a `## Vault Context` section, run `pp_run query discovery.vault-check <N>`. Exit 0 → proceed. Non-zero → the record names no index, a line is not one `` - `<path>` — <why> `` entry, or a selected vault document is neither cited `[vault: <path>]` in the notes nor marked `— not used: <reason>`: fix that session's record or notes and re-run. A session with no `## Vault Context` section ran without the vault and is skipped.
+**Vault-context gate (PBI 75336):** for each of sessions 1–12 whose `.planning/discovery/session-NN.md` carries a `## Vault Context` section, run `pp_run query discovery.vault-check <N>`. Exit 0 → proceed. Non-zero → the record names no index, a line is not one `` - `<path>` — <why> `` entry, a selected vault document is neither cited `[vault: <path>]` in the notes nor marked `— not used: <reason>`, or a document the vault's `INDEX.md` marks `[cross-cutting]` has no record line: fix that session's record or notes and re-run. A session with no `## Vault Context` section ran without the vault and is skipped.
 
 **The screen-traceability gate reports open feedback; it never blocks on it (D-53, first arm).** A round whose `Processing` cells all read `Open` exits 0 and the open count is reported as outstanding work — exactly as an open `Gates-MVP` research item exits 0 under D-43. It fails only on structural faults. The hard block on those same structural faults lives at `/pp-discovery-to-build`, not here (D-53, second arm): the handoff into build is the last moment an uncovered MVP requirement or an unclassified surface is still free to fix. Open feedback is still closed before Session 13 completes, by the `--require-processed` check in Flow 2 Step 7, and the handoff refuses it too.
 

package/pp-core/workflows/discovery-sprint/sessions/01-kick-off.md

@@ -5,7 +5,7 @@
 
 ### Session 1: Discovery Sprint Kick-off
 
-**Goal:** Align all participants on the Discovery Sprint purpose, establish project context, confirm business vision, identify stakeholders, and agree on the discovery approach, ground rules, and logistics.
+**Goal:** Align all participants on the Discovery Sprint purpose, establish project context, confirm business vision, identify stakeholders and who approves what, and agree on the discovery approach, ground rules, and logistics.
 
 **What We Cover:**
 
@@ -29,9 +29,10 @@
 
 4. **Discovery Sprint approach and logistics**
    *Why it matters: sets expectations so the remaining 12 sessions run smoothly without renegotiating format each time. Skip when: the team has already run a Discovery Sprint together before and knows the cadence.*
-   - Walk through the 13-session agenda and expected outputs
+   - Walk through the 13-session agenda and expected outputs, including the cross-reference that closes Session 8 and the one that opens Session 13
    - What is the preferred meeting cadence and format (in-person, remote, hybrid)?
    - How will decisions be documented and communicated?
+   - What is the team shape for the sprint and the build: a full delivery team, a small team, or one person working with an AI assistant? Session 12 builds the delivery model on this answer.
 
 5. **Ground rules and ways of working**
    *Why it matters: prevents disagreements from derailing later sessions once real tradeoffs surface. Skip when: the team already has an established working agreement from a prior engagement.*
@@ -44,16 +45,28 @@
    - Are there hard deadlines (regulatory, contractual, market)?
    - What budget constraints exist? [needs-business-input]
    - Are there technology mandates or restrictions?
+   - Does the client vault or the client mandate a platform: cloud provider, CI/CD, observability? Record the mandate as a Key Decisions row `D-01-<n>`, citing `[vault: <path>]` when the vault states it. Sessions 5, 6 and 10 fill their tables against this decision; with no mandate, record that the platform is open.
 
 7. **Requirement ID prefixes and decision-ID conventions**
    *Why it matters: every requirement, decision, and action across all 13 sessions cites these IDs — chosen once here, never renumbered. Skip when: never — mandatory.*
    - Propose a prefix set derived from the stakeholder domains just mapped in topic 3: one prefix per stakeholder domain, plus `N-` (non-functional) and `T-` (technical) defaults; the user confirms or adjusts (D-09)
    - Create `.planning/discovery/_requirements.md` from the bootstrap template in the pp-core reference `references/discovery-id-conventions.md` — locate it under the installed pp-core root (`${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-id-conventions.md`) and Read it lazily; never `@`-import it. Fill the Prefix Registry header table with the confirmed set (the registry and the requirements table travel in one file — D-10)
-   - Never register a reserved prefix: the proposed set must not include `D-`, `A-`, `SP-`, `DG-`, `RS-` or `SCR-` — they are owned by other ID families, and a row claiming one makes `discovery rollup --check` report `reserved_prefix` (D-44)
+   - Never register a reserved prefix: the proposed set must not include `D-`, `A-`, `SP-`, `DG-`, `RS-`, `SCR-` or `PRC-` — they are owned by other ID families, and a row claiming one makes `discovery rollup --check` report `reserved_prefix` (D-44). Avoid the session-table row prefixes that reference lists too (`C-`, `R-`, `E-`, …), so a citation never reads two ways
    - Decisions are cited inline as `D-<ss>-<n>` per that same reference; record the chosen prefix set as a Key Decisions row in the Session 1 notes
 
+8. **Approval routes**
+   *Why it matters: Sessions 5–7 sign architecture and security deviations; an approval route found only later means those signatures were given by people who could not give them. Skip when: never — "no formal route" is itself an answer to record.*
+   - Which approvals will this project need: scope, budget, architecture, security deviations, data protection, go-live?
+   - Who gives each approval, and who is consulted or informed?
+   - When the client vault is bound, sweep it for approval rules: every document that says who must approve what. Record each route in the **Approval Matrix** with its `[vault: <path>]` citation.
+   - Where no route exists for an approval the sprint will need, who approves it? Record the answer as `D-01-<n>`.
+
 **Notes Template:**
 
+**Background**
+
+The business problem or opportunity, what was tried before and with what result, and the documents handed over, cited by accession number (`[NN]`).
+
 **Stakeholder Register**
 
 | Name | Role | Organization | Interest Area | Decision Authority | Availability |
@@ -70,21 +83,52 @@
 | Success criteria (12-month) | |
 | Key business drivers | |
 
+**Sprint Logistics**
+
+| Aspect | Agreement |
+|--------|-----------|
+| Session cadence and format | |
+| Team shape | |
+| Decision recording and communication | |
+
+**Working Agreement**
+
+| Aspect | Agreement |
+|--------|-----------|
+| Disagreements and competing priorities | |
+| Escalation path for blockers | |
+| Collaboration tools | |
+
 **Constraints and Risks Register**
 
 | ID | Type | Description | Impact (H/M/L) | Mitigation | Owner |
 |----|------|-------------|-----------------|------------|-------|
-| C1 | Constraint | | | | |
-| R1 | Risk | | | | |
+| CON-01 | Constraint | | | | |
+| R-01 | Risk | | | | |
+
+Session 11's **Risk Register** continues the `R-` sequence; a risk raised here keeps its ID there.
+
+**Approval Matrix**
+
+| Approval | Approver | Consulted | Source | Decision |
+|----------|----------|-----------|--------|----------|
+| Scope change | | | | |
+| Budget | | | | |
+| Architecture deviation | | | | |
+| Security deviation | | | | |
+| Data protection | | | | |
+| Go-live | | | | |
+
+**Source** is a `[vault: <path>]` citation or `room`. **Decision** is `—` or the `D-01-<n>` that set a route the vault does not give.
 
 **Key Decisions**
 
-| # | Decision | Rationale | Owner | Date |
+| ID | Decision | Rationale | Owner | Date |
 |---|----------|-----------|-------|------|
 | | | | | |
 
 **Action Items**
 
-| # | Action | Owner | Due Date | Status |
+| ID | Action | Owner | Due Date | Status |
 |---|--------|-------|----------|--------|
 | | | | | |

package/pp-core/workflows/discovery-sprint/sessions/02-as-is.md

@@ -57,7 +57,9 @@
 
 | Process ID | Process Name | Owner | Trigger | End State | Frequency | Avg Duration | Criticality |
 |------------|-------------|-------|---------|-----------|-----------|--------------|-------------|
-| P-01 | | | | | | | |
+| PRC-01 | | | | | | | |
+
+**Process ID** is `PRC-<nn>`, a reserved prefix, so a process never shares an ID with a requirement.
 
 **Pain Points Register**
 
@@ -85,12 +87,12 @@
 
 **Key Decisions**
 
-| # | Decision | Rationale | Owner | Date |
+| ID | Decision | Rationale | Owner | Date |
 |---|----------|-----------|-------|------|
 | | | | | |
 
 **Action Items**
 
-| # | Action | Owner | Due Date | Status |
+| ID | Action | Owner | Due Date | Status |
 |---|--------|-------|----------|--------|
 | | | | | |

package/pp-core/workflows/discovery-sprint/sessions/03-to-be.md

@@ -65,7 +65,7 @@ One Mermaid flowchart block per accepted sub-process decomposition.
 
 **Step Matrices** (populated via Step 5C)
 
-One step matrix per sub-process; Requirements column back-filled at Step 5D.
+One step matrix per sub-process, or one combined matrix per main process when its sub-processes are step-sized (Step 5C); Requirements column back-filled at Step 5D.
 
 **Business Objectives**
 
@@ -99,10 +99,12 @@ Orphan-requirement and uncovered-step flags only — the canonical requirements
 
 | ID | Category | Requirement | Target / Threshold | MoSCoW |
 |----|----------|-------------|-------------------|--------|
-| NFR-01 | Performance | | | |
-| NFR-02 | Availability | | | |
-| NFR-03 | Scalability | | | |
-| NFR-04 | Accessibility | | | |
+| | Performance | | | |
+| | Availability | | | |
+| | Scalability | | | |
+| | Accessibility | | | |
+
+**ID** is the requirement's `N-<nn>` row in `_requirements.md`, minted at Step 5D like every other requirement — never a separate `NFR-` sequence.
 
 **Prototype Validation Plan** (populated via Step 5G)
 
@@ -110,13 +112,13 @@ Flows to be clickable, personas covered, and per-flow definition of "validated".
 
 **Key Decisions**
 
-| # | Decision | Rationale | Owner | Date |
+| ID | Decision | Rationale | Owner | Date |
 |---|----------|-----------|-------|------|
 | | | | | |
 
 **Action Items**
 
-| # | Action | Owner | Due Date | Status |
+| ID | Action | Owner | Due Date | Status |
 |---|--------|-------|----------|--------|
 | | | | | |
 
@@ -173,7 +175,7 @@ For each accepted sub-process, propose a step-level matrix:
 - **Integration:** external systems with direction
 - **Requirements:** leave blank during 5C — back-filled with minted `_requirements.md` IDs during Step 5D consolidation
 
-Present one sub-process matrix at a time. After validation, fill the section titled exactly **Step Matrices** in `.planning/discovery/session-03.md` — edit in place; never append a new heading.
+Present one sub-process matrix at a time. When a main process's sub-processes are step-sized — each one or two steps — propose one combined matrix for the main process instead, with a **Sub-process** column after `#`; the user may still ask for one matrix per sub-process. After validation, fill the section titled exactly **Step Matrices** in `.planning/discovery/session-03.md` — edit in place; never append a new heading.
 
 ### Step 5D: Consolidate Requirements