@pareto4/pp-core 1.19.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/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/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/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>