@pareto4/pp-core 1.18.0 → 1.20.0

package/pp-core/workflows/discovery-sprint/charter.md

@@ -0,0 +1,114 @@
+# Discovery Charter — Draft, Finish, Redraft, Export
+
+> **Lazy-loaded.** Read from `sessions/13-wrap-up.md` Step 0.5 (§ Draft), from Session 13's Closing
+> Step (§ Finish), and from `workflows/discovery-sprint.md` when invoked as `/pp-discovery charter`
+> (§ Redraft). The main workflow's init block has already resolved `PP_TOOLS` and defined `pp_run`.
+
+The charter is `docs/discovery/PROJECT-CHARTER.md` — client-visible, like `docs/architecture/`. Its
+template is `${PP_TOOLS%/bin/pp-tools.cjs}/templates/project-charter.md`; the parser contract, the
+heading keys and their translations are `${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-charter.md`.
+Read both before writing. Write targets are `docs/discovery/PROJECT-CHARTER.md`, `.docx` and `.pdf`
+only — relative paths, never `..`, never an absolute path, never anything under `.planning/`.
+
+The session files and the registers under `.planning/discovery/` are the source of truth; the charter
+condenses them and invents nothing. A value Discovery did not settle reads
+`Not decided in Discovery — OI-n` and that item stands in § 15.
+
+## Language
+
+Resolve once, record in the frontmatter `language` field:
+
+1. Session 1 § Sprint Logistics, row **Charter language** (a BCP-47 code: `nl`, `en`, `nl-BE`).
+2. Else `pp_run query config-get discovery.language --default "" --raw`.
+3. Else the language the sprint was facilitated in (Flow 2 Step 5).
+
+Render headings, labels and prose in that language — the reference carries the English and Dutch
+headings; translate others yourself. Never translate the `<!-- charter:<key> -->` comments, the
+frontmatter field names and values, or an enum cell (`Green / Amber / Red`, `Approve / Approve with
+conditions / Reject`, `Yes / No`). Column order is fixed.
+
+## Draft (Session 13 Step 0.5)
+
+Runs after the cross-reference (Step 0f) and before the topics, so topic 2 reviews a real document.
+
+1. If `docs/discovery/PROJECT-CHARTER.md` already exists, this is not a first draft: go to § Redraft.
+2. Resolve the language (§ Language).
+3. Read the sources the template's source map names: `.planning/discovery/session-01.md` …
+   `session-13.md`, `_progress.md`, `_requirements.md`, `_screens.md`, `_feedback.md`, `_research.md`,
+   `_deviations.md`, `prototype/README.md` — skipping any that does not exist. Spawn an Explore agent
+   to extract the named Notes Template tables from the session files in parallel when one is
+   available; read the registers yourself, in full.
+4. Run `pp_run query discovery.rollup .planning/discovery/_requirements.md` for the counts line: one
+   `<PREFIX>- <n>` per registered prefix counting `MVP` and `Later` rows, then `Dropped <n>`, joined
+   with ` · `. Skip the line's counts when `_requirements.md` does not exist.
+5. Write the file from the fenced template, verbatim in shape: every section, every key comment, every
+   table in order. Fill the frontmatter (`project`, `client`, today's `date`, the `language` code,
+   `discovery_sessions_completed` from `_progress.md`, `version: 1.0`, `status: Draft`,
+   `go_no_go: Pending`) and the document-control table. Fill each section from its source rows only,
+   keeping every ID exactly as minted. Leave § 17's status cells empty and § 15 empty — topics 3 and 4
+   record them — and fill § 16 with what is already known: `⚠️ CONDITIONAL` sections (from each
+   session's `conditional:` frontmatter), open `Gates-MVP` rows of `_research.md`, and every
+   `Dropped (D-ss-n)` requirement. A section with nothing to report keeps its empty table and says
+   `None identified in Discovery.` in the sprint language. **Redo of Session 13:** when `session-13.md`
+   already carries a filled Go / No-Go Assessment and Open Items Register from an earlier run, copy them
+   now as § Finish steps 1–2 describe — the check compares against them once the overall cell is
+   filled, and an empty § 17 would then be a fault, not a draft.
+6. Run `pp_run query discovery.charter-check`. Non-zero: fix every fault it names and re-run until it
+   exits 0 — `unknown_id` means a cell cites an ID nothing minted; `counts_mismatch` means the § 3 line
+   disagrees with the roll-up. The draft is not finished while the check is red.
+7. Report in one block: the path, the language, the sections that read `None identified`, the number of
+   IDs the check resolved. Then return to `sessions/13-wrap-up.md` Step 5: topic 2 walks this document.
+
+## Finish (Session 13 Closing Step)
+
+Runs after Flow 2 Step 7 and before Step 8, every time Session 13 completes, including a redo.
+
+1. Copy Session 13's **Go / No-Go Assessment** into § 17 as recorded — eight rows in order, status cells
+   verbatim — and set the frontmatter `go_no_go` to the overall recommendation. Every condition
+   attached to a `Go with conditions` becomes a § 16 row (Kind: Go condition); an Amber row under a
+   plain `Go` is not a condition and stays an open item.
+2. Copy the **Open Items Register** into § 15 row for row, in the charter's six columns (`Source
+   Session` and `Priority` stay in the register). Every row whose *Must Resolve Before Build?*
+   starts with `Yes` and whose Status is not `Closed`, `Resolved` or `Done` becomes a § 16 row (Kind:
+   Must resolve before build) citing its `OI-` ID.
+3. Add Session 13's scope-, architecture-, cost- or timeline-changing decisions to § 18.
+4. Set `status: For sign-off` and today's `date`; set the § 20 row for the current version to
+   `For sign-off` with that date.
+5. Run `pp_run query discovery.charter-check`. It must exit 0; fix and re-run until it does.
+6. Run § Export.
+7. Commit the markdown and whichever exports exist:
+   `pp_run commit "docs(discovery): project charter for sign-off" --files docs/discovery/PROJECT-CHARTER.md docs/discovery/PROJECT-CHARTER.docx docs/discovery/PROJECT-CHARTER.pdf`
+   (drop a path that was not written).
+8. Tell the user what happens next, in two lines: signatures are recorded in § 19 and the status
+   follows them (`/pp-discovery charter` does it); `/pp-discovery-to-build` requires `Signed` or
+   `Signed with conditions`, and `--unsigned` records the gap instead of waiting.
+
+## Redraft (`/pp-discovery charter`, and any change after `For sign-off`)
+
+1. Read the charter. Ask what changed (`AskUserQuestion`; **text mode fallback:** numbered list):
+   1) Signatures collected / 2) A decision changed a recorded fact / 3) A correction to the text.
+2. **Signatures:** fill the § 19 `Decision`, `Conditions`, `Date` cells as given; set `status` from the
+   rows — `Signed` when every row approves, `Signed with conditions` when any row approves with
+   conditions, `Rejected` when any row rejects. Add a § 20 row with the **same** version, the new
+   status and `Signatures recorded` as the change. The version signed is the version that was
+   circulated; nothing else moves.
+3. **A changed fact or a correction:** bump the minor version (`1.0` → `1.1`), set `status: Draft`,
+   add a § 20 row naming the `D-<ss>-<n>` that caused the change (or `—` for a wording fix), edit the
+   affected rows from their sources, and go back through § Finish steps 4–8 when the text is agreed.
+   A changed fact is first changed where it was recorded — the session table or the register — with
+   the back-amend rule (Flow 2 Step 6); the charter follows the source, never the other way round.
+4. Run `pp_run query discovery.charter-check` (exit 0 required), then § Export, then commit as in
+   § Finish step 7 with the message `docs(discovery): project charter v<version> <status>`.
+
+## Export
+
+The markdown is the source; `docs/discovery/PROJECT-CHARTER.docx` and `docs/discovery/PROJECT-CHARTER.pdf`
+are renderings, regenerated every time the markdown changes and never edited by hand or read back.
+
+1. Invoke the `pareto-brand` skill for the document styling rules, then the `docx` skill to render
+   `docs/discovery/PROJECT-CHARTER.docx` from the markdown — same sections, same order, the key
+   comments omitted — then the `pdf` skill for `docs/discovery/PROJECT-CHARTER.pdf` from the same
+   content. The runtime may list these skills under a namespace (for example `anthropic-skills:docx`);
+   use the name it lists.
+2. When a skill is not installed, say so once, write `export: skipped (<skill> unavailable)` into the
+   Change cell of the current § 20 row, and continue. A missing renderer never blocks the sprint.

package/pp-core/workflows/discovery-sprint/prefill.md

@@ -33,7 +33,7 @@ alongside the mapped input documents.
    to pre-fill from without a mapped package.
 2. The target session file `.planning/discovery/session-NN.md` must exist; if
    absent, create it from its session template exactly as Flow 2 Step 1 of the
-   main workflow does (including `_progress.md` / `_context.md` bootstrap when
+   main workflow does (including the `_progress.md` bootstrap when
    this is the first-ever session artifact).
 3. The session's current status must be `Not Started`. Never pre-fill a session
    that is `In Progress` or `Completed` — live answers outrank paper answers.

package/pp-core/workflows/discovery-sprint/prototype.md

@@ -8,7 +8,7 @@
 > prototype only when new functional requirements have been found; Sessions 5–13 are technical and
 > never trigger an update on their own. It writes only
 > under `.planning/discovery/prototype/`, plus a round in `.planning/discovery/_feedback.md` and
-> the prototype lines of `.planning/discovery/_context.md`.
+> the decisions it produced in Session 4's **Key Decisions**.
 
 ## Step 0: Vault Context
 
@@ -237,9 +237,9 @@ when requirements changed, the roll-up `--check`. All must exit 0.
 
 ## Step 9: Record and summarise
 
-Fill the **Prototype** lines under Session 4's outputs in `.planning/discovery/_context.md`: the
-round, the flows validated, the rows processed, the elements swept and the decisions they produced.
-Then show:
+Record each decision the round produced as a `D-04-<n>` row of `.planning/discovery/session-04.md`
+**Key Decisions**; the round itself — flows validated, rows processed, elements swept — is already
+in `_feedback.md` and `_sweep.md`. Then show:
 
 ```
 Prototype — Round <k> — Complete

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

@@ -19,7 +19,17 @@ documented absent-artifact arm — before the cross-reference analysis begins.
 
 **Element-sweep gate:** run `pp_run query discovery.element-sweep --check`. Exit 0 → proceed. Non-zero → a functional prototype element has no id, a tag names an unknown requirement, or `_sweep.md` leaves an element of the current pages undecided, decides one twice, or cites a reference that does not fit its outcome — finish the sweep with `/pp-discovery prototype` Step 8 and re-run. Without a prototype the check exits 0 by itself.
 
-**Vault-context gate (PBI 75336):** for each of sessions 1–12 whose `.planning/discovery/session-NN.md` carries a `## Vault Context` section, run `pp_run query discovery.vault-check <N>`. Exit 0 → proceed. Non-zero → the record names no index, a line is not one `` - `<path>` — <why> `` entry, or a selected vault document is neither cited `[vault: <path>]` in the notes nor marked `— not used: <reason>`: fix that session's record or notes and re-run. A session with no `## Vault Context` section ran without the vault and is skipped.
+**Vault-context gate (PBI 75336):** for each of sessions 1–12 whose `.planning/discovery/session-NN.md` carries a `## Vault Context` section, run `pp_run query discovery.vault-check <N>`. Exit 0 → proceed. Non-zero → the record names no index, a line is not one `` - `<path>` — <why> `` entry, a selected vault document is neither cited `[vault: <path>]` in the notes nor marked `— not used: <reason>`, or a document the vault's `INDEX.md` marks `[cross-cutting]` has no record line: fix that session's record or notes and re-run. A session with no `## Vault Context` section ran without the vault and is skipped.
+
+**Artifact gates (data model, processes, rules):** run `pp_run query discovery.entity-check`, `pp_run query discovery.process-check` and `pp_run query discovery.rules-check`. Each exits 0 → proceed. Non-zero → a section or table header is off the template, an entity name is not one PascalCase token or is repeated, a lifecycle flag or classification is outside its vocabulary, a relationship end, attribute heading, lifecycle row or step-matrix data object names an entity the data model does not have, a cardinality is not Mermaid's, a `PRC-`/`MP-`/`BR-` ID is malformed, repeated or leaves a hole, a `Replaces` cell names an as-is process that does not exist, a main process has no swimlane or no step matrix, a flow has no `subgraph`, an actor is neither a Session 2 persona nor `System`, a data object is not `Name [C/R/U/D]`, a cited requirement does not exist, a rule names no layer, no requirement or an unknown entity or process — fix the named rows in the artifact and re-run. These gates report: a pending `—` cell and an uncited step are not faults here; the handoff adds `--require-complete` and `--require-cited` and hard-blocks on them. An artifact that does not exist exits 0 by itself. Fault vocabularies: `references/discovery-data-model.md`, `references/discovery-processes.md`.
+
+**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`.
+
+**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`.
+
+**Charter gate (reporting — runs after Step 0.5 and again in the Closing Step, not before 0a):** run `pp_run query discovery.charter-check`. Exit 0 → proceed. Non-zero → the frontmatter misses a field or has a value outside its enum, a `<!-- charter:<key> -->` section is missing, repeated, out of order or unknown, a table cell cites an ID no session table or register minted, the § 3 counts line disagrees with the roll-up, a `Dropped` requirement or a must-resolve open item is not listed under § 16, the § 17 table differs from this session's Go / No-Go Assessment, a § 19 decision is outside its vocabulary or disagrees with `status`, or § 20 does not end at the frontmatter version — fix the named items in `docs/discovery/PROJECT-CHARTER.md` (or the source they copy) and re-run. Before Step 0.5 the file does not exist and `charter_missing` is the cue to draft it, not a fault. The gate never asks for a signature: `--require-signed` belongs to `/pp-discovery-to-build`, where an unsigned charter hard-blocks unless `--unsigned` records the gap. Fault vocabulary: `references/discovery-charter.md`.
 
 **The screen-traceability gate reports open feedback; it never blocks on it (D-53, first arm).** A round whose `Processing` cells all read `Open` exits 0 and the open count is reported as outstanding work — exactly as an open `Gates-MVP` research item exits 0 under D-43. It fails only on structural faults. The hard block on those same structural faults lives at `/pp-discovery-to-build`, not here (D-53, second arm): the handoff into build is the last moment an uncovered MVP requirement or an unclassified surface is still free to fix. Open feedback is still closed before Session 13 completes, by the `--require-processed` check in Flow 2 Step 7, and the handoff refuses it too.
 

package/pp-core/workflows/discovery-sprint/sessions/01-kick-off.md

@@ -5,7 +5,7 @@
 
 ### Session 1: Discovery Sprint Kick-off
 
-**Goal:** Align all participants on the Discovery Sprint purpose, establish project context, confirm business vision, identify stakeholders, and agree on the discovery approach, ground rules, and logistics.
+**Goal:** Align all participants on the Discovery Sprint purpose, establish project context, confirm business vision, identify stakeholders and who approves what, and agree on the discovery approach, ground rules, and logistics.
 
 **What We Cover:**
 
@@ -29,9 +29,10 @@
 
 4. **Discovery Sprint approach and logistics**
    *Why it matters: sets expectations so the remaining 12 sessions run smoothly without renegotiating format each time. Skip when: the team has already run a Discovery Sprint together before and knows the cadence.*
-   - Walk through the 13-session agenda and expected outputs
+   - Walk through the 13-session agenda and expected outputs, including the cross-reference that closes Session 8 and the one that opens Session 13
    - What is the preferred meeting cadence and format (in-person, remote, hybrid)?
    - How will decisions be documented and communicated?
+   - What is the team shape for the sprint and the build: a full delivery team, a small team, or one person working with an AI assistant? Session 12 builds the delivery model on this answer.
 
 5. **Ground rules and ways of working**
    *Why it matters: prevents disagreements from derailing later sessions once real tradeoffs surface. Skip when: the team already has an established working agreement from a prior engagement.*
@@ -44,16 +45,28 @@
    - Are there hard deadlines (regulatory, contractual, market)?
    - What budget constraints exist? [needs-business-input]
    - Are there technology mandates or restrictions?
+   - Does the client vault or the client mandate a platform: cloud provider, CI/CD, observability? Record the mandate as a Key Decisions row `D-01-<n>`, citing `[vault: <path>]` when the vault states it. Sessions 5, 6 and 10 fill their tables against this decision; with no mandate, record that the platform is open.
 
 7. **Requirement ID prefixes and decision-ID conventions**
    *Why it matters: every requirement, decision, and action across all 13 sessions cites these IDs — chosen once here, never renumbered. Skip when: never — mandatory.*
    - Propose a prefix set derived from the stakeholder domains just mapped in topic 3: one prefix per stakeholder domain, plus `N-` (non-functional) and `T-` (technical) defaults; the user confirms or adjusts (D-09)
    - Create `.planning/discovery/_requirements.md` from the bootstrap template in the pp-core reference `references/discovery-id-conventions.md` — locate it under the installed pp-core root (`${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-id-conventions.md`) and Read it lazily; never `@`-import it. Fill the Prefix Registry header table with the confirmed set (the registry and the requirements table travel in one file — D-10)
-   - Never register a reserved prefix: the proposed set must not include `D-`, `A-`, `SP-`, `DG-`, `RS-` or `SCR-` — they are owned by other ID families, and a row claiming one makes `discovery rollup --check` report `reserved_prefix` (D-44)
+   - Never register a reserved prefix: the proposed set must not include `D-`, `A-`, `SP-`, `DG-`, `RS-`, `SCR-`, `PRC-`, `MP-`, `BR-`, `IF-`, `MG-` or `DEV-` — they are owned by other ID families, and a row claiming one makes `discovery rollup --check` report `reserved_prefix` (D-44). Avoid the session-table row prefixes that reference lists too (`C-`, `R-`, `E-`, …), so a citation never reads two ways
    - Decisions are cited inline as `D-<ss>-<n>` per that same reference; record the chosen prefix set as a Key Decisions row in the Session 1 notes
 
+8. **Approval routes**
+   *Why it matters: Sessions 5–7 sign architecture and security deviations; an approval route found only later means those signatures were given by people who could not give them. Skip when: never — "no formal route" is itself an answer to record.*
+   - Which approvals will this project need: scope, budget, architecture, security deviations, data protection, go-live?
+   - Who gives each approval, and who is consulted or informed?
+   - When the client vault is bound, sweep it for approval rules: every document that says who must approve what. Record each route in the **Approval Matrix** with its `[vault: <path>]` citation.
+   - Where no route exists for an approval the sprint will need, who approves it? Record the answer as `D-01-<n>`.
+
 **Notes Template:**
 
+**Background**
+
+The business problem or opportunity, what was tried before and with what result, and the documents handed over, cited by accession number (`[NN]`).
+
 **Stakeholder Register**
 
 | Name | Role | Organization | Interest Area | Decision Authority | Availability |
@@ -70,21 +83,55 @@
 | Success criteria (12-month) | |
 | Key business drivers | |
 
+**Sprint Logistics**
+
+| Aspect | Agreement |
+|--------|-----------|
+| Session cadence and format | |
+| Team shape | |
+| Decision recording and communication | |
+| Charter language | |
+
+**Charter language** is a BCP-47 code (`nl`, `en`, `nl-BE`): the Project Charter Session 13 drafts is rendered in it (`references/discovery-charter.md` § Language resolution). Leave it empty to fall back to `discovery.language` in `.planning/config.json`, else the facilitation language.
+
+**Working Agreement**
+
+| Aspect | Agreement |
+|--------|-----------|
+| Disagreements and competing priorities | |
+| Escalation path for blockers | |
+| Collaboration tools | |
+
 **Constraints and Risks Register**
 
 | ID | Type | Description | Impact (H/M/L) | Mitigation | Owner |
 |----|------|-------------|-----------------|------------|-------|
-| C1 | Constraint | | | | |
-| R1 | Risk | | | | |
+| CON-01 | Constraint | | | | |
+| R-01 | Risk | | | | |
+
+Session 11's **Risk Register** continues the `R-` sequence; a risk raised here keeps its ID there.
+
+**Approval Matrix**
+
+| Approval | Approver | Consulted | Source | Decision |
+|----------|----------|-----------|--------|----------|
+| Scope change | | | | |
+| Budget | | | | |
+| Architecture deviation | | | | |
+| Security deviation | | | | |
+| Data protection | | | | |
+| Go-live | | | | |
+
+**Source** is a `[vault: <path>]` citation or `room`. **Decision** is `—` or the `D-01-<n>` that set a route the vault does not give. The **Approver** column is the approver source for `.planning/discovery/_deviations.md`: `deviations-check` refuses a deviation whose approver this matrix does not name (`references/discovery-standards.md`), so name the architect who signs architecture and security deviations here, spelled as the deviation rows will spell it.
 
 **Key Decisions**
 
-| # | Decision | Rationale | Owner | Date |
+| ID | Decision | Rationale | Owner | Date |
 |---|----------|-----------|-------|------|
 | | | | | |
 
 **Action Items**
 
-| # | Action | Owner | Due Date | Status |
+| ID | Action | Owner | Due Date | Status |
 |---|--------|-------|----------|--------|
 | | | | | |

package/pp-core/workflows/discovery-sprint/sessions/02-as-is.md

@@ -5,7 +5,7 @@
 
 ### Session 2: Business Process Mapping (As-Is)
 
-**Goal:** Document current-state business processes, identify pain points and inefficiencies, define user personas, map the existing systems landscape, and understand current data flows.
+**Goal:** Document current-state business processes, identify pain points and inefficiencies, define user personas, map the existing systems landscape, understand current data flows, and record which data the new solution has to take over.
 
 **What We Cover:**
 
@@ -16,6 +16,7 @@
    - Who is involved at each step and what is their role?
    - What is the average time to complete each process?
    - Are there seasonal or volume-based variations?
+   - Record each process as a `PRC-` row of `.planning/discovery/_processes.md` § As-is — the canonical process register (`references/discovery-processes.md`); the **Process Inventory** below only summarises it
 
 2. **Pain points and inefficiencies**
    *Why it matters: pain points become the EPICs and priorities validated in Session 3. Skip when: the initiative isn't process-improvement driven (e.g. a pure greenfield product).*
@@ -40,7 +41,8 @@
 
 5. **Data flows and information architecture**
    *Why it matters: existing data flows inform the target data model and Session 5's integration map. Skip when: greenfield build with no legacy data to trace.*
-   - What are the key data entities (customer, order, product, invoice)?
+   - What are the key data entities (customer, order, product, invoice)? Each becomes a row of `.planning/discovery/_entities.md` § Entities — the canonical data model (`references/discovery-data-model.md`) — named, never numbered, with Identifier, Classification and Retention `—` until Sessions 5 and 6 fill them
+   - Which word does the client use for each entity, and which other words were heard for the same thing? One `_glossary.md` row per concept, synonyms under `Do not use`
    - How does data flow between systems today?
    - Are there batch processes, real-time integrations, or manual transfers?
    - What data quality issues exist?
@@ -51,13 +53,25 @@
    - What audit trails or reporting obligations exist?
    - Are there data residency or retention requirements?
 
+7. **Data to migrate**
+   *Why it matters: data the new solution takes over from an existing system is a build phase of its own, with a cut-over nobody can improvise; naming it now lets Session 8 design the move and Session 11 plan it. Skip when: greenfield build — no existing data moves.*
+   - Which of the systems in the landscape hold data the new solution must take over, and which data stays behind or is archived?
+   - For each: which entities, roughly how many records, and how clean is the data today?
+   - Record one `MG-<nn>` row per source system and entity set in `.planning/discovery/_migration.md` § Migration — create the file from the template in `${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-integrations.md` § `_migration.md` on first need; `Source system` is spelled as the **Systems Landscape** spells it, `Entity` as `_entities.md` does, `Mapping`, `Cut-over`, `Reconciliation` and `Requirements` stay `—` for Session 8. Run `pp_run query discovery.migration-check` — exit 0, or fix the rows it names.
+
 **Notes Template:**
 
+> **Artifacts this session creates (first run only):** copy the bootstrap templates verbatim, replacing `[PROJECT_NAME]` — `.planning/discovery/_processes.md` and `.planning/discovery/_glossary.md` from `${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-processes.md`, `.planning/discovery/_entities.md` from `${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-data-model.md`, and — only when topic 7 finds data to move — `.planning/discovery/_migration.md` from `${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-integrations.md`. They are the canonical registers; the tables below summarise or point at them and are never the place a fact is first written.
+
 **Process Inventory**
 
-| Process ID | Process Name | Owner | Trigger | End State | Frequency | Avg Duration | Criticality |
-|------------|-------------|-------|---------|-----------|-----------|--------------|-------------|
-| P-01 | | | | | | | |
+The canonical rows live in `.planning/discovery/_processes.md` § As-is: `| ID | Process | Owner | Trigger | End state | Frequency | Avg duration | Criticality |`, one `PRC-<nn>` row per process in the order they were discussed. This table is a reading summary — one row per process, never the place a fact is first written:
+
+| Process ID | Process Name | What the register row does not hold |
+|------------|-------------|-------------------------------------|
+| PRC-01 | | |
+
+**Process ID** is `PRC-<nn>`, a reserved prefix, so a process never shares an ID with a requirement.
 
 **Pain Points Register**
 
@@ -83,14 +97,24 @@
 |--------|-----------------|-----------|-----------|--------|----------------|
 | | | | | | |
 
+Every **Entity** named here is also a row of `.planning/discovery/_entities.md` § Entities, spelled the same (one PascalCase token, `Task`, `AuditEntry`), Source `S2`, pending cells `—`. This map keeps the as-is facts the data model does not hold (system of record, flows, volume, quality); the data model keeps everything the build needs. Close the session with `pp_run query discovery.entity-check` — exit 0, or fix the rows it names.
+
+**Data to Migrate**
+
+The canonical rows live in `.planning/discovery/_migration.md` § Migration (`MG-<nn>`, one per source system and entity set — `references/discovery-integrations.md`). This table is a reading summary; write `None identified in Discovery.` under it when nothing moves:
+
+| Migration ID | Source system | What moves |
+|--------------|---------------|------------|
+| MG-01 | | |
+
 **Key Decisions**
 
-| # | Decision | Rationale | Owner | Date |
+| ID | Decision | Rationale | Owner | Date |
 |---|----------|-----------|-------|------|
 | | | | | |
 
 **Action Items**
 
-| # | Action | Owner | Due Date | Status |
+| ID | Action | Owner | Due Date | Status |
 |---|--------|-------|----------|--------|
 | | | | | |

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

@@ -18,6 +18,7 @@ This session uses the **Session 3: Process-First Protocol** (Steps 5A–5G, at t
    - 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%)?
+   - **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.*
@@ -41,7 +42,7 @@ This session uses the **Session 3: Process-First Protocol** (Steps 5A–5G, at t
 5. **Functional requirements** (derived from 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 calculations, transformations, or business logic are required?
+   - 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**
@@ -55,17 +56,15 @@ This session uses the **Session 3: Process-First Protocol** (Steps 5A–5G, at t
 
 **Main Process Register** (populated via process-first decomposition Step 5A)
 
-| MP ID | Main Process | Trigger | End State | Primary Actor | Related EPICs |
-|-------|--------------|---------|-----------|---------------|---------------|
-| MP-01 | | | | | |
+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)
 
-One Mermaid flowchart block per accepted sub-process decomposition.
+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.
 
 **Step Matrices** (populated via Step 5C)
 
-One step matrix per sub-process; Requirements column back-filled at Step 5D.
+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.
 
 **Business Objectives**
 
@@ -89,20 +88,20 @@ Orphan-requirement and uncovered-step flags only — the canonical requirements
 |---------|-----------|-------------|----------------|--------|----------------|
 | E-01 | | | | | |
 
-**User Stories**
+**User Stories** (populated via Step 5E)
 
-| Story ID | EPIC | User Story | Acceptance Criteria | MoSCoW | Source Step |
-|----------|------|------------|---------------------|--------|-------------|
-| US-01 | | | | | |
+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.
 
 **Non-Functional Requirements**
 
 | ID | Category | Requirement | Target / Threshold | MoSCoW |
 |----|----------|-------------|-------------------|--------|
-| NFR-01 | Performance | | | |
-| NFR-02 | Availability | | | |
-| NFR-03 | Scalability | | | |
-| NFR-04 | Accessibility | | | |
+| | Performance | | | |
+| | Availability | | | |
+| | Scalability | | | |
+| | Accessibility | | | |
+
+**ID** is the requirement's `N-<nn>` row in `_requirements.md`, minted at Step 5D like every other requirement — never a separate `NFR-` sequence.
 
 **Prototype Validation Plan** (populated via Step 5G)
 
@@ -110,13 +109,13 @@ Flows to be clickable, personas covered, and per-flow definition of "validated".
 
 **Key Decisions**
 
-| # | Decision | Rationale | Owner | Date |
+| ID | Decision | Rationale | Owner | Date |
 |---|----------|-----------|-------|------|
 | | | | | |
 
 **Action Items**
 
-| # | Action | Owner | Due Date | Status |
+| ID | Action | Owner | Due Date | Status |
 |---|--------|-------|----------|--------|
 | | | | | |
 
@@ -129,51 +128,57 @@ The agent proposes the process landscape from Session 2 outputs; the user valida
 
 ### Step 5A: Propose Main Processes
 
-Read `.planning/discovery/session-02.md` and `.planning/discovery/_context.md`. Propose the main business processes for the to-be state:
+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:
 
 ```
 Based on Session 2, I'm proposing these main processes for the to-be state:
 
-| MP ID | Main Process | Trigger | End State | Primary Actor | Rationale (from S2) |
-|-------|--------------|---------|-----------|---------------|---------------------|
-| MP-01 | ...          | ...     | ...       | ...           | ...                 |
+| MP ID | Main Process | Replaces (PRC-nn or new) | Trigger | End State | Primary Actor | Rationale (from S2) |
+|-------|--------------|--------------------------|---------|-----------|---------------|---------------------|
+| MP-01 | ...          | ...                      | ...     | ...       | ...           | ...                 |
 
 Validate: accept / edit / add / drop. Then we'll decompose each into sub-processes.
 ```
 
-Iterate until the user accepts the main-process list, then fill the section titled exactly **Main Process Register** in `.planning/discovery/session-03.md` — edit in place; never append a new heading.
+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.
 
 **Text mode fallback:** present numbered options: 1) Accept all / 2) Edit specific process / 3) Add process / 4) Drop process.
 
 ### Step 5B: Decompose into Sub-Processes (per main process)
 
-For each accepted main process, propose 3–8 sub-processes and emit a Mermaid flowchart:
+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 TD
-  Start([Trigger]) --> SP1[Sub-process 1]
-  SP1 --> D1{Decision}
-  D1 -->|Yes| SP2[Sub-process 2]
-  D1 -->|No| SP1_alt[Alternative path]
+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])
 ```
 
-Present to the user and iterate until accepted, then fill the section titled exactly **Sub-Process Flows** in `.planning/discovery/session-03.md` — edit in place; never append a new heading.
+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`.
 
 ### Step 5C: Step Matrix (per sub-process)
 
-For each accepted sub-process, propose a step-level matrix:
+For each accepted sub-process, propose a step-level matrix in the columns `_processes.md` § Steps fixes:
 
-| # | Step | Actor | UI (screen / component) | Data Objects (C/R/U/D) | Integration | Requirements |
+| # | Step | Actor | UI | Data objects | Integration | Exception | Requirements |
 
+- **#:** `<mp>.<n>` — `01.3` is the third step of MP-01
 - **Step:** one imperative verb phrase
-- **Actor:** persona from Session 2 or "System"
+- **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 with CRUD flags (e.g., `Order [C]`)
-- **Integration:** external systems with direction
-- **Requirements:** leave blank during 5C — back-filled with minted `_requirements.md` IDs during Step 5D consolidation
+- **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
 
-Present one sub-process matrix at a time. After validation, fill the section titled exactly **Step Matrices** in `.planning/discovery/session-03.md` — edit in place; never append a new heading.
+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 5D: Consolidate Requirements
 
@@ -192,7 +197,19 @@ Add one row per requirement to the `## Requirements` table — the canonical tab
 
 **No ⚠️ markers in requirement cells (D-46):** never place a `⚠️ CONDITIONAL —` marker inside a `_requirements.md` cell — that grammar is closed and fail-loud, so a marker there is already a `rollup --check` parse error. Express a research-dependent requirement the other way round: an `_research.md` row citing it in `Gates what?`.
 
-Back-fill the Requirements column of each Step 5C matrix in `session-03.md` with the minted IDs.
+Back-fill the Requirements column of each Step 5C matrix in `.planning/discovery/_processes.md` § Steps with the minted IDs, then run `pp_run query discovery.process-check --require-cited` — exit 0, or a step still cites nothing (`uncited_step`) or cites an ID that does not exist.
+
+### Step 5D′: Business Rules
+
+Walk the step matrices once more for what the system must *enforce* rather than *do*: a validation ("a title is required"), a calculation ("the total is the sum of the lines"), an invariant ("exactly one Lead per team"). Mint one `BR-<nn>` row per rule in `.planning/discovery/_rules.md` (template and grammar: `${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-processes.md` § `_rules.md`; create the file from the template when it does not exist):
+
+| ID | Rule | Applies to | Checked at | Requirements | Source |
+
+- **Applies to:** the entity names (as `_entities.md` spells them) or `MP-`/`PRC-` IDs the rule governs
+- **Checked at:** the layers that enforce it — `UI`, `service`, `DB` — the vault's rule that a check has a named owner
+- **Requirements:** the `_requirements.md` IDs the rule realises; a rule nothing requires is a question for the user, not a row
+
+Then run `pp_run query discovery.rules-check` — exit 0, or fix the rows it names.
 
 **Roll-up (REQM-04):** after filling rows, run `pp_run query discovery.rollup .planning/discovery/_requirements.md` and replace the content between the `<!-- rollup:auto -->` markers verbatim with the emitted `table`. Never hand-write or hand-edit totals — the block is machine-owned and Session 13's `--check` gate fails on drift.
 
@@ -202,7 +219,17 @@ Full grammar reference: pp-core `references/discovery-id-conventions.md` (Read l
 
 ### Step 5E: EPICs and User Stories
 
-Group sub-processes into EPICs (one EPIC = one main process). Derive user stories from step-matrix rows where the actor is a persona. Link stories to source steps via `source_step` field. Then fill the section titled exactly **EPIC Register** and fill the section titled exactly **User Stories** in `.planning/discovery/session-03.md` — edit in place; never append a new heading.
+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):
+
+| 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 `—`
+
+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: Business Objectives and KPIs
 

package/pp-core/workflows/discovery-sprint/sessions/04-ux-design.md

@@ -96,7 +96,7 @@ Read every frontend standard that passes these checks, also one the session's ow
 | Loading / empty / error states | | | |
 | Accessibility standard | | | |
 
-**Standard** is a frontend standard's `[vault: <rel path>]` citation, or `not in vault`. **Deviation** is `none` or one line. **Decision** is `—` or the `D-04-<n>` that records the deviation or the decision taken for an uncovered area.
+**Standard** is a frontend standard's `[vault: <rel path>]` citation, or `not in vault`. **Deviation** is `none`, or the `DEV-<nn>` of the row the deviation gets in `.planning/discovery/_deviations.md` (template and grammar: `${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-standards.md`; create the file on first need). **Decision** is `—` or the `D-04-<n>` that records the deviation or the decision taken for an uncovered area.
 
 **Refined Personas**
 
@@ -120,15 +120,24 @@ Read every frontend standard that passes these checks, also one the session's ow
 | Primary | | | | |
 | Secondary | | | | |
 
+**Content and Communication**
+
+| Aspect | Decision | Notes |
+|--------|----------|-------|
+| Tone of voice | | |
+| Notifications and alerts | | |
+| Tooltips, help text and inline guidance | | |
+| Languages | | |
+
 **Key Decisions**
 
-| # | Decision | Rationale | Owner | Date |
+| ID | Decision | Rationale | Owner | Date |
 |---|----------|-----------|-------|------|
 | | | | | |
 
 **Action Items**
 
-| # | Action | Owner | Due Date | Status |
+| ID | Action | Owner | Due Date | Status |
 |---|--------|-------|----------|--------|
 | | | | | |