@pareto4/pp-core 1.19.0 → 1.21.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/execute-phase/steps/check-query-gate.md

@@ -54,13 +54,13 @@ old numbers, which is how 05-13 shifted three rows ~200 lines into a different f
 
 | Query | Handler branch / function | Emits boolean `block` on every path? | Emission site(s) |
 |-------|---------------------------|--------------------------------------|------------------|
-| `gap-analysis.plan-post` | `gap-analysis-plan-post` branch (`cmdGapAnalysisPlanPost`) | yes — always `false` (advisory by design) | `src/check-command-router.cts:1096` |
-| `ship.platform-drift` | `ship-platform-drift` branch (`cmdShipPlatformDrift`) | yes — the only producer that can emit `block: true` from a threshold comparison | `src/check-command-router.cts:1198,1208,1217,1234,1276,1285,1299` |
-| `tdd.review-checkpoint` | `tdd-review-checkpoint` branch | yes — `block = violations > 0`, advisory in the capability | `src/check-command-router.cts:977,1051` |
-| `ui.plan-gate` | `ui-plan-gate` branch (`computeUiPlanGate`) | yes — `block = frontend && !hasUiSpec` | `src/check-command-router.cts:703` (emitted at `:727`) |
-| `ui.safety-gate` | `ui-safety-gate` branch (`computeUiSafetyGate`) | yes — `block = frontend && hasUiFiles && !hasUiSpec` | `src/check-command-router.cts:830` (emitted at `:856`) |
-| `vault.status` | `vault-status` branch (`cmdVaultStatus`) | yes — COMPUTED, not constant: `block` is the `vault.required` policy applied to the shared tier-keyed verdict leaf (`computeVaultVerdict`, GATE-01 / D-VH-4). It is `false` with the policy off (STRICT-01's byte-identical promise), on the inert path (`.platform-bindings.json` absent — that branch runs FIRST by requirement, T-02-28, because `tier !== 'client'` is true of `undefined` and would otherwise block every non-Pareto project), and for a present, fresh, client-tier vault; it is `true` on a required miss, on a fallback-tier load, on a stale client vault whatever its source (D-08-01; the block skips staleness only when `vault.cache_ttl_hours` is 0, D-08-28), and on a client cache fetched from a ref the project no longer configures (D-08-23). The attributed override (`applyVaultOverride`, GATE-07) then gets the last word on every blocking path, and that overwrite is the last emission site cited; and on a passing required-on verdict the envelope now carries a `message` (the success line, D-08-20) — the enforcer's every-run passthrough prints it. | `src/check-command-router.cts:1655,1670,1709,1736,1797` (02-11: CHECKED by the same two-directional probe as the other rows — every cited line lies inside `cmdVaultStatus` and emits a block, and every emission site is cited. This was the one row the probe did NOT cover, so it is the row that rotted: wave 1 wrote the claim before 02-06 computed the block, and 05-13 shifted the citations arithmetically into the manifest-sanitiser, ~200 lines outside the handler) 14-06: + the envelope always carries `reason`, `status` may be `degraded` (index missing / unparseable / empty / unresolvable / unchecked, D-12), the flat index fields follow the override keys, and the healthy message is the one-line standards card (D-15); a degraded index blocks exactly when `vault.required` is on, through the same override (D-13), so it adds no emission site of its own. |
-| `vault.trace` | `vault-trace` branch (`cmdVaultTrace`) — declared by the `vault` capability (`when: vault.enabled`) at **four** points, `plan:post`, `execute:post`, `ship:pre` and `verify:post`, all `blocking: true` / `onError: halt`, and once more at `ship:pre` as a seal gate (`onRecordedArtifacts: true`) that renders with `vault.enabled` off over a phase holding vault records (16-08). It judges each PLAN's `<vault_standards>` block and each SUMMARY's `## Standards Consulted` section through `src/vault-standards.cts` and fails closed on the `standards_*` kinds (`standards_block_absent`, `standards_block_duplicate`, `standards_block_unterminated`, `standards_block_malformed`, `standards_reason_invalid`, `standards_document_duplicate`, `standards_degraded_mixed`, `standards_none_without_reason`, `standards_path_not_resolved`, `standards_pin_mismatch`, `standards_cache_unreadable`, `standards_degraded_untrue`, `standards_consulted_absent`, `standards_consulted_mismatch`, `standards_plan_id_mismatch`, `standards_pair_missing`, `standards_orphan_summary`, `standards_anchor_malformed`). Reads `--stage` (04-03) and `--unpaired` (04-07, D-10); `ship:pre` sets `GATE_UNPAIRED=strict` unconditionally, `verify:post` sets it only on a full-phase run and leaves it unset when **either** partial-execution mode is active — the host's `WAVE_FILTER` set, or `--gaps-only` (04-12, CR-04; 04-18, WR-01) — and the other two leave the tolerant default | yes — `false` before any policy is read (inert), `false` with status `inactive` when `vault.enabled` is off and the phase holds no vault records, `true` once a standards record fails to validate; an agreeing degraded record with `vault.required` off is `false` with a message (D-29), and a recorded override is `false` at the tolerant points and `true` at the strict ones; `true` with status `disabled_with_artifacts` when `vault.enabled` is off and the positional's phase (or plan file) holds engine-written vault records (16-09, SEAL-02, D-21) — the answer the `ship:pre` seal gate dispatches for | `src/check-command-router.cts:3011,3023,3026,3058,3089,3114,3144,3170,3445` (04-16: CHECKED — a test asserts every line cited here lies inside `cmdVaultTrace` and carries a `block` emission, because four plans in this pass moved these numbers and nothing noticed). 16-07 (SEAL-01): at the strict points only, `appendSealProblems` compares the phase's recorded end anchors with `HEAD` through bounded git and adds `uncovered_source_commit` (a source commit after the ends that no record's start-end range covers), `anchor_missing`, `anchor_start_missing`, `anchor_unknown`, `anchor_not_ancestor` and `seal_could_not_check` (all blocking) and the `anchor_backfilled` note; it pushes problems into `checked` and owns no emission site and no status. 16-09 (SEAL-02): + the `disabled_with_artifacts` emission inside the switch-off guard. Standards-only vault: re-derived with the probe's own `handlerRange`/`emitsBlock` after the second record family, the invalid-config refusal and the envelope's mode tag left the handler. |
+| `gap-analysis.plan-post` | `gap-analysis-plan-post` branch (`cmdGapAnalysisPlanPost`) | yes — always `false` (advisory by design) | `src/check-command-router.cts:1151` |
+| `ship.platform-drift` | `ship-platform-drift` branch (`cmdShipPlatformDrift`) | yes — the only producer that can emit `block: true` from a threshold comparison | `src/check-command-router.cts:1253,1263,1272,1289,1331,1340,1354` |
+| `tdd.review-checkpoint` | `tdd-review-checkpoint` branch | yes — `block = violations > 0`, advisory in the capability | `src/check-command-router.cts:1032,1106` |
+| `ui.plan-gate` | `ui-plan-gate` branch (`computeUiPlanGate`) | yes — `block = frontend && !hasUiSpec` | `src/check-command-router.cts:705` (emitted at `:729`) |
+| `ui.safety-gate` | `ui-safety-gate` branch (`computeUiSafetyGate`) | yes — `block = frontend && hasUiFiles && !hasUiSpec` | `src/check-command-router.cts:885` (emitted at `:911`) |
+| `vault.status` | `vault-status` branch (`cmdVaultStatus`) | yes — COMPUTED, not constant: `block` is the `vault.required` policy applied to the shared tier-keyed verdict leaf (`computeVaultVerdict`, GATE-01 / D-VH-4). It is `false` with the policy off (STRICT-01's byte-identical promise), on the inert path (`.platform-bindings.json` absent — that branch runs FIRST by requirement, T-02-28, because `tier !== 'client'` is true of `undefined` and would otherwise block every non-Pareto project), and for a present, fresh, client-tier vault; it is `true` on a required miss, on a fallback-tier load, on a stale client vault whatever its source (D-08-01; the block skips staleness only when `vault.cache_ttl_hours` is 0, D-08-28), and on a client cache fetched from a ref the project no longer configures (D-08-23). The attributed override (`applyVaultOverride`, GATE-07) then gets the last word on every blocking path, and that overwrite is the last emission site cited; and on a passing required-on verdict the envelope now carries a `message` (the success line, D-08-20) — the enforcer's every-run passthrough prints it. | `src/check-command-router.cts:1710,1725,1764,1791,1852` (02-11: CHECKED by the same two-directional probe as the other rows — every cited line lies inside `cmdVaultStatus` and emits a block, and every emission site is cited. This was the one row the probe did NOT cover, so it is the row that rotted: wave 1 wrote the claim before 02-06 computed the block, and 05-13 shifted the citations arithmetically into the manifest-sanitiser, ~200 lines outside the handler) 14-06: + the envelope always carries `reason`, `status` may be `degraded` (index missing / unparseable / empty / unresolvable / unchecked, D-12), the flat index fields follow the override keys, and the healthy message is the one-line standards card (D-15); a degraded index blocks exactly when `vault.required` is on, through the same override (D-13), so it adds no emission site of its own. |
+| `vault.trace` | `vault-trace` branch (`cmdVaultTrace`) — declared by the `vault` capability (`when: vault.enabled`) at **four** points, `plan:post`, `execute:post`, `ship:pre` and `verify:post`, all `blocking: true` / `onError: halt`, and once more at `ship:pre` as a seal gate (`onRecordedArtifacts: true`) that renders with `vault.enabled` off over a phase holding vault records (16-08). It judges each PLAN's `<vault_standards>` block and each SUMMARY's `## Standards Consulted` section through `src/vault-standards.cts` and fails closed on the `standards_*` kinds (`standards_block_absent`, `standards_block_duplicate`, `standards_block_unterminated`, `standards_block_malformed`, `standards_reason_invalid`, `standards_document_duplicate`, `standards_degraded_mixed`, `standards_none_without_reason`, `standards_path_not_resolved`, `standards_pin_mismatch`, `standards_cache_unreadable`, `standards_degraded_untrue`, `standards_consulted_absent`, `standards_consulted_mismatch`, `standards_plan_id_mismatch`, `standards_pair_missing`, `standards_orphan_summary`, `standards_anchor_malformed`). Reads `--stage` (04-03) and `--unpaired` (04-07, D-10); `ship:pre` sets `GATE_UNPAIRED=strict` unconditionally, `verify:post` sets it only on a full-phase run and leaves it unset when **either** partial-execution mode is active — the host's `WAVE_FILTER` set, or `--gaps-only` (04-12, CR-04; 04-18, WR-01) — and the other two leave the tolerant default | yes — `false` before any policy is read (inert), `false` with status `inactive` when `vault.enabled` is off and the phase holds no vault records, `true` once a standards record fails to validate; an agreeing degraded record with `vault.required` off is `false` with a message (D-29), and a recorded override is `false` at the tolerant points and `true` at the strict ones; `true` with status `disabled_with_artifacts` when `vault.enabled` is off and the positional's phase (or plan file) holds engine-written vault records (16-09, SEAL-02, D-21) — the answer the `ship:pre` seal gate dispatches for | `src/check-command-router.cts:3066,3078,3081,3113,3144,3169,3199,3225,3500` (04-16: CHECKED — a test asserts every line cited here lies inside `cmdVaultTrace` and carries a `block` emission, because four plans in this pass moved these numbers and nothing noticed). 16-07 (SEAL-01): at the strict points only, `appendSealProblems` compares the phase's recorded end anchors with `HEAD` through bounded git and adds `uncovered_source_commit` (a source commit after the ends that no record's start-end range covers), `anchor_missing`, `anchor_start_missing`, `anchor_unknown`, `anchor_not_ancestor` and `seal_could_not_check` (all blocking) and the `anchor_backfilled` note; it pushes problems into `checked` and owns no emission site and no status. 16-09 (SEAL-02): + the `disabled_with_artifacts` emission inside the switch-off guard. Standards-only vault: re-derived with the probe's own `handlerRange`/`emitsBlock` after the second record family, the invalid-config refusal and the envelope's mode tag left the handler. |
 | `verify.codebase-drift` | `verify-codebase-drift` branch (`verify.cmdVerifyCodebaseDrift`) | yes — `block = action_required` | `src/verify.cts:2134,2149,2164,2186,2231,2246` |
 | `verify.schema-drift` | `verify-schema-drift` branch (`verify.cmdVerifySchemaDrift`) | yes — `block = !skipped && driftDetected` | `src/verify.cts:2051,2071,2108` |
 

package/pp-core/workflows/execute-phase/steps/codebase-drift-gate.md

@@ -60,6 +60,7 @@ from step `init_context` is for `pp-executor`, not the mapper):
 # with the single-canonical-preamble parity invariant (#619). This block only runs on the
 # `auto-remap` directive, which is always reached after the drift check above has run.
 AGENT_SKILLS_MAPPER=$(pp_run query agent-skills pp-codebase-mapper)
+pp_run timeline start other "${PHASE_NUMBER}" --agent pp-codebase-mapper --source execute-phase --model inherit || true
 ```
 
 Then spawn `pp-codebase-mapper` agents with the `--paths` hint (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze):
@@ -80,11 +81,11 @@ ${AGENT_SKILLS_MAPPER}"
 
 > **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
 
-If the spawn fails or the agent reports an error: log `Codebase drift
+If the spawn fails or the agent reports an error: run `pp_run timeline end other "${PHASE_NUMBER}" failed || true`, then log `Codebase drift
 auto-remap failed: {reason}` and continue to `verify_phase_goal`. The phase
 is NOT failed by a remap failure.
 
-If the remap succeeds: log `Codebase drift auto-remap completed for paths:
+If the remap succeeds: run `pp_run timeline end other "${PHASE_NUMBER}" complete || true`, then log `Codebase drift auto-remap completed for paths:
 {affected_paths}` and continue to `verify_phase_goal`.
 
 The two relevant config keys (continue on error / failure if either is invalid):