@pareto4/pp-core 1.21.1 → 1.23.1

package/pp-core/references/audience-moments.md

@@ -0,0 +1,119 @@
+# Audience moments
+
+The business and engineer forms for five moments (Next Up, a stopped check, a verification result, the fallback-standards question and a confirmation before an irreversible action) plus the discovery narration rule. Read from `audience.md`'s pointer line, never `@`-included.
+
+## When to use this
+
+Use a form below only when the payload (or `pp_run query audience fields`) carries `audience`; pick the section for that audience. A developer never reads this file, and a developer's text stays as it is.
+
+Fill every `{…}` from facts you hold (the `ROADMAP.md` goal, the plan's objective, `VERIFICATION.md`, the check's own output) and never invent one. Keep commands, file names, IDs and paths in backticks, unchanged (`audience.md`, Never reword). When the CLI already printed a card (a `GATE_CARDS=` line, or the lines `vault admission --explain` printed), relay that card word for word and never compose a second one.
+
+## Business user forms
+
+### Next Up
+
+```
+Next: {plain action}, because {reason}. Start a fresh conversation first (`/clear`) so the assistant has its full working memory, then type `{command}`.
+```
+
+- {plain action} names the step and the plan by its name, taken from the plan's objective. Never show a plan ID.
+- {reason} is one clause from that stage's `ROADMAP.md` goal or from the result just shown.
+- Say "stage N of the work", never the internal word for it.
+- A line that would show a command to print a report file becomes "Ask me to show the full report."
+- Several options become one Next line plus "Also possible:" lines in the same shape.
+
+### Stopped check
+
+`The {name} check stopped this step: {why}. What to do: {action}.`
+
+Then `Ref: {code}`, then `Details:` followed by the check's own message exactly as printed. An advisory says the step carries on. Use the card the CLI printed; compose this shape only when none was printed (an older engine).
+
+### Verification result
+
+Status line: `Done` when the report status is `passed`, `Not finished yet` for `gaps_found`, `Needs your check` for `human_needed`. Show the internal names only inside backticks.
+
+Then three headed lists, each item one plain sentence:
+
+- What works ({N} of {M})
+- What is missing
+- What needs your own test
+
+End with the Next Up line.
+
+### Vault fallback question
+
+Your organisation's own standards could not be loaded ({reason}). May the build follow the general Pareto standards instead?
+
+Then: Type `confirmed` to go ahead. This answer is never given for the person and never assumed in an unattended run. {reason} is the plain reason, for example "the connection to your organisation's standards did not answer".
+
+### Irreversible action
+
+Say the action and its target before the person answers, and keep the workflow's own way of answering: its options, or the typed name for `remove-workspace`. One row per action:
+
+- `undo`: This will undo `{commits}`, the saved changes of `{plan name}`; they stay in the history. Then ask exactly as the workflow does, with the same options.
+- `remove-workspace`: This will delete the folder `{workspace path}` and every file in it; it cannot be undone. Type `{workspace name}` to go ahead.
+- `complete-milestone`: In the workflow's question, describe its "Delete without merging" option as: This will delete `{branch}`, the separate line of work for this release; use it when that work is already on the main line or not needed. Keep all of the workflow's options.
+- `transition`: This will skip `{plan names}`, which are then not built in this stage of the work. Then ask exactly as the workflow does, with the same options.
+- `vault-write-back`: This will write `{file}` into your organisation's standards at `{target}`, where others will see it. Then ask exactly as the workflow does, with the same options.
+- `discovery-redo`: This will replace the notes of session {n} in `session-{nn}.md` and hold the session again. Then ask exactly as the workflow does, with the same options.
+- `charter-redraft`: This will reopen `PROJECT-CHARTER.md` as version `{version}`; it must be signed again. Then ask exactly as the workflow does, with the same options.
+- `init-compose`: This will write `.platform-bindings.json` with the answers you gave. Then ask exactly as the workflow does, with the same options.
+
+### Discovery narration
+
+In a discovery session with a business user, never show file paths, internal ID counts (a tally per prefix), check codes or the `vault:` lines. Never ask them to design ID prefixes: choose the prefixes yourself from the people and areas they named and say the split in one plain sentence. Refer to a recorded item as "decision 3" or "open item 2". Keep `/pp-discovery N` commands in backticks.
+
+## Business engineer forms
+
+### Next Up
+
+```
+Next: {plain action} (phase {N}), because {reason}. Run `/clear` first so the assistant starts with a fresh context window, then run `{command}`.
+```
+
+- {plain action} names the step and the plan by its name from the plan's objective; never a plan ID.
+- {reason} is one clause from the phase goal in `ROADMAP.md` or from the result just shown.
+- Explain a real term such as "context window" once, with its line from the Explain once table in `audience.md`.
+- A line that would show a command to print a report file becomes "Ask me to show the full report."
+- Several options become one Next line plus "Also possible:" lines in the same shape.
+
+### Stopped check
+
+`The {name} check stopped this step: {why}. What to do: {action}.`
+
+Then `Ref: {code}`, then `Details:` followed by the check's own message exactly as printed. An advisory says the step carries on. Use the card the CLI printed, word for word; its `Ref:` line already names the query. Compose this shape only when none was printed (an older engine), and then name the check by its query, for example `vault.trace`.
+
+### Verification result
+
+Status line: `Done` for `passed`, `Not finished yet` for `gaps_found` (a required outcome is missing; name the status once in backticks), `Needs your check` for `human_needed`.
+
+Then three headed lists, each item one plain sentence:
+
+- What works ({N} of {M})
+- What is missing
+- What needs your own test
+
+End with the Next Up line.
+
+### Vault fallback question
+
+Your client's standards vault could not be loaded ({reason}); the fallback tier would apply the general Pareto standards instead. Proceed with the fallback? Type `confirmed` to go ahead.
+
+This answer is never given for the person and never assumed in an unattended run.
+
+### Irreversible action
+
+Say the action and its target before the person answers, and keep the workflow's own way of answering: its options, or the typed name for `remove-workspace`. One row per action:
+
+- `undo`: This will revert `{commits}` with `git revert`; history is kept. Then ask exactly as the workflow does, with the same options.
+- `remove-workspace`: This will delete the folder `{workspace path}` and every file in it; it cannot be undone. Type `{workspace name}` to go ahead.
+- `complete-milestone`: In the workflow's question, describe its "Delete without merging" option as: This will delete the branch `{branch}` of this milestone. Keep all of the workflow's options.
+- `transition`: This will skip `{plan names}`; they are not built in phase {N}. Then ask exactly as the workflow does, with the same options.
+- `vault-write-back`: This will write `{file}` to the repository `{repo}` at `{target}`, visible to everyone with access. Then ask exactly as the workflow does, with the same options.
+- `discovery-redo`: This will overwrite the notes of session {n} in `session-{nn}.md` and run the session again. Then ask exactly as the workflow does, with the same options.
+- `charter-redraft`: This will reopen `PROJECT-CHARTER.md` as version `{version}`; it must be signed again. Then ask exactly as the workflow does, with the same options.
+- `init-compose`: This will write `.platform-bindings.json` with the answers you gave. Then ask exactly as the workflow does, with the same options.
+
+### Discovery narration
+
+Show an ID next to its meaning ("decision D-03-2: one database"). Paths and check codes may appear in backticks. Keep `/pp-discovery N` commands in backticks.

package/pp-core/references/audience.md

@@ -0,0 +1,114 @@
+# Audience reference
+
+How pp-core talks to business users and business engineers. Tables below are parsed by `tests/jargon-denylist.test.cjs`; this file is the only copy of these lists.
+
+## When to read this
+
+Read this file only when the `init.*` payload carries `audience` (`business` or `engineer`). The workflow's pointer line sends you here with a Read, never an `@`-include, so a developer run never loads it.
+
+Follow the section for that audience in every message the person sees. That includes what a subagent returned: agents' own prompts stay as they are, and you reword their results when you pass them on. Reply in `response_language`. Keep everything on the Never reword list exactly as written.
+
+At five moments, also Read `audience-moments.md` in this folder and use its form for this audience: a Next Up block, a stopped check, a verification result, the vault fallback question and a confirmation before an irreversible action. In a discovery session, follow its Discovery narration rule as well.
+
+## Business users
+
+Write for someone who runs the work and decides, but does not read code.
+
+- Short sentences. Everyday words. Say what happened, then what to do.
+- Name a thing plus its number: "decision 3", "screen 7", "requirement 4". Never a bare code.
+- Use the Business user column of the glossary for every internal word. Never show anything on the hide list.
+- Keep the words sprint and MVP as they are.
+- Steer away from version-control topics. Do not explain saving, sharing or reviewing code; say pp-core takes care of it.
+- Leave out how files work inside, such as front matter or a change's hash. Say what the file or change is for.
+- Show commands, file names, paths and IDs in backticks, unchanged, next to a plain description.
+- When something fails, use two short sentences: what happened, what to do next.
+
+## Business engineers
+
+Plain English. The person knows the technology.
+
+- Real external terms stay as they are. Explain each once, the first time it comes up in a conversation, with its line from the Explain once table. Never replace one.
+- pp-core's own words use the Business engineer column of the glossary.
+- Keep a code next to its meaning: "decision D-03: use one database".
+- Never show a term the hide list marks both. Terms marked business are hidden from business users only.
+- Say what happened, what it means, what to do next.
+
+## Glossary
+
+`(hide)` means the term is also on the hide list for that audience. `(keep)` means the word stays as it is.
+
+| Internal term | Business user | Business engineer |
+|---|---|---|
+| vault | your organisation's standards | standards vault (the client's coding standards) |
+| milestone | release | milestone (one release) |
+| phase | stage of the work | phase |
+| wave | (hide) | build round |
+| worktree | (hide) | (hide) |
+| agent, subagent, spawn, orchestrator | (hide) | (hide) |
+| gate | the {name} check | the {name} check |
+| checkpoint | needs you | needs you (check, choose or do) |
+| must-haves, must_haves, truths | what must be true when this is done | required outcomes |
+| gaps_found | not finished yet | missing outcome |
+| verify-work | your acceptance test | UAT (you try the feature yourself) |
+| drift | out of date | out of date |
+| binding | platform connection | platform connection |
+| slug | short name | short name (URL-safe) |
+| Nyquist, Dimension 8 | (hide) | test coverage plan |
+| threat model | security risks | security risks |
+| model profile | (hide) | quality and cost level |
+| YOLO | run on its own | run automatically |
+| deviation | change from the standard | change from the plan |
+| accession | document number | document number |
+| artifact | document | document or output |
+| entity | core data | (keep) |
+| register | list | (keep) |
+| persona | user profile | (keep) |
+| Pre-Filled | prepared from your documents | pre-filled from documents |
+
+## Hide list
+
+| Term | Hidden from |
+|---|---|
+| wave | business |
+| worktree | both |
+| agent | both |
+| subagent | both |
+| spawn | both |
+| orchestrator | both |
+| Nyquist | business |
+| Dimension 8 | business |
+| model profile | business |
+| `.planning` | both |
+| `pp_run` | both |
+| Mermaid | business |
+
+A hidden thing is not shown. If it must be shown, show it unchanged in backticks.
+
+## Never reword
+
+| Kind | Examples |
+|---|---|
+| IDs | `D-03`, `REACH-01`, `03-02` |
+| File names | `ROADMAP.md`, `session-04.md` |
+| Commands | `/pp-discovery 4`, `/pp-plan-phase 3` |
+| Paths | `docs/discovery/PROJECT-CHARTER.md` |
+| Config keys | `workflow.research` |
+
+## Explain once
+
+| Term | Aliases | One-line explanation |
+|---|---|---|
+| branch | — | A named line of work, kept apart from the main one until it is ready. |
+| commit | — | A saved set of changes with a short note about why. |
+| pull request | PR, MR, merge request | A request for others to review changes before they join the main line. |
+| merge | — | Bringing the changes from one line of work into another. |
+| repository | repo | The folder of project files together with its full history. |
+| push | — | Sending saved changes to the shared copy of the repository. |
+| SHA | commit hash, sha | The unique code that names one commit. |
+| front matter | frontmatter | The settings block at the top of a document, between two `---` lines. |
+| CI | continuous integration | Automatic checks that run on every change. |
+| TDD | test-driven development, test-first | Writing the test first, then the code that makes it pass. |
+| UAT | user acceptance test | You try the feature yourself and say whether it does what you need. |
+| NFR | non-functional requirement | A quality the system must have, such as speed or security. |
+| MoSCoW | — | Sorting requirements into must, should, could and won't have now. |
+| ASVS | — | A security checklist with three levels of depth. |

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

@@ -43,6 +43,7 @@ blocked by it. The verifier takes the acceptance criteria of the extract's `_req
 | `_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 |
+| `_tests.md` § Process risk, § Focus areas, § Acceptance | the risk rows with `End-to-end` `yes` of the main processes touched; the focus-area rows whose `Requirements` cites one; the acceptance rows of the selected stories (`references/discovery-tests.md`) | planner end-to-end and extra test tasks; verifier UAT (role and test data per story) |
 | `_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` |
 
@@ -69,7 +70,7 @@ table must carry a `Requirements` column; the column name is the join, not the p
 | `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 `—` |
+| `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`); never `—` — a story comes from a step |
 
 ### Parser contract — `pp_run query discovery.stories-check`
 
@@ -82,7 +83,9 @@ table must carry a `Requirements` column; the column name is the join, not the p
 | `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) |
+| `bad_source_step` / `unknown_process_id` / `unknown_process_step` | a `Source step` token is not `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) |
+| `no_source_step` | `Source step` is `—` or empty — every story is tied to the step it came from |
+| `step_without_story` | a step row whose actor is a persona and that cites at least one `MVP` requirement (not `N-`/`T-`) is no story's source step — the stories do not cover the process. Without a parseable `_requirements.md` every persona step needs one |
 | `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 |
 

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

@@ -63,7 +63,7 @@ Column order is fixed; column headings may be translated.
 
 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).
+3. Else English (`en`). A Dutch conversation does not make the charter Dutch; only rung 1 or 2 does.
 
 The resolved code is written to the frontmatter `language` field. `und` is the template's placeholder
 and is replaced at draft time.
@@ -100,7 +100,7 @@ fault code emitted; a rule that is **not** mechanically checked says so.
 | `_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 |
+| prose, table cells other than IDs and enums | free text in the charter 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

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

@@ -102,7 +102,7 @@ Non-functional requirements are not in this list: they are `N-` rows of
 
 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
+`_roles.md`, `_integrations.md`, `_migration.md`, `_deviations.md`, `_tests.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.
 

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

@@ -11,7 +11,7 @@ lazily; it is never `@`-imported.
 | 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` |
+| 3 | Step 5B `## To-be` rows (`MP-`, each with `Replaces`) — the full process inventory; per main process, Step 5C its swimlane under `## Flows` with every step node labelled with its `#`, its `## Sub-processes` rows (`MP-nn.k`) and its step matrix 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 | | |
@@ -48,13 +48,17 @@ Illustration only — not part of the template, names invented:
 |---|---|---|---|---|---|---|---|
 | 01.1 | Create task | Team member | Task form | Task [C] | — | Title missing → form error, nothing saved | K-06 |
 
+| ID | Sub-process | Steps |
+|---|---|---|
+| MP-01.1 | Register the request | 01.1, 01.2 |
+
 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>`.
+**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`. Every main process has sub-processes `MP-nn.k`, each listing its steps by `#`; every step belongs to exactly one. One swimlane and one step matrix per main process; the swimlane labels every step node with its `#`. Nothing is renumbered or deleted; a change after sign-off edits the row in place and appends `→ amended by D-<ss>-<n>`.
 
 ## As-is
 
@@ -66,12 +70,23 @@ Bootstrap template — Session 2 copies it verbatim to `.planning/discovery/_pro
 | ID | Main process | Replaces | Trigger | End state | Primary actor | EPICs |
 |----|--------------|----------|---------|-----------|---------------|-------|
 
+## Sub-processes
+
+| ID | Sub-process | Steps |
+|----|-------------|-------|
+
 ## Flows
 
 ## Steps
 ```
 
-Under `## Flows`, Step 5B adds one `### MP-nn — <name>` heading per main process holding a swimlane:
+An engagement whose `_processes.md` predates the Session 3 rework has no `## Sub-processes`
+section; `process-check` then skips the sub-process and flow-coverage rules below. Adding the
+section (empty) opts the engagement in.
+
+Under `## Flows`, Step 5C adds one `### MP-nn — <name>` heading per main process holding a swimlane.
+Every step node carries its matrix `#` at the start of its label, so the diagram and the matrix
+describe the same steps; decisions and end states need no number:
 
 ````markdown
 ### MP-01 — Handle a task
@@ -79,12 +94,14 @@ Under `## Flows`, Step 5B adds one `### MP-nn — <name>` heading per main proce
 ```mermaid
 flowchart LR
   subgraph Team member
-    S1[Create task] --> S2[Assign]
+    S1["01.1 Create task"] --> S2["01.2 Assign"]
+    S2 --> D1{Urgent?}
   end
   subgraph System
-    S3[Notify assignee]
+    S3["01.3 Notify assignee"]
   end
-  S2 --> S3
+  D1 -->|yes| S3
+  D1 -->|no| E1([Task queued])
 ```
 ````
 
@@ -117,6 +134,13 @@ column name and the reason code — never cell prose. Absent `_processes.md` →
 | `### 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` |
+| `## Sub-processes` (optional — absent on engagements that predate it) | one table with the template's columns | `bad_table_shape (Sub-processes)` |
+| Sub-processes `ID` | `MP-nn.k` — a To-be main process and `k` from 1, unique, contiguous per main process | `bad_subprocess`, `duplicate_id`, `unknown_process`, `sequence_gap` naming `MP-nn.k` |
+| Sub-processes `Sub-process` | non-empty | `empty_cell (Sub-process)` |
+| Sub-processes `Steps` | a comma list of `#` cells of that main process's step matrix | `subprocess_without_steps`, `unknown_step`, `step_in_two_subprocesses` naming `MP-nn #<cell>` |
+| every main process, when the section is on file | at least one sub-process | `subprocess_missing` |
+| every step row, when the section is on file | listed by exactly one sub-process | `step_without_subprocess` naming `MP-nn #<cell>` |
+| every step row, when the section is on file | its `#` appears as a whole token in its main process's flow | `step_not_in_flow` naming `MP-nn #<cell>` |
 | 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` |
@@ -126,7 +150,7 @@ column name and the reason code — never cell prose. Absent `_processes.md` →
 
 **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`.
+`file`, `as_is`, `to_be`, `flows`, `steps`, `sub_processes`, `uncited`.
 
 ## `_rules.md`
 

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

@@ -61,7 +61,7 @@ before setting the score; it exits 0 before a session may read 100.
 
 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
+`_integrations.md`, `_migration.md`, `_deviations.md`, `_tests.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`

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

@@ -20,9 +20,8 @@ table columns. A section with nothing to report stays in place and says so; it i
 or renumbered. That is what lets a reader compare two charters side by side, and what lets
 `pp_run query discovery.charter-check` verify one.
 
-**Language.** The charter is written in the sprint language — the `Charter language` row of Session 1's
-Sprint Logistics, else `discovery.language` in `.planning/config.json`, else the language the sprint
-was facilitated in. Headings, labels and prose are translated; the `<!-- charter:<key> -->` heading
+**Language.** The charter is written in the charter language — the `Charter language` row of Session 1's
+Sprint Logistics, else `discovery.language` in `.planning/config.json`, else English. Headings, labels and prose are translated; the `<!-- charter:<key> -->` heading
 keys, the frontmatter fields and every enum cell (`status`, `go_no_go`, `Green / Amber / Red`,
 `Approve / Approve with conditions / Reject`, `Yes / No`) stay in English, because the check reads them.
 Column order is fixed; column headings may be translated.
@@ -273,7 +272,7 @@ source of truth; the charter only condenses them.
   Aim for a charter that reads in about fifteen minutes.
 - **Fixed shape.** Keep all 20 sections, their keys, their order and their table columns. An empty table
   stays in place with no rows, and the section's prose says `None identified in Discovery.` (in the
-  sprint language). The **Source files** footer names only the files that exist in this engagement.
+  charter language). The **Source files** footer names only the files that exist in this engagement.
 - **Go / No-Go is recorded, not re-judged.** § 17 copies Session 13's assessment verbatim and the
   frontmatter `go_no_go` equals its overall recommendation; `Pending` is allowed only while `status`
   is `Draft`.

package/pp-core/workflows/add-phase.md

@@ -34,6 +34,8 @@ INIT=$(pp_run query init.phase-op "0")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Check `roadmap_exists` from init JSON. If false:
 ```
 ERROR: No roadmap found (.planning/ROADMAP.md)

package/pp-core/workflows/add-tests.md

@@ -38,6 +38,8 @@ INIT=$(pp_run query init.phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`.
 
 Verify the phase directory exists. If not:

package/pp-core/workflows/add-todo.md

@@ -17,6 +17,8 @@ INIT=$(pp_run query init.todos)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Extract from init JSON: `commit_docs`, `date`, `timestamp`, `todo_count`, `todos`, `pending_dir`, `todos_dir_exists`.
 
 Ensure directories exist: