@pareto4/pp-core 1.18.0 → 1.19.0

package/pp-core/references/git-integration.md

@@ -34,11 +34,23 @@ If NO_GIT: Run `git init` silently. pp-core projects always get their own repo.
 
 <commit_formats>
 
+<format name="scope-and-trailer">
+## Scope and Phase Trailer
+
+Every commit follows Conventional Commits: `{type}({scope}): {description}`, an optional body, then trailers.
+
+- **The scope names the part of the codebase**, never a phase, plan or quick-task id: `feat(auth)`, `fix(billing)`, `test(api)`. Pick it from the files the commit touches; leave it out (`chore: ...`) when no single area fits. Commits of `.planning/` artifacts use `docs(planning)` (or `chore(planning)`).
+- **The phase or plan goes in a git trailer**, the last paragraph of the message after a blank line: `Phase: 02-03` for a plan, `Phase: 02` for a phase-level commit, `Quick: <id>` for a quick task. `pp_run query commit` and `pp_run query commit-to-subrepo` add it with `--phase <id>` / `--quick <id>`; a raw `git commit` adds it as a second `-m "Phase: <id>"` or as the last paragraph of the message.
+
+Why: a scope that is a phase number tells a reviewer nothing about what changed and breaks the client standard that the scope is a noun naming the part of the codebase. The trailer keeps every commit traceable to its phase and plan, and git parses it (`%(trailers:key=Phase)`, `git log --grep="^Phase: 02-03$"`), so tools no longer parse subjects.
+
+</format>
+
 <format name="initialization">
 ## Project Initialization (brief + roadmap together)
 
 ```
-docs: initialize [project-name] ([N] phases)
+docs(planning): initialize [project-name] ([N] phases)
 
 [One-liner from PROJECT.md]
 
@@ -51,7 +63,7 @@ Phases:
 What to commit:
 
 ```bash
-pp-tools query commit "docs: initialize [project-name] ([N] phases)" --files .planning/
+pp_run query commit "docs(planning): initialize [project-name] ([N] phases)" --files .planning/
 ```
 
 </format>
@@ -69,11 +81,13 @@ Each task gets its own commit immediately after completion.
 > executor prompt; absent that signal, hooks run normally.
 
 ```
-{type}({phase}-{plan}): {task-name}
+{type}({area}): {task-name}
 
 - [Key change 1]
 - [Key change 2]
 - [Key change 3]
+
+Phase: {phase}-{plan}
 ```
 
 **Commit types:**
@@ -89,29 +103,35 @@ Each task gets its own commit immediately after completion.
 ```bash
 # Standard task
 git add src/api/auth.ts src/types/user.ts
-git commit -m "feat(08-02): create user registration endpoint
+git commit -m "feat(auth): create user registration endpoint
 
 - POST /auth/register validates email and password
 - Checks for duplicate users
 - Returns JWT token on success
+
+Phase: 08-02
 "
 
 # TDD task - RED phase
 git add src/__tests__/jwt.test.ts
-git commit -m "test(07-02): add failing test for JWT generation
+git commit -m "test(auth): add failing test for JWT generation
 
 - Tests token contains user ID claim
 - Tests token expires in 1 hour
 - Tests signature verification
+
+Phase: 07-02
 "
 
 # TDD task - GREEN phase
 git add src/utils/jwt.ts
-git commit -m "feat(07-02): implement JWT generation
+git commit -m "feat(auth): implement JWT generation
 
 - Uses jose library for signing
 - Includes user ID and expiry claims
 - Signs with HS256 algorithm
+
+Phase: 07-02
 "
 ```
 
@@ -123,7 +143,7 @@ git commit -m "feat(07-02): implement JWT generation
 After all tasks committed, one final metadata commit captures plan completion.
 
 ```
-docs({phase}-{plan}): complete [plan-name] plan
+docs(planning): complete [plan-name] plan
 
 Tasks completed: [N]/[N]
 - [Task 1 name]
@@ -131,12 +151,14 @@ Tasks completed: [N]/[N]
 - [Task 3 name]
 
 SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
+
+Phase: {phase}-{plan}
 ```
 
 What to commit:
 
 ```bash
-pp-tools query commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
+pp_run query commit "docs(planning): complete [plan-name] plan" --phase "{phase}-{plan}" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
 ```
 
 **Note:** Code files NOT included - already committed per-task.
@@ -147,7 +169,7 @@ pp-tools query commit "docs({phase}-{plan}): complete [plan-name] plan" --files
 ## Handoff (WIP)
 
 ```
-wip: [phase-name] paused at task [X]/[Y]
+docs(planning): pause [phase-name] at task [X]/[Y]
 
 Current: [task name]
 [If blocked:] Blocked: [reason]
@@ -156,7 +178,7 @@ Current: [task name]
 What to commit:
 
 ```bash
-pp-tools query commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
+pp_run query commit "docs(planning): pause [phase-name] at task [X]/[Y]" --files .planning/
 ```
 
 </format>
@@ -173,36 +195,38 @@ a7f2d1 feat(checkout): Stripe payments with webhook verification
 2f4a8d docs: initialize ecommerce-app (5 phases)
 ```
 
-**New approach (per-task commits):**
+**New approach (per-task commits, phase in the trailer):**
+
+`git log --format='%h %s  [%(trailers:key=Phase,valueonly)]'` reads:
 ```
 # Phase 04 - Checkout
-1a2b3c docs(04-01): complete checkout flow plan
-4d5e6f feat(04-01): add webhook signature verification
-7g8h9i feat(04-01): implement payment session creation
-0j1k2l feat(04-01): create checkout page component
+1a2b3c docs(planning): complete checkout flow plan  [04-01]
+4d5e6f feat(checkout): add webhook signature verification  [04-01]
+7g8h9i feat(checkout): implement payment session creation  [04-01]
+0j1k2l feat(checkout): create checkout page component  [04-01]
 
 # Phase 03 - Products
-3m4n5o docs(03-02): complete product listing plan
-6p7q8r feat(03-02): add pagination controls
-9s0t1u feat(03-02): implement search and filters
-2v3w4x feat(03-01): create product catalog schema
+3m4n5o docs(planning): complete product listing plan  [03-02]
+6p7q8r feat(products): add pagination controls  [03-02]
+9s0t1u feat(products): implement search and filters  [03-02]
+2v3w4x feat(products): create product catalog schema  [03-01]
 
 # Phase 02 - Auth
-5y6z7a docs(02-02): complete token refresh plan
-8b9c0d feat(02-02): implement refresh token rotation
-1e2f3g test(02-02): add failing test for token refresh
-4h5i6j docs(02-01): complete JWT setup plan
-7k8l9m feat(02-01): add JWT generation and validation
-0n1o2p chore(02-01): install jose library
+5y6z7a docs(planning): complete token refresh plan  [02-02]
+8b9c0d feat(auth): implement refresh token rotation  [02-02]
+1e2f3g test(auth): add failing test for token refresh  [02-02]
+4h5i6j docs(planning): complete JWT setup plan  [02-01]
+7k8l9m feat(auth): add JWT generation and validation  [02-01]
+0n1o2p build(deps): install jose library  [02-01]
 
 # Phase 01 - Foundation
-3q4r5s docs(01-01): complete scaffold plan
-6t7u8v feat(01-01): configure Tailwind and globals
-9w0x1y feat(01-01): set up Prisma with database
-2z3a4b feat(01-01): create Next.js 15 project
+3q4r5s docs(planning): complete scaffold plan  [01-01]
+6t7u8v feat(ui): configure Tailwind and globals  [01-01]
+9w0x1y feat(db): set up Prisma with database  [01-01]
+2z3a4b feat: create Next.js 15 project  [01-01]
 
 # Initialization
-5c6d7e docs: initialize ecommerce-app (5 phases)
+5c6d7e docs(planning): initialize ecommerce-app (5 phases)  []
 ```
 
 Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
@@ -233,7 +257,7 @@ Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
 
 **Context engineering for AI:**
 - Git history becomes primary context source for future Claude sessions
-- `git log --grep="{phase}-{plan}"` shows all work for a plan
+- `git log --grep="^Phase: {phase}-{plan}$"` shows all work for a plan
 - `git diff <hash>^..<hash>` shows exact changes per task
 - Less reliance on parsing SUMMARY.md = more context for actual work
 
@@ -287,11 +311,11 @@ Set `commit_docs: false` so planning docs stay local and are not committed to an
 Instead of the standard `commit` command, use `commit-to-subrepo` when `sub_repos` is configured:
 
 ```bash
-pp-tools query commit-to-subrepo "feat(02-01): add user API" \
+pp_run query commit-to-subrepo "feat(users): add user API" --phase "02-01" \
   --files backend/src/api/users.ts backend/src/types/user.ts frontend/src/components/UserForm.tsx
 ```
 
-This stages `src/api/users.ts` and `src/types/user.ts` in the `backend/` repo, and `src/components/UserForm.tsx` in the `frontend/` repo, then commits each independently with the same message.
+This stages `src/api/users.ts` and `src/types/user.ts` in the `backend/` repo, and `src/components/UserForm.tsx` in the `frontend/` repo, then commits each independently with the same message and `Phase: 02-01` trailer.
 
 Files that don't match any configured sub-repo are reported as unmatched.
 

package/pp-core/references/git-planning-commit.md

@@ -9,29 +9,51 @@ Pass the message first, then file paths via `--files`. Both `commit` and `commit
 Always use this for `.planning/` files — it handles `commit_docs` and gitignore checks automatically:
 
 ```bash
-pp-tools query commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
+pp_run query commit "docs(planning): {description}" --phase "{phase-or-plan-id}" --files .planning/STATE.md .planning/ROADMAP.md
 ```
 
 The CLI will return `skipped` (with reason) if `commit_docs` is `false` or `.planning/` is gitignored. No manual conditional checks needed.
 
+## Scope and the Phase trailer
+
+The Conventional Commit scope names the part of the codebase a commit changes, as in `fix(billing): round vat per line`. Planning artifacts are one such part, so every commit of `.planning/` files uses `docs(planning)` (or `chore(planning)` when the type is chore). A phase number, plan number, quick-task id or phase slug never goes in the scope.
+
+To keep commits traceable to their phase, the phase or plan id goes in a git trailer instead:
+
+- `--phase <id>` adds `Phase: <id>`: a plan id such as `02-03`, or a phase id such as `02` for phase-level commits. Use the same padded ids the phase directory uses.
+- `--quick <id>` adds `Quick: <id>` for a quick task.
+
+The trailer is the last paragraph of the message, after a blank line:
+
+```
+docs(planning): complete token refresh plan
+
+Phase: 02-03
+```
+
+Readers find a phase's commits with `git log --grep="^Phase: 02-03$"`, or list each commit's trailer with `git log --format='%h %s %(trailers:key=Phase,valueonly)'`. An id may hold letters, digits, dots, dashes and underscores only; anything else (a space, a newline) is rejected before anything is staged. `--phase` and `--quick` are ignored with `--amend`, which keeps the previous message.
+
 ## Amend previous commit
 
 To fold `.planning/` file changes into the previous commit:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 pp-tools query commit "" --files .planning/codebase/*.md --amend
 ```
 
 ## Commit Message Patterns
 
-| Command | Scope | Example |
-|---------|-------|---------|
-| plan-phase | phase | `docs(phase-03): create authentication plans` |
-| execute-phase | phase | `docs(phase-03): complete authentication phase` |
-| new-milestone | milestone | `docs: start milestone v1.1` |
-| remove-phase | chore | `chore: remove phase 17 (dashboard)` |
-| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |
-| add-phase | phase | `docs: add phase 07 (settings page)` |
+| Command | Message | Trailer |
+|---------|---------|---------|
+| plan-phase | `docs(planning): create phase plan` | `Phase: 03` |
+| execute-plan | `docs(planning): complete authentication plan` | `Phase: 03-02` |
+| execute-phase | `docs(planning): complete phase execution` | `Phase: 03` |
+| quick | `docs(planning): record quick task — fix login typo` | `Quick: 260422-abc` |
+| new-milestone | `docs(planning): start milestone v1.1` | — |
+| remove-phase | `chore(planning): remove phase 17 (dashboard)` | — |
+| insert-phase | `docs(planning): insert phase 16.1 (critical fix)` | — |
+| add-phase | `docs(planning): add phase 07 (settings page)` | — |
 
 ## When to Skip
 

package/pp-core/references/phase-argument-parsing.md

@@ -30,6 +30,7 @@ Returns JSON with:
 Zero-pad integer phases to 2 digits. Preserve decimal suffixes.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Normalize phase number
 if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
   # Integer: 8 → 08

package/pp-core/references/planner-gap-closure.md

@@ -9,6 +9,7 @@ Triggered by `--gaps` flag. Creates plans to address verification or UAT failure
 Use init context (from load_project_state) which provides `phase_dir`:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Check for VERIFICATION.md (code verification gaps)
 ls "$phase_dir"/*-VERIFICATION.md 2>/dev/null
 

package/pp-core/references/planner-revision.md

@@ -7,6 +7,7 @@ Triggered when orchestrator provides `<revision_context>` with checker issues. N
 ### Step 1: Load Existing Plans
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 cat .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
 ```
 
@@ -55,7 +56,8 @@ Group by plan, dimension, severity.
 ### Step 6: Commit
 
 ```bash
-pp-tools query commit "fix($PHASE): revise plans based on checker feedback" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
+pp_run query commit "docs(planning): revise plans based on checker feedback" --phase "$PHASE" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
 ```
 
 ### Step 7: Return Revision Summary

package/pp-core/references/planner-tdd.md

@@ -40,13 +40,13 @@ Output: [Working, tested feature]
 
 ## Red-Green-Refactor Cycle
 
-**RED:** Create test file → write test describing expected behavior → run test (MUST fail) → commit: `test({phase}-{plan}): add failing test for [feature]`
+**RED:** Create test file → write test describing expected behavior → run test (MUST fail) → commit: `test({area}): add failing test for [feature]`
 
-**GREEN:** Write minimal code to pass → run test (MUST pass) → commit: `feat({phase}-{plan}): implement [feature]`
+**GREEN:** Write minimal code to pass → run test (MUST pass) → commit: `feat({area}): implement [feature]`
 
-**REFACTOR (if needed):** Clean up → run tests (MUST pass) → commit: `refactor({phase}-{plan}): clean up [feature]`
+**REFACTOR (if needed):** Clean up → run tests (MUST pass) → commit: `refactor({area}): clean up [feature]`
 
-Each TDD plan produces 2-3 atomic commits.
+`{area}` names the part of the codebase under test (`auth`, `billing`); each commit ends with the trailer `Phase: {phase}-{plan}`. Each TDD plan produces 2-3 atomic commits.
 
 ## Context Budget for TDD
 

package/pp-core/references/planning-config.md

@@ -61,7 +61,7 @@ Configuration options for `.planning/` directory behavior.
 
 ```bash
 # Commit with automatic commit_docs + gitignore checks:
-pp-tools query commit "docs: update state" --files .planning/STATE.md
+pp_run query commit "docs(planning): update state" --files .planning/STATE.md
 
 # Load config via state load (returns JSON):
 INIT=$(pp-tools query state.load)
@@ -79,7 +79,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 **Commit via CLI (handles checks automatically):**
 
 ```bash
-pp-tools query commit "docs: update state" --files .planning/STATE.md
+pp_run query commit "docs(planning): update state" --files .planning/STATE.md
 ```
 
 The CLI checks `commit_docs` config and gitignore status internally — no manual conditionals needed.
@@ -121,7 +121,7 @@ To use uncommitted mode:
 3. **Existing tracked files:** If `.planning/` was previously tracked:
    ```bash
    git rm -r --cached .planning/
-   git commit -m "chore: stop tracking planning docs"
+   git commit -m "chore(planning): stop tracking planning docs"
    ```
 
 4. **Branch merges:** When using `branching_strategy: phase` or `milestone`, the `complete-milestone` workflow automatically strips `.planning/` files from staging before merge commits when `commit_docs: false`.

package/pp-core/references/shell-portability.md

@@ -0,0 +1,28 @@
+# Shell portability — commands you write yourself
+
+The Bash tool runs the user's login shell, which is zsh on macOS. Workflow fences already
+start with the guard line below; shell you compose yourself does not, so add it.
+
+**Start every multi-line command with:**
+
+```text
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
+```
+
+It is a no-op under bash. Under zsh it makes the rest of the command behave like bash does:
+
+| Without the guard, zsh… | Example that breaks |
+|---|---|
+| aborts the whole command on a glob that matches nothing (`nomatch`), even with `2>/dev/null \|\| true` | `for f in .planning/phases/*/*-PLAN.md; do …` |
+| expands a word starting with `=` to a command path | `echo ====` → `==== not found` |
+| does not split an unquoted `$var` into words | `set -- $LIST` gives one argument |
+| indexes arrays from 1 | `${a[0]}` is empty |
+
+For a one-line command, prefer the portable form instead:
+
+- **No GNU-only flags.** macOS ships BSD tools: no `grep -P`, no `sed -i` without a suffix
+  argument, no `readlink -f`. Use `grep -E`, `sed -n 's/…/\1/p'`, `sed -i ''` only where you know
+  the platform.
+- **Quote patterns and globs you don't want expanded**, and use `find … -name '*.md'` to list
+  files that may not exist.
+- **Never begin a word with `=`.** Print separators with `printf '%s\n' '===='`.

package/pp-core/references/tdd.md

@@ -96,18 +96,18 @@ After completion, create SUMMARY.md with:
 2. Write test describing expected behavior (from `<behavior>` element)
 3. Run test - it MUST fail
 4. If test passes: feature exists or test is wrong. Investigate.
-5. Commit: `test({phase}-{plan}): add failing test for [feature]`
+5. Commit: `test({area}): add failing test for [feature]` with the trailer `Phase: {phase}-{plan}`
 
 **GREEN - Implement to pass:**
 1. Write minimal code to make test pass
 2. No cleverness, no optimization - just make it work
 3. Run test - it MUST pass
-4. Commit: `feat({phase}-{plan}): implement [feature]`
+4. Commit: `feat({area}): implement [feature]` with the trailer `Phase: {phase}-{plan}`
 
 **REFACTOR (if needed):**
 1. Clean up implementation if obvious improvements exist
 2. Run tests - MUST still pass
-3. Only commit if changes made: `refactor({phase}-{plan}): clean up [feature]`
+3. Only commit if changes made: `refactor({area}): clean up [feature]` with the trailer `Phase: {phase}-{plan}`
 
 **Result:** Each TDD plan produces 2-3 atomic commits.
 </execution_flow>
@@ -215,30 +215,36 @@ Framework setup is a one-time cost included in the first TDD plan's RED phase.
 TDD plans produce 2-3 atomic commits (one per phase):
 
 ```
-test(08-02): add failing test for email validation
+test(validation): add failing test for email validation
 
 - Tests valid email formats accepted
 - Tests invalid formats rejected
 - Tests empty input handling
 
-feat(08-02): implement email validation
+Phase: 08-02
+
+feat(validation): implement email validation
 
 - Regex pattern matches RFC 5322
 - Returns boolean for validity
 - Handles edge cases (empty, null)
 
-refactor(08-02): extract regex to constant (optional)
+Phase: 08-02
+
+refactor(validation): extract regex to constant (optional)
 
 - Moved pattern to EMAIL_REGEX constant
 - No behavior changes
 - Tests still pass
+
+Phase: 08-02
 ```
 
 **Comparison with standard plans:**
 - Standard plans: 1 commit per task, 2-4 commits per plan
 - TDD plans: 2-3 commits for single feature
 
-Both follow same format: `{type}({phase}-{plan}): {description}`
+Both follow same format: `{type}({area}): {description}`, where `{area}` names the part of the codebase, plus the trailer `Phase: {phase}-{plan}`
 
 **Benefits:**
 - Each commit independently revertable
@@ -256,9 +262,9 @@ When `workflow.tdd_mode` is enabled in config, the RED/GREEN/REFACTOR gate seque
 
 | Gate | Required | Commit Pattern | Validation |
 |------|----------|---------------|------------|
-| RED | Yes | `test({phase}-{plan}): ...` | Test exists AND fails before implementation |
-| GREEN | Yes | `feat({phase}-{plan}): ...` | Test passes after implementation |
-| REFACTOR | No | `refactor({phase}-{plan}): ...` | Tests still pass after cleanup |
+| RED | Yes | `test({area}): ...` + `Phase: {phase}-{plan}` | Test exists AND fails before implementation |
+| GREEN | Yes | `feat({area}): ...` + `Phase: {phase}-{plan}` | Test passes after implementation |
+| REFACTOR | No | `refactor({area}): ...` + `Phase: {phase}-{plan}` | Tests still pass after cleanup |
 
 ### Fail-Fast Rules
 
@@ -270,12 +276,10 @@ When `workflow.tdd_mode` is enabled in config, the RED/GREEN/REFACTOR gate seque
 
 After completing a `type: tdd` plan, the executor validates the git log:
 ```bash
-# Check for RED gate commit
-git log --oneline --grep="^test(${PHASE}-${PLAN})" | head -1
-# Check for GREEN gate commit  
-git log --oneline --grep="^feat(${PHASE}-${PLAN})" | head -1
-# Check for optional REFACTOR gate commit
-git log --oneline --grep="^refactor(${PHASE}-${PLAN})" | head -1
+# Gate commits for this plan: type from the subject, plan from the Phase trailer.
+# Expect a test commit (RED), a feat commit (GREEN) and optionally a refactor commit.
+git log --format='%h%x09%s%x09%(trailers:key=Phase,valueonly,separator=%x2C)' \
+  | awk -F'\t' -v id="${PHASE}-${PLAN}" '$2 ~ /^(test|feat|refactor)(\([^)]*\))?!?:/ && ($3 == id || index($2, "(" id "):") > 0)'
 ```
 
 If RED or GREEN gate commits are missing, add a `## TDD Gate Compliance` section to SUMMARY.md with the violation details.

package/pp-core/references/worktree-path-safety.md

@@ -22,6 +22,7 @@ skipping all worktree guards. The sentinel captures the spawn-time toplevel and
 detects drift before every commit.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 if [ -f .git ]; then  # we are in a worktree
   WT_GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
   case "$WT_GIT_DIR" in

package/pp-core/templates/milestone.md

@@ -51,14 +51,14 @@ If MILESTONES.md doesn't exist, create it with header:
 - Minor bug fixes that don't constitute a release
 
 **Stats to include:**
-- Count modified files: `git diff --stat feat(XX-XX)..feat(YY-YY) | tail -1`
+- Count modified files: `git diff --stat FIRST_SHA^..LAST_SHA | tail -1` (find a plan's commits with `git log --format=%h --grep="^Phase: XX-XX$"`)
 - Count LOC: `find . -name "*.swift" -o -name "*.ts" | xargs wc -l` (or relevant extension)
 - Phase/plan/task counts from ROADMAP
 - Timeline from first phase commit to last phase commit
 
 **Git range format:**
-- First commit of milestone → last commit of milestone
-- Example: `feat(01-01)` → `feat(04-01)` for phases 1-4
+- First commit of milestone → last commit of milestone, each named by short sha and its `Phase:` trailer
+- Example: `a1b2c3d` (Phase: 01-01) → `e4f5a6b` (Phase: 04-01) for phases 1-4
 </guidelines>
 
 <example>
@@ -83,7 +83,7 @@ If MILESTONES.md doesn't exist, create it with header:
 - 2 phases, 3 plans, 12 tasks
 - 8 days from v1.0 to v1.1
 
-**Git range:** `feat(05-01)` → `feat(06-02)`
+**Git range:** `3c9d2e1` (Phase: 05-01) → `7f0a4b8` (Phase: 06-02)
 
 **What's next:** v2.0 SwiftUI redesign with widget support
 
@@ -108,7 +108,7 @@ If MILESTONES.md doesn't exist, create it with header:
 - 4 phases, 7 plans, 28 tasks
 - 12 days from start to ship
 
-**Git range:** `feat(01-01)` → `feat(04-01)`
+**Git range:** `a1b2c3d` (Phase: 01-01) → `e4f5a6b` (Phase: 04-01)
 
 **What's next:** Security audit and hardening for v1.1
 ```

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

@@ -64,7 +64,7 @@ touch "${PHASE_DIR}/.gitkeep"
 ## Step 5: Commit
 
 ```bash
-pp_run query commit "docs: add backlog item ${NEXT} — ${ARGUMENTS}" --files .planning/ROADMAP.md "${PHASE_DIR}/.gitkeep"
+pp_run query commit "docs(planning): add backlog item ${NEXT} — ${ARGUMENTS}" --files .planning/ROADMAP.md "${PHASE_DIR}/.gitkeep"
 ```
 
 ## Step 6: Report

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

@@ -84,6 +84,7 @@ gate on the `execute:pre` payload, filtered in the fence to the `vault`
 capability (D-30):
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 AT_EXECUTE_PRE_HOOKS_JSON=$(pp_run loop render-hooks execute:pre --raw | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const j=JSON.parse(d);j.activeHooks=(j.activeHooks||[]).filter((x)=>x&&x.capId==='vault');process.stdout.write(JSON.stringify(j));}catch{process.stdout.write('');}")
 printf '%s' "$AT_EXECUTE_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('AT_EXECUTE_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 ```
@@ -186,6 +187,7 @@ If user selects "Cancel": exit gracefully.
 Before generating the test plan, discover the project's existing test structure:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 # Find existing test directories
 find . -type d -name "*test*" -o -name "*spec*" -o -name "*__tests__*" 2>/dev/null | head -20
 # Find existing test files for convention matching
@@ -349,7 +351,8 @@ If there are passing tests to commit:
 
 ```bash
 git add {test files}
-git commit -m "test(phase-${phase_number}): add unit and E2E tests from add-tests command"
+# {area}: the part of the codebase the tests cover; drop "({area})" when no single area fits
+git commit -m "test({area}): add unit and E2E tests from add-tests command" -m "Phase: ${padded_phase}"
 ```
 
 Vault door record (D-12): after the door's last source commit, set `DOOR_DIR="${phase_dir}"`,
@@ -364,7 +367,7 @@ The verb writes a `## Vault Door Record` (mode, vault ref and sha, governing pha
 recorded and the end commit; the agent never types a sha) into a fresh per-run artifact, because it refuses a second record
 in one file (D-57) and a rewritten report would drop the earlier run's coverage (D-79). It prints
 nothing and writes nothing unless `vault admission` answers `on`. When it wrote the file and
-`commit_docs` is true, commit the `artifact` path it printed: `pp_run query commit "docs(phase-${phase_number}): vault door record for add-tests" --files "<that artifact>"`.
+`commit_docs` is true, commit the `artifact` path it printed: `pp_run query commit "docs(planning): vault door record for add-tests" --phase "${padded_phase}" --files "<that artifact>"`.
 
 Present next steps:
 

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

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

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

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

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

@@ -110,6 +110,7 @@ gate on the `execute:pre` payload, filtered in the fence to the `vault`
 capability (D-30):
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 AF_EXECUTE_PRE_HOOKS_JSON=$(pp_run loop render-hooks execute:pre --raw | node -e "const d=require('fs').readFileSync(0,'utf-8');try{const j=JSON.parse(d);j.activeHooks=(j.activeHooks||[]).filter((x)=>x&&x.capId==='vault');process.stdout.write(JSON.stringify(j));}catch{process.stdout.write('');}")
 printf '%s' "$AF_EXECUTE_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('AF_EXECUTE_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 ```
@@ -168,9 +169,9 @@ fi
 **c. If tests pass** — commit atomically:
 ```bash
 git add {changed_files}
-git commit -m "fix({scope}): resolve {ID} — {description}"
+git commit -m "fix({area}): resolve {ID} — {description}"
 ```
-The commit message **must** include the finding ID (e.g., F-01) for traceability.
+`{area}` names the part of the codebase the fix touches (`auth`, `billing`); omit `({area})` when no single area fits. The commit message **must** include the finding ID (e.g., F-01) for traceability.
 
 **d. If tests fail** — revert changes, mark finding as `fix-failed`, and **stop the pipeline**:
 ```bash
@@ -200,7 +201,7 @@ The verb writes a `## Vault Door Record` (mode, vault ref and sha, governing pha
 recorded and the end commit; the agent never types a sha) into a fresh per-run artifact, because it refuses a second record
 in one file (D-57) and a rewritten report would drop the earlier run's coverage (D-79). It prints
 nothing and writes nothing unless `vault admission` answers `on`. When it wrote the file and
-`commit_docs` is true, commit the `artifact` path it printed: `pp_run query commit "docs: vault door record for audit-fix" --files "<that artifact>"`.
+`commit_docs` is true, commit the `artifact` path it printed: `pp_run query commit "docs(planning): vault door record for audit-fix" --files "<that artifact>"`.
 </step>
 
 <step name="report">

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

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