@pareto4/pp-core 1.17.1 → 1.19.0

package/pp-core/bin/pp-tools.cjs

@@ -19,8 +19,8 @@
  *   state signal-resume                Remove WAITING.json signal
  *   resolve-model <agent-type>         Get model for agent based on profile
  *   find-phase <phase>                 Find phase directory by number
- *   commit <message> [--files f1 f2] [--no-verify]   Commit planning docs
- *   commit-to-subrepo <msg> --files f1 f2  Route commits to sub-repos
+ *   commit <message> [--files f1 f2] [--phase id] [--quick id] [--no-verify]   Commit planning docs
+ *   commit-to-subrepo <msg> --files f1 f2 [--phase id]  Route commits to sub-repos
  *   verify-summary <path>              Verify a SUMMARY.md file
  *   generate-slug <text>               Convert text to URL-safe slug
  *   current-timestamp [format]         Get timestamp (full|date|filename)
@@ -748,32 +748,10 @@ function createReadlinePrompter({ input = process.stdin, output = process.stdout
   };
 }
 
-/**
- * The vault mode a mode-filtered hook is judged against (Phase 15 D-02). Built
- * here, at the CLI entry, so the pure resolvers (`loop-resolver`,
- * `capability-state`) never import the vault adapter. It asks
- * `vaultModeVerdict`, the single mode owner that honours the org-profile
- * ladder, and answers the mode only for an active gate with a cleanly
- * resolved mode. Anything else, including a throw, is `null`: the undefined
- * mode, fail-closed per D-28. `vault.cjs` is required lazily so commands that
- * never render hooks do not load it.
- */
-function makeVaultModeResolver(cwd) {
-  return () => {
-    try {
-      const v = require('./lib/vault.cjs').vaultModeVerdict(cwd);
-      return v.active && v.ok ? v.mode : null;
-    } catch {
-      return null;
-    }
-  };
-}
-
 /**
  * Does this project hold engine-written vault records? (Phase 16 D-19.) The
  * predicate a seal gate (`onRecordedArtifacts: true`) is rendered under, built
- * here at the CLI entry for the same reason as `makeVaultModeResolver`: the
- * pure resolver never imports vault code. It asks the seal leaf's
+ * here at the CLI entry so the pure resolver never imports vault code. It asks the seal leaf's
  * `hasRecordedVaultArtifacts`, which is bindings-first (D-42) and answers true
  * when it cannot prove absence (D-44). A throw is `false`, the inert answer.
  * Injected ONLY into `loop render-hooks`: `capability state` / `set` report
@@ -793,8 +771,8 @@ function makeRecordedArtifactsResolver(cwd) {
 
 /**
  * Quick 261015-ect (QD-13): the `.platform-bindings.json` measurement
- * `loop render-hooks` injects, built here at the CLI entry for the same reason
- * as `makeVaultModeResolver`: the resolver imports no vault code (D-02). The
+ * `loop render-hooks` injects, built here at the CLI entry so the resolver
+ * imports no vault code (D-02). The
  * reader is EXISTENCE, admission's own step 1 (`hasPlatformBindings`), so a
  * malformed file counts as present and the fence's `vault admission` decides
  * (D-47 b). A throw answers `null`, "could not measure", which the resolver
@@ -912,7 +890,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       // (D-07-04), which is what stops a committed deferral from passing
       // silently forever.
       // --arm-vault (quick 261003-kmd): non-interactive — composes the
-      // client-vault binding from the resolved org profile and arms the three
+      // client-vault binding from the resolved org profile and arms the two
       // vault keys where absent; /pp-new-project calls it. Inert (exit 0,
       // armed:false) when no profile resolves; ok:false means run /pp-init.
       const icArgs = args.slice(1);
@@ -1180,6 +1158,10 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
     }
 
     case 'commit': {
+      // --phase <id> / --quick <id> add a `Phase:` / `Quick:` trailer; pulled out
+      // first so their values are never read as message words or --files paths.
+      const trailerArgs = commands.extractCommitTrailerArgs(args);
+      args = trailerArgs.args;
       const amend = args.includes('--amend');
       const noVerify = args.includes('--no-verify');
       const filesIndex = args.indexOf('--files');
@@ -1190,7 +1172,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       const messageArgs = args.slice(1, endIndex).filter(a => !a.startsWith('--'));
       const message = messageArgs.join(' ') || undefined;
       const files = filesIndex !== -1 ? args.slice(filesIndex + 1).filter(a => !a.startsWith('--')) : [];
-      commands.cmdCommit(cwd, message, files, raw, amend, noVerify);
+      commands.cmdCommit(cwd, message, files, raw, amend, noVerify, { phase: trailerArgs.phase, quick: trailerArgs.quick });
       break;
     }
 
@@ -1200,10 +1182,12 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
     }
 
     case 'commit-to-subrepo': {
+      const trailerArgs = commands.extractCommitTrailerArgs(args);
+      args = trailerArgs.args;
       const message = args[1];
       const filesIndex = args.indexOf('--files');
       const files = filesIndex !== -1 ? args.slice(filesIndex + 1).filter(a => !a.startsWith('--')) : [];
-      commands.cmdCommitToSubrepo(cwd, message, files, raw);
+      commands.cmdCommitToSubrepo(cwd, message, files, raw, { phase: trailerArgs.phase, quick: trailerArgs.quick });
       break;
     }
 
@@ -1723,7 +1707,6 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
           configDir: loopConfigDir ? path.resolve(loopConfigDir) : undefined,
           activeCap: loopActiveCap,
           into: loopInto,
-          resolveVaultMode: makeVaultModeResolver(cwd),
           resolveRecordedArtifacts: makeRecordedArtifactsResolver(cwd),
           resolvePlatformBindingsPresent: makePlatformBindingsPresentResolver(cwd),
         });
@@ -1756,9 +1739,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
           configDir = configDirVal;
         }
         const resolvedConfigDir = configDir ? path.resolve(configDir) : null;
-        capabilityState.cmdCapabilityState(cwd, resolvedConfigDir, raw, {
-          resolveVaultMode: makeVaultModeResolver(cwd),
-        });
+        capabilityState.cmdCapabilityState(cwd, resolvedConfigDir, raw);
       } else if (capSubcommand === 'set') {
         // capability set <id> [--on|--off|--enable|--disable] [--gate <key>=<bool>]... [--config-dir <dir>] [--runtime <r>] [--scope <s>]
         const capId = args[2];
@@ -1837,8 +1818,6 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
             gates: Object.keys(setGates).length > 0 ? setGates : undefined,
             runtime: setRuntime,
             scope: setScope,
-            // 15-REVIEW WR-07: the same mode `capability state` and render-hooks use.
-            resolveVaultMode: makeVaultModeResolver(cwd),
           },
           raw,
         );

package/pp-core/org-profile.json

@@ -11,7 +11,7 @@
       "repo": "pareto000/Pareto-Platform"
     },
     "client": {
-      "vaultRepo": "pareto000/Pareto-Vault",
+      "vaultRepo": "pareto-ooo/pareto-vault-releases",
       "vaultHost": "github.com"
     },
     "provisioning": {

package/pp-core/references/autonomous-best-effort.md

@@ -83,7 +83,7 @@ grep -q "^handled=${PHASE_NUM}:" "$RUN_STATE" 2>/dev/null ||
   printf 'handled=%s:%s\n' "$PHASE_NUM" "$OUTCOME" >> "$RUN_STATE"
 PADDED_PHASE=$(basename "$PHASE_DIR" | cut -d- -f1)
 if [ -f "$REPORT" ]; then
-  pp_run query commit "docs(${PADDED_PHASE}): autonomous report" --files "$REPORT"
+  pp_run query commit "docs(planning): autonomous report" --phase "${PADDED_PHASE}" --files "$REPORT"
 fi
 ```
 
@@ -302,7 +302,7 @@ calls (`pp-ui-phase`, `pp-code-review`, `pp-ui-review`) and the agents on the pa
 | execute-phase/steps/worktree-recovery-policy.md exit 42; execute-phase partial-execution recovery | hard stop (fail closed) |
 | execute-phase `state_exists` false; `--interactive` per-plan menu | unreachable — autonomous requires STATE.md and never passes `--interactive` to execute-phase |
 | post-merge-gate | build-failure "Fix now / Continue" (step 5.8) — this is the U-E2 site: fix once, then continue and record |
-| codebase-drift-gate, per-plan-worktree-gate, execute-pre-dispatch, verify-post-gate, verifier-practice-payload | no prompt (non-blocking or gate-enforcer only) |
+| codebase-drift-gate, per-plan-worktree-gate, execute-pre-dispatch, verify-post-gate | no prompt (non-blocking or gate-enforcer only) |
 | `pp-code-review --fix --auto` (3c.5) | no prompt |
 | **`pp-ui-phase`** (§3a.5-ii): step 9 max-revision choice, and its `pp-ui-researcher` design questions | **remaining stop** — ui-phase has no non-interactive flag; filed as deferred |
 | **`pp-ui-review`** (§3d.5): "UI-REVIEW.md already exists" | **remaining stop** (only on a re-run) — no non-interactive flag; filed as deferred |
@@ -400,6 +400,7 @@ phase. Printed by the lifecycle single-phase banner, the STOPPED banner and the
 Used by `autonomous.md` §3a when `workflow.skip_discuss` is true. Get phase details:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 DETAIL=$(pp_run query roadmap.get-phase ${PHASE_NUM})
 ```
 
@@ -452,7 +453,7 @@ None — discuss phase skipped.
 Commit the minimal context:
 
 ```bash
-pp_run query commit "docs(${padded_phase}): auto-generated context (discuss skipped)" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+pp_run query commit "docs(planning): auto-generated context (discuss skipped)" --phase "${padded_phase}" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
 ```
 
 ## Banner math

package/pp-core/references/autonomous-lifecycle.md

@@ -109,6 +109,7 @@ Skill(skill="pp-complete-milestone", args="${milestone_version}")
 After complete-milestone returns, verify it produced output:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls .planning/milestones/v${milestone_version}-ROADMAP.md 2>/dev/null || true
 ```
 

package/pp-core/references/autonomous-smart-discuss.md

@@ -5,6 +5,7 @@ Smart discuss is the autonomous-optimized variant of `pp-discuss-phase`. It prop
 **Inputs:** `PHASE_NUM` from execute_phase. Run init to get phase paths:
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 PHASE_STATE=$(pp-tools query init.phase-op ${PHASE_NUM})
 ```
 
@@ -34,6 +35,7 @@ Extract from these:
 **Read all prior CONTEXT.md files:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 (find "$(dirname "$STATE_PATH")/phases" -name "*-CONTEXT.md" 2>/dev/null || true) | sort
 ```
 
@@ -68,6 +70,7 @@ Lightweight codebase scan to inform grey area identification and proposals. Keep
 **Check for existing codebase maps:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls .planning/codebase/*.md 2>/dev/null || true
 ```
 
@@ -96,6 +99,7 @@ Read the 3-5 most relevant files to understand existing patterns.
 **Get phase details:**
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 DETAIL=$(pp-tools query roadmap.get-phase ${PHASE_NUM})
 ```
 
@@ -270,7 +274,7 @@ Write the file.
 **Commit:**
 
 ```bash
-pp-tools query commit "docs(${PADDED_PHASE}): smart discuss context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+pp_run query commit "docs(planning): smart discuss context" --phase "${PADDED_PHASE}" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
 ```
 
 Display confirmation:

package/pp-core/references/discovery-id-conventions.md

@@ -17,12 +17,13 @@ never `@`-imported.
 | Data-gathering items | `DG-<nn>` — same shape as SP. Regex: `DG-\d{2}` | `DG-07` | Open data-gathering items in `_risks.md` |
 | Research items | `RS-<nn>` — same shape as SP/DG: zero-padded 2-digit global sequence, no session component. Regex: `RS-\d{2}` | `RS-01` | Rows of `_research.md`, the research-only backlog |
 | Screens | `SCR-<nn>` — zero-padded 2-digit global sequence, no session and no role component, minted by scan (D-12). Regex: `SCR-\d{2}` | `SCR-01` | Rows of `_screens.md`, the requirement-to-screen inventory; Role is a grouping column, not part of the ID (D-50) |
+| Processes | `PRC-<nn>` — zero-padded 2-digit global sequence. Regex: `PRC-\d{2}` | `PRC-03` | Rows of the Session 2 **Process Inventory**, the as-is processes Session 3 transforms |
 | Requirements | `<PREFIX><n>` — PREFIX is a registered domain prefix (uppercase letters/digits ending in `-`, e.g. a stakeholder-domain prefix, `N-` non-functional, `T-` technical); `<n>` is a numeric sequence, zero-padded to 2 digits by convention (`01`..`99`, then `100`). Regex: `[A-Z][A-Z0-9]*-\d+` | `N-01` | Rows of `_requirements.md`; the prefix carries the classification — there is no separate Type column |
 | Input-package accessions | `NN` — zero-padded 2-digit number, assigned in arrival order and never renumbered; a mid-sprint document takes the next number (D-16). Regex: `\d{2}` | `03` | Numbered documents in `.planning/discovery-input/` (including its `confidential/` subdir — one number space spans both locations, D-21). Reading order is a README column, not the number |
 
 ## Reserved Prefixes
 
-Six prefixes are reserved by the ID families above and MUST NOT be registered as
+Seven prefixes are reserved by the ID families above and MUST NOT be registered as
 domain prefixes in the `_requirements.md` Prefix Registry:
 
 | Reserved | Owned by |
@@ -33,6 +34,7 @@ domain prefixes in the `_requirements.md` Prefix Registry:
 | `DG-` | Data-gathering items |
 | `RS-` | Research items |
 | `SCR-` | Screens |
+| `PRC-` | Processes |
 
 Every one of them satisfies the requirement-ID regex `[A-Z][A-Z0-9]*-\d+`, so a
 registry that claims one mints requirement IDs indistinguishable from the family that
@@ -43,7 +45,11 @@ collide, and no reader or parser can tell them apart.
 sequence, so a registry claiming `SCR-` would make `SCR-01` ambiguous between a screen
 and a requirement — the same collision, one artifact further along the traceability ring.
 
-Session 1's kick-off prefix selection (D-09) must refuse all six: pick a different
+`PRC-` followed with issue #12: Session 2 used to number processes `P-<nn>`, which an
+engagement had also registered as a domain prefix, so `P-03` meant two things. Process IDs
+moved to `PRC-` and the prefix is reserved so the clash cannot come back.
+
+Session 1's kick-off prefix selection (D-09) must refuse all seven: pick a different
 domain prefix (any other uppercase letters/digits ending in `-`, e.g. `K-` for *Klant*).
 Non-reserved prefixes are unaffected.
 
@@ -53,6 +59,33 @@ registry, so its requirement rows also report `unknown_prefix`. The check is ret
 — an engagement that registered one of these before the rule existed turns red on
 upgrade. The remedy is the same: choose a different domain prefix.
 
+## Session-Table Row IDs
+
+The Notes Templates number some table rows with their own short prefixes. These IDs are
+local to their table: they are not requirements, never enter `_requirements.md`, and are
+not reserved — but Session 1 should not propose a domain prefix that repeats one, or a
+citation such as `C-01` reads two ways.
+
+| Prefix | Table | Session |
+|--------|-------|---------|
+| `CON-` | Constraints and Risks Register (constraints) | 1 |
+| `R-` | Constraints and Risks Register (risks), continued by the Risk Register | 1, 11 |
+| `PP-` | Pain Points Register | 2 |
+| `MP-` | Main Process Register | 3 |
+| `BO-` | Business Objectives | 3 |
+| `E-` | EPIC Register | 3 |
+| `US-` | User Stories | 3 |
+| `C-` | Component Inventory | 5 |
+| `INT-` | Integration Points Map | 5 |
+| `ADR-` | Architecture Decision Records | 5 |
+| `CR-` | Compliance Requirements Register | 6 |
+| `IF-` | Integration Design Register | 8 |
+| `OI-` | Open Items Register | 13 |
+
+Non-functional requirements are not in this list: they are `N-` rows of
+`_requirements.md`, minted like every other requirement, and Session 3's
+**Non-Functional Requirements** table cites them by that ID.
+
 ## Citation Rules
 
 - Requirement IDs are never renumbered and never reused (REQM-02). A gap in a sequence

package/pp-core/references/execute-mvp-tdd.md

@@ -15,11 +15,11 @@ If any of these is false, the gate is inactive — execution proceeds normally.
 
 For each task gated by MVP+TDD, the executor MUST verify (before running the implementation step):
 
-1. **A failing-test commit exists.** Search git log on the current branch for a commit matching `test({phase}-{plan})` whose subject mentions the same plan as the current task. The commit must touch a test file (`*.test.*`, `*.spec.*`, `tests/**`).
+1. **A failing-test commit exists.** Search git log on the current branch for a commit of type `test` (any scope) that carries the trailer `Phase: {phase}-{plan}` for the same plan as the current task. The commit must touch a test file (`*.test.*`, `*.spec.*`, `tests/**`).
 2. **The test was actually red.** The commit message body or the executor's recent shell history must show the test failed when first run. Acceptable evidence:
    - Commit message contains `RED:` prefix or `(RED)` tag
    - Recent terminal output shows `FAIL` or non-zero exit on the new test before any implementation commit
-3. **No implementation commit yet.** No `feat({phase}-{plan})` commit may exist for the same plan ID before the failing-test commit.
+3. **No implementation commit yet.** No `feat` commit carrying the trailer `Phase: {phase}-{plan}` may exist before the failing-test commit.
 
 If any check fails, the gate trips.
 
@@ -51,7 +51,7 @@ The executor MUST:
 
    Required next step:
    1. Write a failing test for the behavior above.
-   2. Commit it as: test({phase}-{plan}): {short description}
+   2. Commit it as: test({area}): {short description} — with the trailer Phase: {phase}-{plan}
    3. Re-run /pp:execute-phase
    ```
 

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