@pareto4/pp-core 1.18.0 → 1.19.0

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

@@ -120,15 +120,24 @@ Read every frontend standard that passes these checks, also one the session's ow
 | Primary | | | | |
 | Secondary | | | | |
 
+**Content and Communication**
+
+| Aspect | Decision | Notes |
+|--------|----------|-------|
+| Tone of voice | | |
+| Notifications and alerts | | |
+| Tooltips, help text and inline guidance | | |
+| Languages | | |
+
 **Key Decisions**
 
-| # | Decision | Rationale | Owner | Date |
+| ID | Decision | Rationale | Owner | Date |
 |---|----------|-----------|-------|------|
 | | | | | |
 
 **Action Items**
 
-| # | Action | Owner | Due Date | Status |
+| ID | Action | Owner | Due Date | Status |
 |---|--------|-------|----------|--------|
 | | | | | |
 

package/pp-core/workflows/discovery-sprint/sessions/05-architecture.md

@@ -20,8 +20,8 @@
    *Why it matters: the stack choice determines team skills, hosting (Session 10), and integration patterns (Session 8). Skip when: the stack is fixed by client mandate.*
    - What is the preferred frontend technology (React, Angular, Vue, Mendix, etc.)?
    - What is the preferred backend technology (Node.js, .NET, Java, Python)?
-   - What database technology is appropriate (relational e.g. Cloud SQL via pareto-platform-gcp, document, graph, time-series)?
-   - What messaging or eventing technology will be used (Google Cloud Pub/Sub via pareto-platform-gcp, Kafka, RabbitMQ)?
+   - What database technology is appropriate (relational, document, graph, time-series), preferring the managed services of the platform Session 1 recorded?
+   - What messaging or eventing technology will be used (the platform's managed broker, Kafka, RabbitMQ)?
    - What caching strategy applies (Redis, in-memory, CDN)?
 
 3. **Key architectural components**
@@ -46,7 +46,7 @@
 
 **Notes Template:**
 
-> **Platform standard (D-08):** The Pareto platform standard is GCP / `pareto-platform-gcp`. Fill this table against that baseline unless the client has an overriding constraint.
+> **Platform:** fill this table against the platform Session 1 recorded (its `D-01-<n>` platform decision, citing the vault's platform standard when there is one). A row that departs from that platform is a Key Decisions row `D-05-<n>`. When Session 1 recorded the platform as open, each row's Rationale says why the technology was chosen.
 
 **Technology Stack Decisions**
 
@@ -85,12 +85,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/06-security.md

@@ -24,7 +24,7 @@
    - What are the audit requirements and cadence?
 
 3. **Encryption strategy**
-   *Why it matters: key management choices here constrain infrastructure options in Session 10. Skip when: the platform standard (GCP KMS) already covers requirements with no exceptions.*
+   *Why it matters: key management choices here constrain infrastructure options in Session 10. Skip when: the key management service of the platform Session 1 recorded already covers requirements with no exceptions.*
    - What encryption is required at rest (AES-256, TDE)?
    - What encryption is required in transit (TLS 1.2+, mTLS)?
    - How will encryption keys be managed (HSM, KMS, Vault)?
@@ -94,12 +94,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/07-identity.md

@@ -85,12 +85,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/08-integration.md

@@ -72,12 +72,24 @@
 
 **Key Decisions**
 
-| # | Decision | Rationale | Owner | Date |
+| ID | Decision | Rationale | Owner | Date |
 |---|----------|-----------|-------|------|
 | | | | | |
 
 **Action Items**
 
-| # | Action | Owner | Due Date | Status |
+| ID | Action | Owner | Due Date | Status |
 |---|--------|-------|----------|--------|
 | | | | | |
+
+**Mid-Sprint Cross-Reference**
+
+Filled by the Closing Step below: the findings count by severity, each fix applied (file, what changed, why), and each finding left for Session 13.
+
+---
+
+**Closing Step — mid-sprint cross-reference.** Run it after Step 7 and before Step 8, every time Session 8 completes, including a redo. Sessions 9–12 build on Sessions 1–8; an inconsistency found now costs one edit, while Session 13 finds it repeated in every later session.
+
+1. Read `${PP_TOOLS%/bin/pp-tools.cjs}/workflows/discovery-sprint/sessions/13-wrap-up.md` § **Step 0** and run 0a to 0e over Sessions 1–8 only: the **Business Functional** and **Technical** groups. Skip the engine gates and the checklist rows that need Sessions 9–12.
+2. Check every amended decision against the back-amend rule (Flow 2 Step 6): the original line carries `→ amended by D-<ss>-<n>`. Fix any line that does not.
+3. Record the results in this session's **Mid-Sprint Cross-Reference** notes. Session 13 re-checks the findings left open here.

package/pp-core/workflows/discovery-sprint/sessions/09-qa.md

@@ -96,12 +96,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/10-infrastructure.md

@@ -10,24 +10,24 @@
 **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.*
+   *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.*
    - 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)?
+   - What tools will be used for CI/CD (GitHub Actions, GitLab CI, Azure DevOps, Jenkins)? Take the platform's pipeline when Session 1 recorded one.
    - 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)?
+   - What is the approach to containerization (the platform's managed container or Kubernetes service, Kubernetes on-premises, or none)?
 
 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.*
+   - What monitoring platform will be used (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?
@@ -48,7 +48,7 @@
 
 **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.
 
 **Infrastructure Architecture**
 
@@ -103,12 +103,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,7 +24,7 @@
    - 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?
@@ -38,6 +38,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 +51,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 +59,12 @@
 
 **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.
+
 **Milestone Plan**
 
 | Milestone | Target Date | Included EPICs / Features | Entry Criteria | Exit Criteria | Stakeholder Demo? |
@@ -74,17 +77,17 @@
 **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 |
 |---|--------|-------|----------|--------|
 | | | | | |

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

@@ -68,7 +68,7 @@ Before facilitating any topics, execute the **Session 13: Cross-Reference Protoc
 
 | ID | Item | Source Session | Priority (H/M/L) | Must Resolve Before Build? | Owner | Target Date | Status |
 |----|------|---------------|-------------------|---------------------------|-------|-------------|--------|
-| OI-1 | | | | | | | |
+| OI-01 | | | | | | | |
 
 **Cross-Reference Analysis Results**
 
@@ -103,13 +103,13 @@ 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 |
 |---|--------|-------|----------|--------|
 | | | | | |
 
@@ -162,6 +162,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
 

package/pp-core/workflows/discovery-sprint/templates/context-template.md

@@ -28,6 +28,12 @@ _Populated after Session 1 completion_
 ### Stakeholders
 <!-- Key stakeholder list with roles -->
 
+### Approval Routes
+<!-- Who approves scope, budget, architecture and security deviations, go-live -->
+
+### Platform and Team Shape
+<!-- Mandated platform (D-01-n) or "open"; team shape for the build -->
+
 ### Discovery Sprint Scope
 **In Scope:**
 -
@@ -218,13 +224,13 @@ _Populated after Session 11 completion_
 <!-- Phase breakdown -->
 
 ### Timeline
-<!-- Sprint cadence and key dates -->
+<!-- Iteration model (sprints or pp-core phases) and key dates -->
 
 ### MVP Scope (Confirmed)
 <!-- Must-have vs nice-to-have -->
 
 ### Build Order
-<!-- Sprint-by-sprint plan -->
+<!-- Iteration-by-iteration plan -->
 
 ### Key Milestones
 <!-- Milestone dates -->
@@ -244,7 +250,7 @@ _Populated after Session 12 completion_
 <!-- Governance framework summary -->
 
 ### Ceremonies
-<!-- Sprint cadence and meetings -->
+<!-- Iteration cadence and the meetings held -->
 
 ### Support Model
 <!-- Post-go-live support approach -->

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

@@ -182,8 +182,9 @@ 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
@@ -193,7 +194,7 @@ Ask: "Any positions taken that aren't decisions yet?" → append or update an `S
 3. Update `.planning/discovery/_context.md`: populate the session's output section with concise summaries.
 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
 
@@ -229,16 +230,18 @@ When facilitating sessions, reference prior session outputs from `.planning/disc
 | 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

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

@@ -240,6 +240,7 @@ Introduction & Goals section.
 ```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

package/pp-core/workflows/discuss-phase-assumptions.md

@@ -96,6 +96,7 @@ Exit workflow.
 Check if CONTEXT.md already exists using `has_context` from init.
 
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls ${phase_dir}/*-CONTEXT.md 2>/dev/null || true
 ```
 
@@ -210,6 +211,7 @@ Lightweight scan of existing code to inform assumption generation.
 
 **Step 1: Check for existing codebase maps**
 ```bash
+[ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 ls .planning/codebase/*.md 2>/dev/null || true
 ```
 
@@ -553,10 +555,10 @@ Write file.
 Commit phase context and discussion log:
 
 ```bash
-pp_run query commit "docs(${padded_phase}): capture phase context (assumptions mode)" --files "${phase_dir}/${padded_phase}-CONTEXT.md" "${phase_dir}/${padded_phase}-DISCUSSION-LOG.md"
+pp_run query commit "docs(planning): capture phase context (assumptions mode)" --phase "${padded_phase}" --files "${phase_dir}/${padded_phase}-CONTEXT.md" "${phase_dir}/${padded_phase}-DISCUSSION-LOG.md"
 ```
 
-Confirm: "Committed: docs(${padded_phase}): capture phase context (assumptions mode)"
+Confirm: "Committed: docs(planning): capture phase context (assumptions mode) — Phase: ${padded_phase}"
 </step>
 
 <step name="update_state">
@@ -571,7 +573,7 @@ pp_run query state.record-session \
 Commit STATE.md:
 
 ```bash
-pp_run query commit "docs(state): record phase ${PHASE} context session" --files .planning/STATE.md
+pp_run query commit "docs(planning): record phase ${PHASE} context session" --phase "${padded_phase}" --files .planning/STATE.md
 ```
 </step>