@pareto4/pp-core 1.19.0 → 1.21.0

package/pp-core/references/discovery-build-consumption.md

@@ -0,0 +1,256 @@
+# Discovery → Build Consumption Contract
+
+> Lazy-loaded reference. Single home for how a build phase reads the Discovery Sprint's
+> canonical artifacts (Discovery Sprint improvement plan, Batch 4 — §5.5 rules R1 and R3), for the
+> two registers that batch adds (`_stories.md`, `_phases.md`) and for the three commands that serve
+> them: `pp_run query discovery.stories-check`, `pp_run query discovery.phases-check` and
+> `pp_run query discovery.for-phase <N>`. The `_screens.md` recipe in
+> `references/discovery-traceability.md` is the pattern every artifact here follows: a bootstrap
+> template with no example rows, a closed cell grammar, a parser contract, a check that fails on
+> structure and never on judgement.
+
+## The three rules
+
+**R1 — Reference artifacts by ID, filtered per phase; never session files.** A phase's
+`**Requirements**: [K-03, N-02]` line in `ROADMAP.md` is the key (before the handoff, the phase's
+row in `_phases.md`). `for-phase <N>` returns the rows of every canonical artifact that cite those
+IDs as one markdown extract between `<!-- discovery:auto -->` and `<!-- /discovery:auto -->`.
+`/pp-discuss-phase` writes the extract into CONTEXT.md; `/pp-plan-phase` renders it fresh into
+`{padded}-DISCOVERY-EXTRACT.md` for the researcher and the planner, and the planner embeds it in
+every PLAN.md of the phase. No agent opens `.planning/discovery/session-NN.md`.
+
+**R2 — One source of truth, amended in place** (`references/discovery-id-conventions.md`
+§ Precedence). A build decision that changes a discovery fact edits the artifact row and appends
+`→ amended by D-P<nn>-<n>`; the extract is re-rendered, never edited. § R2 in build, below.
+
+**R3 — Report at planning, enforce at verification.** Planning reads discovery; execution is not
+blocked by it. The verifier takes the acceptance criteria of the extract's `_requirements.md` and
+`_stories.md` rows as the UAT and writes a **Discovery conformance** block naming every extract row
+`honoured`, `amended (D-P<nn>-<n>)` or `missed`. A `missed` row is a gap.
+
+**Boundary:** a project without `.planning/discovery/` sees none of this. Every command below exits
+0 with an empty result there, exactly as the vault capability is inert without bindings.
+
+## Consumption table
+
+| Artifact | Rows the extract carries for a phase | Consumer |
+|---|---|---|
+| `_requirements.md` § Requirements | rows whose ID is in the phase's set — all six columns, acceptance criteria verbatim | REQUIREMENTS.md rows (handoff 5e); planner acceptance criteria; verifier UAT |
+| `_stories.md` § Stories | rows whose `Requirements` cites one | planner; verifier UAT |
+| `_processes.md` § To-be, § Steps | the step rows whose `Requirements` cites one, under their `### MP-nn — <name>` heading, preceded by the § To-be row of each main process touched | planner tasks; UAT scripts |
+| `_entities.md` | the entities the selected steps name as data objects: § Entities row, attribute table, relationships touching them, lifecycles | planner data phases; ERD |
+| `_rules.md` § Rules | rows whose `Requirements` cites one | planner; tests |
+| `_screens.md` § Screens, § No screen (still MVP) | screens whose `Requirements` cites one; no-screen rows keyed by one | ui-phase (exists); planner |
+| `_roles.md` § Permissions, § Roles, § Screens | the permission rows whose `Requirements` cites one; the § Roles row of every role those permissions name; the § Screens rows of those roles and of the phase's screens (`references/discovery-access.md`) | planner auth phase; forbidden-path tests |
+| `_integrations.md` § Interfaces, § Contract, § Errors | the interface rows whose `Requirements` cites one or that a selected step names in its `Integration` cell (`IF-nn`); their contract and error rows (`references/discovery-integrations.md`) | planner integration phases |
+| `_migration.md`, `_deviations.md` | generic: every table carrying a `Requirements` (or `Requirement IDs`) column contributes its citing rows. A table with no requirement column is listed as *not filterable* in the extract, never silently dropped — `_deviations.md § Deviations` always is | planner migration phase; `pp-vault-review` reads `_deviations.md` whole (§ Deviations read contract) |
+| `_phases.md` § Phases | the phase's requirement IDs when ROADMAP.md has none yet | ROADMAP.md (handoff 5f, verbatim); `for-phase` |
+
+The grammars of `_roles.md`, `_integrations.md`, `_migration.md` and `_deviations.md` live in
+`references/discovery-access.md`, `references/discovery-integrations.md` and
+`references/discovery-standards.md` (Batch 3). For a generic register's rows to reach a phase the
+table must carry a `Requirements` column; the column name is the join, not the position.
+
+## `_stories.md` — user stories (Session 3 Step 5E)
+
+```markdown
+# User Stories — [PROJECT_NAME]
+
+## Stories
+
+| ID | EPIC | Requirements | Story | Acceptance criteria | Source step |
+|----|------|--------------|-------|---------------------|-------------|
+```
+
+| Cell | Grammar |
+|---|---|
+| `ID` | `US-<nn>`, zero-padded two digits, global sequence, contiguous from `US-01` |
+| `EPIC` | one `E-<nn>` from Session 3's EPIC Register |
+| `Requirements` | comma list of `_requirements.md` IDs (`[A-Z][A-Z0-9]*-\d+`), at least one |
+| `Story` | free text — `As a <persona>, I want <goal> so that <benefit>`; pipes escaped `\|` |
+| `Acceptance criteria` | free text, non-empty, and a criterion — never a pointer such as `As in F-01`; the verifier reads it verbatim as the UAT |
+| `Source step` | comma list of `MP-<nn> #<cell>` — the main process and the `#` cell of the step-matrix row the story was derived from, copied verbatim (`MP-05 #05.1`, `MP-01 #3`) — or `—` |
+
+### Parser contract — `pp_run query discovery.stories-check`
+
+| Fault | Raised when |
+|---|---|
+| `missing_section` | no `## Stories` heading, or no table under it |
+| `bad_table_shape` | the header is not the template's six columns |
+| `bad_id` / `duplicate_id` / `sequence_gap` | the `US-` family rules above |
+| `bad_epic` | `EPIC` is not one `E-nn` |
+| `empty_cell` | `Story` or `Acceptance criteria` is empty (the cell is named) |
+| `acceptance_is_pointer` | `Acceptance criteria` starts with `As in`, `See`, `Zie` or `Idem` — a pointer, not a criterion the verifier can run |
+| `no_requirement` / `unknown_requirement_id` | no requirement cited, or one of the wrong shape or absent from `_requirements.md` (resolution skipped when that file is absent) |
+| `bad_source_step` / `unknown_process_id` / `unknown_process_step` | a `Source step` token is neither `—` nor `MP-nn #<cell>`; the main process is not in `_processes.md` § To-be; the step row is not in its matrix (both resolutions skipped when `_processes.md` is absent) |
+| `mvp_requirement_without_story` | an `MVP` requirement that at least one persona-actor step row cites has no story. Mirrors Step 5E: stories come from the step rows whose actor is not `System`, so a requirement realised only by `System` steps, or cited by no step at all (engagement process rows), needs none; `N-`/`T-` rows never do. Without `_processes.md` only the prefix exemption applies |
+| `requirements_unparseable` / `artifact_unreadable` | `_requirements.md` present but failing `rollup --check`; an artifact present but unreadable |
+
+Exit identity `discovery_stories_check_failed`. Absent `_stories.md` → exit 0, `present: false`.
+Reports at Sessions 8 and 13; hard-blocks at `/pp-discovery-to-build`.
+
+## `_phases.md` — the Phase Plan (Session 11 Closing Step)
+
+```markdown
+# Phase Plan — [PROJECT_NAME]
+
+## Phases
+
+| Phase | Goal | EPICs | Requirement IDs | Success criteria | Depends on |
+|-------|------|-------|-----------------|------------------|------------|
+```
+
+| Cell | Grammar |
+|---|---|
+| `Phase` | positive integer, unique, contiguous from 1 — the pp-core phase number ROADMAP.md will carry |
+| `Goal` | free text, one sentence — copied verbatim into ROADMAP.md `**Goal**:` |
+| `EPICs` | comma list of `E-<nn>`, or `—` for a phase that realises no EPIC (infrastructure, migration) |
+| `Requirement IDs` | comma list of `_requirements.md` IDs, none `Dropped`, or `—` for a phase that realises no requirement (setup, infrastructure) — copied verbatim into `**Requirements**:` |
+| `Success criteria` | observable statements separated by ` · ` (space, middle dot U+00B7, space) — each becomes one numbered line under `**Success Criteria**` |
+| `Depends on` | `—`, or a comma list of earlier phase numbers — `**Depends on**:` |
+
+### Parser contract — `pp_run query discovery.phases-check`
+
+| Fault | Raised when |
+|---|---|
+| `missing_section` / `bad_table_shape` | no `## Phases` table, or a header off the template |
+| `bad_phase_number` / `duplicate_phase` / `sequence_gap` | the `Phase` rules above (a malformed number contributes nothing else) |
+| `empty_cell` | `Goal` or `Success criteria` empty |
+| `bad_epic` | an `EPICs` token is not `E-nn` |
+| `no_requirement` / `unknown_requirement_id` | an empty `Requirement IDs` cell (write `—` for a phase with none), or an ID of the wrong shape or absent from `_requirements.md` (resolution skipped when absent) |
+| `dropped_requirement_planned` | a planned requirement's disposition is `Dropped (…)` |
+| `requirement_in_multiple_phases` | the same ID in two rows (the phases are named) |
+| `mvp_requirement_unplanned` | an `MVP` requirement appears in no phase — the roadmap template's own rule, now mechanical |
+| `bad_dependency` | a `Depends on` token is not an earlier, existing phase number |
+| `requirements_unparseable` / `artifact_unreadable` | as for `stories-check` |
+
+Exit identity `discovery_phases_check_failed`. Absent `_phases.md` → exit 0. Reports at Sessions 11
+and 13; hard-blocks at `/pp-discovery-to-build`, whose Step 5f copies the table into ROADMAP.md.
+
+## `pp_run query discovery.for-phase <N>`
+
+```bash
+pp_run query discovery.for-phase <N>                            # JSON: ids, artifacts, rows, markdown
+pp_run query discovery.for-phase <N> --markdown                 # the extract alone, for injection
+pp_run query discovery.for-phase <N> --conformance-template     # the verifier's block, every row `missed`
+pp_run query discovery.for-phase <N> --verify <VERIFICATION.md> # check the block covers every row
+```
+
+`<N>` is the phase number as ROADMAP.md spells it (`3`, `2.1`). Resolution of the requirement
+IDs: the phase's `**Requirements**:` line in `.planning/ROADMAP.md` (brackets optional); else the
+phase's row in `_phases.md` (integer phases only); else none — the extract then says so and carries
+no rows, exit 0.
+
+### The extract
+
+```markdown
+<!-- discovery:auto -->
+## Discovery extract — Phase 3
+
+Requirement IDs: K-01, K-02 (source: .planning/ROADMAP.md)
+Rendered by `pp_run query discovery.for-phase 3`. Do not edit here: amend the artifact row (`→ amended by D-P<nn>-<n>`) and re-run.
+
+### Requirements — `.planning/discovery/_requirements.md`
+| … six columns, rows verbatim … |
+
+### User stories — `.planning/discovery/_stories.md`
+### Process steps — `.planning/discovery/_processes.md`
+#### Main processes
+#### MP-01 — <name>
+### Entities — `.planning/discovery/_entities.md`
+#### <Entity> (attributes)   #### Relationships   #### Lifecycles
+### Business rules — `.planning/discovery/_rules.md`
+### Screens — `.planning/discovery/_screens.md`
+#### No screen (still MVP)
+### Roles — `.planning/discovery/_roles.md`
+#### Roles   #### Permissions   #### Screens
+### Integrations — `.planning/discovery/_integrations.md`
+#### Interfaces   #### Contract   #### Errors
+### Migration — … (one `####` per section of a generic register)
+
+Not filterable by requirement: `.planning/discovery/_deviations.md § Deviations` has no requirement column — read it whole.
+
+Artifacts read: .planning/discovery/_requirements.md, …
+<!-- /discovery:auto -->
+```
+
+Sections appear only when they carry a row. Cells are copied verbatim with pipes re-escaped. The
+`Artifacts read` line is what a phase's canonical refs name — artifact paths, never session files.
+The join is the ID, so a cross-cutting requirement (an audit or notification rule every flow
+touches) pulls steps of other main processes into the phase that owns it — by design, not scope
+creep: those steps are where the requirement is realised.
+
+### Row keys
+
+Every keyed row has one identity, `<artifact basename> <row>`, used by the conformance block:
+
+| Artifact | Row key |
+|---|---|
+| `_requirements.md` | the requirement ID (`K-01`) |
+| `_stories.md` | the story ID (`US-02`) |
+| `_processes.md` | `MP-<nn> #<cell>` — main process and the matrix's `#` cell verbatim (`MP-05 #05.1`); the same spelling `_stories.md` uses in `Source step`; the § To-be rows are detail, not keys |
+| `_entities.md` | the entity name; attribute, relationship and lifecycle rows are detail |
+| `_rules.md` | `BR-<nn>` |
+| `_screens.md` | `SCR-<nn>`, or `no-screen <requirement ID>` for a bucket row |
+| `_roles.md` | the role name (§ Roles and § Permissions rows share it; § Screens rows are detail) |
+| `_integrations.md` | `IF-<nn>` (§ Contract and § Errors rows are detail) |
+| generic registers | the row's first cell |
+
+### Parser contract — structure only
+
+| Fault | Raised when |
+|---|---|
+| `missing_section` / `bad_table_shape` | a present artifact's owning section or header is off its template (`_requirements.md` § Requirements, `_stories.md` § Stories, `_processes.md` § To-be and every `### MP-nn — <name>` under § Steps, `_entities.md` § Entities and the attribute tables of selected entities, `_rules.md` § Rules, `_screens.md` § Screens and § No screen (still MVP), `_roles.md` § Roles / § Permissions / § Screens, `_integrations.md` § Interfaces / § Contract / § Errors) |
+| `requirements_unparseable` | `_requirements.md` present but failing the rollup parse — run `pp_run query discovery.rollup --check` |
+| `artifact_unreadable` | an artifact present but unreadable |
+
+Exit identity `discovery_for_phase_failed`, on structure only. The command never judges whether a
+row is relevant; the join is the ID.
+
+### The Discovery conformance block (R3)
+
+`--conformance-template` renders, for the verifier to fill:
+
+```markdown
+### Discovery conformance
+
+<!-- discovery:conformance -->
+| Artifact | Row | Status | Evidence |
+|---|---|---|---|
+| `_requirements.md` | K-01 | missed |  |
+| `_processes.md` | MP-01 #2 | missed |  |
+<!-- /discovery:conformance -->
+```
+
+`Status` is exactly `honoured`, `missed`, or `amended (D-P<nn>-<n>)` naming the build decision that
+changed the row (R2). Every row starts as `missed`: an unverified row is a gap until evidence says
+otherwise. `Evidence` is free text (`file:line`, a test name, the amended cell).
+
+`--verify <file>` faults: `conformance_markers` (not exactly one open and one close, in order),
+`bad_table_shape`, `bad_status`, `unknown_row` (a key the extract does not have), `duplicate_row`,
+`missing_row` (an extract row absent from the block). It reports the counts `honoured`, `amended`,
+`missed`; a `missed` row is never a fault of the block — it is the verifier's finding, and the
+verifier's status rule turns it into `gaps_found`.
+
+## R2 in build — amending a discovery fact
+
+When a `/pp-discuss-phase` decision changes something the sprint recorded (a field, a rule, a role,
+a flow step, a screen):
+
+1. Edit the artifact row in place and append `→ amended by D-P<nn>-<n>` to the changed cell
+   (`<nn>` the zero-padded phase, `<n>` the decision's sequence in CONTEXT.md).
+2. Re-run the artifact's check (`entity-check`, `process-check`, `rules-check`, `screen-check`,
+   `stories-check`, `phases-check`, `rollup --check`) — exit 0 before continuing.
+3. Bump `version` in `docs/discovery/PROJECT-CHARTER.md` and add a § 20 Version history row naming
+   the decision; a signed charter is not silently superseded.
+4. Re-run `for-phase` — CONTEXT.md and PLAN.md hold the extract, never an override.
+
+## `_deviations.md` read contract for `pp-vault-review`
+
+`pp_run check vault-review` reads `.planning/discovery/_deviations.md` when present and adds
+`deviations[]` to its payload: every row of every table that carries, by header name, a `Standard`
+column and a `Status` column (`ID`, `Decision` and `Approver` are copied when present). The vault
+reviewer treats a `FAIL` whose clause an `Approved` deviation covers as `N-A` with the reason
+`deviation on file: <ID> (<Decision>)`; a deviation in any other status leaves the `FAIL` standing
+and is named in the row's reason. A present but unreadable file is a payload gap. The file's full
+grammar is `references/discovery-standards.md`; the two column names are the join.

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

@@ -0,0 +1,127 @@
+# Discovery Charter — Parser Contract, Heading Keys & Language
+
+Single home for the machine side of the Project Charter: what `pp_run query discovery.charter-check`
+verifies in `docs/discovery/PROJECT-CHARTER.md`, the heading keys that make the shape
+language-independent, and the heading renderings for the sprint languages. The template itself is
+`templates/project-charter.md`; the drafting procedure is `workflows/discovery-sprint/charter.md`.
+This file is Read lazily; it is never `@`-imported.
+
+## When the charter appears
+
+| Moment | What happens | Who |
+|---|---|---|
+| Session 13 Step 0.5 | Drafted from the session record into `docs/discovery/PROJECT-CHARTER.md`, `status: Draft`, `go_no_go: Pending` | `charter.md` § Draft |
+| Session 13 topics 2–3 | Reviewed section by section; the Go / No-Go table is recorded in `session-13.md` and copied into § 17 | Session 13 |
+| Session 13 Closing Step | `status: For sign-off`, `charter-check` exits 0, exports written, committed | `charter.md` § Finish |
+| Signatures collected | `status` set from the § 19 rows: `Signed`, `Signed with conditions` or `Rejected`; version history row | operator, `charter.md` § Redraft |
+| `/pp-discovery-to-build` Step 2 | `charter-check --require-signed` hard-blocks unless `Signed` or `Signed with conditions`; `--unsigned` records the gap instead | `handoff-gates.md` |
+| any later version | § 20 row, `version` bump, `status: Draft`, exports regenerated | `charter.md` § Redraft |
+
+**Write targets.** The charter and its exports are written under `docs/discovery/` only — relative
+paths, no `..`, no absolute path — the same rule `docs/architecture/` follows for the architecture
+deliverables (T-04-03 extended). Nothing under `.planning/` is a sign-off medium.
+
+## Heading keys
+
+Every section heading carries a key comment: `## 7. Deviations from standards <!-- charter:deviations -->`.
+The check identifies sections by key, so headings, labels and prose can be rendered in the sprint
+language while the shape stays verifiable. The keys, in the only order the check accepts:
+
+| § | Key | English heading | Dutch heading |
+|---|---|---|---|
+| 1 | `purpose` | Purpose and background | Doel en achtergrond |
+| 2 | `objectives` | Objectives and success measures | Doelstellingen en succesmaten |
+| 3 | `scope` | Scope | Scope |
+| 4 | `stakeholders` | Stakeholders and users | Belanghebbenden en gebruikers |
+| 5 | `approvals` | Approvals and role holders | Goedkeuringen en rolhouders |
+| 6 | `solution` | Solution overview | Oplossing in hoofdlijnen |
+| 7 | `deviations` | Deviations from standards | Afwijkingen van de standaarden |
+| 8 | `data` | Data | Gegevens |
+| 9 | `quality` | Quality and acceptance | Kwaliteit en acceptatie |
+| 10 | `validated` | What was validated | Wat is gevalideerd |
+| 11 | `delivery` | Delivery plan | Opleverplan |
+| 12 | `team` | Team and governance | Team en governance |
+| 13 | `budget` | Budget, constraints and assumptions | Budget, randvoorwaarden en aannames |
+| 14 | `risks` | Risks | Risico's |
+| 15 | `open-items` | Open items | Open punten |
+| 16 | `conditions` | Conditions | Voorwaarden |
+| 17 | `go-no-go` | Go / No-Go recommendation | Go / No-Go-advies |
+| 18 | `decisions` | Key decisions | Kernbesluiten |
+| 19 | `sign-off` | Sign-off | Ondertekening |
+| 20 | `history` | Version history | Versiegeschiedenis |
+
+One more key marks a line, not a section: `<!-- charter:counts -->` on the requirement-counts line in
+§ 3. Any other `charter:` key is a fault.
+
+For a language not in this table, translate the headings and labels yourself and keep the keys; the
+check does not read the heading text. Never translate: the frontmatter field names and values, the
+key comments, and the enum cells — `status`, `go_no_go`, `Green` / `Amber` / `Red`, `Approve` /
+`Approve with conditions` / `Reject`, `Yes` / `No` at the start of a *Must resolve before build?* cell.
+Column order is fixed; column headings may be translated.
+
+## Language resolution
+
+1. Session 1 § Sprint Logistics, row **Charter language** — a BCP-47 code (`nl`, `en`, `nl-BE`).
+2. Else `discovery.language` in `.planning/config.json` (`pp_run query config-get discovery.language --default "" --raw`).
+3. Else the language the sprint was facilitated in (Flow 2 Step 5's rule).
+
+The resolved code is written to the frontmatter `language` field. `und` is the template's placeholder
+and is replaced at draft time.
+
+## Parser contract — `pp_run query discovery.charter-check [--require-signed]`
+
+The check takes no positional path: `docs/discovery/PROJECT-CHARTER.md` and every source under
+`.planning/discovery/` resolve against the working directory. Faults are located by 1-based line and
+carry a validated ID, a section key or a field name — never charter prose. Every row below names the
+fault code emitted; a rule that is **not** mechanically checked says so.
+
+| Field / cell | Grammar | Fault when violated |
+|---|---|---|
+| the file | present and readable at `docs/discovery/PROJECT-CHARTER.md` | `charter_missing` (absent — at Session 13 Step 0 this means "proceed to Step 0.5"; at the handoff it blocks unless `--unsigned`); `artifact_unreadable` (present, unreadable) |
+| frontmatter | opens at line 1 with `---`, closes with `---` | `frontmatter_missing` |
+| `document`, `project`, `client`, `version`, `status`, `date`, `language`, `discovery_sessions_completed`, `go_no_go` | each present and non-empty | `field_missing` naming the field |
+| `document` | exactly `project-charter` | `bad_document` |
+| `status` | `Draft` \| `For sign-off` \| `Signed` \| `Signed with conditions` \| `Rejected` | `bad_status` |
+| `go_no_go` | `Pending` \| `Go` \| `Go with conditions` \| `No-Go` | `bad_go_no_go`; `go_no_go_pending` when `Pending` while `status` is not `Draft` |
+| `version` | `<major>.<minor>` digits | `bad_version` (also for a § 20 row) |
+| `date` | `YYYY-MM-DD` shape (`0000-00-00` passes — the placeholder the draft step replaces) | `bad_date` — the date is **not** parsed as a calendar date |
+| `language` | BCP-47 shape: `nl`, `en`, `en-GB`, `und` | `bad_language` |
+| `project`, `client`, `discovery_sessions_completed` | free | **not mechanically checked** beyond presence |
+| section headings | each of the 20 keys on exactly one `## ` heading, in table order | `section_missing` (key), `section_duplicate` (key, at the repeat), `section_order` (the first key out of place), `section_unknown` (a `charter:` key that is not one of the 20 or `counts`, or a section key off a heading line) |
+| tables | the row before a `\|---\|` separator is a header; data rows follow until a non-pipe line | `table_missing` for § 15, 16, 17, 19, 20, which the check reads; other sections' tables are **not required to exist** — an empty table with no rows satisfies the fixed shape |
+| any ID in a table cell | `D-<ss>-<n>` and `A-<ss>-<n>` resolve against the first column of every table in `.planning/discovery/*.md`; `OI-`, `R-`, `CON-`, `SCR-`, `E-`, `US-`, `BO-`, `ADR-`, `IF-`, `CR-`, `RS-`, `DG-`, `DEV-` the same; a registered requirement prefix resolves against the rows of `_requirements.md` | `unknown_id` naming the token — also for a two-part ID in a one-part family or the reverse. A prefix in none of these families (`ISO-27001`) is **not checked**. Requirement IDs are **not checked** while `_requirements.md` is absent; § 20 is never scanned |
+| § 3 counts line (`<!-- charter:counts -->`) | `<PREFIX>- <n>` for every registered prefix (rows with disposition `MVP` or `Later`), then `Dropped <n>`, separated by ` · ` | `counts_missing` (no marked line while `_requirements.md` exists), `counts_mismatch` (any count off, a prefix missing or extra). **Not checked** while `_requirements.md` is absent |
+| dropped requirements | every `Dropped (D-ss-n)` row of `_requirements.md` is cited in a § 16 cell | `dropped_missing` naming the requirement |
+| § 17 table | eight rows in Session 13's order; `Status` is the second column | `go_no_go_mismatch` — located `(rows)` when not eight; `(overall)` when the last row's status differs from `go_no_go`; `(row-n)` when a row's status differs from `session-13.md` § Go / No-Go Assessment; `(frontmatter)` when `go_no_go` differs from the session's overall recommendation. Compared only once the session's overall cell is filled; **not checked** while `session-13.md` is absent |
+| § 16 vs Session 13 open items | every `session-13.md` § Open Items Register row whose *Must Resolve Before Build?* cell starts with `Yes` is either closed (its Status starts with `Closed`, `Resolved` or `Done`) or cited by `OI-` ID in a § 16 cell | `must_resolve_open` naming the item |
+| § 19 `Decision` (third column) | empty, `Approve`, `Approve with conditions` or `Reject` | `bad_signoff_decision` |
+| § 19 vs `status` | `Signed` ⇔ every row `Approve`; `Signed with conditions` ⇔ every row approves and at least one with conditions; `Rejected` ⇒ at least one `Reject`; `Draft` / `For sign-off` unconstrained | `signoff_status_mismatch` |
+| § 20 table | at least one row; versions in `<major>.<minor>`; the last row's version equals the frontmatter `version` | `history_missing`, `bad_version`, `history_version_mismatch` |
+| `_requirements.md` present but unparseable | the rollup grammar is owned by `discovery rollup` | `requirements_unparseable`, once — run `discovery rollup --check` for the detail; requirement IDs and counts are then not resolved |
+| any source under `.planning/discovery/` that exists but cannot be read | present-and-readable | `artifact_unreadable` naming the path — an unreadable source is a fault, never a silent skip |
+| `--require-signed` | `status` is `Signed` or `Signed with conditions` | `charter_unsigned`; when it is the only fault the exit identity is `discovery_charter_unsigned`, so the handoff can tell "unsigned" from "malformed" |
+| prose, table cells other than IDs and enums | free text in the sprint language | **not mechanically checked** — never validated, never echoed |
+
+**Posture (D-43 / D-53).** At Session 13 the check reports: an unsigned charter is not a fault, and a
+`Draft` with `Pending` is the expected state before topic 3. The hard block lives at
+`/pp-discovery-to-build` and nowhere else: `--require-signed` refuses `Draft`, `For sign-off` and
+`Rejected`; `--unsigned` on the handoff lets the build start and records the gap in PROJECT.md and
+STATE.md so nobody later mistakes it for a signed charter.
+
+**§ 7 and `_deviations.md` (improvement plan, Batch 3).** A `DEV-` ID resolves against
+`.planning/discovery/_deviations.md` alone — a `DEV-` in any other table is `unknown_id` — and every
+`DEV-` row of that register appears in the § 7 table (`deviation_missing` naming the row); § 7 holds a
+table even when empty (`table_missing`). Grammar of the register: `references/discovery-standards.md`.
+
+**Exit identity.** `discovery_charter_check_failed` for structural faults; `discovery_charter_unsigned`
+when the only fault is the signature requirement. The JSON payload (`ok`, `file`, `status`, `go_no_go`,
+`version`, `language`, `sections`, `ids_checked`) is emitted before the error on both failure paths.
+
+## Exports
+
+`PROJECT-CHARTER.docx` and `PROJECT-CHARTER.pdf` are written next to the markdown by the `docx` and
+`pdf` skills with the `pareto-brand` skill applied, every time the markdown changes (draft, for
+sign-off, every later version). The markdown is the source; an export is never edited by hand and never
+read back. When a skill is not installed, the draft step says so once, records
+`export: skipped (<skill> unavailable)` in the § 20 row's Change cell, and continues — a missing
+renderer never blocks the sprint. Exports are committed with the markdown.

package/pp-core/references/discovery-data-model.md

@@ -0,0 +1,145 @@
+# Discovery Data Model — `_entities.md` Template & Parser Contract
+
+Single home for the data model a build starts from: the `_entities.md` bootstrap template, its
+cell grammar, and the `pp_run query discovery.entity-check` parser contract (Discovery Sprint
+improvement plan, Batch 2). The handoff's ERD (`architecture-deliverables.md` § Data Model) is
+drawn from this file and nothing else, so a cardinality it does not state is a gap in the
+artifact, never a default. This file is Read lazily; it is never `@`-imported.
+
+## When the file appears
+
+| Session | Writes | From |
+|---|---|---|
+| 2 | creates the file from the template; one `## Entities` row per Data Entity Map row, Source `S2`, pending cells `—` | topic 5 Data flows and information architecture |
+| 3 | names the objects each step touches in `_processes.md` § Steps (`Task [C]`); every name must be an entity, so Step 5C adds missing rows here with Source `S3` | Step 5C |
+| 5 | **consolidates**: identifier, attribute table, relationships with cardinality, lifecycle states for every entity; `Status lifecycle` leaves `—` | topic 3 Key architectural components, § Domain Model / Entity Register |
+| 6 | writes `Classification` (the vault's four levels) and `Retention` for every entity | § Data Classification Matrix |
+| 8 | `entity-check` runs in the Closing Step (reporting) | Closing Step |
+| 13 | `entity-check` runs in the Step 0 gates (reporting) | `session-13-gates.md` |
+| handoff | `entity-check --require-complete` hard-blocks: no `—` left, every entity has attributes | `handoff-gates.md` |
+
+**Entities are named, never numbered** (Batch 2 decision). An entity is cited by its name, exactly
+as the `## Entities` table spells it — in step matrices, in `_rules.md`, in the charter. Nothing is
+deleted or renamed: an entity that turns out not to exist keeps its row with its reason in `Notes`
+and `Retention` `—`, exactly as a dropped requirement keeps its row.
+
+## Shared grammar
+
+- **Closed cells and free-text cells are not the same kind of cell** (`discovery-traceability.md`
+  § Shared grammar). The parser-contract table below says which is which; a free-text cell is never
+  validated and never echoed.
+- **`—` is "not yet known"**, allowed in `Identifier`, `Status lifecycle`, `Classification`,
+  `Retention`, and in an attribute's `Type` and `Required`, while the sprint runs; refused by
+  `--require-complete` at the handoff. Never write a guessed `yes` where `—` is the truth: the gate
+  can only name a gap it can see. An empty cell
+  is never allowed where `—` is: write the dash.
+- **Cardinality is Mermaid's**, so the ERD copies it: a left end `||` (exactly one), `|o` (zero or
+  one), `}o` (zero or more), `}|` (one or more); a line `--` (identifying) or `..` (non-identifying);
+  a right end `||`, `o|`, `o{`, `|{`. `||--o{` reads "one From has zero or more To". The line is
+  `--` when the relationship is carried by a foreign key and `..` when it is a reference by ID
+  without a key (an audit entry that outlives its subject). Inside a
+  markdown table cell every pipe is escaped — write `\|\|--o{` — or the row splits into the wrong
+  columns; the check unescapes before it validates.
+- **Classification is the vault's** (`security/compliance.md` § Information handling): `Public`,
+  `Internal`, `Confidential`, `Restricted`. A data store takes the highest level of any data in it.
+- **A data object in a step matrix is `Name [C/R/U/D]`** — the entity name, a space, and the CRUD
+  letters touched, slash-separated inside brackets: `Task [C]`, `Membership [C/R/U]`. Several are
+  comma-separated; `—` when the step touches none. Only entities of the product being built are
+  data objects: a file, a pull request, a pipeline run or a document of another system belongs in
+  the `Integration` column (with its direction) or in the step text, never in `Data objects`.
+
+Illustration only — these rows are **not** part of the template below, and the names are invented:
+
+| Entity | Identifier | Status lifecycle | Classification | Retention | Owner module | Source |
+|---|---|---|---|---|---|---|
+| Task | `id` GUID, app-generated | yes | Internal | 2 years after done (D-06-3) | Tasks | S2 |
+| Membership | (`team_id`, `user_id`) | none | Confidential | Ends when the member leaves (F-14) | Teams | S3 |
+
+| From | Cardinality | To | Name |
+|---|---|---|---|
+| Team | \|\|--o{ | Membership | has |
+
+**Template verbatim-safety rule.** The fenced template carries the title, the conventions line, the
+four section headings and the table headers with their separator rows — and **no example rows**.
+Copying it verbatim into a new discovery package passes `entity-check` cleanly, and a test proves it
+by executing it.
+
+Bootstrap template — Session 2 copies it verbatim to `.planning/discovery/_entities.md`, replacing
+`[PROJECT_NAME]`:
+
+```markdown
+# Data Model — [PROJECT_NAME]
+
+**Conventions:** pp-core reference `references/discovery-data-model.md`. Entities are named, never numbered, and cited exactly as spelled below. `—` means not yet known; nothing is deleted or renamed. A change after sign-off edits the row in place and appends `→ amended by D-<ss>-<n>` (`references/discovery-id-conventions.md` § Precedence).
+
+## Entities
+
+| Entity | Identifier | Status lifecycle | Classification | Retention | Owner module | Source |
+|--------|------------|------------------|----------------|-----------|--------------|--------|
+
+## Attributes
+
+## Relationships
+
+| From | Cardinality | To | Name |
+|------|-------------|----|------|
+
+## Lifecycles
+
+| Entity | State | Transition | Allowed by |
+|--------|-------|------------|------------|
+```
+
+Under `## Attributes`, Session 5 adds one `### <Entity>` heading per entity with this table:
+
+```markdown
+### Task
+
+| Attribute | Type | Required | Bounds | Notes |
+|-----------|------|----------|--------|-------|
+```
+
+## Parser contract — `pp_run query discovery.entity-check [--require-complete]`
+
+No positional path: `.planning/discovery/_entities.md` and `_processes.md` resolve against the
+working directory. Faults name the artifact, the 1-based line, a validated entity name, a section
+or column name and the reason code — never cell prose. An absent `_entities.md` exits 0 with
+`present: false` (an engagement that predates the data model).
+
+| Cell / field | Grammar | Fault when violated |
+|---|---|---|
+| `## Entities`, `## Attributes`, `## Relationships`, `## Lifecycles` | each present once as a `##` heading; Entities, Relationships and Lifecycles hold one table | `missing_section` naming the section (also when the heading exists but its table is absent) |
+| table headers | the template's columns, in order (case-insensitive) | `bad_table_shape` naming the section, or `Attributes · <Entity>` |
+| `Entity` | `^[A-Z][A-Za-z0-9]*$` — one PascalCase token — unique in the table | `bad_entity_name` (the cell is not echoed), `duplicate_entity` |
+| `Identifier` | non-empty; `—` while pending | `empty_cell (<Entity> · Identifier)`; `incomplete_cell` under `--require-complete` |
+| `Status lifecycle` | `none` \| `yes` \| `—` | `bad_lifecycle_flag`; `yes` without a `## Lifecycles` row → `lifecycle_without_states`; `none` with one → `states_without_lifecycle`; `—` → `incomplete_cell` under `--require-complete` |
+| `Classification` | `Public` \| `Internal` \| `Confidential` \| `Restricted` \| `—` | `bad_classification`; `—` → `incomplete_cell` under `--require-complete` |
+| `Retention` | free text, non-empty; `—` while pending | `empty_cell`; `—` → `incomplete_cell` under `--require-complete`. The text is **not mechanically checked** |
+| `Owner module`, `Source` | free text | **not mechanically checked** |
+| `### <Entity>` under Attributes | names a row of `## Entities`; holds the attribute table | `unknown_entity`; `bad_table_shape (Attributes · <Entity>)` |
+| an entity with no attribute row | every entity has at least one attribute by Session 5 | `attributes_missing` under `--require-complete` only |
+| `Attribute`, `Type` | non-empty; `Type` may be `—` while pending | `empty_cell (<Entity> · Attribute)`; a `—` Type → `incomplete_cell (<Entity> · <attribute> · Type)` under `--require-complete` |
+| `Required` | `yes` \| `no` \| `—` | `bad_required`; `—` → `incomplete_cell (<Entity> · <attribute> · Required)` under `--require-complete` |
+| `Bounds`, `Notes` | free text | **not mechanically checked** |
+| `From`, `To` | entity names from `## Entities` | `unknown_entity` |
+| `Cardinality` | `^(\|\||\|o|\}o|\}\|)(--|\.\.)(\|\||o\||o\{|\|\{)$` | `bad_cardinality` |
+| relationship `Name` | free text | **not mechanically checked** |
+| Lifecycles `Entity` | an entity name | `unknown_entity` |
+| Lifecycles `State` | non-empty | `empty_cell (<Entity> · State)` |
+| Lifecycles `Transition`, `Allowed by` | free text | **not mechanically checked** |
+| `_processes.md` § Steps `Data objects` | every well-formed `Name [C/R/U/D]` token names an entity | `unknown_entity` located in `_processes.md`; a malformed token is `process-check`'s `bad_data_object`, not reported here |
+| `_processes.md` present but unreadable | present-and-readable | `artifact_unreadable` |
+
+**Exit identity.** `discovery_entity_check_failed` for structural faults;
+`discovery_entity_check_incomplete` when every fault is an `incomplete_cell` or `attributes_missing`
+raised by `--require-complete`, so a gate can tell "not finished" from "malformed". The payload
+(`ok`, `present`, `file`, `entities`, `attributes`, `relationships`, `lifecycles`,
+`step_objects_checked`) is emitted before the error on the failure path.
+
+## How the handoff draws from it
+
+`architecture-deliverables.md` § Data Model emits one `erDiagram` entity block per `## Entities` row
+with its attributes (`type name`), and one relationship line per `## Relationships` row with the
+cardinality verbatim. There is no default cardinality any more: a relationship this file does not
+state is not drawn, and the prose says `[not captured in Discovery]`. An engagement without
+`_entities.md` falls back to Session 5's register under the same rule.