@pareto4/pp-core 1.19.0 → 1.20.0

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

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

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

@@ -21,6 +21,7 @@ Valid pp-core subagent types (use exact names — do not fall back to 'general-p
 <context>
 **Flags (parse from `$ARGUMENTS`):**
 - `--skip-validation` — Skip the Discovery completion check (use when sessions are intentionally incomplete). Does NOT skip the screen-inventory gate, which hard-blocks on structural faults (D-53).
+- `--unsigned` — Start the build although `docs/discovery/PROJECT-CHARTER.md` is not `Signed` or `Signed with conditions`, or does not exist (an engagement that predates the charter). The gap is recorded in PROJECT.md's Key Decisions, STATE.md's Blockers/Concerns and the handoff summary. A charter with structural faults still blocks.
 - `--scaffold` — After initialization, also scaffold lightweight application structure from the Session 5 tech stack
 - `--text` — Text mode: render every interactive prompt as a plain-text numbered list (for non-Claude runtimes)
 
@@ -102,8 +103,8 @@ write `.planning/discovery/session-NN.md`: <!-- legacy-read-target -->
 - Preserve `status`, `completed_date`, and `completeness_score` frontmatter fields where
   present in the legacy file; normalize any missing fields to the current session
   template's defaults (do not blind-copy — read what exists, fill gaps honestly).
-- Copy the legacy progress and context files to `.planning/discovery/_context.md` and
-  `.planning/discovery/_progress.md` respectively <!-- legacy-read-target -->, adding a
+- Copy the legacy progress file to `.planning/discovery/_progress.md` <!-- legacy-read-target -->
+  (a legacy context file is a copy of the session tables — leave it, it is not read), adding a
   `Parked` column to the progress table (default 0) if the legacy schema predates it.
 
 **Path safety (T-04-03, reused verbatim):** Reject any source or destination path that is
@@ -132,10 +133,11 @@ Or use /pp-progress to continue where you left off.
 
 **Step 2: Validate Discovery completion**
 
-**Screen-inventory contract gate (D-53), with the feedback and element-sweep gates.**
-`Read(workflows/discovery-to-build/steps/screen-inventory-gate.md)` and run it end-to-end before
+**Screen-inventory contract gate (D-53), with the feedback, element-sweep and signed-charter gates.**
+`Read(workflows/discovery-to-build/steps/handoff-gates.md)` and run it end-to-end before
 anything else in this step. These are hard stops: report what the gate prints and do not continue.
-`--skip-validation` does not cover them. Only when every gate passes, go on with the completion check
+`--skip-validation` does not cover them; `--unsigned` covers only the signature requirement of the
+charter gate and records the gap. Only when every gate passes, go on with the completion check
 below.
 
 Read `.planning/discovery/_progress.md` and parse the Session Progress table. Count sessions by
@@ -213,13 +215,20 @@ them into a single document optimized for the pp-core new-project generators.
 
 Read these files (skip any that don't exist):
 
-1. `.planning/discovery/_context.md` — accumulated cross-session context (primary source)
+1. All 13 session files in `.planning/discovery/session-NN.md` — their Notes Template sections are the primary source; the session-output gate in `steps/handoff-gates.md` proves each present and filled
 2. `.planning/discovery/_progress.md` — session completion status
-3. All 13 session files in `.planning/discovery/session-NN.md` — for detail not captured in `_context.md`
-4. The Project Definition document (glob for `*-Project-Definition.md` in root)
+3. The registers under item 6 — the canonical rows the session tables point at
+4. Legacy only: a `*-Project-Definition.md` in the repository root, left by the pre-charter
+   `pareto-project-setup` scaffold — projects set up since have none
 5. `.planning/discovery/prototype/README.md` — if a prototype exists (built by `/pp-discovery prototype`), note its state
 6. `.planning/discovery/_requirements.md`, `.planning/discovery/_screens.md`,
    `.planning/discovery/_feedback.md` and `.planning/discovery/_sweep.md`
+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
+   (`references/discovery-build-consumption.md`)
 
 **Spawn an Explore agent to read all session files in parallel** and extract every
 populated Notes Template table, all Key Decisions tables, all Action Items, and any
@@ -236,9 +245,11 @@ those generators expect.
 **Synthesis rules:**
 - Use actual content from the session files, never placeholders
 - If a session is incomplete, note `[Session N incomplete — content pending]` in that section
-- Preserve requirement IDs (FR-xxx, NFR-xxx, US-xxx, EPIC-xxx) exactly as defined
+- Preserve IDs exactly as discovery minted them — `<PREFIX>-nn` domain rows and `N-`/`T-`
+  rows from `_requirements.md`, `E-nn` EPICs and `US-nn` stories from Session 3
+  (`references/discovery-id-conventions.md`); never mint `FR-`/`NFR-`/`EPIC-` IDs
 - Preserve role names (Session 7) and technology choices (Session 5) exactly
-- If the Project Definition document has content not in `_context.md`, merge it in
+- If a legacy Project Definition document has content the session files lack, merge it in
 - Keep it factual — no interpretation or recommendations, just structured outputs
 - List every unresolved parked question from Step 2's D-12 scan verbatim in the Parked
   Questions (Unresolved) table — never inflate completeness by omitting them
@@ -251,7 +262,7 @@ those generators expect.
 AskUserQuestion([
   {
     header: "Handoff Ready",
-    question: "I've synthesized your Discovery Sprint into .planning/discovery/_pp-handoff.md.\n\nSummary:\n- {epic_count} EPICs, {story_count} user stories\n- {fr_count} functional / {nfr_count} non-functional requirements\n- Tech stack: {stack_summary}\n- {role_count} user roles, {integration_count} integrations, {phase_count} phases\n- {incomplete_sessions} incomplete sessions (if any)\n\nReview the file and confirm to proceed with pp-core initialization.",
+    question: "I've synthesized your Discovery Sprint into .planning/discovery/_pp-handoff.md.\n\nSummary:\n- {epic_count} EPICs (E-), {story_count} user stories (US-)\n- {req_count} requirements by prefix: {one count per registered prefix, e.g. K- 12 · N- 4 · T- 3}\n- Tech stack: {stack_summary}\n- {role_count} user roles, {integration_count} integrations, {phase_count} phases\n- {incomplete_sessions} incomplete sessions (if any)\n\nReview the file and confirm to proceed with pp-core initialization.",
     multiSelect: false,
     options: [
       { label: "Initialize pp-core", description: "Generate .planning/ from this handoff document (Recommended)" },
@@ -336,9 +347,15 @@ pp_run commit "chore: add project config" --files .planning/config.json
 
 Read `.planning/discovery/_pp-handoff.md` and synthesize `.planning/PROJECT.md` using the pp-core
 project template structure: use "What We're Building" as the description, include all
-Key Decisions, list requirements in Validated/Active/Out-of-Scope form, and reference
+Key Decisions with their `D-<ss>-<n>` in the table's **ID** column, list requirements in
+Validated/Active/Out-of-Scope form, and reference
 Discovery artifacts (the section is added in Step 6a).
 
+**Unsigned charter (`--unsigned`).** When the charter gate passed on `--unsigned`, add one Key
+Decisions row: `| — | Build started on an unsigned Project Charter (status: {CHARTER_STATE}) |
+--unsigned passed to /pp-discovery-to-build; sign-off still owed | ⚠️ Revisit |`. Nothing in
+PROJECT.md may read as if the charter were signed.
+
 **Init deferral (D-07-03, OD-2).** Before writing the file, Read
 `pp-core/workflows/init/steps/project-md-deferral-narration.md` and follow it — the single
 rendering of the reachability-proof deferral `/pp-init` recorded, silent when none is on
@@ -358,16 +375,24 @@ pp_run commit "docs: initialize project from Discovery Sprint" --files .planning
 
 ### 5e. Generate REQUIREMENTS.md
 
-From the Functional Requirements section: map EPICs to requirement groups, user stories
-to individual requirements, include NFRs and Business Rules, preserve all original IDs
-(FR-xxx, NFR-xxx, US-xxx), and mark all requirements active.
+From the Functional Requirements section: map EPICs (`E-nn`) to requirement groups, carry
+every `_requirements.md` row under its EPIC with its own ID (`<PREFIX>-nn`, `N-nn`, `T-nn`)
+and the `US-nn` stories from `_stories.md` that realise it, preserve every ID as minted — never
+renumber, never invent `FR-`/`NFR-`/`EPIC-` IDs — and mark all requirements active.
+
+**Discovery row shape (F-1):** a requirement line keeps what the sprint recorded. Use the
+discovery variant of `pp-core/templates/requirements.md`: the description is followed by
+` — <MoSCoW> · <Disposition> · <Provenance>` copied from the `_requirements.md` row, and the
+acceptance criteria follow on an indented `- AC:` line, verbatim. `MVP` rows go under
+`## v1 Requirements`, `Later` rows under `## v2 Requirements`, `Dropped (…)` rows under
+`## Out of Scope` with the killing decision as the reason. Nothing is summarised.
 
-**Inline source refs (D-05):** Every generated requirement line — FR/NFR/EPIC/US — carries
-a trailing `(source: session-NN §Section)` ref at point of use, e.g. `FR-012: User can
+**Inline source refs (D-05):** Every generated line — requirement, EPIC or story — carries
+a trailing `(source: session-NN §Section)` ref at point of use, e.g. `K-12: User can
 export a report as CSV (source: session-03 §Order Intake)`, naming the canonical
 `.planning/discovery/session-NN.md` file and section it was derived from. Then append one
 `## Discovery Traceability` table (same shape as Step 3b's table) mapping each requirement
-category (Authentication, EPIC group, NFRs, Business Rules, …) to its canonical
+group (registered prefix, EPIC, `N-` rows, …) to its canonical
 `.planning/discovery/session-NN.md` source(s) — the file-level map that complements the
 per-item inline refs above.
 
@@ -377,29 +402,37 @@ pp_run commit "docs: requirements from Discovery Sprint" --files .planning/REQUI
 
 ### 5f. Generate ROADMAP.md
 
-From the Roadmap & Phasing section: map Discovery phases to pp-core phases, derive phase
-goals from EPIC scope, set dependencies from build-order preferences, and include the
-milestone name (Session 11, or default "v1.0 — MVP").
-
-**Canonical refs producer (D-06):** For every generated phase entry, emit a
-`**Canonical refs:** .planning/discovery/session-NN.md, ...` line listing every canonical
-session file that fed that phase's requirements — placed immediately after the
-`**Requirements**:` line and before `**Success Criteria**`, per `pp-core/templates/roadmap.md`'s
-phase-entry field order:
+**From `_phases.md`, verbatim (F-5):** when `.planning/discovery/_phases.md` exists (every
+engagement since Session 11's Closing Step wrote one — the handoff gate has already run
+`phases-check` on it), each row IS one pp-core phase: `Phase` → the phase number, `Goal` →
+`**Goal**:` verbatim, `Depends on` → `**Depends on**:` (`—` → `Nothing (first phase)`),
+`Requirement IDs` → `**Requirements**:` verbatim, each ` · `-separated success criterion → one
+numbered `**Success Criteria**` line. Derive nothing: a phase the table does not have does not
+exist. Only without `_phases.md` (a legacy engagement) fall back to the Roadmap & Phasing
+section: map Discovery phases to pp-core phases, derive goals from EPIC scope and dependencies
+from build-order preferences. Either way include the milestone name (Session 11, or default
+"v1.0 — MVP").
+
+**Canonical refs producer (D-06, artifact paths — R1):** for every phase entry run
+`pp_run query discovery.for-phase <N> --raw` and emit a `**Canonical refs:**` line listing the
+payload's `artifacts` — the discovery registers that carry a row for this phase — placed
+immediately after the `**Requirements**:` line and before `**Success Criteria**`, per
+`pp-core/templates/roadmap.md`'s phase-entry field order:
 
 ```markdown
 ### Phase [N]: [Name]
 **Goal**: [What this phase delivers]
 **Depends on**: [...]
 **Requirements**: [REQ-01, REQ-02]
-**Canonical refs:** .planning/discovery/session-03.md, .planning/discovery/session-05.md
+**Canonical refs:** .planning/discovery/_requirements.md, .planning/discovery/_processes.md
 **Success Criteria** (what must be TRUE):
 ```
 
-Use the exact label string `Canonical refs:` — the existing `discuss-phase.md:313` consumer
-already copies this line unchanged into `CONTEXT.md`'s canonical refs accumulator. Do not
-modify `discuss-phase.md`, the researcher, or the planner — this workflow is the first
-*producer* of a line those consumers already read.
+Use the exact label string `Canonical refs:` — `discuss-phase.md` copies this line into
+`CONTEXT.md`'s canonical refs accumulator. Never name a `session-NN.md` here: the build reads
+the registers through `for-phase`, not the facilitation record
+(`references/discovery-build-consumption.md`). When the payload's `artifacts` is empty, write
+`**Canonical refs:** none — no discovery row cites this phase` so the gap is visible.
 
 ```bash
 pp_run commit "docs: roadmap from Discovery Sprint" --files .planning/ROADMAP.md
@@ -417,7 +450,8 @@ roadmapper agent uses). Populate it from what Step 5f already established:
 - **Current Position:** Phase 1 of N, "Ready to plan", today's date, 0% progress bar
 - **Accumulated Context › Decisions:** none yet (fresh project)
 - **Accumulated Context › Blockers/Concerns:** any unresolved parked questions carried
-  forward from Step 2's D-12 confirmation (see below), so they stay visible after handoff
+  forward from Step 2's D-12 confirmation (see below), so they stay visible after handoff; and,
+  when the charter gate passed on `--unsigned`, `Project Charter not signed (status: {CHARTER_STATE})`
 - **Session Continuity:** last session = now, stopped at "Discovery handoff complete", no
   resume file
 
@@ -533,9 +567,11 @@ Created:
   .planning/github-issues.json    Requirement → GitHub issue mapping (if pushed)
   CLAUDE.md                       Updated with Discovery references
 
+Project Charter: docs/discovery/PROJECT-CHARTER.md — {CHARTER_STATE}{, started on --unsigned: sign-off still owed}
+
 Discovery Traceability:
   Discovery sessions → _pp-handoff.md → pp-core artifacts → (optional) GitHub issues
-  Requirement IDs (FR-xxx, US-xxx) carry through the full chain
+  Requirement IDs (<PREFIX>-nn, N-, E-, US-) carry through the full chain unchanged
 
 Next steps:
   1. Run /pp-plan-phase 1 to create the first phase plan

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

@@ -0,0 +1,83 @@
+# Discuss-phase — Discovery extract and the R2 amend rule
+
+> Lazy-loaded from `workflows/discuss-phase.md` (`analyze_phase` 1b, `discuss_areas`, `write_context`).
+> Inert on a project without `.planning/discovery/`: every command below exits 0 with nothing to
+> inject, and nothing in this file runs. Contract: `references/discovery-build-consumption.md`.
+
+## A. Render the extract (analyze_phase, before 1b)
+
+```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
+DISCOVERY_JSON=$(pp_run query discovery.for-phase "${PHASE}" 2>/dev/null || true)
+if [[ "$DISCOVERY_JSON" == @file:* ]]; then DISCOVERY_JSON=$(cat "${DISCOVERY_JSON#@file:}"); fi
+DISCOVERY_PRESENT=$(printf '%s' "$DISCOVERY_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{const o=JSON.parse(s);console.log(o.present===true&&o.ok===true?'true':'false')}catch{console.log('false')}})")
+if [ "$DISCOVERY_PRESENT" = true ]; then
+  DISCOVERY_EXTRACT=$(pp_run query discovery.for-phase "${PHASE}" --markdown)
+  DISCOVERY_ARTIFACTS=$(printf '%s' "$DISCOVERY_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{const o=JSON.parse(s);console.log((o.artifacts||[]).join(', '))})")
+  echo "DISCOVERY_ARTIFACTS=${DISCOVERY_ARTIFACTS}"
+fi
+```
+
+A non-zero exit here is a structural fault in a discovery artifact (`discovery_for_phase_failed`):
+print the fault list and stop — the sprint's own check names the row to fix; planning on a
+malformed register copies the malformation into the build.
+
+When `DISCOVERY_PRESENT` is `true` (the project ran the sprint — even when the extract says
+`Requirement IDs: none resolved`, which tells the planner that ROADMAP.md names no requirement
+IDs for this phase and is worth seeing):
+
+- **Canonical refs are artifact paths.** Add every path in `DISCOVERY_ARTIFACTS` to the canonical
+  refs accumulator. Never add a `.planning/discovery/session-NN.md`: if ROADMAP.md's
+  `Canonical refs:` line names one (a pre-Batch-4 roadmap), replace it with the artifact paths.
+- **Answered by Discovery.** Before proposing a gray area, read the extract. A question the extract
+  answers — a field, a rule, a role, a flow step, a screen, an acceptance criterion — is
+  pre-answered: list it under **Answered by Discovery** in `present_gray_areas` with the row key
+  (`_rules.md BR-02`), and do not ask it. The test project's "the assistant asked what Discovery
+  had answered" finding is the defect this closes.
+- Gray areas are the gaps the extract leaves (an implementation choice no row decides) and the
+  rows that contradict each other or the codebase.
+
+## B. Write the extract into CONTEXT.md (write_context)
+
+When `DISCOVERY_PRESENT` is `true`, add this section after `<canonical_refs>`, the extract pasted
+byte for byte — markers included, nothing edited:
+
+```markdown
+<discovery_extract>
+## Discovery Extract
+
+**Rows of the Discovery registers that cite this phase's requirement IDs. Downstream agents read
+these before planning; the acceptance criteria are the UAT.**
+
+${DISCOVERY_EXTRACT}
+
+</discovery_extract>
+```
+
+The extract is a render, not a record: a later `/pp-plan-phase` renders it again from the
+registers, so a hand edit here is lost by design (R2 — the register is the source).
+
+## C. R2 — a decision that changes a discovery fact
+
+When a decision taken in `discuss_areas` changes something a register records (a field, a rule, a
+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`)
+   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
+   `_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
+   Version history row naming `D-P${PADDED_PHASE}-<n>` and the row amended; run
+   `pp_run query discovery.charter-check`. A signed charter is not silently superseded.
+4. **Re-render.** Run step A again so `DISCOVERY_EXTRACT` carries the amended cell; the decision
+   itself is recorded in `<decisions>` as usual, with the row key it amended.
+
+CONTEXT.md and PLAN.md hold the extract, never an override: a decision written only in
+`<decisions>` while the register says otherwise is the drift this rule exists to prevent.

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

@@ -91,6 +91,10 @@ Every entry needs a full relative path — not just a name.]
 
 </canonical_refs>
 
+[Include `<discovery_extract>` only when `DISCOVERY_PRESENT` is true (workflows/discuss-phase/discovery.md § B):
+the `pp_run query discovery.for-phase` render pasted byte for byte between its `<!-- discovery:auto -->` markers.
+Omit the whole block on a project without .planning/discovery/.]
+
 <code_context>
 ## Existing Code Insights
 

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

@@ -229,7 +229,7 @@ If a checkpoint file exists:
 
 **If `--auto`:** Auto-select "Resume" — load checkpoint and continue from last completed area.
 
-**Otherwise:** AskUserQuestion (header: "Resume"; question: "Found interrupted discussion checkpoint ({N} areas completed out of {M}). Resume from where you left off?"; options: "Resume" / "Start fresh"). On "Resume", parse the checkpoint JSON, load `decisions` into the internal accumulator, set `areas_completed` to skip those areas, continue to `present_gray_areas` with only the remaining areas. On "Start fresh", delete the checkpoint and continue.
+**Otherwise:** AskUserQuestion (header: "Resume"; question: "Found interrupted discussion checkpoint ({N} areas completed out of {M}). Resume from where you left off?"; options: "Resume" / "Start fresh"). On "Resume", parse the checkpoint JSON, load `decisions` into the accumulator, skip the `areas_completed` areas, continue to `present_gray_areas` with the rest. On "Start fresh", delete the checkpoint and continue.
 
 Check `has_plans` and `plan_count` from init. **If `has_plans` is true:**
 
@@ -314,8 +314,10 @@ Analyze the phase to identify gray areas. Use both `prior_decisions` and `codeba
 
 1. **Domain boundary** — What capability is this phase delivering? State it clearly.
 
+1a. **Discovery extract** — Read and run `workflows/discuss-phase/discovery.md` § A: it renders the discovery register rows citing this phase's requirement IDs; questions they answer are pre-answered. Inert without `.planning/discovery/`.
+
 1b. **Initialize canonical refs accumulator** — Start building `<canonical_refs>` for CONTEXT.md. Sources:
-   - **Now:** Copy `Canonical refs:` from ROADMAP.md for this phase. Expand each to a full relative path. Check REQUIREMENTS.md and PROJECT.md for specs/ADRs referenced.
+   - **Now:** Copy `Canonical refs:` from ROADMAP.md for this phase (artifact paths, not session files). Expand each to a full relative path. Check REQUIREMENTS.md and PROJECT.md for specs/ADRs referenced.
    - **`scout_codebase`:** If existing code references docs (e.g., comments citing ADRs), add those.
    - **`discuss_areas`:** When the user says "read X", "check Y", or references any doc/spec/ADR — add it immediately. These are often the MOST important refs.
 
@@ -329,7 +331,7 @@ Analyze the phase to identify gray areas. Use both `prior_decisions` and `codeba
 
 4. **Skip assessment** — If no meaningful gray areas exist (pure infrastructure, clear-cut implementation, all already decided), the phase may not need discussion.
 
-**Advisor mode hand-off:** If `ADVISOR_MODE` is true, follow `workflows/discuss-phase/modes/advisor.md` for the rest of analyze/discuss flow (it adds an `advisor_research` substep and replaces the standard `discuss_areas` with table-first selection). The detection block (USER-PROFILE.md existence + non-technical-owner signals + calibration tier resolution) lives in that file — read it once when ADVISOR_MODE is true and follow its rules.
+**Advisor mode hand-off:** If `ADVISOR_MODE` is true, follow `workflows/discuss-phase/modes/advisor.md` for the rest of the analyze/discuss flow (adds an `advisor_research` substep; table-first selection replaces `discuss_areas`). Its detection block (USER-PROFILE.md, non-technical-owner signals, calibration tier) lives there — read it once.
 </step>
 
 <step name="present_gray_areas">
@@ -377,15 +379,16 @@ Overlays (combine with the active mode):
 - `--batch` → `workflows/discuss-phase/modes/batch.md` (group 2–5 questions per turn)
 - `--analyze` → `workflows/discuss-phase/modes/analyze.md` (trade-off table before each question)
 
-**Overlay stacking:** overlays combine and apply outer→inner in fixed order `--analyze` → `--batch` → `--text` (e.g., `--batch --analyze` = trade-off table per question group; add `--text` for plain-text rendering). Mode-specific precedence (e.g., `--auto --power`) is documented in each overlay file's "Combination rules" section.
+**Overlay stacking:** overlays combine outer→inner in fixed order `--analyze` → `--batch` → `--text` (`--batch --analyze` = trade-off table per question group; add `--text` for plain-text rendering). Mode-specific precedence (e.g., `--auto --power`) is documented in each overlay file's "Combination rules" section.
 
 All modes preserve the universal rules below.
 
 **Universal rules (apply to every mode):**
 
-- **Canonical ref accumulation** — when the user references a doc/spec/ADR during any answer, immediately Read it (or confirm it exists) and add it to the canonical refs accumulator with full relative path. Use what you learned to inform subsequent questions. These docs are often MORE important than ROADMAP.md refs because the user specifically wants downstream agents to follow them.
+- **Canonical ref accumulation** — when the user references a doc/spec/ADR during any answer, immediately Read it (or confirm it exists) and add it to the accumulator with full relative path; use it to inform later questions. These often matter MORE than ROADMAP.md refs.
+- **Discovery amend (R2)** — a decision changing a discovery register fact follows `discovery.md` § C: amend the row in place, re-run its check, bump the charter.
 - **Scope creep** — if user mentions something outside the phase domain, capture as deferred idea and redirect.
-- **Incremental checkpoint** — after each area completes, write `${phase_dir}/${padded_phase}-DISCUSS-CHECKPOINT.json`. Read `workflows/discuss-phase/templates/checkpoint.json` for the schema. The checkpoint is structured state, not the canonical CONTEXT.md (`write_context` produces the canonical output). On session resume, the parent's `check_existing` step detects the checkpoint and offers to resume.
+- **Incremental checkpoint** — after each area completes, write `${phase_dir}/${padded_phase}-DISCUSS-CHECKPOINT.json` (schema: `workflows/discuss-phase/templates/checkpoint.json`). It is structured state, not CONTEXT.md (`write_context` writes the canonical output); `check_existing` detects it on resume.
 - **Discussion log accumulation** — for each question asked, accumulate area name, options presented, user's selection, follow-up notes. Used by `git_commit` to write DISCUSSION-LOG.md.
 </step>
 
@@ -410,7 +413,7 @@ Set `phase_dir="${expected_phase_dir}"` after creation.
 Read(workflows/discuss-phase/templates/context.md)
 ```
 
-The template documents variable substitutions and conditional sections. Substitute live values for `[X]`, `[Name]`, `[date]`, `${padded_phase}`, `{N}`. Include `<spec_lock>` only when `spec_loaded = true`. Include "Folded Todos" / "Reviewed Todos" subsections only when the `cross_reference_todos` step folded or reviewed todos.
+The template documents variable substitutions and conditional sections. Substitute live values for `[X]`, `[Name]`, `[date]`, `${padded_phase}`, `{N}`. Include `<spec_lock>` only when `spec_loaded = true`; `<discovery_extract>` only when `DISCOVERY_PRESENT` is true (`discovery.md` § B); "Folded Todos" / "Reviewed Todos" only when `cross_reference_todos` folded or reviewed todos.
 
 **SPEC.md integration** — If `spec_loaded = true`:
 - Add the `<spec_lock>` section immediately after `<domain>`.

package/pp-core/workflows/new-project.md

@@ -501,9 +501,9 @@ Initialize with any decisions made during questioning:
 ```markdown
 ## Key Decisions
 
-| Decision | Rationale | Outcome |
-|----------|-----------|---------|
-| [Choice from questioning] | [Why] | — Pending |
+| ID | Decision | Rationale | Outcome |
+|----|----------|-----------|---------|
+| — | [Choice from questioning] | [Why] | — Pending |
 ```
 
 **Last updated footer:**

package/pp-core/workflows/plan-phase/steps/discovery-extract.md

@@ -0,0 +1,41 @@
+# Plan-phase step — Discovery extract (R1)
+
+> Read and executed from `workflows/plan-phase.md` §7 after the context paths are extracted and
+> before the researcher (§5.1) and planner (§8) prompts are built. Inert on a project without
+> `.planning/discovery/`. Contract: `references/discovery-build-consumption.md`.
+
+Render the phase's discovery rows fresh — the registers may have been amended since
+`/pp-discuss-phase` wrote CONTEXT.md — into one file the researcher and the planner read:
+
+```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
+DISCOVERY_EXTRACT_PATH=""
+_DX_JSON=$(pp_run query discovery.for-phase "${PHASE_NUMBER}" 2>/dev/null || true)
+if [[ "$_DX_JSON" == @file:* ]]; then _DX_JSON=$(cat "${_DX_JSON#@file:}"); fi
+_DX_PRESENT=$(printf '%s' "$_DX_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{const o=JSON.parse(s);console.log(o.present===true&&o.ok===true?'true':'false')}catch{console.log('false')}})")
+if [ "$_DX_PRESENT" = true ]; then
+  DISCOVERY_EXTRACT_PATH="${PHASE_DIR}/${PADDED_PHASE}-DISCOVERY-EXTRACT.md"
+  pp_run query discovery.for-phase "${PHASE_NUMBER}" --markdown > "${DISCOVERY_EXTRACT_PATH}"
+  echo "DISCOVERY_EXTRACT_PATH=${DISCOVERY_EXTRACT_PATH}"
+else
+  rm -f "${PHASE_DIR}/${PADDED_PHASE}-DISCOVERY-EXTRACT.md"
+fi
+```
+
+A non-zero exit from the first command is a structural fault in a discovery artifact
+(`discovery_for_phase_failed`): print the fault list and stop. Planning on a malformed register
+copies the malformation into the build; the sprint's own check names the row to fix.
+
+When `DISCOVERY_EXTRACT_PATH` is non-empty:
+
+- add `- {DISCOVERY_EXTRACT_PATH} (Discovery extract — register rows citing this phase's
+  requirement IDs; required reading, never open a session-NN.md)` to the `<files_to_read>` of
+  the researcher prompt (§5.1) and the planner prompt (§8);
+- the planner embeds the file's content verbatim — markers included — as the `<discovery_extract>`
+  block of every PLAN.md it writes, after `<context>` (and after `<vault_standards>` when present)
+  and before `<tasks>`;
+- the file is a render and is never committed: it is regenerated on every planning run and
+  `*-DISCOVERY-EXTRACT.md` is not a phase artifact.
+
+The name is deliberate: `{padded}-DISCOVERY.md` already belongs to the planner's library
+discovery protocol and is a different thing.