@pareto4/pp-core 1.21.1 → 1.22.0

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

@@ -0,0 +1,186 @@
+# Discovery Tests — Template & Parser Contract
+
+Single home for `_tests.md`, the register Session 9 writes: which main processes get an end-to-end
+test and why (a risk analysis per `MP-` process), which parts of the solution get extra test
+attention because they are complex, and the testability review of every user story. The build reads
+it by requirement ID; `pp_run query discovery.tests-check` is its gate. This file is Read lazily; it
+is never `@`-imported.
+
+## Why the register exists
+
+In this delivery the agents write the tests — first, from the acceptance criteria — and run the same
+checks on every change. What the agents cannot decide is *where the risk is*: which processes would
+hurt most if they broke, which components are hard enough that ordinary tests will miss their
+failures, and whether a story's acceptance criteria can be tested at all. Those are the test
+manager's calls, made in Session 9 with the product owner and the architect. The register records
+them in a form the build can act on: the planner adds the end-to-end tests and the extra test work,
+and the verifier knows which role and which data each story is accepted with.
+
+## When the file appears
+
+| Session | `_tests.md` |
+|---|---|
+| 9 | created from the template; topic 2 fills `## Acceptance`, topic 3 `## Process risk`, topic 4 `## Focus areas`; `tests-check` in the session |
+| 13 | `tests-check` in the Step 0 gates (reporting) |
+| handoff | `tests-check --require-complete` hard-blocks |
+
+Session 9's **Test Approach**, **Test Environment Plan**, **Quality Gates** and **UAT Process** stay
+in `session-09.md`: they are decisions for the whole product, not rows the build selects per phase.
+
+## Shared grammar
+
+- **Rows are keyed by the ID they assess** — an `MP-nn`, a `US-nn`, a subject ID. `_tests.md` mints
+  no IDs of its own, so it reserves no prefix.
+- **`—` is a pending cell**, allowed until the session that owns it runs.
+- **Requirements** cites `_requirements.md` IDs, comma-separated.
+- **Roles** are names from `_roles.md` § Roles, spelled the same, 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).
+
+## Risk rating
+
+`Impact` and `Likelihood` are each `high`, `medium` or `low`; `Risk` follows from them and nothing
+else:
+
+| Impact ↓ · Likelihood → | low | medium | high |
+|---|---|---|---|
+| **high** | medium | high | high |
+| **medium** | low | medium | high |
+| **low** | low | low | medium |
+
+- **Impact** — what breaks for the business when this process fails in production: money, legal or
+  regulatory exposure, customers affected, data that cannot be repaired. Session 2's `Criticality` of
+  the as-is processes a main process replaces is the first evidence; Session 6's classification of
+  the entities it touches (`Confidential`, `Restricted`) the second.
+- **Likelihood** — how likely the process is to break: new rather than replaced, many steps, several
+  interfaces (`IF-` in its step matrix), several business rules, new technology, a migration feeding
+  it, exception paths nobody has run before.
+
+A `high` risk process gets an end-to-end test. Choosing not to is allowed only as a decision: the
+`Rationale` cites the `D-09-<n>` Key Decision that records why. A process without an end-to-end test
+is still covered — step by step, by the tests the build writes from the acceptance criteria; the
+end-to-end test proves the steps work *together*, across roles, screens, rules and interfaces.
+
+## `_tests.md`
+
+Illustration only — not part of the template, names invented:
+
+| Process | Impact | Likelihood | Risk | End-to-end | Roles | Test data | Rationale |
+|---|---|---|---|---|---|---|---|
+| MP-01 | high | medium | high | yes | Requester, Approver | Three orders: under, at and over the approval limit | Invoices go to customers; replaces a critical process (PRC-02) |
+| MP-02 | low | low | low | no | — | — | Read-only report; covered by step tests |
+
+| Subject | Complexity | Extra testing | Requirements |
+|---|---|---|---|
+| BR-04 | Tariff rule with 14 branches across three customer types | One test per row of the rule's decision table; boundary values on every threshold | K-12, K-13 |
+| IF-02 | Asynchronous, at-least-once, messages may arrive out of order | Contract test against the provider's schema; duplicate and out-of-order delivery tests | K-20 |
+
+| Story | Testable | Role | Test data |
+|---|---|---|---|
+| US-01 | yes | Requester | An open order under the approval limit |
+| US-02 | amended (D-09-2) | Approver | An order exactly at the limit |
+| US-03 | open (A-09-1) | Finance | — |
+
+Bootstrap template — Session 9 copies it verbatim to `.planning/discovery/_tests.md`, replacing
+`[PROJECT_NAME]`:
+
+```markdown
+# Tests — [PROJECT_NAME]
+
+**Conventions:** pp-core reference `references/discovery-tests.md`. `## Process risk` holds one row per `MP-` main process of `_processes.md` § To-be: impact, likelihood, the risk they give, and whether the process gets an end-to-end test. `## Focus areas` holds the parts of the solution that get extra test attention because they are complex. `## Acceptance` holds the testability review of every `US-` story of `_stories.md`. A change after sign-off edits the row in place and appends `→ amended by D-<ss>-<n>`.
+
+## Process risk
+
+| Process | Impact | Likelihood | Risk | End-to-end | Roles | Test data | Rationale |
+|---------|--------|------------|------|------------|-------|-----------|-----------|
+
+## Focus areas
+
+| Subject | Complexity | Extra testing | Requirements |
+|---------|------------|---------------|--------------|
+
+## Acceptance
+
+| Story | Testable | Role | Test data |
+|-------|----------|------|-----------|
+```
+
+### Cells
+
+**Process risk**
+
+- `Process` — an `MP-nn` of `_processes.md` § To-be. Every main process has exactly one row.
+- `End-to-end` — `yes` or `no`.
+- `Roles`, `Test data` — required when `End-to-end` is `yes`: the roles the test walks the process
+  as, and the data it needs (synthetic, seeded, anonymised — never a production copy unless Session
+  6 allows it). `—` when `no`.
+- `Rationale` — why this rating; the evidence, in a line.
+
+**Focus areas** — a part of the solution whose failures ordinary step tests are likely to miss.
+Not every engagement has one; an empty table is a valid answer only when the session wrote that down
+(`None identified in Discovery.` under the session's **Focus Areas** heading).
+
+- `Subject` — one of: a component `C-nn` of Session 5's **Component Inventory**, an interface
+  `IF-nn` of `_integrations.md`, a business rule `BR-nn` of `_rules.md`, a migration row `MG-nn` of
+  `_migration.md`, or an entity of `_entities.md` (PascalCase, spelled the same). One row per
+  subject.
+- `Complexity` — what makes it hard: branches, state, concurrency, timing, money, volume, an
+  external party, data that cannot be repaired.
+- `Extra testing` — what the build does beyond the step tests, concretely enough to plan: a test per
+  row of a decision table, boundary values, property-based tests, contract tests, duplicate and
+  out-of-order delivery, reconciliation counts on a migration rehearsal, a load test with a number,
+  a security test against a named threat.
+- `Requirements` — the requirements the subject realises; `—` until known, required at the handoff.
+
+**Acceptance** — the testability review: can the build's verifier, reading a story's acceptance
+criteria verbatim, tell pass from fail?
+
+- `Story` — a `US-nn` of `_stories.md`. Every story has exactly one row.
+- `Testable` — `yes` (the criteria name an observable outcome); `amended (D-09-<n>)` (the room
+  rewrote the criteria in `_stories.md`, with `→ amended by D-09-<n>` in the cell); or
+  `open (A-09-<n>)` (an action owns the rewrite — the handoff refuses it).
+- `Role` — the role the story is accepted as.
+- `Test data` — the data the story is accepted with; `—` only for a story that needs none.
+
+### Parser contract — `pp_run query discovery.tests-check [--require-complete]`
+
+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 `_tests.md` → exit 0, `present: false`.
+
+| Cell / field | Grammar | Fault when violated |
+|---|---|---|
+| `## Process risk`, `## Focus areas`, `## Acceptance` | each once as a `##` heading holding one table with the template's columns | `missing_section`, `bad_table_shape` naming the section |
+| Process risk `Process` | `MP-\d{2}`, once per process, present in `_processes.md` § To-be when it is on file | `bad_process`, `duplicate_process`, `unknown_process` |
+| every To-be main process | has a Process risk row | `process_not_assessed` naming the MP |
+| `Impact`, `Likelihood`, `Risk` | `high` \| `medium` \| `low` | `bad_rating` naming the column |
+| `Risk` | the rating the matrix gives for `Impact` and `Likelihood` | `risk_mismatch` naming the MP |
+| `End-to-end` | `yes` \| `no` | `bad_end_to_end` |
+| a `high` risk row with `End-to-end` `no` | `Rationale` cites a `D-09-<n>` | `high_risk_not_end_to_end` |
+| `Roles` | when `End-to-end` is `yes`: a comma list of roles present in `_roles.md` § Roles when it is on file | `empty_cell (Roles)`, `unknown_role` |
+| `Test data` (Process risk) | non-empty when `End-to-end` is `yes` | `empty_cell (Test data)` |
+| `Rationale` | non-empty | `empty_cell (Rationale)` |
+| Focus areas `Subject` | `C-\d{2}`, `IF-\d{2}`, `BR-\d{2}`, `MG-\d{2}` or a PascalCase entity, once each; resolved against its source when that source is on file | `bad_subject`, `duplicate_subject`, `unknown_subject` |
+| `Complexity`, `Extra testing` | non-empty | `empty_cell` naming the column |
+| Focus areas `Requirements` | `—` (uncited), or a comma list of requirement IDs each present in `_requirements.md` when on file and parseable | `unknown_requirement_id`; `uncited_focus` under `--require-complete` only |
+| Acceptance `Story` | `US-\d{2}`, once per story, present in `_stories.md` when it is on file | `bad_story`, `duplicate_story`, `unknown_story` |
+| every story of `_stories.md` | has an Acceptance row | `story_not_reviewed` naming the US |
+| `Testable` | `yes` \| `amended (D-09-<n>)` \| `open (A-09-<n>)` | `bad_testable`; `story_not_testable` for `open` under `--require-complete` only |
+| Acceptance `Role` | one role present in `_roles.md` § Roles when it is on file | `empty_cell (Role)`, `unknown_role` |
+| Acceptance `Test data` | non-empty (`—` allowed) | `empty_cell (Test data)` |
+| `_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_tests_check_failed` for structural faults; `discovery_tests_incomplete`
+when every fault was raised by `--require-complete`. Payload: `ok`, `present`, `file`, `processes`,
+`end_to_end`, `focus_areas`, `stories`, `open_stories`, `uncited`.
+
+## How the build reads it
+
+`discovery for-phase <N>` extracts, for the phase's requirements:
+
+- the **Process risk** rows of the main processes whose steps cite one of them — the planner adds an
+  end-to-end test task for each `yes` row, walking the roles with the test data named;
+- the **Focus areas** rows citing one of them — the planner turns `Extra testing` into tasks, the
+  verifier checks they ran;
+- the **Acceptance** rows of the stories citing one of them — the verifier accepts each story as the
+  role, with the data, the row names.

package/pp-core/workflows/discovery-sprint/session-13-gates.md

@@ -25,6 +25,8 @@ documented absent-artifact arm — before the cross-reference analysis begins.
 
 **Standards-first gates (roles, integrations, migration, deviations):** run `pp_run query discovery.roles-check`, `pp_run query discovery.integrations-check`, `pp_run query discovery.migration-check` and `pp_run query discovery.deviations-check`. Each exits 0 → proceed. Non-zero → a section or table header is off the template, a role is listed twice or is neither a Session 2 persona, a step-matrix actor nor `System`, a permission or screen row names an unknown role, entity, screen or requirement, an operation is not a lowercase verb, an `IF-`/`MG-`/`DEV-` ID is malformed, repeated or leaves a hole, a direction, required flag, reversibility or status is outside its vocabulary, a contract or error row names an interface that does not exist, a step matrix cites an `IF-` the register lacks, a migration source is not in the Systems Landscape, a deviation cites no `[vault: <path>]` or one the cache does not hold, names an approver the Session 1 Approval Matrix lacks, or is approved or rejected without a decision — fix the named rows in the artifact and re-run. These gates report: an uncited interface or migration row and a hard deviation still `Proposed` are not faults here; the handoff adds `--require-cited` and `--require-approved` and hard-blocks on them. An artifact that does not exist exits 0 by itself. Fault vocabularies: `references/discovery-access.md`, `references/discovery-integrations.md`, `references/discovery-standards.md`.
 
+**Test-register gate (Session 9):** run `pp_run query discovery.tests-check`. Exit 0 → proceed. Non-zero → a section or table header of `_tests.md` is off the template, a main process of `_processes.md` § To-be has no risk row or two, a rating is outside `high`/`medium`/`low`, a risk does not follow from its impact and likelihood by the matrix, a high-risk process has no end-to-end test and no `D-09-<n>` saying why, an end-to-end row names no role, an unknown role or no test data, a focus-area subject is malformed, repeated or unknown to its source, a story of `_stories.md` has no acceptance row or two, a `Testable` cell is outside `yes`/`amended (D-09-<n>)`/`open (A-09-<n>)`, or a cited requirement does not exist — fix the named rows and re-run. The gate reports: an `open` story and a focus area without requirements are not faults here; the handoff adds `--require-complete` and hard-blocks on them, so close their actions before the charter is signed. An artifact that does not exist exits 0 by itself. Fault vocabulary: `references/discovery-tests.md`.
+
 **Session-output gate (review F-6):** run `pp_run query discovery.session-check --all`. Exit 0 → proceed. Non-zero → a Notes Template section of a completed session is missing, repeated, off its template columns or empty: fill it in that session file from the session's notes, or write `None identified in Discovery.` under its title, then re-run (`references/discovery-session-output.md`). A session whose `completeness_score` reads 100 while this gate names it empty was scored on the conversation, not the output — correct the score.
 
 **Build-consumption gates (stories, phase plan, extract):** run `pp_run query discovery.stories-check`, `pp_run query discovery.phases-check` and `pp_run query discovery.for-phase 1 --markdown >/dev/null`. Each exits 0 → proceed. Non-zero → a `US-` or phase number is malformed, repeated or leaves a hole, a story names no `E-nn` EPIC, cites no requirement or one that does not exist, has an empty story or acceptance-criteria cell or a source step that is neither `—` nor an existing `MP-nn #k`, an MVP domain requirement has no story, a phase has no goal, no success criteria or no requirement, plans a dropped requirement or one another phase also plans, depends on a later or missing phase, an MVP requirement belongs to no phase, or an artifact the extract reads has a section or header off its template — fix the named rows and re-run. These gates report; the handoff hard-blocks on `stories-check` and `phases-check`. An artifact that does not exist exits 0 by itself; the extract smoke renders empty, exit 0, when no phase plan or roadmap names Phase 1. Fault vocabulary: `references/discovery-build-consumption.md`.

package/pp-core/workflows/discovery-sprint/sessions/03-to-be.md

@@ -5,47 +5,49 @@
 
 ### Session 3: Business Requirements & Future State (To-Be)
 
-**Goal:** Define target-state business objectives, establish MVP scope, identify EPICs and user stories, and capture functional and non-functional requirements using a process-first decomposition approach.
+**Goal:** Agree what the application is for, identify every process it supports, refine each process step by step — sub-processes, a swimlane diagram iterated with the room, a step matrix — until the processes cover the whole application, then derive the requirements, business rules and user stories from those steps.
 
 **Special Protocol — Process-First (required for Session 3):**
-This session uses the **Session 3: Process-First Protocol** (Steps 5A–5G, at the end of this file). The agent proposes the main-process landscape derived from Session 2 outputs; the user validates; then sub-processes are decomposed with step matrices; requirements are derived from validated steps (not collected from a blank template).
+This session uses the **Session 3: Process-First Protocol** (Steps 5A–5G, at the end of this file). It starts from the application's goal, inventories every process the application supports, and refines one process at a time; requirements and stories are derived from validated steps (not collected from a blank template).
 
 **What We Cover:**
 
-1. **Business objectives and success metrics**
-   *Why it matters: gives the roadmap (Session 11) and go/no-go (Session 13) an objective yardstick. Skip when: objectives were already locked in Session 1's business vision.*
-   - What are the measurable business outcomes this initiative must achieve?
-   - How will we measure success? What KPIs will be tracked?
-   - What is the expected ROI or business case?
-   - Are there specific targets (e.g., reduce processing time by 50%)?
+1. **Application goal and business objectives**
+   *Why it matters: the goal is the yardstick for the process inventory — a process that serves no part of it is out of scope, a part of it no process serves is a gap. Skip when: never; with Session 1's vision on file this is a confirmation.*
+   - In one or two sentences: what is this application for, and for whom?
+   - What are the measurable business outcomes it must achieve, and how will we measure them (KPIs, targets)?
    - **Glossary sweep:** for every concept named so far — entities, roles, statuses, documents — confirm the one term the requirements will use and add or complete its `.planning/discovery/_glossary.md` row (definition, synonyms under `Do not use`, source). A term with two spellings is a Session 13 cross-reference finding
 
-2. **MVP scope definition**
-   *Why it matters: the MVP boundary drives Session 11's build order and the go-live target date. Skip when: scope is fixed by contract and non-negotiable.*
-   - What is the minimum set of capabilities needed to deliver value?
-   - What can be deferred to a later release without jeopardizing the business case?
-   - How do we differentiate "must-have" from "nice-to-have"?
-   - What is the target go-live date for MVP? [needs-business-input]
+2. **Process inventory — every process the application supports**
+   *Why it matters: what is not in a process is not in the stories, the requirements, the tests or the build. The inventory is complete when every user, every piece of data and every connection has a process that handles it. Skip when: never.*
+   - Starting from the goal and Session 2's as-is processes: which business processes does the application run?
+   - Then sweep for the processes a business view forgets: user and role management, onboarding and set-up, configuration and reference data, notifications, scheduled and batch jobs, reporting and exports, archiving and deletion, incoming and outgoing integrations.
+   - Check coverage: does every persona have a process, does every entity have a process that creates it and one that ends its life, does every external system have a process that uses it?
 
-3. **EPICs and high-level features** (derived from process decomposition)
-   *Why it matters: EPICs are the units Session 11 sequences into sprints. Skip when: derived directly from Session 2 pain points with no new discussion needed.*
-   - What are the major feature areas (EPICs) that compose the solution?
-   - How do EPICs relate to the pain points identified in Session 2?
-   - What is the relative priority of each EPIC?
+3. **Process refinement — one process at a time**
+   *Why it matters: a process the room has walked step by step, on a diagram, is a process the build can implement and the testers can test end to end. Skip when: never — every main process is refined.*
+   - Which sub-processes does it consist of, and which steps make up each one?
+   - Who does each step — which persona, or the system? What happens when a step cannot complete?
+   - Walk the swimlane diagram with the room and change it until they recognise their work in it.
 
-4. **User stories and acceptance criteria** (derived from step matrices)
-   *Why it matters: acceptance criteria are what QA (Session 9) and UAT (Session 13) will test against. Skip when: only doing high-level EPIC planning this round, not story-level detail.*
-   - For highest-priority EPICs, what are the key user stories?
-   - What does "done" look like for each story (acceptance criteria)?
-   - Are there edge cases or exception flows to account for?
-
-5. **Functional requirements** (derived from step matrices)
+4. **Functional requirements and business rules** (derived from the step matrices)
    *Why it matters: functional requirements are the direct input to architecture (Session 5) and QA planning (Session 9). Skip when: requirements are already captured in a separate BRD to reference.*
-   - What specific functions must the system perform?
+   - What specific functions must the system perform at each step?
    - What calculations, transformations, or business logic are required? Every validation, calculation or invariant becomes a `BR-` row of `.planning/discovery/_rules.md` (Step 5D′), applied to an entity or a process, checked in a named layer, citing the requirements it realises
    - What reporting or analytics capabilities are needed?
 
-6. **Non-functional requirements**
+5. **EPICs, user stories and acceptance criteria** (derived from the steps)
+   *Why it matters: every story is tied to the step it came from and every step a person performs has a story, so the stories cover the processes; acceptance criteria are what QA (Session 9) and UAT (Session 13) test against. Skip when: only doing high-level EPIC planning this round, not story-level detail.*
+   - For each step a persona performs: what does that person want, and what do they observe when it is done?
+   - Are there edge cases or exception flows (the matrix's `Exception` column) that need their own criteria?
+
+6. **MVP scope definition**
+   *Why it matters: the MVP boundary drives Session 11's build order and the go-live target date. Skip when: scope is fixed by contract and non-negotiable.*
+   - Which processes, sub-processes and steps are needed to deliver value first?
+   - What can be deferred to a later release without jeopardizing the business case?
+   - What is the target go-live date for MVP? [needs-business-input]
+
+7. **Non-functional requirements**
    *Why it matters: NFRs drive infrastructure sizing (Session 10) and architecture tradeoffs (Session 5). Skip when: standard defaults apply and the client has no unusual NFR targets.*
    - What are the performance expectations (response time, throughput)?
    - What availability and uptime targets apply (e.g., 99.9%)?
@@ -54,17 +56,29 @@ This session uses the **Session 3: Process-First Protocol** (Steps 5A–5G, at t
 
 **Notes Template:**
 
-**Main Process Register** (populated via process-first decomposition Step 5A)
+**Application Goal**
+
+The goal statement as the room agreed it, in one or two sentences, and where it differs from Session 1's business vision.
+
+**Main Process Register** (populated via the process inventory, Step 5B)
 
 The canonical rows live in `.planning/discovery/_processes.md` § To-be: `| ID | Main process | Replaces | Trigger | End state | Primary actor | EPICs |`, one `MP-<nn>` row per main process, **Replaces** naming the `PRC-` rows it transforms or `new`. Record here only the summary line `N main processes (MP-01 … MP-NN)` and the orphan as-is processes no main process replaces.
 
-**Sub-Process Flows** (populated via Step 5B)
+**Process Coverage** (populated via Step 5B, re-checked at Step 5F)
+
+| Dimension | Item | Covered by | Notes |
+|-----------|------|------------|-------|
+| | | | |
 
-One swimlane per main process in `.planning/discovery/_processes.md` § Flows — a Mermaid `flowchart` with one `subgraph` per actor. Record here only which flows the user changed and why.
+One row per persona, entity, external system and scheduled job the sweep looked at: **Dimension** is `Persona`, `Entity`, `Integration` or `Scheduled job`; **Covered by** is the `MP-nn` (or `MP-nn.k`) that handles it, or `gap — D-03-<n>` when the room decided it is out of scope.
+
+**Sub-Process Flows** (populated via Step 5C)
+
+One swimlane per main process in `.planning/discovery/_processes.md` § Flows — a Mermaid `flowchart` with one `subgraph` per actor and every step node labelled with its `#`; its sub-processes in § Sub-processes. Record here only which flows the room changed during the iterations, and why.
 
 **Step Matrices** (populated via Step 5C)
 
-One step matrix per main process in `.planning/discovery/_processes.md` § Steps, with the **Exception** column; sub-process boundaries are rows, or one combined matrix per main process when its sub-processes are step-sized (Step 5C); Requirements column back-filled at Step 5D. Record here only what the matrices cannot hold.
+One combined matrix per main process in `.planning/discovery/_processes.md` § Steps, with the **Exception** column; the § Sub-processes table groups its rows, every row in exactly one sub-process (Step 5C); Requirements column back-filled at Step 5D. Record here only what the matrices cannot hold.
 
 **Business Objectives**
 
@@ -90,7 +104,7 @@ Orphan-requirement and uncovered-step flags only — the canonical requirements
 
 **User Stories** (populated via Step 5E)
 
-One row per story in `.planning/discovery/_stories.md` § Stories — `ID | EPIC | Requirements | Story | Acceptance criteria | Source step` (`references/discovery-build-consumption.md`); the build's verifier reads the acceptance criteria from there. Record here only what the register cannot hold.
+One row per story in `.planning/discovery/_stories.md` § Stories — `ID | EPIC | Requirements | Story | Acceptance criteria | Source step` (`references/discovery-build-consumption.md`), every story tied to its source step and every persona step covered by a story; the build's verifier reads the acceptance criteria from there. Record here only what the register cannot hold.
 
 **Non-Functional Requirements**
 
@@ -124,61 +138,101 @@ Flows to be clickable, personas covered, and per-flow definition of "validated".
 ## Session 3: Process-First Protocol
 
 **This protocol replaces the generic Step 5 topic loop for Session 3 only.**
-The agent proposes the process landscape from Session 2 outputs; the user validates; requirements are derived from validated process steps (not collected separately).
+Goal first, then the full process inventory, then one process at a time — sub-processes, swimlane, step matrix — until the processes cover the application; requirements, rules and stories are derived from the validated steps (not collected separately). `_processes.md` was created by Session 2; if it does not exist, create it from the template in `${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-processes.md` first. If it has no `## Sub-processes` section (an engagement that predates it), add the section with its table header between `## To-be` and `## Flows` now.
 
-### Step 5A: Propose Main Processes
+### Step 5A: Application Goal and Objectives
 
-Read `.planning/discovery/session-02.md` (its Notes Template sections) and `.planning/discovery/_processes.md`. Propose the main business processes for the to-be state:
+Read Session 1's business vision and Session 2's pain points. Propose the application goal in one or two sentences — what the application is for and for whom — and the business objectives with a measurable KPI each:
 
 ```
-Based on Session 2, I'm proposing these main processes for the to-be state:
+Based on Sessions 1 and 2, I propose this goal for the application:
+
+  <goal statement>
 
-| MP ID | Main Process | Replaces (PRC-nn or new) | Trigger | End State | Primary Actor | Rationale (from S2) |
-|-------|--------------|--------------------------|---------|-----------|---------------|---------------------|
-| MP-01 | ...          | ...                      | ...     | ...       | ...           | ...                 |
+| ID | Objective | Success Metric / KPI | Target Value | Priority |
+|----|-----------|---------------------|--------------|----------|
+| BO-01 | ...   | ...                 | ...          | ...      |
 
-Validate: accept / edit / add / drop. Then we'll decompose each into sub-processes.
+Validate: accept / edit. The process inventory is measured against this goal.
 ```
 
-Iterate until the user accepts the main-process list, then write one `MP-<nn>` row per main process to `.planning/discovery/_processes.md` § To-be — **Replaces** is the comma list of `PRC-` rows from § As-is this main process transforms, or `new` — and fill the section titled exactly **Main Process Register** in `.planning/discovery/session-03.md` with the summary line — edit in place; never append a new heading. `_processes.md` was created by Session 2; if it does not exist, create it from the template in `${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-processes.md` first.
+Iterate until the room accepts both, then fill the section titled exactly **Application Goal** and the section titled exactly **Business Objectives** in `.planning/discovery/session-03.md` — edit in place; never append a new heading. Run the glossary sweep (topic 1) before moving on.
 
-**Text mode fallback:** present numbered options: 1) Accept all / 2) Edit specific process / 3) Add process / 4) Drop process.
+### Step 5B: Process Inventory
+
+Read `.planning/discovery/session-02.md` (its Notes Template sections), `.planning/discovery/_processes.md` § As-is and `.planning/discovery/_entities.md`. Propose **every** main process the application supports — the business processes that replace Session 2's as-is processes, and the supporting processes a business view forgets:
+
+- user and role management, onboarding and set-up;
+- configuration and reference data;
+- notifications and reminders;
+- scheduled and batch jobs (`System` as primary actor);
+- reporting, exports and audits;
+- archiving, retention and deletion;
+- every incoming and outgoing exchange with another system.
 
-### Step 5B: Decompose into Sub-Processes (per main process)
-
-For each accepted main process, propose 3–8 sub-processes and emit a **swimlane**: a Mermaid `flowchart` with one `subgraph` per actor (a Session 2 persona or `System`), so the lane says who does each step:
-
-```mermaid
-flowchart LR
-  subgraph Team member
-    SP1[Sub-process 1] --> D1{Decision}
-    D1 -->|No| SP1_alt[Alternative path]
-  end
-  subgraph System
-    SP2[Sub-process 2]
-  end
-  D1 -->|Yes| SP2
-  SP2 --> End([End state])
 ```
+For the goal "<goal>", I'm proposing these main processes:
+
+| MP ID | Main Process | Replaces (PRC-nn or new) | Trigger | End State | Primary Actor | Serves (goal / BO-nn) |
+|-------|--------------|--------------------------|---------|-----------|---------------|-----------------------|
+| MP-01 | ...          | ...                      | ...     | ...       | ...           | ...                   |
 
-Present to the user and iterate until accepted, then write it under `### MP-<nn> — <name>` in `.planning/discovery/_processes.md` § Flows, and fill the section titled exactly **Sub-Process Flows** in `.planning/discovery/session-03.md` with what changed — edit in place; never append a new heading. A flowchart without a `subgraph` is refused by `process-check`.
+Validate: accept / edit / add / drop.
+```
 
-### Step 5C: Step Matrix (per sub-process)
+Then run the **coverage sweep** with the room and fill the section titled exactly **Process Coverage** in `.planning/discovery/session-03.md` — one row per item, edit in place; never append a new heading:
 
-For each accepted sub-process, propose a step-level matrix in the columns `_processes.md` § Steps fixes:
+- every persona of Session 2's User Personas table has at least one process;
+- every entity of `_entities.md` has a process that creates it and one that ends its life (closes, archives or deletes it);
+- every external system of Session 2's Systems Landscape that stays has a process that uses it;
+- every recurring job the business mentioned has a process.
 
-| # | Step | Actor | UI | Data objects | Integration | Exception | Requirements |
+An item no process covers is either a new main process or a decision `D-03-<n>` that it is out of scope. Iterate until the room accepts the list, then write one `MP-<nn>` row per main process to `.planning/discovery/_processes.md` § To-be — **Replaces** is the comma list of `PRC-` rows from § As-is this main process transforms, or `new` — and fill the section titled exactly **Main Process Register** in `.planning/discovery/session-03.md` with the summary line — edit in place; never append a new heading. A process found later in the session is added the same way; nothing is renumbered.
 
-- **#:** `<mp>.<n>` — `01.3` is the third step of MP-01
-- **Step:** one imperative verb phrase
-- **Actor:** a persona from Session 2's User Personas table, spelled the same, or `System`; two actors are comma-separated — never a slash-joined pair or a parenthetical qualifier
-- **UI:** screen/component, or `—` if backend-only
-- **Data objects:** entities of the product with CRUD flags, `Task [C], Membership [C/R]`, or `—`. Every name is a row of `.planning/discovery/_entities.md` § Entities; add a missing entity there now (Source `S3`, pending cells `—`) — `entity-check` refuses a data object that is not an entity. A file, a pull request or another system's document is not a data object: it goes in **Integration** or the step text
-- **Integration:** external systems with direction, or `—`
-- **Exception:** what happens when the step cannot complete — the error path the build must handle — or `—` when the step cannot fail
-- **Requirements:** `—` during 5C — back-filled with minted `_requirements.md` IDs during Step 5D consolidation
+**Text mode fallback:** present numbered options: 1) Accept all / 2) Edit specific process / 3) Add process / 4) Drop process.
 
-Present one sub-process matrix at a time. When a main process's sub-processes are step-sized — each one or two steps — propose one combined matrix for the main process instead, with a **Sub-process** column after `#` only when the user wants the boundary visible; the user may still ask for one matrix per sub-process. Either way the rows are written under `### MP-<nn> — <name>` in `.planning/discovery/_processes.md` § Steps — one matrix per main process, sub-process boundaries as rows. After validation, fill the section titled exactly **Step Matrices** in `.planning/discovery/session-03.md` with what the matrices cannot hold — edit in place; never append a new heading.
+### Step 5C: Refine Each Process — Sub-processes, Swimlane, Steps
+
+Take the main processes one at a time, in the order the room prefers (usually the core business process first). For each:
+
+1. **Sub-processes.** Propose the 2–8 sub-processes it consists of, each a named stretch of work with its own outcome (`MP-01.1 Register the request`, `MP-01.2 Approve`). Even a short process has one.
+2. **Swimlane.** Emit a Mermaid `flowchart` with one `subgraph` per actor (a Session 2 persona or `System`), so the lane says who does each step. Every step is a node whose label starts with its `#` (`01.3`); decisions and end states need none:
+
+   ```mermaid
+   flowchart LR
+     subgraph Team member
+       S1["01.1 Create task"] --> D1{Complete?}
+       D1 -->|No| S2["01.2 Add missing details"]
+       S2 --> D1
+     end
+     subgraph System
+       S3["01.3 Notify assignee"]
+     end
+     D1 -->|Yes| S3
+     S3 --> End([Task assigned])
+   ```
+
+3. **Show it and iterate.** Write the draft under `### MP-<nn> — <name>` in `.planning/discovery/_processes.md` § Flows at once — the register holds every round, nothing is kept in the conversation only — and let the room see it drawn:
+   - **Viewing.** A terminal does not draw Mermaid. Render the process with `pp_run query discovery.flow-page MP-<nn>` — it writes `.planning/discovery/_flows/MP-<nn>.html` from the register (swimlane, sub-processes, steps). When your runtime can publish an artifact (Claude Code's Artifact tool), publish that file as a private artifact and give the room the link; after every round re-run the command and publish **the same file path** again, so the link stays the same and a refresh shows the new version. The page is generated — publish it as written, never edit it. `flow-page` renders and checks nothing, so it has no Session 13 gate; `process-check` is the check. Without an artifact tool, open `_processes.md` in a Mermaid-capable viewer (VS Code with a Mermaid preview, or GitHub).
+   - **Consent, once per engagement.** Publishing puts the client's process on claude.ai (private to the publisher until shared). Before the first publish, ask whether that is acceptable and record the answer as a Key Decision `D-03-<n>`; if not, use the local viewer. Add `.planning/discovery/_flows/` to the project's `.gitignore` — the pages are derived.
+   - **Stop for review — every round.** After publishing (or, without an artifact tool, after writing the draft), **stop and end your turn**: give the link, list the sub-processes and the open questions you have about the diagram (a missing step, a lane you were unsure of, a `No` branch with no path, a step that cannot fail), and ask the room to review it. Do not write the step matrix, do not start the next process and do not propose the next round until the user answers. Their answer is the review: free text, no menu.
+   - **Each round.** Apply exactly what the room said — a step missing, in the wrong lane, in the wrong order, a `No` branch or a failure path — by editing the draft in place; re-render, republish to the same file path, and stop again with the same review request. Expect two or three rounds for a core process. Only an explicit acceptance ("accepted", "looks right", "next") ends the loop; then continue with the step matrix below. A flowchart without a `subgraph` is refused by `process-check`.
+4. **Step matrix.** Turn the accepted diagram into the matrix in the columns `_processes.md` § Steps fixes — one row per numbered node, written under `### MP-<nn> — <name>` in § Steps, one combined matrix per main process:
+
+   | # | Step | Actor | UI | Data objects | Integration | Exception | Requirements |
+
+   - **#:** `<mp>.<n>` — `01.3` is the third step of MP-01, the same number the diagram shows
+   - **Step:** one imperative verb phrase
+   - **Actor:** a persona from Session 2's User Personas table, spelled the same, or `System`; two actors are comma-separated — never a slash-joined pair or a parenthetical qualifier
+   - **UI:** screen/component, or `—` if backend-only
+   - **Data objects:** entities of the product with CRUD flags, `Task [C], Membership [C/R]`, or `—`. Every name is a row of `.planning/discovery/_entities.md` § Entities; add a missing entity there now (Source `S3`, pending cells `—`) — `entity-check` refuses a data object that is not an entity. A file, a pull request or another system's document is not a data object: it goes in **Integration** or the step text
+   - **Integration:** external systems with direction, or `—`
+   - **Exception:** what happens when the step cannot complete — the error path the build must handle — or `—` when the step cannot fail
+   - **Requirements:** `—` during 5C — back-filled with minted `_requirements.md` IDs during Step 5D consolidation
+5. **Sub-process rows.** Write one row per sub-process to `.planning/discovery/_processes.md` § Sub-processes — `| MP-01.2 | Approve | 01.4, 01.5, 01.6 |` — listing its steps by `#`. Every step belongs to exactly one sub-process.
+6. **Check the process.** Run `pp_run query discovery.process-check` — exit 0, or fix what it names before the next process: `step_not_in_flow` (a matrix row the diagram does not show — add the node or drop the row), `step_without_subprocess`, `step_in_two_subprocesses`, `subprocess_without_steps`. A data object it accepts may still be refused by `entity-check`.
+
+After the last process, fill the section titled exactly **Sub-Process Flows** and the section titled exactly **Step Matrices** in `.planning/discovery/session-03.md` with what changed during the iterations and what the matrices cannot hold — edit in place; never append a new heading.
 
 ### Step 5D: Consolidate Requirements
 
@@ -221,19 +275,24 @@ Full grammar reference: pp-core `references/discovery-id-conventions.md` (Read l
 
 Group sub-processes into EPICs (one EPIC = one main process). Fill the section titled exactly **EPIC Register** in `.planning/discovery/session-03.md` — edit in place; never append a new heading.
 
-Derive user stories from step-matrix rows where the actor is a persona and mint one `US-<nn>` row per story in `.planning/discovery/_stories.md` § Stories (template and grammar: `${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-build-consumption.md` § `_stories.md`; create the file from the template when it does not exist):
+Walk the step matrices process by process and derive the user stories from the rows where the actor is a persona — every such row that realises an MVP requirement gets at least one story, and every story names the steps it came from. Mint one `US-<nn>` row per story in `.planning/discovery/_stories.md` § Stories (template and grammar: `${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-build-consumption.md` § `_stories.md`; create the file from the template when it does not exist):
 
 | ID | EPIC | Requirements | Story | Acceptance criteria | Source step |
 
 - **Requirements:** the `_requirements.md` IDs the story realises — every `MVP` requirement that a persona-actor step cites needs at least one story (`System`-only and `N-`/`T-` rows do not)
 - **Acceptance criteria:** what the user observes when the story is done, written out — never a pointer such as `As in F-01`; the build's verifier reads this cell verbatim as the UAT
-- **Source step:** the matrix rows the story came from, as `MP-nn #<cell>` with the `#` cell copied verbatim (`MP-05 #05.1`), comma-separated when a story spans two steps, or `—`
+- **Source step:** the matrix rows the story came from, as `MP-nn #<cell>` with the `#` cell copied verbatim (`MP-05 #05.1`), comma-separated when a story spans two steps — never `—`: a story no step needs points at a step the inventory missed
+
+Then run `pp_run query discovery.stories-check` — exit 0, or fix the rows it names: `step_without_story` names a persona step no story covers, `no_source_step` a story tied to no step, `mvp_requirement_without_story` a requirement no story covers. Then fill the section titled exactly **User Stories** in `.planning/discovery/session-03.md` with only what the register cannot hold — edit in place; never append a new heading.
 
-Then run `pp_run query discovery.stories-check` — exit 0, or fix the rows it names (`mvp_requirement_without_story` names a requirement no story covers). Then fill the section titled exactly **User Stories** in `.planning/discovery/session-03.md` with only what the register cannot hold — edit in place; never append a new heading.
+### Step 5F: Coverage Review
 
-### Step 5F: Business Objectives and KPIs
+Before closing, check that the processes cover the application and the stories cover the processes:
 
-Cover measurable outcomes and KPIs per main process. Link each KPI to `MP-XX` IDs. Then fill the section titled exactly **Business Objectives** in `.planning/discovery/session-03.md` — edit in place; never append a new heading.
+1. Re-read the **Process Coverage** table against the final process list: every row names a process that exists (`MP-nn` or `MP-nn.k`) or a decision. Add a row for any persona, entity or system the session introduced after Step 5B.
+2. Run `pp_run query discovery.process-check --require-cited`, `pp_run query discovery.stories-check` and `pp_run query discovery.rules-check` — each exits 0, or fix the rows they name.
+3. Read the application goal once more: is there a part of it no process serves? That is a missing process (back to Step 5B) or a decision to narrow the goal.
+4. Settle the MVP boundary (topic 6) per process and sub-process, then fill the section titled exactly **MVP Scope Boundary** in `.planning/discovery/session-03.md` — edit in place; never append a new heading.
 
 ### Step 5G: Prototype Validation Plan