@pareto4/pp-core 1.18.0 → 1.20.0

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/verifier-discovery-conformance.md

@@ -0,0 +1,36 @@
+# Discovery conformance — the verifier contract (R3)
+
+**Load this file from pp-verifier Step 6d on a project that ran the Discovery Sprint** (contract:
+`references/discovery-build-consumption.md`). Planning read the Discovery registers; verification
+is where conformance is enforced — "did we build what was signed" is answered per phase.
+
+```bash
+DISCOVERY_CONFORMANCE=$(pp_run query discovery.for-phase "$PHASE_NUM" --conformance-template 2>/dev/null || true)
+```
+
+Empty output means no `.planning/discovery/` — write no block and stop here. A non-zero exit is a
+structural fault in a discovery register: record it as a gap naming the fault list.
+
+Otherwise the output is the **Discovery conformance** block: one row per Discovery register row
+that cites this phase's requirement IDs (`_requirements.md`, `_stories.md`, `_processes.md` steps,
+`_entities.md`, `_rules.md`, `_screens.md`, roles, integrations), every row `missed`. Fill it:
+
+1. **The acceptance criteria ARE the UAT.** Each `_requirements.md` and `_stories.md` row's
+   acceptance criteria is a truth in Step 3 — add any the plans' `must_haves` omitted — verified
+   by the same evidence rules as every other truth.
+2. **One status per row**, exactly one of:
+   - `honoured` — evidence that the build realises the row (`file:line`, a test name) in `Evidence`;
+   - `amended (D-P<nn>-<n>)` — the register cell carries `→ amended by` that decision and the build
+     matches the amended cell; name the cell in `Evidence`;
+   - `missed` — no evidence, or the build contradicts the row; say which in `Evidence`.
+3. **Never add, remove or rename a row**; never open a `.planning/discovery/session-NN.md` — the
+   register row is the fact, and `--verify` refuses an unknown or missing row.
+4. **A `missed` row is a gap.** It fires rule 1 of Step 9 (`gaps_found`) and appears in the Gaps
+   Summary with its row key (`_rules.md BR-02`).
+5. **Paste the filled block into VERIFICATION.md** under `### Discovery conformance`, markers
+   included, after Requirements Coverage. Then run
+
+   `pp_run query discovery.for-phase "$PHASE_NUM" --verify "$REPORT_PATH"`
+
+   and repair the block until it exits 0 (markers once each, header, every row present once, legal
+   statuses). A `missed` count is never a fault of the block.

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/templates/project-charter.md

@@ -1,32 +1,51 @@
 # Project Charter Template
 
-Template for `.planning/discovery/PROJECT-CHARTER.md`, the document every stakeholder signs at the end
-of a Discovery Sprint.
+Template for `docs/discovery/PROJECT-CHARTER.md`, the document every stakeholder signs at the end of a
+Discovery Sprint. It lives under `docs/` because it is client-visible, like `docs/architecture/`;
+`.planning/discovery/` holds the facilitation record it condenses.
 
 **Purpose:** one short, fixed-shape document that states what will be built, why, for whom, how it will
-be delivered and on what conditions, so that sign-off is a decision on the same questions in the same
-order for every engagement. It summarises the thirteen session files; it does not replace them.
-
-**When:** after Session 13 (wrap-up and Go / No-Go), before `/pp-discovery-to-build`.
-
-**Shape is fixed.** Every charter has the same 14 numbered sections in the same order, with the same
-headings and the same table columns. A section with nothing to report stays in place and says so; it is
-never dropped, merged or renumbered. That is what lets a reader compare two charters side by side.
+be delivered, where it departs from the standards and on what conditions, so that sign-off is a decision
+on the same questions in the same order for every engagement. It summarises the thirteen session files
+and the discovery registers; it does not replace them.
+
+**When:** drafted in Session 13 Step 0.5 (after the cross-reference, before the wrap-up topics), reviewed
+in topics 2–3, set to `For sign-off` at the Closing Step, and required `Signed` or `Signed with
+conditions` by `/pp-discovery-to-build`. The drafting procedure is
+`workflows/discovery-sprint/charter.md`; the parser contract and the heading translations are in
+`references/discovery-charter.md`.
+
+**Shape is fixed.** Every charter has the same 20 numbered sections in the same order, with the same
+table columns. A section with nothing to report stays in place and says so; it is never dropped, merged
+or renumbered. That is what lets a reader compare two charters side by side, and what lets
+`pp_run query discovery.charter-check` verify one.
+
+**Language.** The charter is written in the sprint language — the `Charter language` row of Session 1's
+Sprint Logistics, else `discovery.language` in `.planning/config.json`, else the language the sprint
+was facilitated in. Headings, labels and prose are translated; the `<!-- charter:<key> -->` heading
+keys, the frontmatter fields and every enum cell (`status`, `go_no_go`, `Green / Amber / Red`,
+`Approve / Approve with conditions / Reject`, `Yes / No`) stay in English, because the check reads them.
+Column order is fixed; column headings may be translated.
 
 ---
 
 ## File Template
 
-```markdown
+Copy verbatim, then fill. Tables carry no example rows: a row is written only when a session table
+supplies it. The frontmatter placeholders `0000-00-00`, `0/13` and `und` are valid to the check and are
+replaced by the drafting step.
+
+````markdown
 ---
 document: project-charter
 project: [Project name]
 client: [Client name]
-version: [1.0]
-status: [Draft | For sign-off | Signed | Signed with conditions | Rejected]
-date: [YYYY-MM-DD]
-discovery_sessions_completed: [N]/13
-go_no_go: [Go | Go with conditions | No-Go]
+version: 1.0
+status: Draft
+date: 0000-00-00
+language: und
+discovery_sessions_completed: 0/13
+go_no_go: Pending
 ---
 
 # [Project name] — Project Charter
@@ -36,61 +55,68 @@ go_no_go: [Go | Go with conditions | No-Go]
 | Document control | |
 |---|---|
 | Client | [Client name] |
-| Version / status | [1.0] · [Draft] |
-| Date | [YYYY-MM-DD] |
+| Version / status | 1.0 · Draft |
+| Date | 0000-00-00 |
 | Prepared by | [Name, role] |
-| Based on | Discovery Sprint sessions 1–13, completed [YYYY-MM-DD] |
+| Based on | Discovery Sprint sessions 1–13, completed 0000-00-00 |
 
 ---
 
-## 1. Purpose and background
+## 1. Purpose and background <!-- charter:purpose -->
 
 [Two to four sentences: the business problem and why it matters now.]
 
 **Top pain points today**
 
-| # | Pain point | Who is affected | Impact |
-|---|---|---|---|
-| 1 | | | |
+| # | Pain point | Who is affected | Impact | Source |
+|---|---|---|---|---|
 
-## 2. Objectives and success measures
+## 2. Objectives and success measures <!-- charter:objectives -->
 
-| # | Objective | KPI | Baseline | Target | Measured by |
+| ID | Objective | KPI | Baseline | Target | Measured by |
 |---|---|---|---|---|---|
-| O-1 | | | | | |
 
-## 3. Scope
+## 3. Scope <!-- charter:scope -->
 
 **In scope (MVP)**
 
-| EPIC | Title | Priority |
-|---|---|---|
-| | | |
+| EPIC | Title | Priority | Requirements |
+|---|---|---|---|
 
 **Out of scope**
 
-- [Item] — [reason or later release]
+| Item | Reason | Decision |
+|---|---|---|
 
-**Requirements:** [N] functional, [N] non-functional, [N] business rules, as registered in
-`_requirements.md`.
+**Requirements:** [one count per registered prefix, then the dropped count — `K- 12 · N- 4 · T- 3 · Dropped 1`] <!-- charter:counts -->
 
-## 4. Stakeholders and users
+## 4. Stakeholders and users <!-- charter:stakeholders -->
 
 | Stakeholder | Role | Decision authority | Involvement |
 |---|---|---|---|
-| | | | |
 
 | Persona | Description | Main goal |
 |---|---|---|
-| | | |
 
-## 5. Solution overview
+## 5. Approvals and role holders <!-- charter:approvals -->
+
+| Approval | Approver | Consulted | Source |
+|---|---|---|---|
+
+| Role | Holder | Source |
+|---|---|---|
+| Privacy owner | | |
+| Security owner | | |
+| Incident contact | | |
+| Architect (signs deviations) | | |
+
+## 6. Solution overview <!-- charter:solution -->
 
 [Two to four sentences: the shape of the solution.]
 
 | Layer | Choice | Decision |
 |---|---|---|
-| Frontend | | [D-05-n] |
+| Frontend | | |
 | Backend | | |
 | Data | | |
 | Hosting | | |
@@ -98,129 +124,164 @@ go_no_go: [Go | Go with conditions | No-Go]
 
 **Integrations**
 
-| System | Direction | Purpose |
+| ID | System | Direction | Purpose |
+|---|---|---|---|
+
+## 7. Deviations from standards <!-- charter:deviations -->
+
+| ID | Standard | Choice | Reason | Reversible | Approver | Decision | Status |
+|---|---|---|---|---|---|---|---|
+
+## 8. Data <!-- charter:data -->
+
+| Aspect | Statement | Source |
 |---|---|---|
-| | | |
+| Highest data classification | | |
+| Personal data processed | | |
+| Controller / processor role | | |
+| Retention headline | | |
+| Availability target (RTO / RPO) | | |
 
-**Security and compliance:** [data classification, applicable regulations, availability target, in two to
-four lines.]
+## 9. Quality and acceptance <!-- charter:quality -->
 
-## 6. Quality and acceptance
+| Gate | Criterion | Approved by |
+|---|---|---|
+| UAT sign-off | | |
+| Go-live readiness | | |
 
-| Gate | Criterion |
-|---|---|
-| UAT sign-off | [criteria] — approved by [role] |
-| Go-live readiness | [criteria] |
+## 10. What was validated <!-- charter:validated -->
 
-## 7. Delivery plan
+| Round | Prototype version | Flows validated | Verdicts (change / keep / drop / question) | Closed? |
+|---|---|---|---|---|
+
+**Screens:** [n] required, [n] deferred, [n] MVP requirements in the no-screen bucket with a reason, 0 uncovered — as `_screens.md` records them.
 
-| Milestone | Target date | Included EPICs | Exit criteria |
+## 11. Delivery plan <!-- charter:delivery -->
+
+| Milestone | Target | Included EPICs | Exit criteria |
 |---|---|---|---|
-| [v1.0 — MVP] | | | |
 
 **Build order:** [EPIC order and why.]
 
-## 8. Team and governance
+## 12. Team and governance <!-- charter:team -->
 
 | Role | Name / party | Responsibility |
 |---|---|---|
-| | | |
 
 **Scope changes are approved by:** [role]. **Progress is reported:** [cadence, format].
 
-## 9. Budget, constraints and assumptions
+## 13. Budget, constraints and assumptions <!-- charter:budget -->
 
 | Type | Item | Source |
 |---|---|---|
-| Budget | [amount or "Not decided in Discovery — OI-n"] | |
-| Constraint | | |
-| Assumption | | |
 
-## 10. Risks
+## 14. Risks <!-- charter:risks -->
 
-| # | Risk | Likelihood | Impact | Mitigation | Owner |
+| ID | Risk | Likelihood | Impact | Mitigation | Owner |
 |---|---|---|---|---|---|
-| R-1 | | | | | |
 
-## 11. Open items
+## 15. Open items <!-- charter:open-items -->
 
-| ID | Item | Must resolve before build? | Owner | Target date |
-|---|---|---|---|---|
-| OI-1 | | | | |
+| ID | Item | Must resolve before build? | Owner | Target date | Status |
+|---|---|---|---|---|---|
+
+## 16. Conditions <!-- charter:conditions -->
+
+| Kind | ID | Statement | Resolution |
+|---|---|---|---|
 
-## 12. Go / No-Go recommendation
+## 17. Go / No-Go recommendation <!-- charter:go-no-go -->
 
 | Criterion | Status | Note |
 |---|---|---|
-| Business requirements clarity | [Green / Amber / Red] | |
+| Business requirements clarity | | |
 | Technical architecture feasibility | | |
 | Security and compliance readiness | | |
 | Integration dependencies resolved | | |
 | Team and budget availability | | |
 | Timeline confidence | | |
 | Stakeholder alignment | | |
-| **Overall recommendation** | **[Go / Go with conditions / No-Go]** | |
+| **Overall recommendation** | | |
 
-**Conditions:** [each condition attached to a Go, or "None".]
-
-## 13. Key decisions
+## 18. Key decisions <!-- charter:decisions -->
 
 | ID | Decision | Rationale | Owner |
 |---|---|---|---|
-| D-01-1 | | | |
 
-## 14. Sign-off
+## 19. Sign-off <!-- charter:sign-off -->
 
-By signing, each party agrees that sections 1–13 describe the project to be built, subject to the
-conditions stated.
+By signing, each party agrees that sections 1–18 describe the project to be built, subject to the
+conditions in § 16.
 
 | Role | Name | Decision | Conditions | Date | Signature |
 |---|---|---|---|---|---|
-| [Sponsor] | | [Approve / Approve with conditions / Reject] | | | |
+| [Sponsor] | | | | | |
 | [Product owner] | | | | | |
 | [Delivery lead] | | | | | |
 
+## 20. Version history <!-- charter:history -->
+
+| Version | Date | Status | Change | Decision |
+|---|---|---|---|---|
+| 1.0 | 0000-00-00 | Draft | Initial draft from Sessions 1–13 | — |
+
 ---
 
-**Source files:** `.planning/discovery/session-01.md` … `session-13.md`, `_requirements.md`.
-```
+**Source files:** `.planning/discovery/session-01.md` … `session-13.md`, `_requirements.md`, `_screens.md`,
+`_feedback.md`, `_research.md`, `_deviations.md`.
+````
 
 ---
 
 ## Where each section comes from
 
-Fill every section from the session tables below and nothing else. The session files are the source of
-truth; the charter only condenses them.
+Fill every section from the tables below and nothing else. The session files and the registers are the
+source of truth; the charter only condenses them.
 
 | § | Section | Source (file § table) |
 |---|---|---|
-| — | Front matter, document control | `_progress.md` (completion dates); Session 1 § Stakeholder Register (client) |
-| 1 | Purpose and background | Session 1 § Business Vision Summary; Session 2 § Pain Points Register (top 3–5 by impact) |
-| 2 | Objectives and success measures | Session 3 § Business Objectives |
-| 3 | Scope | Session 3 § MVP Scope Boundary and § EPIC Register; counts from the roll-up block in `_requirements.md` |
+| — | Front matter, document control | `_progress.md` (completion dates); Session 1 § Stakeholder Register (client); language per the rule above |
+| 1 | Purpose and background | Session 1 § Business Vision Summary; Session 2 § Pain Points Register (top 3–5 by impact, `PP-` IDs in Source) |
+| 2 | Objectives and success measures | Session 3 § Business Objectives (`BO-` IDs); a column the source table does not have (Baseline, say) reads `—` |
+| 3 | Scope | Session 3 § MVP Scope Boundary and § EPIC Register (`E-` IDs, each with the requirement IDs it groups — from the register's requirement column when it has one, else from the Step Matrices' Requirements cells grouped by EPIC); out-of-scope items with their `D-` decision; counts from the roll-up block of `_requirements.md` |
 | 4 | Stakeholders and users | Session 1 § Stakeholder Register; Session 4 § Refined Personas (else Session 2 § User Personas) |
-| 5 | Solution overview | Session 5 § Technology Stack Decisions and § Architecture Decision Records; Session 8 § Integration Design Register; Session 6 § Data Classification Matrix, § Compliance Requirements Register, § Availability and DR Targets; Session 7 § IdP Integration Design |
-| 6 | Quality and acceptance | Session 9 § UAT Process and § Quality Gates; Session 10 § Go-Live Readiness Checklist |
-| 7 | Delivery plan | Session 11 § Milestone Plan, § Project Timeline, § EPIC Build Order |
-| 8 | Team and governance | Session 12 § Team Structure and § Governance Structure; reporting cadence from Session 12 topic "Communication and reporting" |
-| 9 | Budget, constraints and assumptions | Session 1 § Constraints and Risks Register; any `[needs-business-input]` item still parked |
-| 10 | Risks | Session 11 § Risk Register, plus open risks from Session 1 § Constraints and Risks Register |
-| 11 | Open items | Session 13 § Open Items Register |
-| 12 | Go / No-Go recommendation | Session 13 § Go / No-Go Assessment (copied as recorded, not re-scored) |
-| 13 | Key decisions | § Key Decisions of every session — only decisions that change scope, architecture, cost or timeline |
-| 14 | Sign-off | Session 1 § Stakeholder Register — every stakeholder with approval authority gets a row |
+| 5 | Approvals and role holders | Session 1 § Approval Matrix (one row each, Source `[vault: <path>]` or `room`); a Session 1 that predates the matrix gives the Stakeholder Register's decision-authority column instead. Role holders (privacy owner, security owner, incident contact, architect) from the Key Decision of any session that names one — `Not decided in Discovery — OI-n` when none does |
+| 6 | Solution overview | Session 5 § Technology Stack Decisions (`D-05-n`) and § Architecture Decision Records; Session 8 § Integration Design Register (`IF-` IDs); Session 7 § IdP Integration Design |
+| 7 | Deviations from standards | `_deviations.md` (`DEV-` IDs, every row — `charter-check` reports a row left out) when it exists; until then every **Deviation Record** table a session carries (Sessions 5–10, `ADR-` IDs, Status as signed or superseded) plus every Sessions 4–10 **Standards Applied** row whose Deviation is not `none`, each with its `D-ss-n` |
+| 8 | Data | Session 6 § Data Classification Matrix, § Compliance Requirements Register, § Availability and DR Targets; Session 2 § Data Entity Map for personal data |
+| 9 | Quality and acceptance | Session 9 § UAT Process and § Quality Gates; Session 10 § Go-Live Readiness Checklist |
+| 10 | What was validated | `_feedback.md` (one row per round: verdict counts, whether every `Processing` cell is closed); `_screens.md` (required / deferred counts, and the number of MVP requirements in the no-screen bucket — uncovered requirements are always 0 once `screen-check` passes); `prototype/README.md` (flows, version) |
+| 11 | Delivery plan | Session 11 § Milestone Plan, § Project Timeline, § EPIC Build Order |
+| 12 | Team and governance | Session 12 § Team Structure and § Governance Structure; reporting cadence from Session 12 topic "Communication and reporting" |
+| 13 | Budget, constraints and assumptions | Session 1 § Constraints and Risks Register (`CON-` IDs); any `[needs-business-input]` item still parked. IDs are copied as minted — an engagement that minted `C1`/`R1` without a hyphen keeps them, and those rows are then outside the families `charter-check` resolves |
+| 14 | Risks | Session 11 § Risk Register plus open risks from Session 1 § Constraints and Risks Register (`R-` IDs, as minted) |
+| 15 | Open items | Session 13 § Open Items Register, row for row, in the charter's six columns — `Source Session` and `Priority` stay in the register (`OI-` IDs) |
+| 16 | Conditions | every condition attached to a `Go with conditions` (an Amber row under a plain `Go` is not a condition; it stays an open item); every section carrying `⚠️ CONDITIONAL — <RS-nn\|DG-nn>` (from the sessions' `conditional:` frontmatter); every open `Gates-MVP` row of `_research.md`; every `Dropped (D-ss-n)` row of `_requirements.md`; every Session 13 open item that must resolve before build and is still open |
+| 17 | Go / No-Go recommendation | Session 13 § Go / No-Go Assessment, copied as recorded — the eight rows in order, status cells verbatim |
+| 18 | Key decisions | § Key Decisions of every session — only decisions that change scope, architecture, cost or timeline |
+| 19 | Sign-off | Session 1 § Stakeholder Register and § Approval Matrix — every party with approval authority gets a row |
+| 20 | Version history | one row per version of this document; the last row's version equals the frontmatter `version` |
 
 ## Fill rules
 
 - **Never invent.** Every statement traces to a session table above. A value Discovery did not settle is
-  written as `Not decided in Discovery — OI-n`, and that item appears in § 11 Open items.
-- **Keep the IDs.** Requirement, EPIC, decision (`D-<ss>-<n>`), risk and open-item IDs are copied
-  exactly as the session files write them, so every line can be traced back.
+  written as `Not decided in Discovery — OI-n`, and that item appears in § 15 Open items.
+- **Keep the IDs.** Requirement, EPIC, decision (`D-<ss>-<n>`), risk, open-item, screen and deviation IDs
+  are copied exactly as the session files and registers write them. `charter-check` resolves every ID a
+  table cell cites; an ID nothing minted is a fault.
 - **Condense, don't copy.** Tables carry the headline rows; the full detail stays in the session files.
   Aim for a charter that reads in about fifteen minutes.
-- **Fixed shape.** Keep all 14 sections, their numbers, headings and table columns. An empty section
-  says `None identified in Discovery.`
-- **Go / No-Go is recorded, not re-judged.** § 12 copies Session 13's assessment and conditions verbatim.
+- **Fixed shape.** Keep all 20 sections, their keys, their order and their table columns. An empty table
+  stays in place with no rows, and the section's prose says `None identified in Discovery.` (in the
+  sprint language). The **Source files** footer names only the files that exist in this engagement.
+- **Go / No-Go is recorded, not re-judged.** § 17 copies Session 13's assessment verbatim and the
+  frontmatter `go_no_go` equals its overall recommendation; `Pending` is allowed only while `status`
+  is `Draft`.
+- **Conditions are the honest qualifiers of the sign-off.** A Session 13 open item marked
+  `Yes` under *Must resolve before build?* is either closed in Session 13 or listed in § 16.
 - **Status follows the signatures.** `Draft` while being written, `For sign-off` once circulated,
-  `Signed` when every § 14 row says Approve, `Signed with conditions` when any row approves with
-  conditions, `Rejected` when any row rejects. A new version resets the status to `Draft`.
+  `Signed` when every § 19 row says `Approve`, `Signed with conditions` when any row approves with
+  conditions, `Rejected` when any row rejects.
+- **A change is a new version.** Any edit after `For sign-off` adds a § 20 row, bumps `version`,
+  resets `status` to `Draft` and regenerates the exports (`workflows/discovery-sprint/charter.md`
+  § Redraft). The markdown is the source; `PROJECT-CHARTER.docx` and `.pdf` next to it are renderings.

package/pp-core/templates/project.md

@@ -68,9 +68,9 @@ Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Perform
 
 <!-- Decisions that constrain future work. Add throughout project lifecycle. -->
 
-| Decision | Rationale | Outcome |
-|----------|-----------|---------|
-| [Choice] | [Why] | [✓ Good / ⚠️ Revisit / — Pending] |
+| ID | Decision | Rationale | Outcome |
+|----|----------|-----------|---------|
+| [D-<ss>-<n> from Discovery, or —] | [Choice] | [Why] | [✓ Good / ⚠️ Revisit / — Pending] |
 
 ---
 *Last updated: [date] after [trigger]*

package/pp-core/templates/requirements.md

@@ -107,6 +107,24 @@ Which phases cover which requirements. Updated during roadmap creation.
 - Complete: Requirement verified
 - Blocked: Waiting on external factor
 
+**Discovery variant (projects handed over by `/pp-discovery-to-build`):**
+- Every line is one `_requirements.md` row with its minted ID; nothing is renumbered
+- The description is followed by ` — <MoSCoW> · <Disposition> · <Provenance>` copied from the row
+  (`Must · MVP · [03 §2.1]`), and the acceptance criteria follow on an indented `- AC:` line, verbatim
+- `MVP` rows are v1, `Later` rows are v2, `Dropped (D-ss-n)` rows are Out of Scope with the decision
+  as the reason; the `**ID**` lead keeps every existing parser working
+
+```markdown
+### Order Intake (E-01)
+
+- [ ] **K-01**: User can create a task — Must · MVP · [03 §2.1]
+  - AC: A task appears in the list within one second of saving
+```
+
+The planner and verifier read the same rows through `pp_run query discovery.for-phase <N>`
+(`references/discovery-build-consumption.md`); this file is the roadmap-side mirror, not a second
+source.
+
 </guidelines>
 
 <evolution>

package/pp-core/templates/verification-report.md

@@ -69,6 +69,22 @@ behavior_unverified_items: # Only if behavior_unverified > 0 — the truths abov
 
 **Coverage:** {N}/{M} requirements satisfied
 
+## Discovery conformance
+
+{Only on a project that ran the Discovery Sprint — omit the whole section otherwise. The block is
+rendered by `pp_run query discovery.for-phase {X} --conformance-template`, one row per Discovery
+register row citing this phase's requirement IDs; the verifier fills Status and Evidence and checks
+it with `--verify`. Status is exactly `honoured`, `amended (D-P<nn>-<n>)` or `missed`; a `missed`
+row is a gap. Contract: `references/discovery-build-consumption.md`.}
+
+<!-- discovery:conformance -->
+| Artifact | Row | Status | Evidence |
+|---|---|---|---|
+| `_requirements.md` | {K-01} | honoured | {file:line or test that realises the acceptance criteria} |
+| `_processes.md` | {MP-01 #3} | amended (D-P{XX}-{n}) | {the amended cell the build matches} |
+| `_rules.md` | {BR-02} | missed | {what contradicts or is absent} |
+<!-- /discovery:conformance -->
+
 ## Anti-Patterns Found
 
 | File | Line | Pattern | Severity | Impact |

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