@pareto4/pp-core 1.18.0 → 1.20.0

package/pp-core/references/discovery-standards.md

@@ -0,0 +1,107 @@
+# Discovery Standards First — `_deviations.md` Template, Parser Contract & the Standards Applied Table
+
+Single home for how the Discovery Sprint treats the client's standards once a vault is bound
+(Discovery Sprint improvement plan, Batch 3): the questions the vault already answers are not asked
+open-ended, every session from 4 to 10 records which standard governs each area in a **Standards
+Applied** table, and every departure from a standard is one `DEV-` row of `_deviations.md` — the
+register the charter § 7 copies, the handoff gates on, and `pp-vault-review` reads so an approved
+deviation is reported as a deviation on file, never as a violation. This file is Read lazily; it is
+never `@`-imported.
+
+## Standards first — the question rule
+
+When a session's `## Vault Context` record names a document that already fixes what a topic asks the
+client to decide, the facilitator does not ask the open question. The question becomes:
+
+> The vault fixes `<what>` — `[vault: <path>]`. Does this product deviate, and why?
+
+- **No deviation:** the Standards Applied row cites the standard, `Deviation` reads `none`. Nothing
+  else is written — the vault stays the single home of the standard (never copy its text).
+- **A deviation:** mint one `DEV-<nn>` row in `.planning/discovery/_deviations.md` (create the file
+  from the template below on first need), record the decision as a Key Decisions row `D-<ss>-<n>` and
+  write both IDs into the Standards Applied row (`Deviation` = the `DEV-nn`, `Decision` = the `D-ss-n`).
+- **No standard covers the area:** the Standards Applied row reads `not in vault`; the question stays
+  open-ended and the answer is a Key Decisions row; add an Action Items row for the vault owner when
+  the gap should be closed in the vault.
+- **No vault bound** (the session record says `Index: none`, or the project runs without the vault
+  capability): every question stays open-ended, Standards Applied rows read `not in vault`, and
+  `_deviations.md` is never created — there is no standard to deviate from.
+
+The session files phrase their stack and tooling questions in this shape; the vault document to cite
+is the one the session's `## Vault Context` record selected for that topic.
+
+## The Standards Applied table
+
+Every session from 4 to 10 carries one, in its Notes Template, with the areas the session decides:
+
+| Area | Standard | Deviation | Decision |
+|------|----------|-----------|----------|
+
+- **Standard** is the governing document's `[vault: <rel path>]` citation (several, space-separated,
+  when more than one applies), or `not in vault`.
+- **Deviation** is `none`, or the `DEV-<nn>` of the `_deviations.md` row.
+- **Decision** is `—`, or the `D-<ss>-<n>` that records the deviation or the decision taken for an
+  uncovered area.
+
+The charter § 7 reads `_deviations.md`, not these tables; the tables are where a reader of one
+session sees which standards bound it. Session 4 introduced the shape (frontend standards); Sessions
+5–10 follow it.
+
+## `_deviations.md`
+
+A deviation is a choice that goes against a standard the vault states. The vault's own rule
+(`architecture/deviations.md` in the Pareto vault, and its equivalent elsewhere): deviating is
+allowed, hiding it is not; an architect signs every one; only what is **hard to reverse** waits for
+the signature before the dependent work proceeds, and a security or compliance deviation is always
+hard. The register carries exactly that record.
+
+Illustration only — not part of the template:
+
+| ID | Standard | Choice | Reason | Reversible | Approver | Decision | Status |
+|---|---|---|---|---|---|---|---|
+| DEV-01 | [vault: pipeline/quality-gates.md] | Trivy and CodeQL instead of SonarCloud | Free plan, one-person team | easy | Architect | D-09-3 | Approved |
+
+Bootstrap template — the first session that records a deviation copies it verbatim to
+`.planning/discovery/_deviations.md`, replacing `[PROJECT_NAME]`:
+
+```markdown
+# Deviations from standards — [PROJECT_NAME]
+
+**Conventions:** pp-core reference `references/discovery-standards.md`. One `DEV-` row per departure from a vault standard: the standard as a `[vault: <path>]` citation, the choice made instead, why, whether it is `easy` or `hard` to reverse (a security or compliance deviation is always `hard`), who approves it (an approver of Session 1's Approval Matrix), the `D-<ss>-<n>` that recorded it and its status (`Proposed`, `Approved`, `Rejected`, `Superseded`). A hard deviation is approved before the handoff. Rows are never renumbered or deleted; a change after sign-off edits the row in place and appends `→ amended by D-<ss>-<n>`.
+
+## Deviations
+
+| ID | Standard | Choice | Reason | Reversible | Approver | Decision | Status |
+|----|----------|--------|--------|------------|----------|----------|--------|
+```
+
+### Parser contract — `pp_run query discovery.deviations-check [--require-approved]`
+
+No positional path. Faults name the artifact, the 1-based line, a validated ID or path, a column name
+and the reason code — never cell prose. Absent `_deviations.md` → exit 0, `present: false`.
+
+| Cell / field | Grammar | Fault when violated |
+|---|---|---|
+| `## Deviations` | once, holding one table with the template's columns | `missing_section`, `bad_table_shape` |
+| `ID` | `DEV-\d{2}`, unique, contiguous from 01 | `bad_id`, `duplicate_id`, `sequence_gap` naming the missing ID |
+| `Standard` | at least one `[vault: <path>]`; each path relative, no `..` or dot segment, ending `.md`, and present in the vault cache when `.planning/vault/` is on disk | `bad_standard` (no citation, or an unsafe path); `unknown_standard` naming the path. **Not resolved** while there is no cache |
+| `Choice`, `Reason` | non-empty | `empty_cell` naming the column |
+| `Reversible` | `easy` \| `hard` | `bad_reversible` |
+| `Approver` | non-empty; one of the `Approver` tokens of Session 1's **Approval Matrix** when that table is on file with rows | `empty_cell (Approver)`; `unknown_approver`. **Not resolved** while Session 1 has no matrix (an engagement that predates it) |
+| `Decision` | `—`, or `D-<ss>-<n>` / `D-P<nn>-<n>` (shape only — `charter-check` resolves it) | `bad_decision`; `decision_missing` when `Status` is `Approved` or `Rejected` and the cell is `—` |
+| `Status` | `Proposed` \| `Approved` \| `Rejected` \| `Superseded` | `bad_status` |
+| a `hard` row still `Proposed` | approved before the handoff | `hard_deviation_unapproved` under `--require-approved` only |
+| `session-01.md` present but unreadable | present-and-readable | `artifact_unreadable` naming the path |
+
+**Exit identity.** `discovery_deviations_check_failed` for structural faults;
+`discovery_deviations_unapproved` when every fault is a `hard_deviation_unapproved`. Payload: `ok`,
+`present`, `file`, `deviations`, `approved`, `unapproved_hard`.
+
+## Who reads it
+
+| Reader | Contract |
+|---|---|
+| Project Charter § 7 | copies every row; `charter-check` resolves `DEV-` IDs against this file alone and reports `deviation_missing` for a row the charter leaves out (`references/discovery-charter.md`) |
+| `/pp-discovery-to-build` | `deviations-check --require-approved` hard-blocks on a hard deviation still `Proposed` (`workflows/discovery-to-build/steps/handoff-gates.md`) |
+| `pp-vault-review` | reads `Standard` and `Status` by header name; an `Approved` row covering a failed clause turns the FAIL into `N-A` "deviation on file" (`references/discovery-build-consumption.md` § `_deviations.md` read contract) |
+| `discovery for-phase` | the register has no requirement column, so every extract lists it as not filterable — the planner reads it whole |

package/pp-core/references/discovery-traceability.md

@@ -14,8 +14,8 @@ does not restate them. Read that file when you need an ID's shape or the reserve
 
 ## When these files appear
 
-Both artifacts are bootstrapped **on first need**, exactly the way `_progress.md` and
-`_context.md` are in Flow 2 Step 1, and exactly the way the three research-track registers
+Both artifacts are bootstrapped **on first need**, exactly the way `_progress.md`
+is in Flow 2 Step 1, and exactly the way the three research-track registers
 are in `references/discovery-research-track.md`: if the file is absent when a session first
 has something to put in it, create it verbatim from the template below, then add the row.
 There is no sub-command and no setup step — an empty inventory is not a milestone, and an

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-discovery-extract.md

@@ -0,0 +1,35 @@
+# Discovery extract — the planner and researcher contract (R1)
+
+**Load this file when a `{padded}-DISCOVERY-EXTRACT.md` is listed in your files to read** — the
+plan-phase orchestrator renders it with `pp_run query discovery.for-phase <N> --markdown` on a
+project that ran the Discovery Sprint (contract: `references/discovery-build-consumption.md`).
+When no such file is listed, nothing described here applies.
+
+The extract holds the rows of the Discovery registers (`_requirements.md`, `_stories.md`,
+`_processes.md`, `_entities.md`, `_rules.md`, `_screens.md`, roles, integrations) that cite this
+phase's requirement IDs. It is the client's signed-off fact base for this phase.
+
+## Planner
+
+1. **Required reading.** Read the extract in full before planning.
+2. **Never open `.planning/discovery/session-NN.md`.** The session files are the facilitation
+   record; the registers are the source of truth, amended in place. A fact you need that the
+   extract lacks is a question for the user — surface it under Claude's Discretion or the plan's
+   open questions — not a reason to read a transcript.
+3. **Cite rows, do not restate them.** A task that realises a step cites `MP-01 #3`; a validation
+   task cites `BR-02`; a data task cites the entity by name; a screen task cites `SCR-04`. Put the
+   row's acceptance criteria (`_requirements.md`, `_stories.md`) into the task's
+   `<acceptance_criteria>` verbatim — they are the verifier's UAT (R3).
+4. **Embed verbatim.** Copy the file's content byte for byte, `<!-- discovery:auto -->` markers
+   included, as the `<discovery_extract>` block of every PLAN.md of this phase, after `<context>`
+   (after `<vault_standards>` when present) and before `<tasks>`. Never edit a cell: a discovery
+   fact that must change is amended in the register by `/pp-discuss-phase` (R2), then re-rendered.
+5. **Contradictions are findings.** If the extract contradicts CONTEXT.md, the codebase or itself,
+   plan nothing on the contradiction — name both sides in the plan's open questions.
+
+## Researcher
+
+Research HOW to build what the rows say, never WHETHER: entities, rules, process steps, screens
+and acceptance criteria here are decided. List the entities, integrations and rules the extract
+names under `## User Constraints` as "Discovery facts (by row ID)" so the planner sees them beside
+the locked decisions. Rule 2 above applies in full.

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' '===='`.