@pareto4/pp-core 1.19.0 → 1.20.0

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

@@ -63,7 +63,7 @@ for the plan-checker gate to be meaningful.
 
 ## 0. Git Branch Invariant
 
-**Do not create, rename, or switch git branches during plan-phase.** Branch identity is established at discuss-phase and is owned by the user's git workflow. A phase rename in ROADMAP.md is a plan-level change only — it does not mutate git branch names. If `phase_slug` in the init JSON differs from the current branch name, that is expected and correct; leave the branch unchanged.
+**Do not create, rename, or switch git branches during plan-phase.** Branch identity is established at discuss-phase and owned by the user's git workflow. A phase rename in ROADMAP.md is a plan-level change only — it never mutates branch names. A `phase_slug` differing from the current branch name is expected; leave the branch unchanged.
 
 ## 1. Initialize
 
@@ -96,7 +96,7 @@ Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_
 
 ## 1.5. Closed-Phase Gate (#3569)
 
-The init JSON includes `phase_status` — one of `Pending | Planned | In Progress | Executed | Complete | Needs Review`. `Complete` means the phase has all summaries AND a `VERIFICATION.md` with `status: passed`. Replanning a closed phase silently rewrites plan docs that no longer match the shipped code, so the workflow must hard-stop here unless the operator explicitly overrides.
+The init JSON includes `phase_status` — one of `Pending | Planned | In Progress | Executed | Complete | Needs Review`. `Complete` means all summaries exist AND a `VERIFICATION.md` with `status: passed`. Replanning a closed phase silently rewrites plan docs that no longer match the shipped code; the workflow hard-stops here unless the operator overrides.
 
 Parse `phase_status` from the init JSON, then:
 
@@ -142,7 +142,7 @@ The gate fires only on `Complete`. `Executed` and `Needs Review` are not gated
 
 Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--research-phase <N>`, `--gaps`, `--skip-verify`, `--skip-ui`, `--prd <filepath>`, `--ingest <path-or-glob>`, `--ingest-format <auto|nygard|madr|narrative>`, `--reviews`, `--text`, `--bounce`, `--skip-bounce`, `--chunked`, `--mvp`, `--tdd`, `--granularity <coarse|standard|fine>`, `--force` (override closed-phase gate, see §1.5), `--unattended`).
 
-**`--research-phase <N>` — research-only mode (#3042 + #3044).** When this flag is present, parse `<N>` as the phase number (overrides any positional phase argument), set `RESEARCH_ONLY=true`, and treat the rest of this workflow as a research-dispatch only — the planner spawn (step 8), plan-checker, verification, gaps, bounce, and post-planning-gaps blocks all skip on `RESEARCH_ONLY`. Use this for cross-phase research, doc review before committing to a planning approach, and correction-without-replanning loops. Replaces the deleted `/pp-research-phase` command.
+**`--research-phase <N>` — research-only mode (#3042 + #3044).** When present, parse `<N>` as the phase number (overrides any positional phase argument), set `RESEARCH_ONLY=true`, and treat the rest of this workflow as a research dispatch only — the planner spawn (step 8), plan-checker, verification, gaps, bounce and post-planning-gaps blocks all skip on `RESEARCH_ONLY`. Use it for cross-phase research, doc review before committing to an approach, and correction-without-replanning loops. Replaces the deleted `/pp-research-phase` command.
 
 In research-only mode, two modifiers control behavior when `RESEARCH.md` already exists:
 
@@ -162,9 +162,9 @@ if $RESEARCH_ONLY && [[ "$ARGUMENTS" =~ (^|[[:space:]])--view([[:space:]]|$) ]];
 fi
 ```
 
-**`--granularity <coarse|standard|fine>` — CLI override (#703).** When present, this value is the resolved granularity passed to the planner — it wins over any per-phase `granularities.<type>` config, top-level `granularity` config, or project defaults. The init JSON always includes a `granularity` field reflecting the resolved value; read it from there. Invalid values (anything other than `coarse`, `standard`, `fine`) cause an error at the CLI boundary.
+**`--granularity <coarse|standard|fine>` — CLI override (#703).** When present, this is the resolved granularity passed to the planner — it wins over per-phase `granularities.<type>` config, top-level `granularity` config and project defaults. The init JSON always carries the resolved `granularity` field; read it from there. Any other value (not `coarse`, `standard`, `fine`) errors at the CLI boundary.
 
-**`--unattended`** — set by `/pp:autonomous` (never `--auto`, which would auto-advance into execute-phase). At each prompt site marked `U-Pn` below, do not prompt: apply rule `U-Pn` from `pp-core/references/autonomous-best-effort.md` (Read it at the first such site) and append the record it names to the phase's AUTONOMOUS-REPORT. It does not touch `workflow._auto_chain_active`.
+**`--unattended`** — set by `/pp:autonomous` (never `--auto`, which would auto-advance into execute-phase). At each prompt site marked `U-Pn` below, do not prompt: apply rule `U-Pn` from `pp-core/references/autonomous-best-effort.md` (Read at first use) and append the record it names to the phase's AUTONOMOUS-REPORT. It does not touch `workflow._auto_chain_active`.
 
 Set `TEXT_MODE=true` if `--text` is present in $ARGUMENTS OR `text_mode` from init JSON is `true`. When `TEXT_MODE` is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for Claude Code remote sessions (`/rc` mode) where TUI menus don't work through the Claude App.
 
@@ -194,7 +194,7 @@ When `WALKING_SKELETON=true`:
 - Planner is instructed to produce `SKELETON.md` in the phase directory alongside `PLAN.md`. The template lives at `~/.claude/pp-core/references/skeleton-template.md` — the planner reads it when producing SKELETON.md (lazy; not loaded on non-skeleton runs).
 - The plan must scaffold project + routing + one real DB read/write + one real UI interaction + dev deployment — the thinnest possible end-to-end working slice.
 
-**Interaction with `--prd <filepath>`.** `--mvp` and `--prd` compose. The PRD express path (Step 3.5) creates `CONTEXT.md` from the PRD file and continues to research; the Walking Skeleton gate fires independently from the conditions above. When both are active on Phase 1 of a new project, the planner receives `WALKING_SKELETON=true` and PRD-derived context simultaneously — the PRD informs *what the skeleton should prove*. No precedence is needed; the two signals are orthogonal. See [`references/mvp-concepts.md`](../references/mvp-concepts.md) for the broader interaction map.
+**Interaction with `--prd <filepath>`.** `--mvp` and `--prd` compose: the PRD express path (Step 3.5) creates `CONTEXT.md` from the PRD file and continues to research; the Walking Skeleton gate fires independently. On Phase 1 of a new project the planner receives `WALKING_SKELETON=true` and PRD-derived context together — the PRD informs *what the skeleton should prove*; the two signals are orthogonal. See [`references/mvp-concepts.md`](../references/mvp-concepts.md).
 
 Extract express-path args from $ARGUMENTS: `PRD_FILE` (`--prd <filepath>`), `INGEST_PATH` (`--ingest <path-or-glob>`), and optional `INGEST_FORMAT` (`--ingest-format <auto|nygard|madr|narrative>`, default `auto`).
 
@@ -527,7 +527,9 @@ Read and execute `pp-core/workflows/execute-phase/steps/vault-fetch.md` — the
 
 ### into:researcher contributions
 
-In `PLAN_PRE_HOOKS_JSON`, read active plan:pre entries where `kind == "contribution"` and `into == "researcher"` (in array order). If none, inject nothing. If present, append each entry's `fragment.inline` verbatim to `filled_research_hook_fragment` (or add it as a `<files_to_read>`/context line in the researcher prompt) — typically a pointer to `.planning/vault/SUMMARY.md` (the bounded vault index). Inject verbatim — do not paraphrase.
+In `PLAN_PRE_HOOKS_JSON`, read active plan:pre entries where `kind == "contribution"` and `into == "researcher"` (in array order). If none, inject nothing. If present, append each entry's `fragment.inline` verbatim to `filled_research_hook_fragment` (or as a `<files_to_read>` line in the researcher prompt) — typically a pointer to `.planning/vault/SUMMARY.md`. Inject verbatim — do not paraphrase.
+
+When `DISCOVERY_EXTRACT_PATH` (§7) is set, add `- {DISCOVERY_EXTRACT_PATH} (Discovery extract — required reading)` to the researcher `<files_to_read>`.
 
 Find the active `research` step hook in `PLAN_PRE_HOOKS_JSON`. Use the hook's `fragment.inline` as the prompt template and substitute the phase fields below before spawning its declared `ref.agent`.
 
@@ -612,7 +614,7 @@ Resolve active contribution hooks from `PLAN_PRE_HOOKS_JSON` where `kind == "con
 
 **If no active security contribution hook exists:** Skip to step 5.6.
 
-**If an active security contribution hook exists:** Read `SECURITY_ASVS` from the active hook's `configValues.security_asvs_level` (default: `1`) and `SECURITY_BLOCK` from `configValues.security_block_on` (default: `"high"`). These values are resolved by the capability registry from user config using the same four-level precedence as hook activation — no inline `config-get` is needed.
+**If an active security contribution hook exists:** Read `SECURITY_ASVS` from the active hook's `configValues.security_asvs_level` (default: `1`) and `SECURITY_BLOCK` from `configValues.security_block_on` (default: `"high"`). The registry resolves them from user config with the same four-level precedence as hook activation — no inline `config-get` is needed.
 
 Display banner:
 
@@ -775,6 +777,8 @@ SPEC_FILE=$(ls "${PHASE_DIR_FOR_SPEC}"/*-SPEC.md 2>/dev/null | grep -Ev -- '-(AI
 SPEC_PATH="${SPEC_FILE}"
 ```
 
+Then Read and execute `pp-core/workflows/plan-phase/steps/discovery-extract.md` (sets `DISCOVERY_EXTRACT_PATH`; inert without `.planning/discovery/`).
+
 ## 7.5. Verify Nyquist Artifacts
 
 Skip if `nyquist_validation_enabled` is false OR `research_enabled` is false.
@@ -890,6 +894,7 @@ Planner prompt:
 - {AI_SPEC_PATH} (AI Design Contract — framework and evaluation strategy, if exists)
 - {UI_SPEC_PATH} (UI Design Contract — visual/interaction specs, if exists)
 - {SPEC_PATH} (Phase SPEC — carries the ## Edge Coverage section to lift covered/backstop edges from, if exists)
+- {DISCOVERY_EXTRACT_PATH} (Discovery extract — required reading, embed verbatim as <discovery_extract>; if exists)
 - {SPIKE_FINDINGS_PATH} (Spike Findings — validated patterns, constraints, landmines from experiments, if exists)
 - {SKETCH_FINDINGS_PATH} (Sketch Findings — validated design decisions, CSS patterns, visual direction, if exists)
 - {API_SURFACE_PATH} (API Surface — HINT ONLY, when intel capability is active; see <intel_surface_hint> below)
@@ -904,7 +909,7 @@ ${CONTEXT_WINDOW >= 500000 ? `
 </files_to_read>
 ${API_SURFACE_PATH ? `
 <intel_surface_hint>
-**API Surface (HINT — may be incomplete):** When \`intel.enabled\` is true, \`.planning/intel/API-SURFACE.md\` lists symbols extracted from the codebase by regex/JS analysis. Prefer symbols listed there when referencing existing code. This surface is regex/JS-derived and MAY BE INCOMPLETE — a symbol's absence means *unknown*, not *nonexistent*. Never treat the surface as exhaustive. If you reference a symbol that is not in the surface and this phase creates it, list it under "Artifacts this phase produces".
+**API Surface (HINT — may be incomplete):** When \`intel.enabled\` is true, \`.planning/intel/API-SURFACE.md\` lists symbols extracted from the codebase by regex/JS analysis. Prefer its symbols when referencing existing code. The surface is regex/JS-derived and MAY BE INCOMPLETE — a symbol's absence means *unknown*, not *nonexistent*; never treat it as exhaustive. If you reference a symbol not in the surface that this phase creates, list it under "Artifacts this phase produces".
 </intel_surface_hint>
 ` : ''}
 ${AGENT_SKILLS_PLANNER}
@@ -944,7 +949,7 @@ Output consumed by /pp:execute-phase. Plans need:
 - Verification criteria
 - must_haves for goal-backward verification
 - If the SPEC has an `## Edge Coverage` section, lift every `covered` edge's acceptance criterion into `must_haves.truths`, and every `backstop` edge into `must_haves.truths` as a non-inferable check (note it needs a held-out/property-based test). `unresolved` edges are explicit assumptions — surface them in the plan, do not silently drop them.
-- If the SPEC has a `## Prohibitions` section, lift every resolved prohibition into the `must_haves.prohibitions:` sibling block (NOT `truths` — ADR-550 D3) carrying `statement` + `status` + `verification`; unresolved prohibitions are explicit assumptions — surface them in the plan, do not silently drop them. A prohibition is a must-NOT (negative) check that belongs in its own `must_haves.prohibitions` block. Never place a must-NOT under `must_haves.truths` — that block keeps positive-observable semantics only.
+- If the SPEC has a `## Prohibitions` section, lift every resolved prohibition into the `must_haves.prohibitions:` sibling block (NOT `truths` — ADR-550 D3) carrying `statement` + `status` + `verification`; unresolved prohibitions are explicit assumptions — surface them in the plan, do not silently drop them. A prohibition is a must-NOT (negative) check with its own `must_haves.prohibitions` block. Never place one under `must_haves.truths`, which keeps positive-observable semantics only.
 - **"Artifacts this phase produces" section (MANDATORY)** — list every symbol this phase creates: decorators, classes, functions, CLI flags, struct/dataclass fields, new file paths. The plan-review-convergence source-grounding pass reads this section to exclude newly-created symbols from drift verification; omitting it causes new symbols to be flagged for acknowledgement.
 </downstream_consumer>
 

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

@@ -85,6 +85,11 @@ reinterpret it.
   range (`filesTruncated` when the list was capped).
 - `gaps[]`: facts the CLI could not establish. Every gap goes into the artifact's `## Not Derived`
   section; a gap is never silently dropped and never turned into a verdict.
+- `deviations[]`: the rows of `.planning/discovery/_deviations.md` when the project ran the
+  Discovery Sprint (`id`, `standard`, `status`, `decision`, `approver`); empty otherwise. An
+  `Approved` deviation that covers a clause turns that document's `FAIL` into `N-A` with the reason
+  `deviation on file: …` — the agent's rule, in `agents/pp-vault-reviewer.md`
+  (`references/discovery-build-consumption.md` § `_deviations.md` read contract).
 
 ## 3. Spawn pp-vault-reviewer
 

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

@@ -1,272 +0,0 @@
-# Bootstrap Template — .planning/discovery/_context.md
-
-> **Lazy-loaded.** Read this file from `workflows/discovery-sprint.md` — from
-> Flow 2 Step 1, or from the Bootstrap Templates section — when
-> `.planning/discovery/_context.md` is absent (first-ever session on this
-> project). Create that file verbatim from the fenced schema below. The path is
-> fixed under `.planning/discovery/` (T-04-03): never a root-level directory,
-> never an absolute path, never a path containing `..`.
-
-**`.planning/discovery/_context.md`:**
-
-```markdown
-# Cross-Session Context — [PROJECT_NAME]
-
-This file accumulates key outputs from each completed session to provide context for subsequent sessions. It is automatically maintained as sessions are completed.
-
----
-
-## Session 1: Kick-off Outputs
-_Populated after Session 1 completion_
-
-### Project Context
-<!-- Notes about the rationale and context -->
-
-### Business Vision
-<!-- Business vision summary, KPIs -->
-
-### Stakeholders
-<!-- Key stakeholder list with roles -->
-
-### Approval Routes
-<!-- Who approves scope, budget, architecture and security deviations, go-live -->
-
-### Platform and Team Shape
-<!-- Mandated platform (D-01-n) or "open"; team shape for the build -->
-
-### Discovery Sprint Scope
-**In Scope:**
--
-
-**Out of Scope:**
--
-
----
-
-## Session 2: As-Is Outputs
-_Populated after Session 2 completion_
-
-### Core Processes
-<!-- Current business processes -->
-
-### Pain Points
-<!-- Prioritized pain points -->
-
-### User Personas
-<!-- Key personas and their journeys -->
-
-### Current Systems
-<!-- Systems landscape -->
-
-### Data Flows
-<!-- How information moves today -->
-
----
-
-## Session 3: To-Be Outputs
-_Populated after Session 3 completion_
-
-### Business Objectives
-<!-- Measurable outcomes and KPIs -->
-
-### MVP Scope
-<!-- What's in/out for MVP -->
-
-### EPICs Summary
-<!-- EPIC registry table -->
-
-### User Stories Summary
-<!-- Story count and distribution -->
-
-### Requirements Summary
-<!-- Copy the rollup:auto totals table verbatim from .planning/discovery/_requirements.md — never hand-count -->
-
----
-
-## Session 4: UX Design Outputs
-_Populated after Session 4 completion_
-
-### Design Principles
-<!-- Numbered design principles -->
-
-### UX Standards
-<!-- Standards Applied: the frontend standard citations and every D-04 deviation -->
-
-### Key Personas (Refined)
-<!-- Persona categories and interaction patterns -->
-
-### Key Screen Decisions
-<!-- Screen layout decisions -->
-
-### Prototype
-<!-- Session 4 Closing Step answer; per /pp-discovery prototype round: flows validated, open feedback count -->
-
----
-
-## Session 5: Architecture Outputs
-_Populated after Session 5 completion_
-
-### Target Architecture
-<!-- Platform, architecture style, ownership -->
-
-### Technology Stack
-<!-- Full stack listing -->
-
-### Key Components
-<!-- Module/component list -->
-
-### Integration Points
-<!-- External system integrations -->
-
-### ADRs
-<!-- Architecture Decision Records -->
-
-### Domain Model / Entity Register
-<!-- Entity, key attributes, relationships, owner module -->
-
----
-
-## Session 6: Security Outputs
-_Populated after Session 6 completion_
-
-### Data Classification
-<!-- Data sensitivity levels -->
-
-### Compliance Framework
-<!-- Standards and regulations -->
-
-### Encryption
-<!-- In-transit, at-rest, key management -->
-
-### Network & Access
-<!-- Network security approach -->
-
-### Audit Logging
-<!-- Logging strategy and retention -->
-
-### Availability
-<!-- SLA targets -->
-
----
-
-## Session 7: Identity Management Outputs
-_Populated after Session 7 completion_
-
-### RBAC Model
-<!-- Roles and permissions summary -->
-
-### IdP Integration
-<!-- Identity provider details -->
-
-### User Lifecycle
-<!-- Provisioning approach -->
-
----
-
-## Session 8: Integration Outputs
-_Populated after Session 8 completion_
-
-### External Systems
-<!-- Systems and their interfaces -->
-
-### Interface Patterns
-<!-- Chosen patterns and protocols -->
-
-### Data Exchange
-<!-- Key data flows and formats -->
-
----
-
-## Session 9: QA Outputs
-_Populated after Session 9 completion_
-
-### Test Strategy
-<!-- Testing approach -->
-
-### Tooling
-<!-- Test management and automation tools -->
-
-### Test Environments
-<!-- Environment list and purposes -->
-
-### Quality Gates
-<!-- Gate definitions -->
-
-### UAT
-<!-- UAT participants, period, criteria -->
-
----
-
-## Session 10: Infrastructure Outputs
-_Populated after Session 10 completion_
-
-### Infrastructure
-<!-- Cloud/hosting setup -->
-
-### Deployment
-<!-- Deployment strategy -->
-
-### Monitoring
-<!-- Monitoring and alerting approach -->
-
-### Backup & DR
-<!-- Backup and disaster recovery -->
-
-### Go-Live Readiness
-<!-- Readiness checklist status -->
-
----
-
-## Session 11: Roadmap Outputs
-_Populated after Session 11 completion_
-
-### Project Phases
-<!-- Phase breakdown -->
-
-### Timeline
-<!-- Iteration model (sprints or pp-core phases) and key dates -->
-
-### MVP Scope (Confirmed)
-<!-- Must-have vs nice-to-have -->
-
-### Build Order
-<!-- Iteration-by-iteration plan -->
-
-### Key Milestones
-<!-- Milestone dates -->
-
-### Risks
-<!-- Top risks and mitigations -->
-
----
-
-## Session 12: Delivery Model Outputs
-_Populated after Session 12 completion_
-
-### Team Structure
-<!-- Key roles and people -->
-
-### Governance
-<!-- Governance framework summary -->
-
-### Ceremonies
-<!-- Iteration cadence and the meetings held -->
-
-### Support Model
-<!-- Post-go-live support approach -->
-
----
-
-## Session 13: Wrap-up Outputs
-_Populated after Session 13 completion_
-
-### Decision Readiness
-<!-- Go / Conditional Go / No-Go assessment -->
-
-### Open Items
-<!-- Items carried forward -->
-
-### Next Steps
-<!-- Transition plan to execution -->
-```
-