@pareto4/pp-core 1.18.0 → 1.20.0

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,27 +253,48 @@ 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
 
 _PP_SHIM_NAME="pp-tools.cjs"; _pp_root() { ( for _v in $(env | sed -n 's/^\(GIT_[A-Za-z0-9_]*\)=.*/\1/p'); do unset "$_v"; done; _c=$(git rev-parse --git-common-dir 2>/dev/null); if [ "${_c##*/}" = .git ] && cd "$_c/.." 2>/dev/null; then pwd -P; else git rev-parse --show-toplevel 2>/dev/null || pwd; fi ); }; pp_run() { case "$PP_TOOLS" in *.cjs) node "$PP_TOOLS" "$@";; *) "$PP_TOOLS" "$@";; esac; }; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(_pp_root)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then :; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+[ -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`)

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

@@ -8,7 +8,7 @@
 # Discovery Sprint Synthesis — pp-core Handoff
 
 > Auto-generated from {completed_count}/13 completed Discovery Sprint sessions.
-> Source: .planning/discovery/_context.md + individual session files
+> Source: the session files and the registers under .planning/discovery/
 > Generated: {date}
 
 ---
@@ -50,32 +50,31 @@ application — what it does, who it's for, why it matters}
 {From Session 3: EPICs and user stories, structured for requirements generation. When
 `_requirements.md` exists it is the requirement source — it holds what prototype feedback and the
 element sweep added: carry every `MVP` and `Later` row, and list each `Dropped` row under Out of
-Scope with its decision}
+Scope with its decision. IDs are the ones discovery minted — `references/discovery-id-conventions.md`:
+`<PREFIX>-nn`/`N-nn`/`T-nn` requirements, `E-nn` EPICs, `US-nn` stories — never a `FR-`/`NFR-`/`EPIC-`
+ID of this document's own}
 
 ### EPIC Registry
 | ID | Title | Priority | Phase | Stories |
 |----|-------|----------|-------|---------|
-| {epic-id} | {title} | {must/should/could} | {phase} | {count} |
+| {E-nn} | {title} | {must/should/could} | {phase} | {count} |
 
 ### Requirements by EPIC
 
-#### {EPIC-001}: {Title}
+#### {E-nn}: {Title}
 {Brief EPIC description}
 
+**Requirements:** {the `_requirements.md` IDs this EPIC groups — `<PREFIX>-nn`, `N-nn`, `T-nn`}
+
 **User Stories:**
 | ID | Story | Priority | Acceptance Criteria Summary |
 |----|-------|----------|---------------------------|
-| {us-id} | As a {role}, I want {goal} so that {benefit} | {priority} | {brief AC} |
+| {US-nn} | As a {role}, I want {goal} so that {benefit} | {priority} | {brief AC} |
 
 ### Non-Functional Requirements
 | ID | Category | Requirement | Target |
 |----|----------|-------------|--------|
-| {nfr-id} | {Performance/Security/Usability/Availability} | {requirement} | {target} |
-
-### Business Rules
-| ID | Rule | Applies To |
-|----|------|------------|
-| {br-id} | {rule} | {module/scope} |
+| {N-nn} | {Performance/Security/Usability/Availability} | {requirement} | {target} |
 
 ---
 
@@ -138,14 +137,14 @@ row for row — never summarise them. Without a screen inventory or prototype, w
 {From Session 6: data classification, compliance, encryption, auth, audit, SLA}
 
 ## User Roles & Identity
-{From Session 7: RBAC roles + permissions, identity provider}
+{From `.planning/discovery/_roles.md` (§ Roles, § Permissions, § Screens) when it exists, else Session 7's RBAC Matrix; identity provider from Session 7 § IdP Integration Design}
 
 | Role | Description | Key Permissions |
 |------|-------------|-----------------|
 | {role} | {description} | {permissions} |
 
 ## Integrations
-{From Session 8: external systems, direction, protocol, data, phase}
+{From `.planning/discovery/_integrations.md` § Interfaces when it exists (one row per `IF-nn`: system, direction, protocol, format), else Session 8's Integration Design Register; phase from `_phases.md`. Migration from `.planning/discovery/_migration.md` when it exists}
 
 | System | Direction | Protocol | Data | Phase |
 |--------|-----------|----------|------|-------|
@@ -207,20 +206,22 @@ list each parked question verbatim, honestly, as a known gap — never silently
 
 | Topic | Primary Source | Secondary Sources |
 |-------|---------------|-------------------|
-| Business context & vision | `.planning/discovery/session-01.md` | `.planning/discovery/_context.md` §1 |
-| Current state & pain points | `.planning/discovery/session-02.md` | `.planning/discovery/_context.md` §2 |
-| Requirements & user stories | `.planning/discovery/session-03.md` | `.planning/discovery/_context.md` §3 |
-| UX design principles | `.planning/discovery/session-04.md` | `.planning/discovery/_context.md` §4 |
+| Business context & vision | `.planning/discovery/session-01.md` | `.planning/discovery/_requirements.md` § Prefix Registry |
+| Current state & pain points | `.planning/discovery/session-02.md` | `.planning/discovery/_processes.md`, `_entities.md`, `_glossary.md` |
+| Requirements & user stories | `.planning/discovery/session-03.md` | `.planning/discovery/_requirements.md`, `_stories.md`, `_rules.md` |
+| UX design principles | `.planning/discovery/session-04.md` | `.planning/discovery/_screens.md` |
 | Requirement register | `.planning/discovery/_requirements.md` | `.planning/discovery/session-03.md` |
 | Screens | `.planning/discovery/_screens.md` | `.planning/discovery/session-04.md` |
 | Prototype | `.planning/discovery/prototype/` | `.planning/discovery/_feedback.md`, `.planning/discovery/_sweep.md` |
-| Architecture & tech stack | `.planning/discovery/session-05.md` | `.planning/discovery/_context.md` §5 |
-| Security & compliance | `.planning/discovery/session-06.md` | `.planning/discovery/_context.md` §6 |
-| Roles & identity | `.planning/discovery/session-07.md` | `.planning/discovery/_context.md` §7 |
-| Integrations | `.planning/discovery/session-08.md` | `.planning/discovery/_context.md` §8 |
-| QA & testing | `.planning/discovery/session-09.md` | `.planning/discovery/_context.md` §9 |
-| Infrastructure & deployment | `.planning/discovery/session-10.md` | `.planning/discovery/_context.md` §10 |
-| Roadmap & release plan | `.planning/discovery/session-11.md` | `.planning/discovery/_context.md` §11 |
-| Team & delivery model | `.planning/discovery/session-12.md` | `.planning/discovery/_context.md` §12 |
-| Wrap-up & go/no-go | `.planning/discovery/session-13.md` | `.planning/discovery/_context.md` §13 |
+| Architecture & tech stack | `.planning/discovery/session-05.md` | `.planning/discovery/_entities.md`, `_integrations.md`, `_deviations.md` |
+| Security & compliance | `.planning/discovery/session-06.md` | `.planning/discovery/_entities.md` (classification, retention), `_deviations.md` |
+| Roles & identity | `.planning/discovery/_roles.md` | `.planning/discovery/session-07.md` |
+| Integrations | `.planning/discovery/_integrations.md` | `.planning/discovery/session-08.md` |
+| Migration | `.planning/discovery/_migration.md` | `.planning/discovery/session-02.md`, `session-08.md` |
+| Deviations from standards | `.planning/discovery/_deviations.md` | the sessions' **Standards Applied** tables |
+| QA & testing | `.planning/discovery/session-09.md` | the **Standards Applied** table |
+| Infrastructure & deployment | `.planning/discovery/session-10.md` | the **Standards Applied** table |
+| Roadmap & release plan | `.planning/discovery/session-11.md` | `.planning/discovery/_phases.md` |
+| Team & delivery model | `.planning/discovery/session-12.md` | `.planning/discovery/session-01.md` **Sprint Logistics** |
+| Wrap-up & go/no-go | `.planning/discovery/session-13.md` | `docs/discovery/PROJECT-CHARTER.md` |
 ```