@pareto4/pp-core 1.19.0 → 1.20.0

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

@@ -1,7 +1,7 @@
 # Discovery ID & Decision Conventions
 
 Single source for every ID family used across discovery artifacts (TRACE-01). All
-discovery artifacts — session notes, `_context.md`, `_requirements.md`, research-track
+discovery artifacts — session notes, `_requirements.md`, research-track
 files — cite IDs inline against this file. IDs are never renumbered: once minted, an ID
 keeps its meaning for the life of the engagement, and readers can follow any citation
 back to exactly one definition. This file is Read lazily by discovery sessions; it is
@@ -11,19 +11,26 @@ never `@`-imported.
 
 | Family | Format | Example | Used for |
 |--------|--------|---------|----------|
-| Decisions | `D-<ss>-<n>` — `<ss>` = zero-padded 2-digit session number, `<n>` = unpadded per-session sequence. Regex: `D-\d{2}-\d+` | `D-04-2` (Session 4, decision 2) | Decisions recorded during any session; cited by requirements, actions, and later sessions |
+| Decisions | `D-<ss>-<n>` — `<ss>` = zero-padded 2-digit session number, or `P<nn>` for a build phase (§ Precedence), `<n>` = unpadded per-session sequence. Regex: `D-(\d{2}|P\d{2})-\d+` | `D-04-2` (Session 4, decision 2); `D-P03-2` (phase 3, decision 2) | Decisions recorded during any session, and build-phase decisions that amend a discovery fact; cited by requirements, actions, and later sessions |
 | Actions | `A-<ss>-<n>` — same shape as decisions. Regex: `A-\d{2}-\d+` | `A-03-1` | Action items owned by a person, minted in the session that raised them |
 | Sparring positions | `SP-<nn>` — zero-padded 2-digit global sequence, no session component. Regex: `SP-\d{2}` | `SP-03` | Positions taken in the sparring tracker `_sparring.md` |
 | Data-gathering items | `DG-<nn>` — same shape as SP. Regex: `DG-\d{2}` | `DG-07` | Open data-gathering items in `_risks.md` |
 | Research items | `RS-<nn>` — same shape as SP/DG: zero-padded 2-digit global sequence, no session component. Regex: `RS-\d{2}` | `RS-01` | Rows of `_research.md`, the research-only backlog |
 | Screens | `SCR-<nn>` — zero-padded 2-digit global sequence, no session and no role component, minted by scan (D-12). Regex: `SCR-\d{2}` | `SCR-01` | Rows of `_screens.md`, the requirement-to-screen inventory; Role is a grouping column, not part of the ID (D-50) |
-| Processes | `PRC-<nn>` — zero-padded 2-digit global sequence. Regex: `PRC-\d{2}` | `PRC-03` | Rows of the Session 2 **Process Inventory**, the as-is processes Session 3 transforms |
+| Processes (as-is) | `PRC-<nn>` — zero-padded 2-digit global sequence. Regex: `PRC-\d{2}` | `PRC-03` | Rows of `_processes.md` § As-is (Session 2), the processes Session 3 transforms (`references/discovery-processes.md`) |
+| Main processes (to-be) | `MP-<nn>` — same shape. Regex: `MP-\d{2}` | `MP-01` | Rows of `_processes.md` § To-be (Session 3 Step 5A); each names the `PRC-` rows it replaces or `new` |
+| Business rules | `BR-<nn>` — same shape. Regex: `BR-\d{2}` | `BR-01` | Rows of `_rules.md` (Session 3 Step 5D′); every rule cites at least one requirement |
+| Entities | named, never numbered — one PascalCase token, cited exactly as `_entities.md` § Entities spells it (`references/discovery-data-model.md`) | `Task`, `AuditEntry` | Rows of `_entities.md`; step matrices cite them as `Task [C]` |
+| Interfaces | `IF-<nn>` — same shape as SP. Regex: `IF-\d{2}` | `IF-01` | Rows of `_integrations.md` § Interfaces (Session 5 mints, Session 8 completes); step matrices cite them in their `Integration` cell (`references/discovery-integrations.md`) |
+| Migration rows | `MG-<nn>` — same shape. Regex: `MG-\d{2}` | `MG-01` | Rows of `_migration.md` (Session 2 seeds, Session 8 completes) |
+| Deviations | `DEV-<nn>` — same shape. Regex: `DEV-\d{2}` | `DEV-01` | Rows of `_deviations.md`, the agreed departures from vault standards (Sessions 1, 4–10; `references/discovery-standards.md`); the charter § 7 copies them |
+| Roles | named, never numbered — a Session 2 persona, a step-matrix actor or `System`, spelled as `_roles.md` § Roles spells it (`references/discovery-access.md`) | `Team lead` | Rows of `_roles.md` |
 | Requirements | `<PREFIX><n>` — PREFIX is a registered domain prefix (uppercase letters/digits ending in `-`, e.g. a stakeholder-domain prefix, `N-` non-functional, `T-` technical); `<n>` is a numeric sequence, zero-padded to 2 digits by convention (`01`..`99`, then `100`). Regex: `[A-Z][A-Z0-9]*-\d+` | `N-01` | Rows of `_requirements.md`; the prefix carries the classification — there is no separate Type column |
 | Input-package accessions | `NN` — zero-padded 2-digit number, assigned in arrival order and never renumbered; a mid-sprint document takes the next number (D-16). Regex: `\d{2}` | `03` | Numbered documents in `.planning/discovery-input/` (including its `confidential/` subdir — one number space spans both locations, D-21). Reading order is a README column, not the number |
 
 ## Reserved Prefixes
 
-Seven prefixes are reserved by the ID families above and MUST NOT be registered as
+Twelve prefixes are reserved by the ID families above and MUST NOT be registered as
 domain prefixes in the `_requirements.md` Prefix Registry:
 
 | Reserved | Owned by |
@@ -34,7 +41,12 @@ domain prefixes in the `_requirements.md` Prefix Registry:
 | `DG-` | Data-gathering items |
 | `RS-` | Research items |
 | `SCR-` | Screens |
-| `PRC-` | Processes |
+| `PRC-` | Processes (as-is) |
+| `MP-` | Main processes (to-be) |
+| `BR-` | Business rules |
+| `IF-` | Interfaces |
+| `MG-` | Migration rows |
+| `DEV-` | Deviations |
 
 Every one of them satisfies the requirement-ID regex `[A-Z][A-Z0-9]*-\d+`, so a
 registry that claims one mints requirement IDs indistinguishable from the family that
@@ -47,9 +59,12 @@ and a requirement — the same collision, one artifact further along the traceab
 
 `PRC-` followed with issue #12: Session 2 used to number processes `P-<nn>`, which an
 engagement had also registered as a domain prefix, so `P-03` meant two things. Process IDs
-moved to `PRC-` and the prefix is reserved so the clash cannot come back.
+moved to `PRC-` and the prefix is reserved so the clash cannot come back. `MP-` and `BR-`
+joined when `_processes.md` and `_rules.md` became artifacts of their own (improvement plan,
+Batch 2), `IF-`, `MG-` and `DEV-` when `_integrations.md`, `_migration.md` and `_deviations.md`
+did (Batch 3): an artifact ID family is reserved the day it gets a check.
 
-Session 1's kick-off prefix selection (D-09) must refuse all seven: pick a different
+Session 1's kick-off prefix selection (D-09) must refuse all twelve: pick a different
 domain prefix (any other uppercase letters/digits ending in `-`, e.g. `K-` for *Klant*).
 Non-reserved prefixes are unaffected.
 
@@ -71,21 +86,42 @@ citation such as `C-01` reads two ways.
 | `CON-` | Constraints and Risks Register (constraints) | 1 |
 | `R-` | Constraints and Risks Register (risks), continued by the Risk Register | 1, 11 |
 | `PP-` | Pain Points Register | 2 |
-| `MP-` | Main Process Register | 3 |
 | `BO-` | Business Objectives | 3 |
 | `E-` | EPIC Register | 3 |
 | `US-` | User Stories | 3 |
 | `C-` | Component Inventory | 5 |
-| `INT-` | Integration Points Map | 5 |
 | `ADR-` | Architecture Decision Records | 5 |
 | `CR-` | Compliance Requirements Register | 6 |
-| `IF-` | Integration Design Register | 8 |
 | `OI-` | Open Items Register | 13 |
 
 Non-functional requirements are not in this list: they are `N-` rows of
 `_requirements.md`, minted like every other requirement, and Session 3's
 **Non-Functional Requirements** table cites them by that ID.
 
+## Precedence — one source of truth, amended in place (R2)
+
+The canonical artifacts — `_requirements.md`, `_screens.md`, `_feedback.md`, `_sweep.md`,
+`_processes.md`, `_entities.md`, `_rules.md`, `_glossary.md`, `_stories.md`, `_phases.md`,
+`_roles.md`, `_integrations.md`, `_migration.md`, `_deviations.md`, the research registers and
+the Project Charter — are the single source of truth for the life of the engagement, through the
+build and after it. The session files are the facilitation record behind them.
+
+- **A decision that changes a recorded fact edits the row where the fact lives** — a field, a
+  rule, a role, a flow step, a requirement — and appends ` → amended by D-<ss>-<n>` to the changed
+  cell. That is the back-amend rule Flow 2 Step 6 applies to session notes, applied to artifacts.
+  The old text stays readable before the arrow; the artifact is its own changelog.
+- **Never a second copy.** CONTEXT.md and PLAN.md hold an *extract* of the rows a phase needs
+  (the `discovery for-phase` output); they never hold an override. A build that wants a different
+  answer changes the artifact, then re-runs the artifact's check.
+- **In build, `<ss>` is `P<nn>`**: the zero-padded number of the pp-core phase whose
+  `/pp-discuss-phase` minted the decision, so `D-P03-2` is the second decision of phase 3, recorded
+  in that phase's CONTEXT.md **Decisions** table. Every engine that reads a decision ID accepts both
+  shapes (`D-(\d{2}|P\d{2})-\d+`); `charter-check` resolves `D-<ss>-` IDs against the session
+  files and takes `D-P` IDs on shape, because their mint lives outside `.planning/discovery/`.
+- **The charter follows.** An amendment to a fact the charter states adds a § 20 Version history
+  row citing the decision and bumps the version (`workflows/discovery-sprint/charter.md`
+  § Redraft).
+
 ## Citation Rules
 
 - Requirement IDs are never renumbered and never reused (REQM-02). A gap in a sequence
@@ -144,14 +180,14 @@ counts as NOT covered. `⚠️ CONDITIONAL` means a real decision was made in th
 knowingly contingent on outside work — that IS the answer, honestly qualified, and it
 counts as COVERED for the Step 7 completeness score.
 
-Where markers may live (D-46): **prose sections only** — session notes, `_context.md`
-sections, and (Phase 4) mockup surfaces. They are explicitly forbidden inside
+Where markers may live (D-46): **prose sections only** — session notes and (Phase 4)
+mockup surfaces. They are explicitly forbidden inside
 `_requirements.md` table cells; the closed requirements grammar already rejects a marker
 in any structured cell. The join for a research-dependent requirement is an `_research.md`
 row citing that requirement in its `Gates what?` cell, not a marker in the row itself.
 
-A marker travels with the content it qualifies: when Step 7 propagates a session answer
-into a `_context.md` section, the marker propagates with it.
+A marker travels with the content it qualifies: when an answer is copied into a register
+row or a later session, the marker goes with it.
 
 The three research-track register templates (`_research.md`, `_risks.md`, `_sparring.md`),
 their cell grammars, and the `research-check` parser contract live in the sibling

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

@@ -0,0 +1,151 @@
+# Discovery Integrations & Migration — Templates & Parser Contracts
+
+Single home for two artifacts the build reads instead of session files (Discovery Sprint improvement
+plan, Batch 3): `_integrations.md` (interfaces with other systems, their contracts and error
+handling) and `_migration.md` (data the new solution takes over from existing systems). Each has a
+`pp_run query discovery.*-check` gate. This file is Read lazily; it is never `@`-imported.
+
+## When the files appear
+
+| Session | `_integrations.md` | `_migration.md` |
+|---|---|---|
+| 2 | — | created from the template; topic 7 writes one `MG-` row per source system and entity set, `Requirements` `—` |
+| 3 | step matrices name a system in their `Integration` cell (prose until Session 5) | — |
+| 5 | created from the template; topic 4 mints one `IF-` row per external system (system, direction, pattern, owner, requirements), `Protocol`/`Format`/`Idempotency` `—`, and back-fills the step matrices' `Integration` cells with the `IF-nn` | — |
+| 8 | topics 2–4 fill `Protocol`, `Format`, `Idempotency`, `## Contract` and `## Errors`; `integrations-check --require-cited` in the session | topic 6 fills `Mapping`, `Cut-over`, `Reconciliation` and back-fills `Requirements`; `migration-check --require-cited` in the session |
+| 8 | both checks in the Closing Step (reporting) | |
+| 13 | both in the Step 0 gates (reporting) | |
+| handoff | `integrations-check --require-cited` and `migration-check --require-cited` hard-block | |
+
+Session 5's **Integration Points Map** and Session 8's **Integration Design Register**, **Data
+Transformation Map** and **Error Handling Strategy** keep their headings as reading summaries that
+point here; Session 2's **Data to Migrate** and Session 8's **Migration and Cut-over** do the same.
+`IF-` and `MG-` are reserved prefixes (`references/discovery-id-conventions.md`); the old `INT-`
+numbering of the Session 5 map is retired — an interface has one ID from Session 5 to go-live.
+
+## Shared grammar
+
+- **Nothing is renumbered and nothing is deleted.** `IF-` and `MG-` run contiguously from 01; a
+  hole is reported naming the missing ID. A retired interface keeps its row.
+- **`—` is a pending cell**, allowed until the session that owns the cell runs; the handoff refuses a
+  pending `Requirements` with `--require-cited`.
+- **Requirements** cites `_requirements.md` IDs, comma-separated.
+- **A change after sign-off edits the row in place** and appends `→ amended by D-<ss>-<n>`
+  (`references/discovery-id-conventions.md` § Precedence).
+
+## `_integrations.md`
+
+Illustration only — not part of the template, names invented:
+
+| ID | System | Direction | Pattern | Protocol | Format | Idempotency | Owner | Requirements |
+|---|---|---|---|---|---|---|---|---|
+| IF-01 | Entra ID | inbound | sign-in | OIDC | JWT | n/a (read-only) | Identity team | N-05 |
+
+| Interface | Field | Type | Required | Mapping | Validation |
+|---|---|---|---|---|---|
+| IF-01 | oid | string | yes | User.entra_object_id | GUID |
+
+| Interface | Failure | Handling | Retry | Dead letter | Alert |
+|---|---|---|---|---|---|
+| IF-01 | Token invalid | 401, sign-in page | none | — | none |
+
+Bootstrap template — Session 5 copies it verbatim to `.planning/discovery/_integrations.md`,
+replacing `[PROJECT_NAME]`:
+
+```markdown
+# Integrations — [PROJECT_NAME]
+
+**Conventions:** pp-core reference `references/discovery-integrations.md`. One `IF-` row per interface with another system; `Direction` is `inbound`, `outbound` or `bidirectional` from the product's side; `## Contract` lists the fields exchanged and `## Errors` the failures handled, both keyed by interface. Step matrices cite an interface by its `IF-nn`. Rows are never renumbered or deleted; a change after sign-off edits the row in place and appends `→ amended by D-<ss>-<n>`.
+
+## Interfaces
+
+| ID | System | Direction | Pattern | Protocol | Format | Idempotency | Owner | Requirements |
+|----|--------|-----------|---------|----------|--------|-------------|-------|--------------|
+
+## Contract
+
+| Interface | Field | Type | Required | Mapping | Validation |
+|-----------|-------|------|----------|---------|------------|
+
+## Errors
+
+| Interface | Failure | Handling | Retry | Dead letter | Alert |
+|-----------|---------|----------|-------|-------------|-------|
+```
+
+### Parser contract — `pp_run query discovery.integrations-check [--require-cited]`
+
+No positional path. Faults name the artifact, the 1-based line, a validated ID, a section or column
+name and the reason code — never cell prose. Absent `_integrations.md` → exit 0, `present: false`.
+
+| Cell / field | Grammar | Fault when violated |
+|---|---|---|
+| `## Interfaces`, `## Contract`, `## Errors` | each once as a `##` heading holding one table with the template's columns | `missing_section`, `bad_table_shape` naming the section |
+| Interfaces `ID` | `IF-\d{2}`, unique, contiguous from 01 | `bad_id`, `duplicate_id`, `sequence_gap` naming the missing ID |
+| `System`, `Pattern`, `Protocol`, `Format`, `Idempotency`, `Owner` | non-empty (`—` is a pending cell) | `empty_cell` naming the column |
+| `Direction` | `inbound` \| `outbound` \| `bidirectional` | `bad_direction` |
+| Interfaces `Requirements` | `—` (uncited), or a comma list of requirement IDs each present in `_requirements.md` when on file and parseable | `unknown_requirement_id`; `uncited_interface` under `--require-cited` only |
+| Contract / Errors `Interface` | an `IF-nn` present in `## Interfaces` | `unknown_interface` |
+| Contract `Field`, `Type` | non-empty | `empty_cell` |
+| Contract `Required` | `yes` \| `no` | `bad_required` |
+| Contract `Mapping`, `Validation`; Errors `Retry`, `Dead letter`, `Alert` | free text (`—` allowed) | **not mechanically checked** |
+| Errors `Failure`, `Handling` | non-empty | `empty_cell` |
+| a step matrix `Integration` cell in `_processes.md` | `—`, or text naming at least one `IF-nn` present in `## Interfaces` | `unknown_interface` located in `_processes.md`; `step_integration_unlinked` (a non-`—` cell with no `IF-`) under `--require-cited` only |
+| `_requirements.md` present but unparseable | the rollup grammar is owned by `discovery rollup` | `requirements_unparseable`, once |
+| a source present but unreadable | present-and-readable | `artifact_unreadable` naming the path |
+
+**Exit identity.** `discovery_integrations_check_failed` for structural faults;
+`discovery_integrations_uncited` when every fault was raised by `--require-cited`. Payload: `ok`,
+`present`, `file`, `interfaces`, `contract_rows`, `error_rows`, `uncited`.
+
+## `_migration.md`
+
+A migration row is one source system and the entities the new solution takes over from it: how much
+(volume), how each field maps, how the cut-over runs (big bang, parallel run, phased) and how the move
+is proven (reconciliation counts, spot checks). Most engagements migrate nothing — the file is then
+never created and every check exits 0.
+
+Illustration only:
+
+| ID | Source system | Entity | Volume | Mapping | Cut-over | Reconciliation | Requirements |
+|---|---|---|---|---|---|---|---|
+| MG-01 | Legacy tracker | Task, Comment | 12k tasks, 40k comments | tracker.csv → Task (title, status map), Comment | Big bang on go-live weekend; tracker read-only from Friday | Row counts per status; 50 tasks compared by hand | T-07 |
+
+Bootstrap template — Session 2 topic 7 copies it verbatim to `.planning/discovery/_migration.md` when
+there is data to migrate:
+
+```markdown
+# Migration — [PROJECT_NAME]
+
+**Conventions:** pp-core reference `references/discovery-integrations.md` § `_migration.md`. One `MG-` row per source system and entity set; `Source system` is a row of Session 2's Systems Landscape, `Entity` names rows of `_entities.md`. Session 2 fills what moves and how much; Session 8 fills mapping, cut-over and reconciliation and cites the requirements. Rows are never renumbered or deleted; a change after sign-off edits the row in place and appends `→ amended by D-<ss>-<n>`.
+
+## Migration
+
+| ID | Source system | Entity | Volume | Mapping | Cut-over | Reconciliation | Requirements |
+|----|---------------|--------|--------|---------|----------|----------------|--------------|
+```
+
+### Parser contract — `pp_run query discovery.migration-check [--require-cited]`
+
+| Cell / field | Grammar | Fault when violated |
+|---|---|---|
+| `## Migration` | once, holding one table with the template's columns | `missing_section`, `bad_table_shape` |
+| `ID` | `MG-\d{2}`, unique, contiguous from 01 | `bad_id`, `duplicate_id`, `sequence_gap` |
+| `Source system` | non-empty; a first-column value of Session 2's **Systems Landscape** when that table is on file with rows | `empty_cell (Source system)`; `unknown_system` naming the system |
+| `Entity` | a comma list of PascalCase names, each present in `_entities.md` § Entities when on file | `bad_entity`; `unknown_entity` naming the entity |
+| `Volume`, `Mapping`, `Cut-over`, `Reconciliation` | non-empty (`—` is a pending cell) | `empty_cell` naming the column |
+| `Requirements` | `—` (uncited), or a comma list of requirement IDs each present in `_requirements.md` when on file and parseable | `unknown_requirement_id`; `uncited_migration` under `--require-cited` only |
+| `_requirements.md` present but unparseable | owned by `discovery rollup` | `requirements_unparseable`, once |
+| a source present but unreadable | present-and-readable | `artifact_unreadable` naming the path |
+
+**Exit identity.** `discovery_migration_check_failed` for structural faults;
+`discovery_migration_uncited` when every fault is an `uncited_migration`. Payload: `ok`, `present`,
+`file`, `rows`, `uncited`.
+
+## How the build reads them
+
+`pp_run query discovery.for-phase <N>` selects the § Interfaces rows that cite the phase's requirement
+IDs or that a selected step names in its `Integration` cell, with their § Contract and § Errors rows;
+`_migration.md` rows reach the phase through their `Requirements` column
+(`references/discovery-build-consumption.md`). The handoff's C4 Context diagram draws its
+`System_Ext` nodes from § Interfaces (`workflows/discovery-to-build/steps/architecture-deliverables.md`).

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

@@ -0,0 +1,190 @@
+# Discovery Processes, Rules & Glossary — Templates & Parser Contracts
+
+Single home for three artifacts the build reads instead of session files (Discovery Sprint
+improvement plan, Batch 2): `_processes.md` (as-is and to-be processes, swimlanes, step
+matrices), `_rules.md` (business rules) and `_glossary.md` (the ubiquitous language). The first
+two have a `pp_run query discovery.*-check` gate; the glossary deliberately has none. This file is Read
+lazily; it is never `@`-imported.
+
+## When the files appear
+
+| Session | `_processes.md` | `_rules.md` | `_glossary.md` |
+|---|---|---|---|
+| 2 | created from the template; `## As-is` rows (`PRC-`) from topic 1 | — | created from the template; terms the client used for the same thing |
+| 3 | Step 5A `## To-be` rows (`MP-`, each with `Replaces`); 5B one swimlane per main process under `## Flows`; 5C one step matrix per main process under `## Steps`, `Exception` column filled; 5D back-fills `Requirements` | Step 5D′ mints `BR-` rows from the step matrices | topic 1 glossary sweep: one row per term, synonyms under `Do not use` |
+| 8 | `process-check` and `rules-check` in the Closing Step (reporting) | | |
+| 13 | both in the Step 0 gates (reporting) | | |
+| handoff | `process-check --require-cited` and `rules-check` hard-block | | |
+
+**The session files keep their Notes Template headings as pointers** (Main Process Register,
+Sub-Process Flows, Step Matrices, Process Inventory): the canonical rows live here, exactly as the
+requirements table lives in `_requirements.md`. `PRC-`, `MP-` and `BR-` are reserved prefixes
+(`references/discovery-id-conventions.md`), so none of them can collide with a requirement ID.
+
+## Shared grammar
+
+- Closed cells and free-text cells are not the same kind of cell; the contract tables say which.
+- **Nothing is renumbered and nothing is deleted.** `PRC-`, `MP-` and `BR-` run contiguously from
+  01; a hole is reported naming the missing ID. A retired process or rule keeps its row.
+- **An actor is a Session 2 persona or `System`**, spelled as the User Personas table spells it;
+  a step two actors perform together names both, comma-separated (`Team lead, System`). A
+  qualifier in parentheses or a slash-joined pair is not a persona and is refused.
+- **A data object is `Name [C/R/U/D]`** (`references/discovery-data-model.md`); `—` when a step
+  touches none.
+- **A step cites requirements by ID**, comma-separated, after Step 5D; `—` before it. The handoff
+  refuses an uncited step.
+- **A swimlane is a Mermaid `flowchart` with one `subgraph` per actor**, so the lane shows who does
+  the step; a flowchart without a `subgraph` is a decision tree, not a swimlane, and is refused.
+
+## `_processes.md`
+
+Illustration only — not part of the template, names invented:
+
+| ID | Main process | Replaces | Trigger | End state | Primary actor | EPICs |
+|---|---|---|---|---|---|---|
+| MP-01 | Handle a task from request to done | PRC-02, PRC-03 | A team member needs work tracked | Task closed with an outcome | Team member | E-01 |
+
+| # | Step | Actor | UI | Data objects | Integration | Exception | Requirements |
+|---|---|---|---|---|---|---|---|
+| 01.1 | Create task | Team member | Task form | Task [C] | — | Title missing → form error, nothing saved | K-06 |
+
+Bootstrap template — Session 2 copies it verbatim to `.planning/discovery/_processes.md`, replacing
+`[PROJECT_NAME]`:
+
+```markdown
+# Processes — [PROJECT_NAME]
+
+**Conventions:** pp-core reference `references/discovery-processes.md`. `PRC-` rows are the as-is processes (Session 2), `MP-` rows the to-be main processes (Session 3) with the as-is processes each replaces or `new`. One swimlane and one step matrix per main process. Nothing is renumbered or deleted; a change after sign-off edits the row in place and appends `→ amended by D-<ss>-<n>`.
+
+## As-is
+
+| ID | Process | Owner | Trigger | End state | Frequency | Avg duration | Criticality |
+|----|---------|-------|---------|-----------|-----------|--------------|-------------|
+
+## To-be
+
+| ID | Main process | Replaces | Trigger | End state | Primary actor | EPICs |
+|----|--------------|----------|---------|-----------|---------------|-------|
+
+## Flows
+
+## Steps
+```
+
+Under `## Flows`, Step 5B adds one `### MP-nn — <name>` heading per main process holding a swimlane:
+
+````markdown
+### MP-01 — Handle a task
+
+```mermaid
+flowchart LR
+  subgraph Team member
+    S1[Create task] --> S2[Assign]
+  end
+  subgraph System
+    S3[Notify assignee]
+  end
+  S2 --> S3
+```
+````
+
+Under `## Steps`, Step 5C adds one `### MP-nn — <name>` heading per main process holding its matrix:
+
+```markdown
+### MP-01 — Handle a task
+
+| # | Step | Actor | UI | Data objects | Integration | Exception | Requirements |
+|---|------|-------|----|--------------|-------------|-----------|--------------|
+```
+
+### Parser contract — `pp_run query discovery.process-check [--require-cited]`
+
+No positional path. Faults name the artifact, the 1-based line, a validated ID, a section or
+column name and the reason code — never cell prose. Absent `_processes.md` → exit 0, `present: false`.
+
+| Cell / field | Grammar | Fault when violated |
+|---|---|---|
+| `## As-is`, `## To-be`, `## Flows`, `## Steps` | each once as a `##` heading; As-is and To-be hold one table | `missing_section` |
+| table headers | the template's columns, in order | `bad_table_shape` naming the section, or `Steps · MP-nn` |
+| As-is `ID` | `PRC-\d{2}`, unique, contiguous from 01 | `bad_id`, `duplicate_id`, `sequence_gap` naming the missing ID |
+| As-is `Process` | non-empty | `empty_cell (Process)` |
+| As-is other columns | free text | **not mechanically checked** |
+| To-be `ID` | `MP-\d{2}`, unique, contiguous from 01 | `bad_id`, `duplicate_id`, `sequence_gap` |
+| To-be `Main process` | non-empty | `empty_cell (Main process)` |
+| `Replaces` | `new`, or a comma list of `PRC-` IDs present in `## As-is` | `bad_replaces` (empty, or a token of the wrong shape), `unknown_process` naming the PRC |
+| `Primary actor`, step `Actor` | a comma list of `System` and names from Session 2's User Personas table (first column), spelled exactly | `bad_actor` (empty, or any token that is neither). **Not resolved** while `session-02.md` or its table is absent — the cell is then only required non-empty |
+| `Trigger`, `End state`, `EPICs` | free text | **not mechanically checked** (EPIC IDs are not resolved against Session 3) |
+| `### MP-nn — <name>` under Flows and Steps | names a To-be row | `unknown_process` |
+| a main process without a `### MP-nn` under Flows / Steps | one swimlane and one matrix each | `flow_missing`, `steps_missing` naming the MP |
+| a flow body | a ```` ```mermaid ```` block opening with `flowchart` and holding at least one `subgraph` | `flow_not_swimlane` |
+| step `#`, `Step` | non-empty | `empty_cell (Step)` |
+| `UI`, `Integration`, `Exception` | free text (`—` allowed) | **not mechanically checked** — the Exception column must exist, its content is the facilitator's |
+| `Data objects` | `—`, or a comma list of `Name [C/R/U/D]` tokens | `bad_data_object`; whether each name is an entity is `entity-check`'s `unknown_entity` |
+| `Requirements` | `—` (uncited), or a comma list of requirement IDs, each present in `_requirements.md` when it is on file and parseable | `unknown_requirement_id`; `uncited_step` under `--require-cited` only |
+| `_requirements.md` present but unparseable | the rollup grammar is owned by `discovery rollup` | `requirements_unparseable`, once; IDs are then shape-checked only |
+| a source present but unreadable | present-and-readable | `artifact_unreadable` naming the path |
+
+**Exit identity.** `discovery_process_check_failed` for structural faults;
+`discovery_process_steps_uncited` when every fault is an `uncited_step`. Payload: `ok`, `present`,
+`file`, `as_is`, `to_be`, `flows`, `steps`, `uncited`.
+
+## `_rules.md`
+
+A business rule is a validation, a calculation or an invariant the system enforces. It applies to
+an entity or a process, is checked in exactly the layers named (the vault's "one owning layer per
+check"), and realises at least one requirement — a rule nothing requires is a rule nobody asked for.
+
+Illustration only:
+
+| ID | Rule | Applies to | Checked at | Requirements | Source |
+|---|---|---|---|---|---|
+| BR-01 | A team has exactly one Lead | Membership | service, DB | K-15 | S3 |
+
+Bootstrap template — Session 3 Step 5D′ copies it verbatim to `.planning/discovery/_rules.md`:
+
+```markdown
+# Business Rules — [PROJECT_NAME]
+
+**Conventions:** pp-core reference `references/discovery-processes.md` § `_rules.md`. `BR-` is reserved; rows are never renumbered or deleted; a change after sign-off edits the row in place and appends `→ amended by D-<ss>-<n>`.
+
+## Rules
+
+| ID | Rule | Applies to | Checked at | Requirements | Source |
+|----|------|------------|------------|--------------|--------|
+```
+
+### Parser contract — `pp_run query discovery.rules-check`
+
+| Cell / field | Grammar | Fault when violated |
+|---|---|---|
+| `## Rules` | once, holding one table with the template's columns | `missing_section`, `bad_table_shape` |
+| `ID` | `BR-\d{2}`, unique, contiguous from 01 | `bad_id`, `duplicate_id`, `sequence_gap` |
+| `Rule` | non-empty | `empty_cell (Rule)` |
+| `Applies to` | a comma list; each token an entity name (`^[A-Z][A-Za-z0-9]*$`) present in `_entities.md` § Entities, or a `PRC-`/`MP-` ID present in `_processes.md` | `bad_subject` (empty, or a token of neither shape); `unknown_subject` naming the token. **Not resolved** while the owning artifact is absent |
+| `Checked at` | a comma list from `UI` \| `service` \| `DB` | `bad_checked_at` |
+| `Requirements` | at least one requirement ID, each present in `_requirements.md` when on file and parseable | `no_requirement`, `unknown_requirement_id` |
+| `Source` | free text | **not mechanically checked** |
+
+**Exit identity.** `discovery_rules_check_failed`. Payload: `ok`, `present`, `file`, `rules`.
+
+## `_glossary.md`
+
+One word per concept (the vault's naming rule). A term the requirements use must be defined once;
+every other word for it goes under `Do not use`, so the build inherits the vocabulary instead of
+re-deriving it. Rows are keyed by `Term`, not by an ID.
+
+Bootstrap template — Session 2 copies it verbatim to `.planning/discovery/_glossary.md`:
+
+```markdown
+# Glossary — [PROJECT_NAME]
+
+**Conventions:** pp-core reference `references/discovery-processes.md` § `_glossary.md`. One row per concept; the term is the one the requirements and the code use; `Do not use` lists the synonyms heard in the room.
+
+| Term | Definition | Do not use | Source |
+|------|------------|------------|--------|
+```
+
+**Not mechanically checked — deliberately.** A definition has no closed grammar, and a check that
+only counted rows would reward padding. The glossary is read by every agent and reviewed in the
+Session 13 cross-reference ("Stakeholder names" and "KPIs and metrics" rows), where a term with
+two spellings is a finding.

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

@@ -20,8 +20,8 @@ changes on account of this file.
 
 ## When this file appears
 
-`_rebaseline.md` is bootstrapped **on first need** (D-31), exactly the way `_progress.md` and
-`_context.md` are in Flow 2 Step 1, and exactly the way `_screens.md`, `_feedback.md` and the
+`_rebaseline.md` is bootstrapped **on first need** (D-31), exactly the way `_progress.md`
+is in Flow 2 Step 1, and exactly the way `_screens.md`, `_feedback.md` and the
 three research-track registers are: the file does not exist until the first re-baselining round
 runs, and if it is absent when a round first has something to put in it, create it verbatim from
 the template below and then add the rows. There is no setup step and no separate sub-command. An

package/pp-core/references/discovery-research-track.md

@@ -17,7 +17,7 @@ restate them. Read that file when you need an ID's shape or the reserved set.
 ## When these files appear
 
 The three registers are bootstrapped **on first need**, exactly the way `_progress.md`
-and `_context.md` are in Flow 2 Step 1: if the file is absent when a session first has
+is in Flow 2 Step 1: 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 `/pp-discovery research` sub-command and no setup step — an empty register
 is not a milestone, and a register that exists with zero rows is indistinguishable from
@@ -231,8 +231,7 @@ qualifies (D-45). Three engine consequences:
    frontmatter ID with no marker in the body — is `conditional_frontmatter_drift`. The
    frontmatter is derived state and must match what is actually marked.
 
-**Where markers may live (D-46): prose sections only.** Session notes and `_context.md`
-sections carry markers; `_requirements.md` table cells never do. The closed requirements
+**Where markers may live (D-46): prose sections only.** Session notes carry markers; `_requirements.md` table cells never do. The closed requirements
 grammar already rejects a marker in any structured cell, and the correct join for a
 research-dependent requirement already exists: an `_research.md` row citing that
 requirement in its `Gates what?` cell.
@@ -244,9 +243,9 @@ paper that no human has confirmed. `⚠️ CONDITIONAL` means a real decision wa
 the room and is knowingly contingent on outside work — that *is* the answer, honestly
 qualified.
 
-**A marker travels with the content it qualifies.** When Step 7 propagates a session
-answer into a `_context.md` section, the marker propagates with it; the marker is part
-of the answer, not an annotation on the session file.
+**A marker travels with the content it qualifies.** When an answer is copied into a
+register row or a later session, the marker goes with it; the marker is part of the
+answer, not an annotation on the session file.
 
 ## Parser contract — `pp-tools discovery research-check`
 

package/pp-core/references/discovery-session-output.md

@@ -0,0 +1,70 @@
+# Discovery Session Output Gate
+
+> **Lazy-loaded.** Read from `workflows/discovery-sprint.md` Flow 2 Step 7 when a session
+> closes, from Session 8's Closing Step and from `session-13-gates.md`. Never `@`-import it.
+> Single home for what `pp_run query discovery.session-check` measures and for the one rule that
+> keeps the session files the only source of what a session produced (Discovery Sprint
+> improvement plan, Batch 5; review findings F-6 and F-7).
+
+## The contract
+
+A session's **Notes Template** in `workflows/discovery-sprint/sessions/NN-*.md` is the
+list of what the session must leave behind. Each whole-line bold title under
+`**Notes Template:**` names one section of `.planning/discovery/session-NN.md`:
+
+- the section is present **exactly once** — written as `**Title**` or as a heading
+  `## Title`, titled exactly as the template spells it; never append a second copy, edit the
+  one that is there;
+- a section that is a table in the template keeps the template's column count and holds
+  **at least one data row** — a row with two or more filled cells; a pre-filled label with
+  nothing beside it (`| PRC-01 | | |`, `| Business problem / opportunity | |`) is the
+  template, not data;
+- a section that is prose in the template holds at least one line of prose (or a table
+  with a data row); an HTML comment is not prose;
+- a section the session genuinely found nothing for says so on one line under its title:
+  `None identified in Discovery.` — the literal, so a reader and the check both know the
+  room was asked;
+- a parked topic's section carries `PARKED — needs business/senior input` (Flow 2
+  Step 5.3); the section is accounted for, the score is not.
+
+The check reads the template from the pp-core install, so the required-section list cannot
+drift from the file the facilitator reads. It checks structure, never judgement: it does not
+read what a row says.
+
+## The command
+
+```
+pp_run query discovery.session-check <N> [<N>…]   # named sessions, whatever their status
+pp_run query discovery.session-check --all        # every session-NN.md whose status is Completed
+```
+
+Exit 0 → the payload lists each session's `required`, `filled` and `empty` sections. Non-zero
+(`discovery_session_check_failed`) → one line per fault:
+
+| Fault | Meaning | Fix |
+|-------|---------|-----|
+| `missing_section (Title)` | the title is not in the session file | add the section, titled as the template spells it |
+| `duplicate_section (Title)` | the title appears twice | merge into the first copy |
+| `bad_table_shape (Title)` | the table's column count is off the template | restore the template's columns |
+| `empty_section (Title)` | no data row or prose, and no literal | fill it from what the room said, or write the literal |
+| `session_missing` | `session-NN.md` does not exist | the session has not started |
+| `template_missing` | the install has no content file for that session | reinstall pp-core |
+
+## The score
+
+`discovery-sprint.md` Step 7 computes `completeness_score` from the topics covered. A topic
+whose Notes Template section the check reports `empty_section` counts as **not covered**,
+however long it was discussed — the output is the measure, not the conversation. Run the check
+before setting the score; it exits 0 before a session may read 100.
+
+## One source of truth
+
+The session files and the registers they point at (`_requirements.md`, `_entities.md`,
+`_processes.md`, `_rules.md`, `_glossary.md`, `_screens.md`, `_roles.md`,
+`_integrations.md`, `_migration.md`, `_deviations.md`) are the only record of what a session
+produced. Nothing is summarised into a second file at session close: later sessions read the
+earlier session's Notes Template sections (the **Context-Awareness Rules** table names
+which), the Session 13 cross-reference reads the session files, and `/pp-discovery-to-build`
+reads the session files and the registers. A `.planning/discovery/_context.md` left by an
+engagement that predates this rule is neither read nor maintained; its content was always a
+copy of the session tables.