@pareto4/pp-core 1.21.1 → 1.23.1

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

@@ -5,43 +5,62 @@
 
 ### Session 9: Quality Assurance & Testing Strategy
 
-**Goal:** Define the overall test strategy, confirm the testing tooling and quality gates against the client's standards, plan test environments, and design the UAT approach.
+**Goal:** Decide where the testing effort goes. Review every story's acceptance criteria for testability, choose by risk which main processes get an end-to-end test, name the complex parts of the solution that need extra test attention, confirm the test levels, environments and gates against the client's standards, and agree how UAT is run and signed off.
+
+**Who is in the room.** The client's test manager (or QA lead) leads this session; the product owner decides what "accepted" means; the architect knows where the solution is hard. Without a test manager, the product owner takes the risk calls and the session records that as a Key Decision.
+
+**How testing works in this delivery — say this first, in a minute.** The agents write the tests, before the code, from the acceptance criteria; every change runs the same checks; an agent never marks its own work — a separate verifier reads the acceptance criteria verbatim and decides pass or fail. So this session does not choose test tools or write test cases. It makes the calls the agents cannot: what "done" means for each story, where the business risk is, which parts are hard enough that ordinary tests will miss their failures, and who signs off.
+
+**Inputs — read before topic 1.** `.planning/discovery/_stories.md` (the acceptance criteria); `.planning/discovery/_processes.md` § As-is (`Criticality`), § To-be and § Steps; `.planning/discovery/_rules.md`; `.planning/discovery/_roles.md`; `.planning/discovery/_integrations.md` and `_migration.md` when they exist; `.planning/discovery/_entities.md` (the classification Session 6 copied in); `session-05.md` **Component Inventory**; `session-06.md` **Compliance Requirements Register**; `session-04.md` (the accessibility level); the `N-` rows of `_requirements.md`.
+
+**The register.** Copy the bootstrap template of `${PP_TOOLS%/bin/pp-tools.cjs}/references/discovery-tests.md` to `.planning/discovery/_tests.md` before topic 2 (replace `[PROJECT_NAME]`). Topics 2–4 fill it; the reference holds the cell grammar and the risk matrix.
 
 **Standards first.** Where a document this session's `## Vault Context` record names already fixes a test level, a coverage bar, a tool, the environments, a merge or release gate, 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-09-<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. **Test strategy and approach**
-   *Why it matters: sets the coverage bar every EPIC (Session 3) gets built and verified against. Skip when: the client has an existing enterprise test strategy this project simply inherits.*
-   - Test levels and coverage: the vault's coding standards and quality gates fix them when bound — does this product deviate, and why? Otherwise: unit, integration, system, E2E, performance, security, and which target per level?
-   - How will TDD or BDD be applied?
-   - What is the approach to regression testing?
-   - How will non-functional testing be addressed (load, stress, soak, accessibility)?
-
-2. **Testing tools and frameworks**
-   *Why it matters: tooling choice affects CI/CD pipeline design in Session 10. Skip when: the vault's stack and quality gates fix every tool and the client deviates nowhere — record the rows and move on.*
-   - Unit and E2E tooling: the vault's language standards fix the frameworks when bound — does this product deviate? Otherwise: Jest, xUnit, JUnit, PyTest; Cypress, Playwright, Selenium?
-   - Performance tooling: the vault's sizing and release rules fix the performance test when bound — does this product deviate? Otherwise: k6, JMeter, Gatling?
-   - Security scanning: the vault's quality gates fix the scanners when bound — does this product deviate, and with which substitute? Otherwise: OWASP ZAP, Snyk, SonarQube?
-
-3. **Test environments**
-   *Why it matters: environment count and refresh cadence feed Session 10's infrastructure sizing. Skip when: a single shared environment is acceptable for this scale of project.*
-   - How many test environments are needed? When a vault is bound, start from the environments its naming standard defines and record only deviations; otherwise choose (dev, test, staging, pre-prod).
-   - How will test data be provisioned (synthetic data, anonymized production data, seed scripts)?
-   - How will environments be kept in sync with production?
-
-4. **Quality gates and CI/CD integration**
-   *Why it matters: gates here become the literal pass/fail criteria in Session 10's deployment pipeline. Skip when: never — always define at least a minimal merge gate.*
-   - Merge gates: the vault's quality gates fix them when bound — does this product deviate, and why? Otherwise: code review, linting, unit tests, coverage threshold?
-   - Release gates: the vault's release rules fix them when bound — does this product deviate? Otherwise: what must pass before a release is promoted?
-   - How will automated testing be integrated into the CI/CD pipeline?
-
-5. **UAT approach**
-   *Why it matters: UAT sign-off criteria are what Session 13's go/no-go assessment checks against. Skip when: internal tool with no formal business acceptance step.*
-   - Who will perform UAT (business users, product owner, dedicated UAT team)?
-   - How will UAT scenarios be defined and managed?
-   - What constitutes UAT sign-off (criteria, approvers)?
-   - How will UAT defects be triaged and prioritized?
+1. **Test approach and standards**
+   *Why it matters: the levels, coverage bar and gates are what every change is checked against for the life of the product. Skip when: never — but with a vault bound this is a quick confirmation, not a discussion.*
+   - Walk the test levels — unit, integration, end-to-end, performance, security, accessibility — and for each say who writes the tests (agents), what runs them (the pipeline, on every change, or before a release) and what a person decides. Record it in **Test Approach**.
+   - Coverage bar and tooling: the vault's coding standards and quality gates fix them when bound — does this product deviate, and why? Otherwise: which coverage target, which frameworks? Settle it in one pass; tool choice is not this session's job.
+   - Does the client's test manager have an existing test policy or test strategy this product must follow? Note it in the Standards Applied row, cited as an input-package document `[NN]` when it is one.
+
+2. **Testability review of the acceptance criteria**
+   *Why it matters: the build's verifier reads each story's acceptance criteria verbatim as the test (`references/discovery-build-consumption.md`). Criteria it cannot check — "works correctly", "is user-friendly", "as in the old system" — pass whatever is built. Skip when: never.*
+   - Walk `_stories.md` § Stories with the test manager, story by story. For each: does it name an outcome someone can observe? With which data? As which role (a role of `_roles.md`)? Where does it end — what is on screen, in the data, sent to another system?
+   - A weak criterion is rewritten now, in `_stories.md`, with `→ amended by D-09-<n>` in the cell; the row in `_tests.md` § Acceptance reads `amended (D-09-<n>)`. One the room cannot settle gets an action `A-09-<n>` with an owner and reads `open (A-09-<n>)` — the handoff refuses it, so it has to be closed before the build starts.
+   - Fill one `## Acceptance` row per story: `Testable`, `Role`, `Test data`.
+
+3. **Risk-based selection of end-to-end processes**
+   *Why it matters: an end-to-end test proves that the steps of a process work together, across roles, screens, rules and interfaces — and it is the most expensive test to build and keep running. Spend it where a failure hurts most. Skip when: never; with one main process, assess the one.*
+   - For each main process of `_processes.md` § To-be, rate with the test manager:
+     - **Impact** — what breaks for the business if this process fails in production: money, legal or regulatory exposure, customers affected, data that cannot be repaired? Start from the `Criticality` of the as-is processes it replaces and the classification of the entities its steps touch.
+     - **Likelihood** — how likely is it to break: new rather than replaced, many steps, several interfaces or business rules in its step matrix, new technology, a migration feeding it, untested exception paths?
+   - The risk follows from the two by the matrix in `references/discovery-tests.md`. A `high` risk process gets an end-to-end test; not testing one end to end is a Key Decision `D-09-<n>` cited in the row's `Rationale`. A `medium` or `low` process may still get one when the room sees a reason.
+   - For every `yes`: as which roles does the test walk the process, and with what test data? Fill one `## Process risk` row per main process.
+
+4. **Complex components that need extra test attention**
+   *Why it matters: step tests written from acceptance criteria check the expected path. They miss the failures that live in branching rules, timing, concurrency, volume, money and other parties' systems — so those parts need tests designed for how they fail. Skip when: the architect and the test manager agree nothing is complex; write `None identified in Discovery.` under **Focus Areas**.*
+   - Ask the architect: which components of Session 5's **Component Inventory** are hardest — the most logic, state, concurrency or performance pressure?
+   - Walk the candidates the earlier sessions already flagged: business rules in `_rules.md` with many branches or thresholds; interfaces in `_integrations.md` that are asynchronous, at-least-once or owned by a party that changes them (Session 8's consistency model); `_migration.md` rows with large volumes or messy mappings; entities Session 6 classified `Restricted`.
+   - For each subject the room picks: what makes it complex, and what testing goes beyond the step tests — a test per row of a decision table, boundary values, property-based tests, contract tests against the provider, duplicate and out-of-order delivery, a migration rehearsal with reconciliation counts, a load test with a target number, a security test against a named threat? Fill one `## Focus areas` row per subject, with the requirements it realises.
+
+5. **Tests that follow from earlier sessions**
+   *Why it matters: the earlier sessions already decided much of what must be tested; the build derives those tests from the registers, so this session only confirms nothing is missing. Skip when: never — it takes minutes.*
+   - Present, do not re-ask: every role and screen in `_roles.md` gets a forbidden-path test (a role reaching what it may not); every `## Errors` row of `_integrations.md` a failure test; every Session 6 compliance requirement (`CR-`) and audit-logging row a security or audit test; Session 4's accessibility level an automated accessibility check; every `N-` requirement with a number (response time, volume, availability) a performance or availability test with that number.
+   - Ask the test manager: is a risk missing that none of these covers? Record it as a Focus areas row or a Key Decision.
+
+6. **Test environments and test data**
+   *Why it matters: environment count and refresh cadence feed Session 10's infrastructure sizing; test data decides whether the end-to-end tests and UAT can run at all. Skip when: a single shared environment is acceptable for this scale of project — still answer the test-data question.*
+   - Which environments: when a vault is bound, start from the environments its naming standard defines and record only deviations; otherwise choose (dev, test, acceptance, production).
+   - Where does test data come from — synthetic data, seed scripts, anonymised production data? Session 6's classification decides what may leave production: `Confidential` and `Restricted` data is never copied unmasked.
+   - Who refreshes the data, and how often?
+
+7. **UAT and sign-off**
+   *Why it matters: UAT sign-off is what Session 13's go/no-go and every release checks against. Skip when: an internal tool with no formal business acceptance step — record who accepts instead.*
+   - What does UAT consist of here: the end-to-end processes of topic 3, walked by business users, plus the stories accepted on their criteria? Which processes does the business walk by hand?
+   - Who performs UAT, who signs off, and on what criteria (for example: every high-risk process passed, no open severity-1 or severity-2 defects)?
+   - How are defects found in UAT classified and triaged, and who decides a release may go with known defects?
 
 **Notes Template:**
 
@@ -49,6 +68,7 @@
 
 | Area | Standard | Deviation | Decision |
 |------|----------|-----------|----------|
+| Test policy | | | |
 | Test levels and coverage | | | |
 | Test tooling | | | |
 | Environments | | | |
@@ -56,58 +76,64 @@
 | Release gates | | | |
 | UAT and sign-off | | | |
 
-**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-09-<n>` that records the deviation or the decision taken for an uncovered area (`references/discovery-standards.md`).
+**Standard** is the governing document's `[vault: <rel path>]` citation, the client's own test policy as an input-package citation `[NN]`, or `not in vault`. **Deviation** is `none` or the `DEV-<nn>` of the `_deviations.md` row. **Decision** is `—` or the `D-09-<n>` that records the deviation or the decision taken for an uncovered area (`references/discovery-standards.md`).
+
+**Test Approach**
+
+| Test level | What it proves | Written by | Runs | Person decides | Standard or target |
+|-----------|----------------|------------|------|----------------|--------------------|
+| Unit | | | | | |
+| Integration | | | | | |
+| End-to-end | | | | | |
+| Performance | | | | | |
+| Security | | | | | |
+| Accessibility | | | | | |
+| User acceptance | | | | | |
 
-**Test Strategy Matrix**
+**Written by** is `Agents` for every automated level and `People` for user acceptance; **Runs** is `Every change`, `Before release` or a schedule; **Person decides** is what a human owns at that level (the coverage bar, the processes chosen, the sign-off). End-to-end proves the processes chosen in `_tests.md` § Process risk.
 
-| Test Level | Scope | Coverage Target | Automation Level | Tools | Responsible | When Executed |
-|-----------|-------|-----------------|-----------------|-------|-------------|---------------|
-| Unit | | | | | | |
-| Integration | | | | | | |
-| System / E2E | | | | | | |
-| Performance | | | | | | |
-| Security | | | | | | |
-| Accessibility | | | | | | |
+**Acceptance Review**
 
-**Testing Toolchain**
+The rows live in `.planning/discovery/_tests.md` § Acceptance. Record here only the totals and what the room learned: stories reviewed, how many were `yes`, `amended` and `open`, and the patterns behind the weak criteria (to feed back into Session 3's way of writing them).
 
-| Purpose | Tool | Version | License | Notes |
-|---------|------|---------|---------|-------|
-| Unit testing | | | | |
-| E2E testing | | | | |
-| Performance testing | | | | |
-| Security scanning | | | | |
-| Code quality | | | | |
+**Process Risk**
+
+The rows live in `.planning/discovery/_tests.md` § Process risk. Record here the main processes chosen for an end-to-end test, one line each with the reason, and any high-risk process deliberately left without one with its `D-09-<n>`.
+
+**Focus Areas**
+
+The rows live in `.planning/discovery/_tests.md` § Focus areas. Record here the subjects chosen, one line each, or `None identified in Discovery.`
 
 **Test Environment Plan**
 
 > **Environments:** when the bound vault names the environments (its naming standard, cited `[vault: <path>]` in this session's record), the rows below carry those names, in the vault's promotion order, and no others — an extra or renamed environment is a Key Decisions row `D-09-<n>`. The preset rows stand only when no vault is bound.
 
-| Environment | Purpose | Data Strategy | Refresh Cadence | Access | Infrastructure | Owner |
-|-------------|---------|---------------|-----------------|--------|---------------|-------|
-| Dev | | | | | | |
-| Test | | | | | | |
-| Staging | | | | | | |
-| Pre-prod | | | | | | |
+| Environment | Purpose | Test data | Refresh cadence | Access | Owner |
+|-------------|---------|-----------|-----------------|--------|-------|
+| Dev | | | | | |
+| Test | | | | | |
+| Acceptance | | | | | |
 
 **Quality Gates**
 
-| Gate | Stage | Criteria | Threshold | Blocking? | Tool |
-|------|-------|----------|-----------|-----------|------|
-| Code review | PR merge | | | Yes | |
-| Unit test pass | PR merge | | | Yes | |
-| Code coverage | PR merge | | | Yes | |
-| Integration tests | Deploy to staging | | | Yes | |
+| Gate | Stage | Criteria | Threshold | Blocking? | Standard |
+|------|-------|----------|-----------|-----------|----------|
+| Code review | | | | | |
+| Unit and integration tests | | | | | |
+| Code coverage | | | | | |
+| End-to-end tests | | | | | |
+| UAT sign-off | | | | | |
 
 **UAT Process**
 
 | Aspect | Decision | Notes |
 |--------|----------|-------|
 | UAT participants | | |
-| UAT scenario source | | |
+| Processes walked by hand | | |
 | Sign-off criteria | | |
 | Sign-off approver(s) | | |
-| Defect triage process | | |
+| Defect severity and triage | | |
+| Release with known defects — who decides | | |
 
 **Key Decisions**
 
@@ -120,3 +146,7 @@
 | ID | Action | Owner | Due Date | Status |
 |---|--------|-------|----------|--------|
 | | | | | |
+
+---
+
+**Closing Step.** Run `pp_run query discovery.tests-check` — exit 0, or fix the rows it names in `_tests.md`. Faults that mean a topic is unfinished: `process_not_assessed` (topic 3 skipped a main process), `story_not_reviewed` (topic 2 skipped a story), `high_risk_not_end_to_end` (a high-risk process without an end-to-end test and without a decision), `risk_mismatch` (the rating does not follow the matrix). `open` stories and focus areas without requirements are allowed here; the handoff refuses them (`--require-complete`), so each needs its action closed before Session 13.

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

@@ -162,6 +162,7 @@ For each group: read all session files — their Notes Template sections and the
 - [ ] **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
+- [ ] **Process coverage:** the S3 **Process Coverage** table names a process or a decision for every persona, entity, external system and scheduled job; `discovery process-check` and `discovery stories-check` exit 0 (every step in one sub-process and in its swimlane, every persona step covered by a story)
 - [ ] **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)
 - [ ] **Research-track gate:** `discovery research-check` exits 0 (no structural faults, no stale ⚠️ markers)
@@ -170,7 +171,7 @@ For each group: read all session files — their Notes Template sections and the
 - [ ] **Stakeholder names:** Consistent across all sessions
 - [ ] **KPIs and metrics:** Consistent definitions between S1, S3, S11
 - [ ] **Security constraints:** S6 constraints reflected in S5 and S10
-- [ ] **Test strategy:** S9 covers all S3 requirements and S5 components
+- [ ] **Test strategy:** `discovery tests-check` exits 0 (every S3 main process risk-rated, every story reviewed for testability, every high-risk process tested end to end or decided otherwise); the S9 focus areas cover the S5 components the architect called complex
 - [ ] **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)
@@ -215,6 +216,6 @@ Capture in `.planning/discovery/session-13.md` notes:
 
 #### 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.
+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 charter 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

@@ -89,6 +89,21 @@ These documents are the binding engineering standards for this work: build to th
 Paraphrase at point of use with a `[vault: <rel path>]` citation. Never inline raw vault content
 into the session notes.
 
+**Business user (D-14).** When `audience` is `business`, print none of the `vault:` lines this file names. Once the selection is done, say one of these instead, and hand the record back unchanged:
+
+Business form: "I have your organisation's standards for this session at hand."
+
+Business form: "Your organisation's standards add nothing for this session."
+
+Business form: "I could not load your organisation's standards for this session, so I am working without them. Ask your Pareto contact if they should be here."
+
+Business form: "I could not check some of your organisation's standards for this session, so I am working without those. Ask your Pareto contact if they should be here."
+
+Use the second only when the index was read and nothing in it bore on this session. Use the third
+when there is no cache index (the stop arm below): the standards were not consulted, so never say
+they add nothing. Use the fourth, after the first or on its own, when a selected document was not
+read because the cache index is truncated or the document is not in the cache.
+
 **Read order.** Read `.planning/vault/SUMMARY.md` first. It is the engine-written bounded index —
 each cached path with its first heading, not full vault content — and it is what tells you which
 documents actually exist in this client's cache.

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

@@ -37,10 +37,14 @@ INIT=$(pp_run query init.phase-op "${SESSION_ARG:-}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 `SESSION_ARG` is the optional session number 1–13, extracted from `$ARGUMENTS` in the block above (empty when no argument was passed).
 
 **Text mode:** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
 
+**First run — who you are (D-06):** before dispatching, run `pp_run query audience status --raw`. If `needs_choice` is `true`, show its `prompt` exactly as printed and wait for the reply. Then run `pp_run query audience answer '<reply>'` (the reply in single quotes, with any single quote in it removed) and show its output. If that fails, show the prompt once more, then continue either way. Once an answer is saved, re-run the init call above and apply the **Audience** line to the new `INIT`. Never write `~/.gsd/person.json` yourself. With nobody to answer (a headless run), skip this and save nothing.
+
 **Dispatch:**
 - If `FIRST_TOKEN` is `input` → Read `${PP_TOOLS%/bin/pp-tools.cjs}/workflows/discovery-sprint/input-package.md` and follow it. Stop — do not continue into the session flow.
 - 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).
@@ -88,6 +92,8 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 
 ## Flow 1: Show Progress (no argument)
 
+**Business user or business engineer (D-14):** when the init payload carries `audience`, run `pp_run query discovery.status` and show its output exactly as printed, with nothing before or after it, instead of steps 1-3 below; it gives the sprint's state and next step in the person's wording. If it exits non-zero or prints nothing, show none of its output and follow steps 1-3 instead, worded for this audience. A developer run follows steps 1-3 as written.
+
 1. Read `.planning/discovery/_progress.md`. If not found, tell the user no Discovery Sprint is set up for this project and suggest creating the artifacts first by running `/pp-discovery 1`.
 
 2. Parse the Session Progress table and display:
@@ -114,6 +120,8 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
      > "Next recommended session: Session N — [Name]. Run `/pp-discovery N` to start."
    - 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.
 
+`/pp-progress`, `/pp-progress --next` and `/pp-resume-work` show the same recommendation through `pp_run query discovery.status`, which applies the order above in code (`src/discovery-status.cts`); a change to this order must change it too. That command reports and checks nothing, so it has no Session 13 gate.
+
 ---
 
 ## Flow 2: Facilitate Session N (argument = 1–13)
@@ -137,6 +145,10 @@ For each session dependency, verify its status in `_progress.md`. If any depende
 
 **Text mode fallback:** present as numbered list: 1) Yes, continue anyway / 2) No, go back.
 
+For a business user ask it in these words (D-14):
+
+Business form: "This session builds on session {X} and {Y}, which are not finished yet. We can start now, but some answers may change later. Start anyway?"
+
 If the user confirms, proceed. Otherwise, stop and suggest the incomplete dependency.
 
 ### Step 3: Check for Resume
@@ -166,6 +178,8 @@ Update `.planning/discovery/_progress.md`: set session row status to "In Progres
 
 Facilitate in the language the user writes in. Prototypes and software are always English.
 
+When `audience` is `business`, follow § Discovery narration of `audience-moments.md` (in the references folder, next to `audience.md`) in everything you say in this session (D-14); the session file is still written exactly as below.
+
 For each numbered topic in the session's "What We Cover" section:
 
 1. **Present the topic** conversationally: "Let's talk about [Topic Name]."
@@ -222,7 +236,7 @@ Each session's Goal, "What We Cover" topics and Notes Template live in their own
 
 ## Context-Awareness Rules
 
-When facilitating sessions, reference prior session outputs from 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:
+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`, `_tests.md`) — never from a summary written at session close; the session tables are the single source:
 
 | Current Session | Reference From |
 |----------------|----------------|
@@ -233,7 +247,7 @@ When facilitating sessions, reference prior session outputs from the earlier ses
 | 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 9 | Session 2: as-is criticality. Session 3: processes, stories, rules. Session 4: accessibility. Session 5: components. Session 6: classification, compliance. Session 7: roles. Session 8: interfaces, migration |
 | 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 |

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

@@ -5,7 +5,7 @@
 > of them ends the handoff. They are the only hard blocks in the workflow — every other check in
 > 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.
+> migration, deviations, tests) and the signed charter.
 
 **Screen-inventory contract gate (D-53)**
 
@@ -66,13 +66,13 @@ The check ran in the first fence above.
 
 **If `SWEEP_STATUS` is 0:** Continue with the artifact gates below.
 
-**Artifact gates (data model, processes, rules, stories, phase plan, roles, integrations, migration, deviations)**
+**Artifact gates (data model, processes, rules, stories, phase plan, roles, integrations, migration, deviations, tests)**
 
 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
+`_integrations.md`, `_migration.md` and `_tests.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,
+hard-to-reverse deviation nobody has approved, or a story whose acceptance criteria nobody can test 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
@@ -103,20 +103,27 @@ echo "MIGRATION_STATUS=$MIGRATION_STATUS"
 pp_run query discovery.deviations-check --require-approved
 DEVIATIONS_STATUS=$?
 echo "DEVIATIONS_STATUS=$DEVIATIONS_STATUS"
+pp_run query discovery.tests-check --require-complete
+TESTS_STATUS=$?
+echo "TESTS_STATUS=$TESTS_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
+**If all eleven 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
+model; `uncited_step` means Step 5D did not back-fill a step; `step_without_subprocess` and
+`step_not_in_flow` mean Step 5C left a step out of its sub-processes or its swimlane;
+`mvp_requirement_without_story`, `step_without_story` and `no_source_step` mean Step 5E skipped a
+requirement or a persona step, or left a story tied to no step; `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`;
+`story_not_testable` and `uncited_focus` mean Session 9 left a story's acceptance criteria open or a
+focus area without requirements — close the `A-09-<n>` action and amend the row;
 `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
@@ -124,8 +131,8 @@ the named section in that session file, or write `None identified in Discovery.`
 (`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
+`references/discovery-access.md`, `references/discovery-integrations.md`,
+`references/discovery-standards.md` and `references/discovery-tests.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

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

@@ -53,5 +53,5 @@ This project has a completed Discovery Sprint in `.planning/discovery/`. pp-core
    - 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`)
+   - Testing → `.planning/discovery/_tests.md` (end-to-end processes by risk, focus areas, testability of every story); levels, environments, gates and UAT sign-off: Session 9 (`.planning/discovery/session-09.md`)
 ```

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

@@ -151,7 +151,15 @@ row for row — never summarise them. Without a screen inventory or prototype, w
 | {system} | {in/out/bi} | {REST/webhook} | {data} | {when} |
 
 ## Quality & Testing Strategy
-{From Session 9: framework, coverage target, test types, UAT, quality gates}
+{From `.planning/discovery/_tests.md` when it exists: the main processes tested end to end (the `yes` rows of § Process risk, with their risk) and the § Focus areas subjects with their extra testing; from Session 9: Test Approach, Quality Gates, UAT Process (participants, sign-off criteria, approvers)}
+
+| Process | Risk | Roles | Test data |
+|---------|------|-------|-----------|
+| {MP-nn — name} | {high/medium/low} | {roles} | {data} |
+
+| Focus area | Extra testing |
+|------------|---------------|
+| {subject} | {what beyond the step tests} |
 
 ## Infrastructure & Deployment
 {From Session 10: environments, deployment approach, monitoring, backup/DR}

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

@@ -40,8 +40,12 @@ Valid pp-core subagent types (use exact names — do not fall back to 'general-p
 Resolve the `pp_run` helper before anything else. Every `pp_run` call below uses this shim.
 
 ```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
+pp_run query audience fields
 ```
 
+**Audience, before any question:** run the block above. If it prints `pp-tools.cjs not found`, show that error and stop. If it exits non-zero for any other reason, tell the person the audience setting could not be read (show the error) and continue; if it prints JSON, apply the **Audience** line below to it now.
+
 ---
 
 **Step 1: Validate environment**
@@ -226,8 +230,8 @@ Read these files (skip any that don't exist):
 7. `.planning/discovery/_stories.md`, `.planning/discovery/_phases.md`,
    `.planning/discovery/_entities.md`, `.planning/discovery/_processes.md`,
    `.planning/discovery/_rules.md`, `.planning/discovery/_roles.md`,
-   `.planning/discovery/_integrations.md`, `.planning/discovery/_migration.md` and
-   `.planning/discovery/_deviations.md` — the registers Steps 5e and 5f copy from
+   `.planning/discovery/_integrations.md`, `.planning/discovery/_migration.md`,
+   `.planning/discovery/_deviations.md` and `.planning/discovery/_tests.md` — the registers Steps 5e and 5f copy from
    (`references/discovery-build-consumption.md`)
 
 **Spawn an Explore agent to read all session files in parallel** and extract every
@@ -291,13 +295,15 @@ workflow uses.
 ### 5a. Run init
 
 ```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
+command -v pp_run >/dev/null 2>&1 || { echo "ERROR: pp_run is not on PATH; prepend the resolver line from the top block to this block and run it again" >&2; exit 1; }
 mkdir -p .planning
-INIT=$(pp_run query init.new-project 2>/dev/null)
+INIT=$(pp_run query init.new-project)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 echo "$INIT"
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 ### 5b. Collect preferences
 
 Ask the pp-core configuration questions — identical to `/pp-new-project` Step 2a:

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

@@ -64,13 +64,13 @@ role, a flow step, a screen, an acceptance criterion, a phase's requirement set)
 
 1. **Amend the register row in place.** Edit the cell in the artifact (`_entities.md`,
    `_rules.md`, `_processes.md`, `_screens.md`, `_stories.md`, `_requirements.md`, `_phases.md`,
-   `_roles.md`, `_integrations.md`, `_migration.md`, `_deviations.md`)
+   `_roles.md`, `_integrations.md`, `_migration.md`, `_deviations.md`, `_tests.md`)
    and append `→ amended by D-P${PADDED_PHASE}-<n>` to it, `<n>` being the decision's sequence in
    this CONTEXT.md. Never add a second row for the new fact, never strike the old cell: one row,
    amended.
 2. **Re-run the artifact's check** — `pp_run query discovery.entity-check`, `process-check`,
    `rules-check`, `screen-check`, `stories-check`, `phases-check`, `roles-check`,
-   `integrations-check`, `migration-check`, `deviations-check`, or `rollup --check` for
+   `integrations-check`, `migration-check`, `deviations-check`, `tests-check`, or `rollup --check` for
    `_requirements.md` — exit 0 before continuing. A build decision that departs from a vault
    standard is a new `DEV-` row of `_deviations.md` with `Decision` = `D-P${PADDED_PHASE}-<n>`.
 3. **Bump the charter.** In `docs/discovery/PROJECT-CHARTER.md` raise `version` and add a § 20

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

@@ -70,6 +70,8 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_ANALYZER=$(pp_run query agent-skills pp-assumptions-analyzer)
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`,
 `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `has_verification`,
 `plan_count`, `roadmap_exists`, `planning_exists`.

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

@@ -127,7 +127,7 @@ AGENT_SKILLS_ADVISOR=$(pp_run query agent-skills pp-advisor-researcher)
 
 Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `has_verification`, `plan_count`, `roadmap_exists`, `planning_exists`, `response_language`.
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
 
 **If `phase_found` is false:**
 ```

package/pp-core/workflows/edit-phase.md

@@ -39,6 +39,8 @@ INIT=$(pp_run query init.phase-op "${target}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Check `roadmap_exists` from init JSON. If false:
 ```
 ERROR: No roadmap found (.planning/ROADMAP.md)

package/pp-core/workflows/eval-review.md

@@ -18,6 +18,8 @@ INIT=$(pp_run query init.phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
+**Audience:** if `audience` is set, Read and follow `{audience_ref}`. Reply in any `response_language` and pass it to subagents; code and paths stay as is.
+
 Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `commit_docs`.
 
 ```bash