@pareto4/pp-core 1.19.0 → 1.21.0

package/pp-core/workflows/discovery-sprint/sessions/13-wrap-up.md

@@ -19,11 +19,11 @@ Before facilitating any topics, execute the **Session 13: Cross-Reference Protoc
    - Which assumptions were validated and which were invalidated?
    - What issues were identified and resolved by the cross-reference analysis?
 
-2. **Project Definition Document (PDD) review**
-   *Why it matters: this is the client's last chance to catch a scoping or architecture error before build starts. Skip when: never — always required before go/no-go.*
-   - Walk through the PDD structure and key sections
-   - Are there sections requiring further refinement?
-   - Does the client agree with documented scope, architecture, and approach?
+2. **Project Charter review**
+   *Why it matters: the charter (`docs/discovery/PROJECT-CHARTER.md`, drafted in Step 0.5 from `templates/project-charter.md`) is the one document every stakeholder signs, so this is the client's last chance to catch a scoping or architecture error before build starts. Skip when: never — always required before go/no-go.*
+   - Walk through the drafted charter section by section; every statement traces to a session, decision or requirement ID
+   - Are there sections requiring further refinement? Correct the charter in place; a correction that changes a recorded fact is a Key Decisions row `D-13-<n>` and a back-amend of the original line (Flow 2 Step 6)
+   - Does the client agree with documented scope, architecture, approach, deviations and conditions?
 
 3. **Go / No-Go assessment**
    *Why it matters: this is the literal decision gate that authorizes spend on the build phase. Skip when: never — always required.*
@@ -31,6 +31,7 @@ Before facilitating any topics, execute the **Session 13: Cross-Reference Protoc
    - Is the technical architecture validated and feasible?
    - Are there blocking risks or unresolved dependencies?
    - What is the confidence level for the proposed timeline and budget? [needs-business-input]
+   - Record the assessment in the Notes Template below; the Closing Step copies it into the charter § 17 and its frontmatter as recorded — the charter never re-judges it
 
 4. **Open items and parking lot**
    *Why it matters: unresolved items surfaced here become explicit known-gaps in the handoff, not silent omissions. Skip when: never — always required, even an empty parking lot is worth stating explicitly.*
@@ -64,12 +65,16 @@ Before facilitating any topics, execute the **Session 13: Cross-Reference Protoc
 | Stakeholder alignment | | |
 | **Overall Recommendation** | | |
 
+This table is copied into the charter § 17 as recorded here — the charter never re-judges it. **Status** is `Green`, `Amber` or `Red`; **Overall Recommendation** is `Go`, `Go with conditions` or `No-Go` — `charter-check` compares these literals.
+
 **Open Items Register**
 
 | ID | Item | Source Session | Priority (H/M/L) | Must Resolve Before Build? | Owner | Target Date | Status |
 |----|------|---------------|-------------------|---------------------------|-------|-------------|--------|
 | OI-01 | | | | | | | |
 
+**Must Resolve Before Build?** starts with `Yes` or `No` (a reason may follow); **Status** starts with `Open`, `Closed`, `Resolved` or `Parked`. `charter-check` reads these literals: an item that must resolve before build and is not `Closed`/`Resolved` has to stand in the charter § 16 Conditions.
+
 **Cross-Reference Analysis Results**
 
 | Metric | Count | Notes |
@@ -115,6 +120,10 @@ Before facilitating any topics, execute the **Session 13: Cross-Reference Protoc
 
 ---
 
+**Closing Step — charter for sign-off.** Run it after Step 7 and before Step 8, every time Session 13 completes, including a redo. Read `${PP_TOOLS%/bin/pp-tools.cjs}/workflows/discovery-sprint/charter.md` § **Finish** and follow it: the Go / No-Go table and the Open Items Register are copied into `docs/discovery/PROJECT-CHARTER.md` as recorded, must-resolve items become § 16 conditions, the status becomes `For sign-off`, `pp_run query discovery.charter-check` exits 0, the DOCX and PDF are rendered next to the markdown, and all of it is committed.
+
+---
+
 ## Session 13: Cross-Reference Protocol
 
 **Run this protocol (Step 0) before facilitating Session 13 topics.**
@@ -134,7 +143,7 @@ Analyze all prior sessions in three groups. Use Explore agents if available, or
 | Technical | 5–8 (Architecture, Security, Identity, Integration) | Technology stack consistency, role/RBAC alignment, integration point definitions, API contracts |
 | Governance & Costs | 9–12 (QA, Infrastructure, Roadmap, Team) | Timeline feasibility, resource allocation, test strategy alignment, sprint capacity |
 
-For each group: read all session files AND `.planning/discovery/_context.md`. Cross-reference factual claims, role names, technology choices, integration points, and requirement IDs. Check for contradictions between sessions.
+For each group: read all session files — their Notes Template sections and the registers they cite. Cross-reference factual claims, role names, technology choices, integration points, and requirement IDs. Check for contradictions between sessions.
 
 #### 0b. Issue Severity Categories
 
@@ -147,9 +156,11 @@ For each group: read all session files AND `.planning/discovery/_context.md`. Cr
 
 #### 0c. Cross-Reference Checklist
 
-- [ ] **Roles & RBAC:** Same role names, count, and permissions across all sessions (especially S5 vs S7)
+- [ ] **Roles & RBAC:** Same role names, count, and permissions across all sessions (especially S5 vs S7); `discovery roles-check` exits 0 (every role a persona or step actor, every permission citing an existing entity and requirement, every screen row resolving)
 - [ ] **Technology stack:** Consistent tools/frameworks referenced (especially S5, S8, S10)
-- [ ] **Integration points:** Same systems, directions, and protocols across S5, S8, S10
+- [ ] **Integration points:** Same systems, directions, and protocols across S5, S8, S10; `discovery integrations-check` and `discovery migration-check` exit 0 (every step-matrix `IF-` resolving, every contract and error row naming a known interface, every migration source in the Systems Landscape)
+- [ ] **Deviations:** every Standards Applied `Deviation` that is not `none` is a `DEV-` row of `_deviations.md`; `discovery deviations-check` exits 0 (standard in the vault cache, approver in the Session 1 Approval Matrix, a decision on every approved or rejected row)
+- [ ] **Session outputs:** `discovery session-check --all` exits 0 (every Notes Template section of every completed session present once, with a data row, prose or `None identified in Discovery.`)
 - [ ] **Requirements traceability:** Every S3 requirement addressable in S5 architecture
 - [ ] **Requirements roll-up:** `discovery rollup --check` exits 0 (totals block matches table)
 - [ ] **Pre-fill/confidential gate:** `discovery input-check` exits 0 (no unconfirmed markers, no tracked confidential files)
@@ -193,7 +204,7 @@ Ask the user how to proceed (AskUserQuestion or text-mode numbered list):
 3. Review each finding one by one
 4. Skip cross-reference (not recommended)
 
-Apply fixes using Edit tool across affected session files. Update `.planning/discovery/_context.md` if key facts change.
+Apply fixes using Edit tool across affected session files and registers — the original line, per the back-amend rule (Flow 2 Step 6).
 
 #### 0f. Record Cross-Reference Results
 
@@ -202,4 +213,8 @@ Capture in `.planning/discovery/session-13.md` notes:
 - List of all fixes applied (file, what changed, why)
 - Any findings deferred or noted but not fixed
 
+#### 0.5. Draft the Project Charter
+
+Read `${PP_TOOLS%/bin/pp-tools.cjs}/workflows/discovery-sprint/charter.md` § **Draft** and follow it: the charter is written to `docs/discovery/PROJECT-CHARTER.md` from `templates/project-charter.md`, in the sprint language, every section from its source map, `status: Draft`, and `pp_run query discovery.charter-check` exits 0 before you go on. Topics 2 and 3 review and score that document, not a summary of the sessions.
+
 Then proceed to Step 5 (Facilitate Session 13 topics).

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

@@ -1,7 +1,7 @@
 <purpose>
 Facilitate the 13-session Pareto Discovery Sprint. Guide each session topic-by-topic,
 capture outputs into structured notes templates, and write all artifacts to
-.planning/discovery/ (session-01.md … session-13.md, _progress.md, _context.md).
+.planning/discovery/ (session-01.md … session-13.md, _progress.md and the registers).
 </purpose>
 
 <required_reading>
@@ -46,6 +46,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 - Else if `FIRST_TOKEN` is `gap` → Read `${PP_TOOLS%/bin/pp-tools.cjs}/workflows/discovery-sprint/gap-analysis.md` and follow it. Stop. The numeric token is a document accession number, not a session number — the 1–13 range check and `SESSION_INVALID` do not apply here (the subfile re-derives the accession from `$ARGUMENTS` in its Step 0).
 - Else if `FIRST_TOKEN` is `rebaseline` → Read `${PP_TOOLS%/bin/pp-tools.cjs}/workflows/discovery-sprint/rebaseline.md` and follow it. Stop. The numeric token is a document accession number, not a session number — the 1–13 range check and `SESSION_INVALID` do not apply here (the subfile re-derives the accession from `$ARGUMENTS` in its Step 0).
 - Else if `FIRST_TOKEN` is `prototype` → Read `${PP_TOOLS%/bin/pp-tools.cjs}/workflows/discovery-sprint/prototype.md` and follow it. Stop. It builds the clickable prototype from Sessions 1–4 and can be run at any moment, also after a No at the end of Session 4.
+- Else if `FIRST_TOKEN` is `charter` → Read `${PP_TOOLS%/bin/pp-tools.cjs}/workflows/discovery-sprint/charter.md` § Redraft and follow it. Stop. It records signatures on, or redrafts and re-exports, `docs/discovery/PROJECT-CHARTER.md`; the first draft is Session 13's Step 0.5.
 - Else if `--prefill` is in `$ARGUMENTS` → requires a session number: if `SESSION_ARG` is empty, say so politely and stop; else Read `${PP_TOOLS%/bin/pp-tools.cjs}/workflows/discovery-sprint/prefill.md` and follow it. Stop.
 - Else if `SESSION_INVALID` is non-empty → show a usage error: "Session `$SESSION_INVALID` is out
   of range — valid sessions are 1–13." Do not run any session or the progress view.
@@ -77,7 +78,6 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 **Artifact paths:**
 - Session files: `.planning/discovery/session-01.md` … `.planning/discovery/session-13.md`
 - Progress tracker: `.planning/discovery/_progress.md`
-- Context file: `.planning/discovery/_context.md`
 - Research track: `.planning/discovery/_research.md` (backlog), `.planning/discovery/_risks.md` (data-gathering), `.planning/discovery/_sparring.md` (positions)
 - Scope re-baseline matrix: `.planning/discovery/_rebaseline.md`
 - Prototype: `.planning/discovery/prototype/` (built by `/pp-discovery prototype`)
@@ -112,7 +112,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
      > "Confirm Session N — [Name] (pre-filled). Run `/pp-discovery N` to walk its `[TO CONFIRM]` markers."
    - Otherwise, find the first "Not Started" session whose dependencies are all "Completed":
      > "Next recommended session: Session N — [Name]. Run `/pp-discovery N` to start."
-   - If every session is "Completed", say the Discovery Sprint is complete and point to Session 13's wrap-up output.
+   - If every session is "Completed", say the Discovery Sprint is complete and report the Project Charter: read the frontmatter of `docs/discovery/PROJECT-CHARTER.md` and state its `version`, `status` and `go_no_go` (`/pp-discovery charter` records signatures; `/pp-discovery-to-build` needs `Signed` or `Signed with conditions`). If the file does not exist, say so and point to `/pp-discovery 13` — its Step 0.5 drafts it.
 
 ---
 
@@ -127,9 +127,8 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 1. Determine the session file path: `.planning/discovery/session-NN.md` (zero-padded, e.g. `session-03.md`).
 2. If the file does not exist, create it using the session template from the session content file.
 3. Read `.planning/discovery/_progress.md` (create if absent — use the **Bootstrap Templates** section near the end of this workflow for the literal schema).
-4. Read `.planning/discovery/_context.md` (create if absent — use the **Bootstrap Templates** section near the end of this workflow for the literal schema).
-5. Read `.planning/discovery/_risks.md` and `.planning/discovery/_sparring.md` when they exist — they are created on first need (see the research-track reference named in **Bootstrap Templates**). Surface as opening context every `DG-`/`SP-` item whose `Feeds:` names this session (D-40).
-6. If the session content file carries a **Precondition**, run it now. When it stops, stop the session here — do not mark it In Progress.
+4. Read `.planning/discovery/_risks.md` and `.planning/discovery/_sparring.md` when they exist — they are created on first need (see the research-track reference named in **Bootstrap Templates**). Surface as opening context every `DG-`/`SP-` item whose `Feeds:` names this session (D-40).
+5. If the session content file carries a **Precondition**, run it now. When it stops, stop the session here — do not mark it In Progress.
 
 ### Step 2: Check Dependencies
 
@@ -189,9 +188,9 @@ Ask: "Any positions taken that aren't decisions yet?" → append or update an `S
 
 ### Step 7: Complete the Session
 
-1. Update `.planning/discovery/session-NN.md` frontmatter: `status: "Completed"`, `completed_date: "[YYYY-MM-DD]"`, `completeness_score: [N]`. Compute `N = round(100 × topics_covered ÷ total_topics)` for this session — only use 100 when every topic was covered. If topics were skipped (see Edge Cases) **or parked** (Step 5.3), the score reflects the proportion actually completed — a session with parked items must read honestly below 100%. Topics whose captured answers still carry `[TO CONFIRM]` count as **not covered**, exactly like parked topics — a pre-filled session must read honestly below 100 until its markers are confirmed (D-18/D-19). A section carrying `⚠️ CONDITIONAL — <RS-nn|DG-nn>` counts as **covered** — the decision was made in the room and is knowingly contingent on outside work, the deliberate opposite of `[TO CONFIRM]` (D-47). Record the cited IDs in frontmatter as `conditional: [RS-03, DG-07]`, set the session's `Conditional` count in `_progress.md` and its `Conditional sections (open):` total (D-48).
+1. Update `.planning/discovery/session-NN.md` frontmatter: `status: "Completed"`, `completed_date: "[YYYY-MM-DD]"`, `completeness_score: [N]`. Compute `N = round(100 × topics_covered ÷ total_topics)` for this session — only use 100 when every topic was covered. A topic whose Notes Template section `pp_run query discovery.session-check <N>` (item 3) reports `empty_section` counts as **not covered**, however long it was discussed — the output is the measure, not the conversation (`references/discovery-session-output.md`). If topics were skipped (see Edge Cases) **or parked** (Step 5.3), the score reflects the proportion actually completed — a session with parked items must read honestly below 100%. Topics whose captured answers still carry `[TO CONFIRM]` count as **not covered**, exactly like parked topics — a pre-filled session must read honestly below 100 until its markers are confirmed (D-18/D-19). A section carrying `⚠️ CONDITIONAL — <RS-nn|DG-nn>` counts as **covered** — the decision was made in the room and is knowingly contingent on outside work, the deliberate opposite of `[TO CONFIRM]` (D-47). Record the cited IDs in frontmatter as `conditional: [RS-03, DG-07]`, set the session's `Conditional` count in `_progress.md` and its `Conditional sections (open):` total (D-48).
 2. Update `.planning/discovery/_progress.md`: set row to Completed with date and score.
-3. Update `.planning/discovery/_context.md`: populate the session's output section with concise summaries.
+3. Run `pp_run query discovery.session-check <N>`. Exit 0 → continue. Non-zero → a Notes Template section is missing, repeated, off its template columns or still empty: fill it from what the room said, or write `None identified in Discovery.` on one line under its title when the session found nothing — never leave a template row blank and never record the answer in a second file. Re-run until 0, then set the score as item 1 says. Read `${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-session-output.md` for the contract.
 4. If the session content file carries a **Closing Step**, run it now, before Step 8.
 5. If `_feedback.md` exists, run `pp_run query discovery.screen-check --require-processed`. Non-zero: process the `Open` rows as `prototype.md` Step 7 describes before the session counts as closed.
 6. If `session-NN.md` carries a `## Vault Context` section, run `pp_run query discovery.vault-check <N>`. Non-zero: cite each named document `[vault: <path>]` beside the answer it informed, or append `— not used: <reason>` to its record line; for `cross_cutting_missing`, add the named document's record line, read it against this session's decisions, and cite or mark it the same way. Then re-run.
@@ -223,7 +222,7 @@ Each session's Goal, "What We Cover" topics and Notes Template live in their own
 
 ## Context-Awareness Rules
 
-When facilitating sessions, reference prior session outputs from `.planning/discovery/_context.md`:
+When facilitating sessions, reference prior session outputs from the earlier session files' Notes Template sections and from the registers they point at (`_requirements.md`, `_entities.md`, `_processes.md`, `_roles.md`, `_integrations.md`, `_deviations.md`) — never from a summary written at session close; the session tables are the single source:
 
 | Current Session | Reference From |
 |----------------|----------------|
@@ -247,7 +246,7 @@ When facilitating sessions, reference prior session outputs from `.planning/disc
 ## Edge Cases
 
 - **Session file not found:** Create it from the session template content above.
-- **All sessions completed:** Congratulate the user and suggest reviewing `_context.md` for a full summary.
+- **All sessions completed:** Congratulate the user and point at the Project Charter Session 13 drafted and at `/pp-discovery-to-build`.
 - **User wants to skip a topic:** Allow it. Note the topic was skipped and continue.
 - **User provides very brief answers:** Ask at least one follow-up question before accepting.
 - **Session 3:** ALWAYS use the Process-First Protocol (Steps 5A–5G) — never use the generic topic loop.
@@ -258,7 +257,7 @@ When facilitating sessions, reference prior session outputs from `.planning/disc
 
 ## Bootstrap Templates
 
-`/pp-discovery` is self-sufficient — it does not depend on any other skill or command having run first. When `.planning/discovery/_progress.md` or `.planning/discovery/_context.md` is absent (first-ever session on this project — see Flow 2 Step 1), create it verbatim from its schema: the `_progress.md` schema is below, and the `_context.md` schema is one lazy Read away under `workflows/discovery-sprint/templates/`. Both paths are fixed under `.planning/discovery/` (T-04-03) — never write to a root-level directory, an absolute path, or a path containing `..`.
+`/pp-discovery` is self-sufficient — it does not depend on any other skill or command having run first. When `.planning/discovery/_progress.md` is absent (first-ever session on this project — see Flow 2 Step 1), create it verbatim from the schema below. The path is fixed under `.planning/discovery/` (T-04-03) — never write to a root-level directory, an absolute path, or a path containing `..`.
 
 **`.planning/discovery/_progress.md`** (Parked-aware schema — D-11):
 
@@ -313,16 +312,14 @@ When facilitating sessions, reference prior session outputs from `.planning/disc
 
 The Status column takes one of four values: Not Started / Pre-Filled / In Progress / Completed — "Pre-Filled" marks a session populated from source documents but not yet confirmed live. The `Parked` column tracks how many topics in that session were marked `PARKED — needs business/senior input` instead of being answered — increment it whenever a topic is parked, and add a matching row to the `Open Action Items` table (owner: `business/senior`). Decrement that session's `completeness_score` in Step 7 to reflect the parked topic as not-covered. Keep `Parked questions (open):` in the Summary block equal to the sum of the `Parked` column across all sessions, minus any parked items subsequently resolved. The `Conditional` column tracks how many sections in that session carry a `⚠️ CONDITIONAL — <RS-nn|DG-nn>` marker. Unlike a parked topic, a conditional section does **not** decrement that session's `completeness_score` — it counts as covered (D-47). Keep `Conditional sections (open):` equal to that column's sum across all sessions.
 
-**`.planning/discovery/_context.md`:** Read `${PP_TOOLS%/bin/pp-tools.cjs}/workflows/discovery-sprint/templates/context-template.md` lazily and create the file verbatim from the schema it carries. The path is fixed under `.planning/discovery/` (T-04-03) — never a root-level directory, never an absolute path, never a path containing `..`.
-
-**Research track (`_research.md` / `_risks.md` / `_sparring.md`):** these three registers are created on first need exactly like `_progress.md` and `_context.md` — no sub-command bootstraps them (D-31). Read `${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-research-track.md` lazily for their three schemas, the `⚠️ CONDITIONAL —` marker grammar and the `research-check` parser contract; never `@`-import it, as with `discovery-id-conventions.md` (D-30).
+**Research track (`_research.md` / `_risks.md` / `_sparring.md`):** these three registers are created on first need exactly like `_progress.md` — no sub-command bootstraps them (D-31). Read `${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-research-track.md` lazily for their three schemas, the `⚠️ CONDITIONAL —` marker grammar and the `research-check` parser contract; never `@`-import it, as with `discovery-id-conventions.md` (D-30).
 
 </process>
 
 <success_criteria>
 - All 13 sessions are facilitated as substantive guided steps with Goal, guiding questions, and notes templates, each held in its `sessions/` content file.
 - The Session 3 process-first protocol and Session 13 cross-reference protocol are present as text procedures in `sessions/03-to-be.md` and `sessions/13-wrap-up.md`.
-- All artifact writes resolve to `.planning/discovery/session-NN.md`, `.planning/discovery/_progress.md`, `.planning/discovery/_context.md`, `.planning/discovery/_research.md`, `.planning/discovery/_risks.md`, `.planning/discovery/_sparring.md`, the `.planning/discovery-input/` package family (incl. `00-README.md` and `confidential/.gitignore`), `.planning/discovery/gap-<accession>.md` gap reports, or the `.planning/discovery/prototype/` tree.
+- All artifact writes resolve to `.planning/discovery/session-NN.md`, `.planning/discovery/_progress.md`, `.planning/discovery/_research.md`, `.planning/discovery/_risks.md`, `.planning/discovery/_sparring.md`, the `.planning/discovery-input/` package family (incl. `00-README.md` and `confidential/.gitignore`), `.planning/discovery/gap-<accession>.md` gap reports, or the `.planning/discovery/prototype/` tree.
 - No writes target a root-level capital-D Discovery directory, an absolute path, or a `..` path.
 - Text-mode fallback is documented for all AskUserQuestion steps.
 </success_criteria>

package/pp-core/workflows/discovery-to-build/steps/architecture-deliverables.md

@@ -15,13 +15,16 @@
 
 ## What this step produces
 
-Two deliverables, both written under the client project's `docs/` tree —
+Three deliverables, all written under the client project's `docs/` tree —
 **never** under `.planning/`, which stays process-state only:
 
 1. `docs/architecture/architecture.md` — one arc42-lite document with four
    sections: Introduction & Goals, Context, Containers, Data Model.
 2. `docs/architecture/adr/NNNN-title.md` — one file per row of Session 5's
    Architecture Decision Records table.
+3. `docs/processes/MP-nn.md` — one file per main process of
+   `.planning/discovery/_processes.md`: its swimlane and its step matrix,
+   verbatim (Discovery Sprint improvement plan, Batch 2).
 
 ## Source of truth
 
@@ -31,12 +34,18 @@ captured elsewhere in the synthesis:
 
 - **Introduction & Goals** — `.planning/PROJECT.md`'s core problem statement
   (from Session 1) plus Session 5's stated architecture goals/constraints.
-- **Context (C4Context)** — Session 5's Integration Points Map plus Session 8
-  (external systems, direction, protocol) for `System_Ext`/`Rel` actors.
+- **Context (C4Context)** — `.planning/discovery/_integrations.md` § Interfaces
+  (one `System_Ext` per `IF-` row, `Rel` carrying `Direction` and `Protocol` —
+  `references/discovery-integrations.md`); an engagement without that file falls
+  back to Session 5's Integration Points Map plus Session 8's Integration Design
+  Register.
 - **Containers (C4Container)** — Session 5's Component Inventory and
   Technology Stack table for `Container`/`ContainerDb` nodes.
-- **Data Model (erDiagram)** — Session 5's Domain Model / Entity Register
-  table (D-16: entity, key attributes, relationships, owner module).
+- **Data Model (erDiagram)** — `.planning/discovery/_entities.md` (entities
+  with attributes, relationships with cardinality, lifecycles —
+  `references/discovery-data-model.md`); an engagement without that file
+  falls back to Session 5's Domain Model / Entity Register table (D-16).
+- **Processes** — `.planning/discovery/_processes.md` § Flows and § Steps.
 - **ADRs** — Session 5's Architecture Decision Records table
   (`ADR ID | Title | Context | Decision | Consequences | Status`).
 
@@ -47,15 +56,19 @@ Never invent facts that are not present in the session content. If a Session
 ## Path safety (extends T-04-03)
 
 The same discipline `discovery-sprint.md` already applies to
-`.planning/discovery/` writes applies here to `docs/architecture/` writes:
+`.planning/discovery/` writes applies here to `docs/architecture/` and
+`docs/processes/` writes:
 
-- All write targets MUST be relative paths under `docs/architecture/`
-  (`docs/architecture/architecture.md`, `docs/architecture/adr/NNNN-title.md`).
+- All write targets MUST be relative paths under `docs/architecture/` or
+  `docs/processes/` (`docs/architecture/architecture.md`,
+  `docs/architecture/adr/NNNN-title.md`, `docs/processes/MP-nn.md`).
 - Never write to an absolute path.
 - Never write to a path containing `..`.
-- The only read target for this step is `.planning/discovery/session-05.md`
+- The only read targets for this step are `.planning/discovery/session-05.md`,
+  `.planning/discovery/_entities.md`, `.planning/discovery/_processes.md` and
+  `.planning/discovery/_integrations.md`
   (plus the already-loaded synthesis context) — never read or write outside
-  `docs/architecture/` and `.planning/discovery/`.
+  `docs/architecture/`, `docs/processes/` and `.planning/discovery/`.
 
 ## Idempotent overwrite handling
 
@@ -96,12 +109,13 @@ that were not stated during Discovery.
 ### Section 2: Context
 
 One paragraph of prose describing the system's boundary and the actors that
-interact with it, followed by a Mermaid `C4Context` block built from Session
-5's Integration Points Map and Session 8's Integrations table. Map each
-external system in Session 8 to a `System_Ext` node, the product itself to a
-`System` node, and each user-facing actor from Session 5/Session 1 to a
-`Person` node. Connect them with `Rel` lines carrying the protocol from
-Session 8's table where known.
+interact with it, followed by a Mermaid `C4Context` block built from
+`.planning/discovery/_integrations.md` § Interfaces (falling back to Session 5's
+Integration Points Map and Session 8's Integration Design Register when the
+register does not exist). Map each `IF-` row to a `System_Ext` node, the product
+itself to a `System` node, and each user-facing actor from Session 5/Session 1 to
+a `Person` node. Connect them with `Rel` lines carrying the row's `Protocol`
+where known, pointing in its `Direction`.
 
 Example shape (fill every placeholder from actual captured facts — never
 leave a literal `[System Name]` placeholder in the generated output):
@@ -138,16 +152,33 @@ C4Container
 ### Section 4: Data Model
 
 One paragraph of prose summarizing the domain model, followed by a Mermaid
-`erDiagram` block built directly from Session 5's Domain Model / Entity
-Register table (D-16). Emit one entity per register row and one relationship
-line per captured relationship; use the register's stated cardinality where
-given, otherwise default to the most conservative reading (`||--o{`) and
-note the assumption in prose.
+`erDiagram` block built directly from `.planning/discovery/_entities.md`:
+one entity block per `## Entities` row, holding its `## Attributes` rows as
+`type name` lines (a `PK` comment on the identifier), and one relationship
+line per `## Relationships` row with the **cardinality copied verbatim**
+(unescape the table's `\|` to `|`). **There is no default cardinality.** A
+relationship the artifact does not state is not drawn; `entity-check` has
+already refused a malformed one, so every line here is one Discovery
+recorded.
+
+When `_entities.md` does not exist (an engagement that predates it), build the
+block from Session 5's Domain Model / Entity Register table (D-16) under the
+same rule: a relationship whose cardinality the register does not state is
+listed in prose as `[not captured in Discovery]`, never drawn with a guessed
+cardinality.
 
 Example shape (fill every placeholder from actual captured facts):
 
 ```mermaid
 erDiagram
+  ORDER {
+    guid id PK
+    string reference
+  }
+  LINE_ITEM {
+    guid id PK
+    int quantity
+  }
   ORDER ||--|{ LINE_ITEM : contains
   CUSTOMER ||--o{ ORDER : places
 ```
@@ -222,19 +253,38 @@ captured), skip `docs/architecture/adr/` entirely rather than generating
 empty placeholder files, and note the gap in `architecture.md`'s
 Introduction & Goals section.
 
+## Generating `docs/processes/MP-nn.md`
+
+One file per `## To-be` row of `.planning/discovery/_processes.md`, named by
+its ID (`docs/processes/MP-01.md`), holding in this order: a `# MP-nn — <Main
+process>` title; one line naming the as-is processes it replaces (`Replaces:
+PRC-02, PRC-03` or `Replaces: new`), the trigger, the end state and the
+primary actor from the To-be row; the swimlane `mermaid` block from § Flows,
+verbatim; the step matrix from § Steps, verbatim, with its `Exception` and
+`Requirements` columns. Nothing is summarised or re-drawn: the file is the
+artifact's rows, exported where the client can read them. Skip the whole
+section when `_processes.md` does not exist; a main process without a flow or
+a matrix has already failed `process-check` at the handoff gate.
+
+Idempotency: a `docs/processes/MP-nn.md` that already exists is overwritten
+only after the same confirmation the architecture document asks for above —
+the file is a rendering of the artifact, so the artifact is the thing to edit.
+
 ## Completing the step
 
-1. Create `docs/architecture/` and `docs/architecture/adr/` directories as
-   needed (they do not exist in a fresh client project).
+1. Create `docs/architecture/`, `docs/architecture/adr/` and
+   `docs/processes/` directories as needed (they do not exist in a fresh
+   client project).
 2. Write `docs/architecture/architecture.md` per the section instructions
    above, applying the idempotent replace-or-append rule.
 3. Write one `docs/architecture/adr/NNNN-title.md` per Session 5 ADR row,
-   skipping any that already exist (idempotent).
+   skipping any that already exist (idempotent), and one
+   `docs/processes/MP-nn.md` per main process.
 4. Commit the generated files. This step is the SOLE committer of
-   `docs/architecture/` — `discovery-to-build.md` Step 5h does not commit
-   these files itself, so this block inlines the canonical `pp_run`
-   resolver unconditionally, exactly as every other workflow file does.
-   The resolver is idempotent, so redefining `pp_run` when a caller has
+   `docs/architecture/` and `docs/processes/` — `discovery-to-build.md` Step
+   5h does not commit these files itself, so this block inlines the canonical
+   `pp_run` resolver unconditionally, exactly as every other workflow file
+   does. The resolver is idempotent, so redefining `pp_run` when a caller has
    already defined it is harmless:
 
 ```bash
@@ -243,7 +293,8 @@ _PP_SHIM_NAME="pp-tools.cjs"; _pp_root() { ( for _v in $(env | sed -n 's/^\(GIT_
 [ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 FILES="docs/architecture/architecture.md"
 ls docs/architecture/adr/*.md >/dev/null 2>&1 && FILES="$FILES docs/architecture/adr/*.md"
-pp_run commit "docs: generate architect-grade handoff (arc42-lite architecture + ADRs)" --files $FILES
+ls docs/processes/*.md >/dev/null 2>&1 && FILES="$FILES docs/processes/*.md"
+pp_run commit "docs: generate architect-grade handoff (arc42-lite architecture, ADRs, processes)" --files $FILES
 ```
 
 5. Return control to `discovery-to-build.md`'s Step 5h caller — this step

package/pp-core/workflows/discovery-to-build/steps/{screen-inventory-gate.md → handoff-gates.md}

@@ -3,11 +3,13 @@
 > **Lazily-loaded.** Read this file from `pp-core/workflows/discovery-to-build.md` at the start of
 > Step 2, before the completion check. It is not `@`-imported. Run the gates in order; a stop in any
 > of them ends the handoff. They are the only hard blocks in the workflow — every other check in
-> Step 2 is a confirmation prompt.
+> Step 2 is a confirmation prompt. Four gates: the screen-inventory contract, the element sweep,
+> the artifact gates (data model, processes, rules, stories, phase plan, roles, integrations,
+> migration, deviations) and the signed charter.
 
 **Screen-inventory contract gate (D-53)**
 
-This is the one gate in this workflow that hard-blocks; every other check in Step 2 is a
+This gate hard-blocks; every other check in Step 2 is a
 confirmation prompt, deliberately. A percentage-based visual gate over a curated list cannot
 detect an omission — a surface dropped from the list is dropped from the denominator too — and
 this handoff is the last moment such an omission is still free to fix.
@@ -62,9 +64,115 @@ receives screens with fields, columns and actions that no requirement or decisio
 
 The check ran in the first fence above.
 
-**If `SWEEP_STATUS` is 0:** The gates pass. Return to Step 2 of `discovery-to-build.md`.
+**If `SWEEP_STATUS` is 0:** Continue with the artifact gates below.
+
+**Artifact gates (data model, processes, rules, stories, phase plan, roles, integrations, migration, deviations)**
+
+The build's planner reads `_entities.md`, `_processes.md`, `_rules.md`, `_stories.md`, `_roles.md`,
+`_integrations.md` and `_migration.md` by requirement ID, Step 5f copies `_phases.md` into ROADMAP.md
+verbatim, and `pp-vault-review` reads `_deviations.md` for the deviations on file. A pending `—` cell,
+an uncited step, interface or migration row, an MVP requirement with no story or no phase, or a
+hard-to-reverse deviation nobody has approved at this point is a fact the build would have to invent,
+so the same checks that only report at Sessions 8, 11 and 13 hard-block here with their strict flags.
+
+```bash
+pp_run query discovery.entity-check --require-complete
+ENTITY_STATUS=$?
+echo "ENTITY_STATUS=$ENTITY_STATUS"
+pp_run query discovery.process-check --require-cited
+PROCESS_STATUS=$?
+echo "PROCESS_STATUS=$PROCESS_STATUS"
+pp_run query discovery.rules-check
+RULES_STATUS=$?
+echo "RULES_STATUS=$RULES_STATUS"
+pp_run query discovery.stories-check
+STORIES_STATUS=$?
+echo "STORIES_STATUS=$STORIES_STATUS"
+pp_run query discovery.phases-check
+PHASES_STATUS=$?
+echo "PHASES_STATUS=$PHASES_STATUS"
+pp_run query discovery.roles-check
+ROLES_STATUS=$?
+echo "ROLES_STATUS=$ROLES_STATUS"
+pp_run query discovery.integrations-check --require-cited
+INTEGRATIONS_STATUS=$?
+echo "INTEGRATIONS_STATUS=$INTEGRATIONS_STATUS"
+pp_run query discovery.migration-check --require-cited
+MIGRATION_STATUS=$?
+echo "MIGRATION_STATUS=$MIGRATION_STATUS"
+pp_run query discovery.deviations-check --require-approved
+DEVIATIONS_STATUS=$?
+echo "DEVIATIONS_STATUS=$DEVIATIONS_STATUS"
+pp_run query discovery.session-check --all
+SESSION_STATUS=$?
+echo "SESSION_STATUS=$SESSION_STATUS"
+```
+
+**If all ten are 0:** Continue with the charter gate below. An artifact that does not exist exits
+0 by itself (an engagement that predates it), so every pre-existing engagement is unaffected.
+
+**If any is non-zero:** Stop with no option to proceed. Report the fault list the check printed,
+verbatim — `incomplete_cell` and `attributes_missing` mean Session 5 or 6 did not finish the data
+model; `uncited_step` means Step 5D did not back-fill a step; `mvp_requirement_without_story` means
+Step 5E skipped a requirement; `mvp_requirement_unplanned` means Session 11's Closing Step left a
+requirement out of the Phase Plan; `uncited_interface`, `step_integration_unlinked` and
+`uncited_migration` mean Session 8 did not finish `_integrations.md` or `_migration.md`;
+`hard_deviation_unapproved` means a hard-to-reverse deviation still waits for its architect — get the
+signature and set the row `Approved` with its decision, or set it `Rejected` and rework;
+`empty_section` and `missing_section` mean a session closed without its Notes Template output — fill
+the named section in that session file, or write `None identified in Discovery.` under its title
+(`references/discovery-session-output.md`); anything else
+is a malformed artifact (vocabularies in `references/discovery-data-model.md`,
+`references/discovery-processes.md`, `references/discovery-build-consumption.md`,
+`references/discovery-access.md`, `references/discovery-integrations.md` and
+`references/discovery-standards.md`). Fix the artifact, re-run its check, then re-run
+`/pp-discovery-to-build`. Neither `--skip-validation` nor `--unsigned` covers these gates.
 
 **If `SWEEP_STATUS` is non-zero:** Stop with no option to proceed. Report the fault list the check
 printed, verbatim, and tell the user to finish the sweep with `/pp-discovery prototype` Step 8, then
 re-run `/pp-discovery-to-build`. `--skip-validation` does not cover this gate. Without a prototype
 the check exits 0 by itself.
+
+**Signed-charter gate**
+
+The Project Charter (`docs/discovery/PROJECT-CHARTER.md`) is what the sponsor signed. A build that
+starts on a `Draft`, a `For sign-off` or a `Rejected` charter builds something nobody agreed to, so
+the handoff requires `Signed` or `Signed with conditions`. Two checks, run separately so a malformed
+charter and an unsigned one are told apart: the structural check never yields to a flag; the signature
+requirement yields to `--unsigned`, which records the gap instead of waiting.
+
+```bash
+if [ -f docs/discovery/PROJECT-CHARTER.md ]; then
+  pp_run query discovery.charter-check
+  CHARTER_STRUCT=$?
+  pp_run query discovery.charter-check --require-signed >/dev/null 2>&1
+  CHARTER_SIGNED=$?
+  CHARTER_STATE=$(sed -n 's/^status: *//p' docs/discovery/PROJECT-CHARTER.md | head -1)
+else
+  CHARTER_STRUCT=absent
+  CHARTER_SIGNED=absent
+  CHARTER_STATE=none
+fi
+echo "CHARTER_STRUCT=$CHARTER_STRUCT"
+echo "CHARTER_SIGNED=$CHARTER_SIGNED"
+echo "CHARTER_STATE=$CHARTER_STATE"
+```
+
+**If `CHARTER_STRUCT` is 0 and `CHARTER_SIGNED` is 0:** The gates pass. Return to Step 2 of
+`discovery-to-build.md`.
+
+**If `CHARTER_STRUCT` is a non-zero number:** Stop with no option to proceed. Report the fault list the
+check printed, verbatim: the charter has structural faults (a section missing, an ID nothing minted, a
+Go / No-Go table that differs from Session 13's, a must-resolve item not listed as a condition — the
+vocabulary is `references/discovery-charter.md`). Neither `--skip-validation` nor `--unsigned` covers
+this arm: a malformed charter is not an unsigned one. Fix it with `/pp-discovery charter`, then re-run.
+
+**If `CHARTER_STRUCT` is 0 and `CHARTER_SIGNED` is non-zero, or both are `absent`:**
+
+- **Without `--unsigned`:** Stop with no option to proceed. Say which it is — `status: {CHARTER_STATE}`
+  or no charter at all — and that `/pp-discovery charter` records the signatures (`/pp-discovery 13`
+  drafts the charter when none exists). Re-run `/pp-discovery-to-build` once the status reads `Signed`
+  or `Signed with conditions`.
+- **With `--unsigned`:** Continue, and carry `CHARTER_STATE` forward: Step 5d adds the Key Decisions
+  row that records the build started on an unsigned charter, Step 5g lists it under Blockers/Concerns,
+  and Step 8 prints it. The flag records a gap; it does not make the charter signed.

package/pp-core/workflows/discovery-to-build/templates/discovery-references.md

@@ -15,13 +15,15 @@ Discovery outputs are the source of truth for business decisions and requirement
 
 | Topic | File | Use When |
 |-------|------|----------|
-| All decisions (accumulated) | `.planning/discovery/_context.md` | Understanding why a decision was made |
+| All decisions | the **Key Decisions** table of each `.planning/discovery/session-NN.md` (`D-<ss>-<n>`) | Understanding why a decision was made |
 | pp-core handoff synthesis | `.planning/discovery/_pp-handoff.md` | Complete structured summary of all sessions |
 | Business requirements | `.planning/discovery/session-03.md` | Detailed EPICs, user stories, acceptance criteria |
 | Architecture decisions | `.planning/discovery/session-05.md` | Tech stack rationale, ADRs, component design |
 | Security requirements | `.planning/discovery/session-06.md` | Compliance, encryption, audit requirements |
-| Role definitions | `.planning/discovery/session-07.md` | RBAC model, permissions, identity provider |
-| Integration specs | `.planning/discovery/session-08.md` | External system interfaces, protocols, data flows |
+| Role definitions | `.planning/discovery/_roles.md` | Roles, permissions per entity, screens per role (Session 7 holds the identity provider) |
+| Integration specs | `.planning/discovery/_integrations.md` | Interfaces, contracts, error handling (Session 8 holds the sync approach) |
+| Migration | `.planning/discovery/_migration.md` | Source systems, entities moved, cut-over, reconciliation |
+| Deviations from standards | `.planning/discovery/_deviations.md` | Every agreed departure from a vault standard, with approver and status |
 | QA strategy | `.planning/discovery/session-09.md` | Test types, coverage targets, quality gates |
 | Release plan | `.planning/discovery/session-11.md` | Sprint plan, milestones, build order |
 | Interactive prototype | `.planning/discovery/prototype/` | Visual reference for UI implementation |
@@ -30,7 +32,7 @@ Discovery outputs are the source of truth for business decisions and requirement
 
 - **During discuss phases:** Reference specific sessions when answering gray-area questions
 - **During research:** Check Discovery sessions before external research — many answers are already there
-- **During planning:** Use requirement IDs from Discovery (FR-xxx, US-xxx) in plan references
+- **During planning:** Use requirement IDs as Discovery minted them (`<PREFIX>-nn`, `N-nn`, `E-nn`, `US-nn`) in plan references
 - **During verification:** Trace completed work back to Discovery requirements
 ```
 
@@ -42,12 +44,13 @@ Discovery outputs are the source of truth for business decisions and requirement
 This project has a completed Discovery Sprint in `.planning/discovery/`. pp-core agents should:
 
 1. **Check Discovery before asking the user** — most business and architecture decisions are already documented
-2. **Reference `.planning/discovery/_context.md`** for accumulated cross-session decisions
+2. **Reference the sessions' Key Decisions tables** (`D-<ss>-<n>`) for cross-session decisions — the original line carries any amendment
 3. **Reference `.planning/discovery/_pp-handoff.md`** for the structured synthesis used to initialize pp-core
-4. **Use original requirement IDs** (FR-xxx, NFR-xxx, US-xxx, EPIC-xxx) from Discovery in plans and commits
-5. **Reference specific session files** when a phase involves topics covered in that session:
-   - Auth/roles → Session 7 (`.planning/discovery/session-07.md`)
-   - Integrations → Session 8 (`.planning/discovery/session-08.md`)
+4. **Cite IDs as Discovery minted them** — `<PREFIX>-nn`/`N-nn`/`T-nn` requirements from `.planning/discovery/_requirements.md`, `E-nn` EPICs and `US-nn` stories from Session 3 (`references/discovery-id-conventions.md`) — in plans and commits; never invent `FR-`/`NFR-`/`EPIC-` IDs
+5. **Read the registers before the session files** — `_requirements.md` (with acceptance criteria) and `_screens.md` are the canonical artifacts; a session file is the facilitation record behind them. Open a session file only when a phase involves a topic no register covers yet:
+   - Auth/roles → `.planning/discovery/_roles.md` (identity provider: Session 7, `.planning/discovery/session-07.md`)
+   - Integrations → `.planning/discovery/_integrations.md`; migration → `.planning/discovery/_migration.md` (sync approach: Session 8, `.planning/discovery/session-08.md`)
+   - Deviations from the client's standards → `.planning/discovery/_deviations.md`
    - UI/UX → Session 4 (`.planning/discovery/session-04.md`) + `.planning/discovery/prototype/`
    - Security → Session 6 (`.planning/discovery/session-06.md`)
    - Testing → Session 9 (`.planning/discovery/session-09.md`)