@pareto4/pp-core 1.18.0 → 1.20.0

package/pp-core/workflows/discovery-sprint/sessions/10-infrastructure.md

@@ -5,38 +5,40 @@
 
 ### Session 10: Infrastructure & Deployment Readiness
 
-**Goal:** Define the cloud or hosting strategy, plan the deployment approach, establish monitoring and alerting, determine backup and disaster recovery procedures, and assess go-live readiness criteria.
+**Goal:** Confirm the hosting, deployment, monitoring and recovery approach against the client's platform standards, record the deviations, and assess go-live readiness criteria.
+
+**Standards first.** Where a document this session's `## Vault Context` record names already fixes the hosting platform, the pipeline, infrastructure as code, naming, monitoring, backup or recovery, do not ask the open question: present the vault's answer — "the vault fixes X `[vault: <path>]` — does this product deviate, and why?" — and record the standard in the **Standards Applied** row for that area. A deviation is one `DEV-<nn>` row of `.planning/discovery/_deviations.md` (template and grammar: `${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-standards.md`; create the file on first need) plus a Key Decisions row `D-10-<n>`, both cited in the Standards Applied row; never recommend an alternative the standards rule out. An area no standard covers reads `not in vault` and keeps its question open. With no vault bound, every question below stays open-ended.
 
 **What We Cover:**
 
 1. **Cloud / hosting strategy**
-   *Why it matters: hosting choice constrains every deployment, monitoring, and DR decision below. Skip when: the platform standard (GCP/pareto-platform-gcp) applies with no client override.*
-   - What cloud provider will be used (GCP / `pareto-platform-gcp` is the Pareto platform standard; or AWS, Azure, on-premises, hybrid)?
+   *Why it matters: hosting choice constrains every deployment, monitoring, and DR decision below. Skip when: Session 1 recorded a mandated platform and the client has no override.*
+   - What cloud provider will be used? Start from the platform Session 1 recorded; when it is open, choose between cloud providers, on-premises and hybrid.
    - What is the account and subscription structure?
    - What regions and availability zones are required?
    - Are there data sovereignty or residency requirements that constrain hosting?
    - What is the cost model and budget for infrastructure? [needs-business-input]
 
 2. **Deployment strategy**
-   *Why it matters: deployment model determines rollback risk and go-live readiness criteria (Session 13). Skip when: the platform CI/CD pipeline already fixes this by default.*
-   - What deployment model will be used (blue-green, canary, rolling, immutable)?
-   - How will the CI/CD pipeline be structured?
-   - What tools will be used for CI/CD (GitLab CI is the Pareto platform pipeline; or GitHub Actions, Azure DevOps, Jenkins)?
-   - How will infrastructure be managed (IaC with Terraform, Pulumi, CloudFormation)?
-   - What is the approach to containerization (GKE or Cloud Run via pareto-platform-gcp; Docker/Kubernetes on-prem; or other cloud options)?
+   *Why it matters: deployment model determines rollback risk and go-live readiness criteria (Session 13). Skip when: the mandated platform's CI/CD pipeline already fixes this by default.*
+   - Deployment model: the vault's release rules fix stages and gates when bound — does this product deviate? Otherwise: blue-green, canary, rolling, immutable?
+   - Pipeline structure and tool: the vault's pipeline standard fixes them when bound — does this product deviate? Otherwise: GitHub Actions, GitLab CI, Azure DevOps, Jenkins? Take the platform's pipeline when Session 1 recorded one.
+   - Infrastructure as code: the vault's IaC standard fixes it when bound — does this product deviate? Otherwise: Terraform, Pulumi, CloudFormation?
+   - Resource naming: the vault's naming convention fixes it when bound — record the standard; a name outside it is a deviation.
+   - What is the approach to containerization (the platform's managed container or Kubernetes service, Kubernetes on-premises, or none)? The vault's container rules apply when bound.
 
 3. **Monitoring, logging, and alerting**
-   *Why it matters: alerting design determines who gets paged and how incidents are caught pre-go-live. Skip when: a platform-standard observability stack already covers requirements.*
-   - What monitoring platform will be used (Google Cloud Monitoring / Cloud Logging via pareto-platform-gcp; or Datadog, New Relic, CloudWatch)?
+   *Why it matters: alerting design determines who gets paged and how incidents are caught pre-go-live. Skip when: the mandated platform's observability stack already covers requirements.*
+   - Monitoring platform: the vault's default stack fixes observability when bound — does this product deviate? Otherwise: the platform's native monitoring and logging, or Datadog, New Relic, Grafana?
    - What metrics will be tracked (latency, error rate, throughput, saturation)?
    - What is the alerting strategy (thresholds, escalation chains, on-call rotation)?
    - How will application logs be aggregated and queried?
 
 4. **Backup and disaster recovery**
    *Why it matters: DR strategy directly answers Session 6's RTO/RPO targets with a concrete implementation. Skip when: non-critical internal tool with no formal DR requirement.*
-   - What is the backup strategy (frequency, retention, storage location)?
+   - Backup strategy: the vault's governance and compliance rules fix frequency, retention and location when bound — does this product deviate? Otherwise: which?
    - How will backups be tested and validated?
-   - What is the DR strategy (active-passive, active-active, pilot light)?
+   - DR strategy: the vault fixes the tier per criticality when bound — does this product deviate? Otherwise: active-passive, active-active, pilot light?
    - How often will DR drills be conducted?
 
 5. **Go-live readiness criteria**
@@ -48,7 +50,22 @@
 
 **Notes Template:**
 
-> **Platform standard (D-08):** The Pareto deployment platform is GCP / `pareto-platform-gcp` with GitLab CI as the CI/CD pipeline and Google Cloud Monitoring / Cloud Logging for observability. Fill the tables below against this baseline unless the client has an overriding constraint.
+> **Platform:** fill the tables below against the platform Session 1 recorded (its `D-01-<n>` platform decision, citing the vault's platform standard when there is one): its cloud provider, CI/CD pipeline and observability stack. A choice that departs from it is a Key Decisions row `D-10-<n>`. When Session 1 recorded the platform as open, the choices are made here.
+
+**Standards Applied**
+
+| Area | Standard | Deviation | Decision |
+|------|----------|-----------|----------|
+| Hosting platform and landing zone | | | |
+| Environments and promotion | | | |
+| CI/CD pipeline | | | |
+| Infrastructure as code | | | |
+| Resource naming | | | |
+| Monitoring and alerting | | | |
+| Backup and disaster recovery | | | |
+| Sizing and cost | | | |
+
+**Standard** is the governing document's `[vault: <rel path>]` citation, or `not in vault`. **Deviation** is `none` or the `DEV-<nn>` of the `_deviations.md` row. **Decision** is `—` or the `D-10-<n>` that records the deviation or the decision taken for an uncovered area (`references/discovery-standards.md`).
 
 **Infrastructure Architecture**
 
@@ -62,6 +79,8 @@
 
 **Deployment Pipeline Design**
 
+> **Environments:** the deploy stages name the environments Session 9's Test Environment Plan recorded — the bound vault's names when one is bound (its naming standard, cited `[vault: <path>]`), one `Deploy to <env>` row per environment in promotion order. The preset rows stand only when no vault is bound.
+
 | Stage | Trigger | Actions | Quality Gate | Environment | Duration |
 |-------|---------|---------|-------------|-------------|----------|
 | Build | | | | | |
@@ -103,12 +122,12 @@
 
 **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/11-roadmap.md

@@ -14,7 +14,7 @@
    - What are the major phases of the project (Discovery, Build, UAT, Go-Live, Hypercare)?
    - What is the overall timeline from build start to production go-live?
    - Are there hard deadlines driven by business events, regulatory dates, or contracts? [needs-business-input]
-   - What is the sprint cadence (1-week, 2-week, 3-week)?
+   - What is the iteration model: calendar sprints (1, 2 or 3 weeks), or one iteration = one pp-core phase (discuss, plan, execute, verify), sized by scope rather than by the calendar? Record the choice as `D-11-<n>`; Session 12's cadence follows it.
 
 2. **MVP scope confirmation**
    *Why it matters: re-validates Session 3's MVP boundary before locking the build order below. Skip when: no time has passed since Session 3 and nothing has changed.*
@@ -24,11 +24,12 @@
    - What is the minimum viable product that demonstrates value to end-users?
 
 3. **Build order and dependencies**
-   *Why it matters: this ordering becomes the literal sprint-by-sprint plan the delivery team executes. Skip when: only a single EPIC exists with no sequencing decision to make.*
+   *Why it matters: this ordering becomes the literal iteration-by-iteration plan the delivery team executes. Skip when: only a single EPIC exists with no sequencing decision to make.*
    - In what order should EPICs be built?
    - What are the technical dependencies between EPICs?
    - Are there infrastructure or integration prerequisites that must be ready first?
    - What is the critical path?
+   - Which requirement IDs does each phase realise, and what must be observably true when it is done? The answers are the **Phase Plan** (`.planning/discovery/_phases.md`, Closing Step) — the literal source of ROADMAP.md; every MVP requirement belongs to exactly one phase.
 
 4. **Milestones and release plan**
    *Why it matters: milestone criteria are what stakeholder demos and Session 13's transition plan are scheduled against. Skip when: a single go-live milestone applies with no phased rollout.*
@@ -38,6 +39,7 @@
 
 5. **Risk register and mitigation**
    *Why it matters: risks captured here are what Session 13's go/no-go recommendation weighs most heavily. Skip when: never — always capture at least the top known risks.*
+   - Which risks from Session 1's **Constraints and Risks Register** are still open? They keep their `R-` IDs here.
    - What are the top project risks (technical, resourcing, scope, external)?
    - What is the likelihood and impact of each risk?
    - What mitigation strategies will be applied?
@@ -50,7 +52,7 @@
 | Phase | Start Date | End Date | Duration | Key Activities | Dependencies |
 |-------|-----------|----------|----------|---------------|--------------|
 | Discovery | | | | | |
-| Sprint 0 / Setup | | | | | |
+| Setup (Sprint 0 or first phase) | | | | | |
 | Build -- MVP | | | | | |
 | UAT | | | | | |
 | Go-Live | | | | | |
@@ -58,10 +60,16 @@
 
 **EPIC Build Order**
 
-| Order | EPIC ID | EPIC Name | Sprint(s) | Dependencies | Critical Path? | Notes |
-|-------|---------|-----------|-----------|--------------|---------------|-------|
+| Order | EPIC ID | EPIC Name | Iteration(s) | Dependencies | Critical Path? | Notes |
+|-------|---------|-----------|--------------|--------------|---------------|-------|
 | 1 | | | | | | |
 
+**Iteration(s)** names sprints (`S1–S2`) or pp-core phases (`Phase 3`), following the iteration model chosen in topic 1.
+
+**Phase Plan** (populated via the Closing Step)
+
+One row per pp-core phase in `.planning/discovery/_phases.md` § Phases — `Phase | Goal | EPICs | Requirement IDs | Success criteria | Depends on`. Record here only what the table cannot hold (why a requirement moved phase, what was debated).
+
 **Milestone Plan**
 
 | Milestone | Target Date | Included EPICs / Features | Entry Criteria | Exit Criteria | Stakeholder Demo? |
@@ -74,17 +82,33 @@
 **Risk Register**
 
 | ID | Risk Description | Category | Likelihood (H/M/L) | Impact (H/M/L) | Risk Score | Mitigation | Owner | Status |
-|----|-----------------|----------|--------------------|-----------------|-----------|-----------:|-------|--------|
+|----|-----------------|----------|--------------------|-----------------|-----------|------------|-------|--------|
 | R-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 |
 |---|--------|-------|----------|--------|
 | | | | | |
+
+---
+
+## Session 11: Phase Plan
+
+**Closing Step — Phase Plan.** Run it after Step 7 and before Step 8, every time Session 11 completes, including a redo. The EPIC Build Order says in what order; the Phase Plan says what each phase delivers, by requirement ID, so `/pp-discovery-to-build` copies it into ROADMAP.md verbatim and every build phase can read its discovery rows (`references/discovery-build-consumption.md`).
+
+1. Create `.planning/discovery/_phases.md` from the bootstrap template in `${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-build-consumption.md` § `_phases.md` when it does not exist.
+2. Write one row per pp-core phase, in build order, following the iteration model from topic 1 (one iteration = one phase when that was chosen; otherwise one phase per EPIC Build Order row, several sprints to a phase being fine). pp-core phases count from 1: a "Phase 0", "Sprint 0" or "Setup" row of this session becomes Phase 1 and every later row shifts by one — record the mapping (`Session 11 phase 0 → pp-core Phase 1`) under **Phase Plan** in the Notes Template so the two numberings never meet unexplained:
+   - **Goal** — one sentence, the phase's deliverable;
+   - **EPICs** — the `E-nn` rows the phase realises, or `—`;
+   - **Requirement IDs** — every `_requirements.md` ID the phase realises: each EPIC's requirements from Session 3, the `N-`/`T-` rows that belong with them; an `MVP` requirement goes in exactly one phase, a `Later` one in none unless the plan reaches it, a `Dropped` one never. A requirement the build order splits across phases ("basic list" now, "filters" later) belongs to the phase where its acceptance criteria are fully met — the earlier phase names the partial work in its Goal, not in this column. A cross-cutting process or validation requirement that every phase exercises belongs to the phase that establishes it. A setup or infrastructure phase that realises no requirement writes `—`;
+   - **Success criteria** — two to five observable statements separated by ` · `, written from the user's seat ("A clerk closes a task and it leaves the list");
+   - **Depends on** — the earlier phase numbers whose output this phase needs, or `—`.
+3. Run `pp_run query discovery.phases-check` — exit 0, or fix the rows it names: `mvp_requirement_unplanned` is an MVP requirement no phase owns, `requirement_in_multiple_phases` a requirement two phases both claim.
+4. Smoke the join: `pp_run query discovery.for-phase 1 --markdown` renders the rows Phase 1 will read. An empty section is a fact to settle now (no step cites those IDs, no screen covers them), not a rendering fault.

package/pp-core/workflows/discovery-sprint/sessions/12-delivery-model.md

@@ -5,34 +5,34 @@
 
 ### Session 12: Team & Delivery Model Definition
 
-**Goal:** Define the team structure and roles, establish governance and decision-making processes, agree on agile ceremonies, and plan the support model for post-go-live.
+**Goal:** Define the team structure and roles, establish governance and decision-making processes, agree on the working rhythm, and plan the support model for post-go-live. The model fits the team shape Session 1 recorded, from a full delivery team to one person working with an AI assistant.
 
 **What We Cover:**
 
 1. **Team structure and roles**
    *Why it matters: role allocation is what the Session 11 build-order plan assumes has capacity to execute. Skip when: the team is already fully staffed and roles are fixed by contract.*
-   - What roles are needed for the build phase (PO, Scrum Master, developers, QA, UX, architect)?
-   - How many people are needed for each role?
+   - What roles are needed for the build phase (product owner, delivery lead, architect, developers, QA, UX)?
+   - How many people are needed for each role? In a small team one person holds several roles: list each role, with the same name against it. When an AI assistant does part of the work, give it its own row, with the person who reviews its output.
    - Which roles are filled by the client and which by the delivery partner? [needs-business-input]
    - Are there part-time or shared resources? What is their allocation?
 
 2. **Governance and decision-making**
    *Why it matters: governance structure determines how scope changes get approved mid-build, preventing later rework. Skip when: an existing PMO governance model already applies unchanged.*
-   - What is the governance structure (steering committee, project board)?
+   - What is the governance structure (steering committee, project board, or a single sponsor)? Start from Session 1's **Approval Matrix**.
    - How often does the governance body meet?
    - What decisions require steering committee approval vs. team-level authority?
    - What is the escalation path for blockers or scope changes?
 
-3. **Agile ceremonies and cadence**
-   *Why it matters: cadence must match the sprint length assumed in Session 11's timeline. Skip when: the team already has an established ceremony rhythm from prior engagements.*
-   - What agile framework will be followed (Scrum, Kanban, SAFe, hybrid)?
-   - What is the sprint cadence and duration?
-   - What ceremonies are planned (standup, sprint planning, review, retrospective, backlog refinement)?
+3. **Working rhythm and cadence**
+   *Why it matters: the rhythm must match the iteration model Session 11 chose. Skip when: the team already has an established rhythm from prior engagements.*
+   - What way of working will be followed (Scrum, Kanban, pp-core phases, hybrid)?
+   - What is the iteration cadence: the sprint length, or the pp-core phase rhythm Session 11 chose?
+   - Which meetings are held? For a pp-core phase rhythm, planning is `/pp-discuss-phase` plus `/pp-plan-phase` and review is `/pp-verify-work` with the client. A one-person team drops the meetings it has no one to hold; record each one dropped as `D-12-<n>`.
    - What tools will be used for backlog management (Jira, Azure DevOps, Linear)?
 
 4. **Communication and reporting**
    *Why it matters: reporting cadence sets stakeholder expectations for visibility into progress. Skip when: an existing status-reporting process already covers this project.*
-   - How will progress be communicated to stakeholders (sprint review, status report, dashboard)?
+   - How will progress be communicated to stakeholders (iteration review, status report, dashboard)?
    - What is the reporting cadence (weekly, bi-weekly)?
    - What metrics will be tracked (velocity, burndown, defect rate, cycle time)?
 
@@ -50,12 +50,13 @@
 | Role | Name / TBD | Allocation (%) | Responsible Party (Client / Partner) | Start Date | Notes |
 |------|-----------|----------------|--------------------------------------|-----------|-------|
 | Product Owner | | | | | |
-| Scrum Master | | | | | |
+| Delivery Lead (Scrum Master, or none) | | | | | |
 | Solution Architect | | | | | |
 | Frontend Developer | | | | | |
 | Backend Developer | | | | | |
 | QA Engineer | | | | | |
 | UX Designer | | | | | |
+| AI assistant (reviewed by) | | | | | |
 
 **Governance Structure**
 
@@ -69,11 +70,13 @@
 
 | Ceremony | Cadence | Duration | Participants | Facilitator | Tool |
 |----------|---------|----------|--------------|-------------|------|
-| Daily standup | Daily | | | | |
-| Sprint planning | Per sprint | | | | |
-| Sprint review | Per sprint | | | | |
-| Retrospective | Per sprint | | | | |
-| Backlog refinement | Weekly | | | | |
+| Daily sync | | | | | |
+| Iteration planning | Per iteration | | | | |
+| Iteration review / demo | Per iteration | | | | |
+| Retrospective | Per iteration | | | | |
+| Backlog refinement | | | | | |
+
+An iteration is a sprint or a pp-core phase, as Session 11 chose. Write `—` in **Cadence** for a meeting the team does not hold.
 
 **Support Model**
 
@@ -85,12 +88,12 @@
 
 **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/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,11 +65,15 @@ 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-1 | | | | | | | |
+| 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**
 
@@ -103,18 +108,22 @@ Before facilitating any topics, execute the **Session 13: Cross-Reference Protoc
 
 **Key Decisions**
 
-| # | Decision | Rationale | Owner | Date |
+| ID | Decision | Rationale | Owner | Date |
 |---|----------|-----------|-------|------|
 | | | | | |
 
 **Action Items**
 
-| # | Action | Owner | Due Date | Status |
+| ID | Action | Owner | Due Date | Status |
 |---|--------|-------|----------|--------|
 | | | | | |
 
 ---
 
+**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)
@@ -162,6 +173,8 @@ For each group: read all session files AND `.planning/discovery/_context.md`. Cr
 - [ ] **Test strategy:** S9 covers all S3 requirements and S5 components
 - [ ] **Timeline and capacity:** S11 roadmap feasible given S12 team and S9 test needs
 - [ ] **Action items:** No duplicates or contradictions in `_progress.md`
+- [ ] **Back-amends:** every decision that changes an earlier record has `→ amended by D-<ss>-<n>` at the original line (Flow 2 Step 6)
+- [ ] **Mid-sprint findings:** every finding `session-08.md` **Mid-Sprint Cross-Reference** left open is fixed or deferred again here
 
 #### 0d. Present Findings
 
@@ -191,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
 
@@ -200,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/vault-context.md

@@ -109,7 +109,9 @@ needs no knowledge of the vault's folders (PBI 75336).
 
 - **If `.planning/vault/SUMMARY.md` lists `INDEX.md`**, Read `.planning/vault/INDEX.md`. The
   selection index is `INDEX.md`. Take only its list lines of the form
-  `` - `<path>` — <description> `` as candidates and ignore everything else in it.
+  `` - `<path>` — <description> `` as candidates and ignore everything else in it. A line whose
+  description starts with `[cross-cutting]` is a rule that binds every session — approval routes,
+  folder layout, naming — and is selected by the rule below, not by topic.
 - **Otherwise** select from the listing in `SUMMARY.md` itself (each path with its first heading).
   The selection index is `SUMMARY.md`. Print `vault: the vault ships no INDEX.md; selecting from
   the cache index` and continue.
@@ -132,7 +134,14 @@ or reordered session cannot move out from under its selection (D-11-16). Take th
 - Select a document when its index line bears on a decision one of this session's topics asks the
   client to make. Note the topic number; it is the "why" of the record.
 - Select at most **8** documents. When more qualify, keep the ones that bear on the most topics.
-- Selecting nothing is a valid outcome. Kick-off and wrap-up sessions often have nothing to select.
+- **Always select every `[cross-cutting]` document as well**, outside the cap of 8 and whatever
+  the session's topics. The cap stops topic documents crowding each other out; it must never drop
+  a rule every decision answers to. A session can sign a deviation only the vault's approval route
+  may sign, or place a folder the layout rule forbids, without any of its topics naming that
+  document. Its record line says why: `` - `<path>` — cross-cutting: <what it governs> ``.
+- Selecting nothing is a valid outcome when the index marks nothing `[cross-cutting]`. Wrap-up
+  sessions often have nothing to select; Session 1 selects the documents that state approval rules
+  or mandate a platform.
 
 **Bounds — the engine index decides what may be read.** Read a selected document only if
 `.planning/vault/SUMMARY.md` lists its path. The engine builds that listing with `isSecretFile`
@@ -182,7 +191,9 @@ answer in the session notes. The vault does not answer for the client; it puts t
 prior answer on the table. A loaded document that turns out to bear on no answer gets
 `— not used: <reason>` appended to its record line before the session closes. Flow 2 Step 7 runs
 `pp_run query discovery.vault-check <N>`, which fails while a recorded document is neither cited nor
-marked not used.
+marked not used, and, when the record's index is `INDEX.md`, while a `[cross-cutting]` document has
+no record line (`cross_cutting_missing`). A cross-cutting document that no answer drew on still
+gets its line, marked `— not used: <reason>`; that line is the record that it was checked.
 
 ## 5. Return
 

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
 
@@ -182,18 +181,19 @@ For each numbered topic in the session's "What We Cover" section:
 
 ### Step 6: Key Decisions and Action Items
 
-Ask: "Any key decisions made?" → populate Key Decisions table.
-Ask: "Any action items to track?" → populate Action Items table and update `_progress.md`. (Parked-topic Action Items rows were already added in Step 5.3b — do not duplicate them here.)
+Ask: "Any key decisions made?" → populate Key Decisions table; each row's **ID** is `D-<ss>-<n>`.
+**Back-amend rule:** when a decision changes something an earlier session recorded — a decision, a requirement, a risk, a table value — edit the original line in the same step: keep its text and append `→ amended by D-<ss>-<n>`. A reader of the earlier session then sees the change where they read the old answer.
+Ask: "Any action items to track?" → populate Action Items table (**ID** `A-<ss>-<n>`) and update `_progress.md`. (Parked-topic Action Items rows were already added in Step 5.3b — do not duplicate them here.)
 Ask: "Any positions taken that aren't decisions yet?" → append or update an `SP-<nn>` position block in `.planning/discovery/_sparring.md` with all seven fields (`Position` / `Key point` / `To nail down` / `DECISION` / `Residual risk accepted` / `Feeds:` / `Status:`). Evolve a position **in place** — never a second block for the same question, not even on a reversal (D-39).
 
 ### 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, then re-run.
+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.
 
 ### Step 8: Show Summary
 
@@ -222,29 +222,31 @@ 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 |
 |----------------|----------------|
 | Session 2 | Session 1: project context, vision, stakeholders |
 | Session 3 | Session 2: pain points, processes, personas, systems, data flows |
 | Session 4 | Session 1: vision, constraints. Session 2: personas, pain points. Session 3: processes, requirements, EPICs |
-| Session 5 | Session 3: requirements, scope. Session 4: UX decisions |
-| Session 6 | Session 5: architecture, technology stack |
+| Session 5 | Session 1: platform decision. Session 3: requirements, scope. Session 4: UX decisions |
+| Session 6 | Session 1: platform decision, approval routes. Session 5: architecture, technology stack |
 | Session 7 | Session 5: architecture. Session 6: security requirements |
 | Session 8 | Session 5: architecture, integration points |
 | Session 9 | Session 3: requirements. Session 5: architecture |
-| Session 10 | Session 5: architecture. Session 9: test environments |
-| Session 11 | Session 3: EPICs, scope. Session 5: architecture. Session 9: QA |
-| Session 12 | Session 11: roadmap, phases, timeline |
+| Session 10 | Session 1: platform decision. Session 5: architecture. Session 9: test environments |
+| Session 11 | Session 1: risks. Session 3: EPICs, scope. Session 5: architecture. Session 9: QA |
+| Session 12 | Session 1: team shape, approval routes. Session 11: roadmap, iteration model, timeline |
 | Session 13 | All previous sessions — full context review |
 
+**Shell you write yourself** (not a fence from this workflow): start every multi-line command with `[ -z "${ZSH_VERSION:-}" ] || emulate -R sh`, never begin a word with `=`, and use no GNU-only flags — the user's shell may be zsh on macOS. Read `${PP_TOOLS%/bin/pp-tools.cjs}/references/shell-portability.md` for why.
+
 ---
 
 ## 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.
@@ -255,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):
 
@@ -310,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>