@pareto4/pp-core 1.19.0 → 1.21.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pp-core",
   "displayName": "PP Core",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "description": "PP Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "author": {
     "name": "pareto4",

package/agents/pp-nyquist-auditor.md

@@ -31,6 +31,7 @@ For each gap in `<gaps>`: generate minimal behavioral test, run it, debug if fai
 - Treating "test file created" as "gap filled" before the test actually runs and passes
 - Marking gaps as SKIP without escalating — a skipped gap is an unverified requirement, not a resolved one
 - Debugging a failing test by weakening the assertion rather than fixing the implementation via ESCALATE
+- Counting a test that asserts nothing as coverage
 
 **Required finding classification:**
 - **BLOCKER** — gap test fails after 3 iterations; requirement unmet; ESCALATE to developer
@@ -80,6 +81,9 @@ Action by gap type:
 - `no_test_file` → Create test file
 - `test_fails` → Diagnose and fix the test (not impl)
 - `no_automated_command` → Determine command, update map
+- `asserts_nothing` → Read the case first; an assertion made inside a helper it calls clears it (report it covered, no edit). Otherwise add an assertion of the requirement's behaviour to the existing test. Never delete the test or weaken an assertion. An added assertion that still fails after the 3 debug iterations is an implementation bug → ESCALATE.
+
+While reading tests, also report any case you find yourself that asserts nothing, as an `asserts_nothing` gap. Rules: `~/.claude/pp-core/references/test-substance.md` § Assertion-free tests at validation.
 </step>
 
 <step name="generate_tests">
@@ -117,8 +121,8 @@ After 3 failed iterations: ESCALATE with requirement, expected vs actual behavio
 </step>
 
 <step name="report">
-Resolved gaps: `{ task_id, requirement, test_type, automated_command, file_path, status: "green" }`
-Escalated gaps: `{ task_id, requirement, reason, debug_iterations, last_error }`
+Resolved gaps: `{ task_id, requirement, gap_type, test_type, automated_command, file_path, status: "green" }`
+Escalated gaps: `{ task_id, requirement, gap_type, reason, debug_iterations, last_error }`
 
 Return one of three formats below.
 </step>
@@ -141,9 +145,9 @@ Return one of three formats below.
 | 1 | {path} | {unit/integration/smoke} | `{cmd}` |
 
 ### Verification Map Updates
-| Task ID | Requirement | Command | Status |
-|---------|-------------|---------|--------|
-| {id} | {req} | `{cmd}` | green |
+| Task ID | Requirement | Gap Type | Command | Status |
+|---------|-------------|----------|---------|--------|
+| {id} | {req} | {gap_type} | `{cmd}` | green |
 
 ### Files for Commit
 {test file paths}
@@ -158,14 +162,14 @@ Return one of three formats below.
 **Resolved:** {M}/{total} | **Escalated:** {K}/{total}
 
 ### Resolved
-| Task ID | Requirement | File | Command | Status |
-|---------|-------------|------|---------|--------|
-| {id} | {req} | {file} | `{cmd}` | green |
+| Task ID | Requirement | Gap Type | File | Command | Status |
+|---------|-------------|----------|------|---------|--------|
+| {id} | {req} | {gap_type} | {file} | `{cmd}` | green |
 
 ### Escalated
-| Task ID | Requirement | Reason | Iterations |
-|---------|-------------|--------|------------|
-| {id} | {req} | {reason} | {N}/3 |
+| Task ID | Requirement | Gap Type | Reason | Iterations |
+|---------|-------------|----------|--------|------------|
+| {id} | {req} | {gap_type} | {reason} | {N}/3 |
 
 ### Files for Commit
 {test file paths for resolved gaps}
@@ -180,9 +184,9 @@ Return one of three formats below.
 **Resolved:** 0/{total}
 
 ### Details
-| Task ID | Requirement | Reason | Iterations |
-|---------|-------------|--------|------------|
-| {id} | {req} | {reason} | {N}/3 |
+| Task ID | Requirement | Gap Type | Reason | Iterations |
+|---------|-------------|----------|--------|------------|
+| {id} | {req} | {gap_type} | {reason} | {N}/3 |
 
 ### Recommendations
 - **{req}:** {manual test instructions or implementation fix needed}
@@ -197,6 +201,7 @@ Return one of three formats below.
 - [ ] Tests verify behavior, not structure
 - [ ] Every test executed — none marked passing without running
 - [ ] Implementation files never modified
+- [ ] `asserts_nothing` gaps filled by adding assertions, never by deleting or weakening tests
 - [ ] Max 3 debug iterations per gap
 - [ ] Implementation bugs escalated, not fixed
 - [ ] Structured return provided (GAPS FILLED / PARTIAL / ESCALATE)

package/agents/pp-phase-researcher.md

@@ -61,6 +61,12 @@ Before researching, discover project context:
 | `## Deferred Ideas` | Out of scope — ignore completely |
 
 If CONTEXT.md exists, it constrains your research scope. Don't explore alternatives to locked decisions.
+
+**`{padded}-DISCOVERY-EXTRACT.md`** (if listed in your files to read) — the Discovery registers' rows
+that cite this phase's requirement IDs. Required reading; Read
+`pp-core/references/planner-discovery-extract.md` § Researcher and follow it. **Never open
+`.planning/discovery/session-NN.md`**: the session files are the facilitation record, not a
+source. Absent file → nothing here applies.
 </upstream_input>
 
 <downstream_consumer>
@@ -548,6 +554,10 @@ cat "$phase_dir"/*-CONTEXT.md 2>/dev/null
 - User decided "simple UI, no animations" → don't research animation libraries
 - Marked as Claude's discretion → research options and recommend
 
+Then read `$phase_dir`/*-DISCOVERY-EXTRACT.md if it exists (see `<upstream_input>`): list the
+entities, integrations and rules it names under `## User Constraints` as "Discovery facts (by row
+ID)" so the planner sees them beside the locked decisions. Do not open any `session-NN.md`.
+
 ## Step 1.3: Load Graph Context
 
 Check for knowledge graph:

package/agents/pp-plan-checker.md

@@ -85,6 +85,7 @@ REVIEWS.md is audit trail and feedback input, not a hidden execution contract. /
 - Do not re-open historical findings that are already incorporated, explicitly deferred/rejected in PLAN.md, or marked fully resolved.
 - Verify each current actionable review finding appears in executable PLAN.md content: a task, `<action>`, `<acceptance_criteria>`, `<verify>`, `must_haves`, threat model, artifact list, stale-path correction, or explicit deferral/rejection rationale.
 - If a current actionable finding remains only in REVIEWS.md and would be invisible to /pp:execute-phase, return `## ISSUES FOUND`. Use WARNING by default; use BLOCKER when the missing incorporation can prevent the phase goal, create unsafe execution, or invalidate verification.
+**Check mode.** When the prompt says `**Check mode:** blockers-only`, Read `~/.claude/pp-core/references/ceremony.md` § `## Blockers-only checker mode` before Step 1 and follow it: report BLOCKER issues only.
 </upstream_input>
 
 <core_principle>
@@ -244,37 +245,43 @@ issue:
 
 ## Dimension 5: Scope Sanity
 
-**Question:** Will plans complete within context budget?
+**Question:** Will plans complete within context budget, and is every split justified?
 
 **Process:**
-1. Count tasks per plan
-2. Estimate files modified per plan
-3. Check against thresholds
+1. Run `pp_run check plan-sizing "$phase_number" --raw` (reads every PLAN.md and `context_window`)
+2. Raise each `over_ceiling` plan with `has_summary` false and each `unjustified_splits` or `unestimated_serial` pair as a blocker, naming each `unparseable_estimate` value (fix: a bare integer or `60k`). `phase_found` false means the phase number is wrong: re-run with the right one before judging scope
+3. Compare each unexecuted plan's `percent_of_window` with the Total-context row
+4. Judge whether each `context_estimate` is plausible for its tasks and files (signals: planner-guidance.md Task Sizing)
+
+**Executed plans:** a plan with `has_summary` true is executed. Report its task count and context as info, never as a warning or blocker, under every threshold and red flag below and in Step 8: the planner cannot split it.
 
 **Thresholds:**
 | Metric | Target | Warning | Blocker |
 |--------|--------|---------|---------|
-| Tasks/plan | 2-3 | 4 | 5+ |
-| Files/plan | 5-8 | 10 | 15+ |
-| Total context | ~50% | ~70% | 80%+ |
+| Tasks/plan | 1-6 | — | 7+ |
+| Total context (`context_estimate` vs `context_window`) | ~50% | ~70% | 80%+ |
+| Serial split (`unjustified_splits`) | none | — | any pair |
+
+Files per plan are a cross-check on the estimate, not a threshold: a plan in `estimate_files_mismatch` (many files, low estimate) is a warning. A plan above 50% but under 70% is info (the planner should have split it). A plan without `context_estimate` is judged on task count only: alone it is info; in an `unestimated_serial` pair (serial, merge fits 6 tasks, no estimate shows a budget reason) it is a blocker.
 
 **Red flags:**
-- Plan with 5+ tasks (quality degrades)
-- Plan with 15+ file modifications
+- Unexecuted plan with 7+ tasks
+- A serial pair, each plan alone in its wave, whose merge fits 6 tasks and the budget (a split with neither a parallelism nor a budget reason)
 - Single task with 10+ files
-- Complex work (auth, payments) crammed into one plan
+- A context_estimate implausibly low for the plan's tasks and files
 
 **Example issue:**
 ```yaml
 issue:
   dimension: scope_sanity
-  severity: warning
-  description: "Plan 01 has 5 tasks - split recommended"
-  plan: "01"
+  severity: blocker
+  description: "Plans 02 and 03 are a serial split with no reason: each alone in its wave, merged 4 tasks / 70000 tokens fits the 100000 budget"
+  plan: "02"
   metrics:
-    tasks: 5
-    files: 12
-  fix_hint: "Split into 2 plans: foundation (01) and integration (02)"
+    merged_tasks: 4
+    merged_estimate: 70000
+    plan_budget_tokens: 100000
+  fix_hint: "Merge 03 into 02"
 ```
 
 ## Dimension 6: Verification Derivation
@@ -446,11 +453,17 @@ issue:
 
 ## Dimension 8: Nyquist Compliance
 
-Skip if: `workflow.nyquist_validation` is explicitly set to `false` in config.json (absent key = enabled), phase has no RESEARCH.md, or RESEARCH.md has no "Validation Architecture" section. Output: "Dimension 8: SKIPPED (nyquist_validation disabled or not applicable)"
+Skip only if `workflow.nyquist_validation` is explicitly `false` in config.json (absent key = enabled; the verb then reports `enforced: false`). Output: "Dimension 8: SKIPPED (nyquist_validation disabled)". A missing RESEARCH.md never skips this dimension, at any tier, light included. Rules: Read `~/.claude/pp-core/references/test-substance.md`.
+
+### Check 8f — Test Substance (run first)
+
+Run `pp_run check test-substance "$phase_number" --raw` (launcher bound in Step 1). `phase_found` false: re-run with the right phase. Raise every finding on a plan with `executed` false as a BLOCKER under its `code` and `detail` (every code is a blocker, so blockers-only mode keeps them). Then judge what code cannot:
+- Does each `<behavior>` name what its `<automated>` command actually asserts? A statement about a different behaviour than the command tests is a BLOCKER.
+- For each `tdd_candidates_without_tdd` task, apply the planner's TDD heuristic (`expect(fn(input)).toBe(output)` before `fn`): a confirmed business-logic task without `tdd="true"` is a BLOCKER; glue code that touches source files is not raised.
 
 ### Check 8e — VALIDATION.md Existence (Gate)
 
-Before running checks 8a-8d, verify VALIDATION.md exists:
+Applies only when RESEARCH.md exists and has a `## Validation Architecture` section; otherwise skip 8e and run 8a-8d and 8f. Before checks 8a-8d, verify VALIDATION.md exists:
 
 ```bash
 [ -z "${ZSH_VERSION:-}" ] || emulate -R sh
@@ -467,7 +480,7 @@ Skip checks 8a-8d entirely. Report Dimension 8 as FAIL with this single issue.
 For each `<task>` in each plan:
 - `<verify>` must contain `<automated>` command, OR a Wave 0 dependency that creates the test first
 - If `<automated>` is absent with no Wave 0 dependency → **BLOCKING FAIL**
-- If `<automated>` says "MISSING", a Wave 0 task must reference the same test file path → **BLOCKING FAIL** if link broken
+- If `<automated>` says "MISSING" → **BLOCKING FAIL**: the executor cannot run the marker. A test file not yet written is listed by a `tdd="true"` task's own `<files>` or an earlier task of the same plan, which must be test infrastructure or `tdd="true"` (its own verify fails on the still-failing assertion), and `<automated>` runs that file's real command. Wave 0 plans carry test infrastructure only.
 
 ### Check 8b — Feedback Latency Assessment
 
@@ -482,9 +495,10 @@ Map tasks to waves. Per wave, any consecutive window of 3 implementation tasks m
 
 ### Check 8d — Wave 0 Completeness
 
-For each `<automated>MISSING</automated>` reference:
-- Wave 0 task must exist with matching `<files>` path
-- Wave 0 plan must execute before dependent task
+For each test file an `<automated>` command runs that is not on disk yet. Check 8f's verb reports the order as `scaffold_uncreated` (`later_task`, `other_plan:<id>`, `no_creator`); raise those as in 8f, then judge what it accepts:
+- The test file that carries the task's own assertion is listed by a `tdd="true"` task's own `<files>` or an earlier task of the same plan (test infrastructure or `tdd="true"`). Across plans it is accepted only when a Wave 0 test-infrastructure task (no behaviour assertion) has a matching `<files>` path
+- The verb accepts any earlier-wave creator. Test infrastructure, or a test that passes with its own code in that wave, is fine; a plan that writes this task's assertion ahead of its code → **BLOCKING FAIL** (no wave merges a failing test)
+- That creator executes before the dependent task
 - Missing match → **BLOCKING FAIL**
 
 ### Dimension 8 Output
@@ -492,10 +506,11 @@ For each `<automated>MISSING</automated>` reference:
 ```
 ## Dimension 8: Nyquist Compliance
 
-| Task | Plan | Wave | Automated Command | Status |
-|------|------|------|-------------------|--------|
-| {task} | {plan} | {wave} | `{command}` | ✅ / ❌ |
+| Task | Plan | Wave | Automated Command | Behavior | Status |
+|------|------|------|-------------------|----------|--------|
+| {task} | {plan} | {wave} | `{command}` | {what it asserts} | ✅ / ❌ |
 
+Test substance: {N} findings → ✅ / ❌
 Sampling: Wave {N}: {X}/{Y} verified → ✅ / ❌
 Wave 0: {test file} → ✅ present / ❌ MISSING
 Overall: ✅ PASS / ❌ FAIL
@@ -789,9 +804,10 @@ Missing: No mention of fetch/API call → Issue: Key link not planned
 ```bash
 pp_run query plan.task-structure "$PHASE_DIR/$PHASE-01-PLAN.md"
 pp_run query frontmatter.get "$PHASE_DIR/$PHASE-01-PLAN.md" files_modified
+pp_run check plan-sizing "$phase_number" --raw
 ```
 
-Thresholds: 2-3 tasks/plan good, 4 warning, 5+ blocker (split required).
+Thresholds (task count and percent_of_window apply to unexecuted plans only, `has_summary` false; an executed plan is info): 1-6 tasks/plan accepted, 7+ blocker (split). Every unjustified_splits pair: blocker (merge). Every unestimated_serial pair: blocker (estimate, or merge). percent_of_window above 50% info, ~70% warning, 80%+ blocker. A doubtful estimate: warning.
 
 ## Step 9: Verify must_haves Derivation
 
@@ -817,8 +833,9 @@ Severities: `blocker` (must fix), `warning` (should fix), `info` (suggestions).
 
 **Plan 01 analysis:**
 ```
-Tasks: 5
+Tasks: 7
 Files modified: 12
+context_estimate: 150000   (context_window: 200000, plan_budget_tokens: 100000)
   - prisma/schema.prisma
   - src/app/api/auth/login/route.ts
   - src/app/api/auth/logout/route.ts
@@ -833,19 +850,19 @@ Files modified: 12
   - src/types/auth.ts
 ```
 
-5 tasks exceeds 2-3 target, 12 files is high, auth is complex domain → quality degradation risk.
+7 tasks exceed the 6-task ceiling and 150000 tokens is 75% of the window, over the 100000 per-plan budget.
 
 ```yaml
 issue:
   dimension: scope_sanity
   severity: blocker
-  description: "Plan 01 has 5 tasks with 12 files - exceeds context budget"
+  description: "Plan 01 has 7 tasks and context_estimate 150000 - over the 6-task ceiling and the per-plan budget"
   plan: "01"
   metrics:
-    tasks: 5
+    tasks: 7
     files: 12
-    estimated_context: "~80%"
-  fix_hint: "Split into: 01 (schema + API), 02 (middleware + lib), 03 (UI components)"
+    context_estimate: 150000
+  fix_hint: "Split into two plans of at most 6 tasks and 100000 tokens each: parallel when their files are disjoint, otherwise serial (justified by budget)"
 ```
 
 </examples>
@@ -870,15 +887,21 @@ issue:
 - Missing requirement coverage
 - Missing required task fields
 - Circular dependencies
-- Scope > 5 tasks per plan
+- Scope > 6 tasks per plan (unexecuted, `has_summary` false)
+- A split flagged by check plan-sizing (unjustified_splits, unestimated_serial)
+- context_estimate at 80%+ of context_window (unexecuted plan)
+- A `check test-substance` finding on an unexecuted plan, or a confirmed business-logic task without `tdd="true"`
 
 **warning** - Should fix, execution may work
-- Scope 4 tasks (borderline)
+- context_estimate at ~70% of context_window (unexecuted plan)
+- A doubtful estimate (implausible for its tasks and files, or listed in estimate_files_mismatch)
 - Implementation-focused truths
 - Minor wiring missing
 
 **info** - Suggestions for improvement
-- Could split for better parallelization
+- Could split independent subsystems into parallel plans
+- context_estimate above 50% of context_window
+- Plan without context_estimate (not in a serial pair)
 - Could improve verification specificity
 
 Return all issues as a structured `issues:` YAML list (see dimension examples for format).
@@ -956,7 +979,7 @@ Plans verified. Run `/pp:execute-phase {phase}` to proceed.
 
 **DO NOT** skip dependency analysis. Circular/broken dependencies cause execution failures.
 
-**DO NOT** ignore scope. 5+ tasks/plan degrades quality. Report and split.
+**DO NOT** ignore scope. 7+ tasks in an unexecuted plan or a flagged serial split is a blocker: report it — split the first, merge the second.
 
 **DO NOT** verify implementation details. Check that plans describe what to build.
 

package/agents/pp-planner.md

@@ -26,7 +26,7 @@ Your job: Produce PLAN.md files that Claude executors can implement without inte
 
 **Core responsibilities:**
 - **FIRST: Parse and honor user decisions from CONTEXT.md** (locked decisions are NON-NEGOTIABLE)
-- Decompose phases into parallel-optimized plans with 2-3 tasks each
+- Size plans by estimated context cost: up to 6 tasks, split only for parallelism or budget
 - Build dependency graphs and assign execution waves
 - Derive must-haves using goal-backward methodology
 - Handle both standard planning and gap closure mode
@@ -114,7 +114,7 @@ Exclusions (not gaps): Deferred Ideas in CONTEXT.md, items scoped to other phase
 The planner has no authority to judge a feature as too difficult, omit features because they seem challenging, or use "complex/difficult/non-trivial" to justify scope reduction.
 
 **Only three legitimate reasons to split or flag:**
-1. **Context cost:** implementation would consume >50% of a single agent's context window
+1. **Context cost:** implementation would consume >50% of the configured context window (`plan_budget_tokens` from init)
 2. **Missing information:** required data not present in any source artifact
 3. **Dependency conflict:** feature cannot be built until another phase ships
 
@@ -162,7 +162,7 @@ For niche domains (3D/games/audio/shaders/ML), suggest `/pp:plan-phase --researc
 
 ## Task Anatomy
 
-Every task has four required fields:
+Every task has five required fields:
 
 **<files>:** Exact file paths created or modified.
 - Good: `src/app/api/auth/login/route.ts`, `prisma/schema.prisma`
@@ -186,7 +186,7 @@ Every task has four required fields:
 - Bad: "It works", "Looks good", manual-only verification
 - Simple format also accepted: `npm test` passes, `curl -X POST /api/auth/login` returns 200
 
-**Nyquist Rule:** Every `<verify>` includes `<automated>`. If no test exists, set `<automated>MISSING — Wave 0 must create {test_file} first</automated>` and create that scaffold.
+**Nyquist Rule:** Every `<verify>` includes `<automated>`, and every non-checkpoint task has a `<behavior>` naming what that command asserts as input → expected output (`tdd="true"`: its test cases; "tests pass", "works", "file exists" are not behaviours). With no test yet, list that test file, assertion included, in an earlier task of the plan or a `tdd="true"` task's own `<files>`; `<automated>` runs it, never `MISSING — Wave 0 must create {test_file} first`; never a vacuous scaffold. Rules: Read `~/.claude/pp-core/references/test-substance.md`.
 
 **Grep gate hygiene:** `grep -c` counts comments, so header prose can be self-invalidating. Use `grep -v '^#' | grep -c token`. Bare `== 0` gates on unfiltered files are forbidden.
 
@@ -212,37 +212,7 @@ See @~/.claude/pp-core/references/planner-guidance.md for Task Types table, Task
 
 **When `workflow.tdd_mode` is enabled:** Apply TDD heuristics aggressively — all eligible tasks MUST use `type: tdd`. Read @~/.claude/pp-core/references/tdd.md for gate enforcement rules and the end-of-phase review checkpoint format.
 
-**When `workflow.tdd_mode` is disabled (default):** Apply TDD heuristics opportunistically — use `type: tdd` only when the benefit is clear.
-
-**Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
-- Yes → Create a dedicated TDD plan (type: tdd)
-- No → Standard task in standard plan
-
-**TDD candidates (dedicated TDD plans):** Business logic with defined I/O, API endpoints with request/response contracts, data transformations, validation rules, algorithms, state machines.
-
-**Standard tasks:** UI layout/styling, configuration, glue code, one-off scripts, simple CRUD with no business logic.
-
-**Why TDD gets own plan:** TDD requires RED→GREEN→REFACTOR cycles consuming 40-50% context. Embedding in multi-task plans degrades quality.
-
-**Task-level TDD** (for code-producing tasks in standard plans): When a task creates or modifies production code, add `tdd="true"` and a `<behavior>` block to make test expectations explicit before implementation:
-
-```xml
-<task type="auto" tdd="true">
-  <name>Task: [name]</name>
-  <files>src/feature.ts, src/feature.test.ts</files>
-  <behavior>
-    - Test 1: [expected behavior]
-    - Test 2: [edge case]
-  </behavior>
-  <action>[Implementation after tests pass]</action>
-  <verify>
-    <automated>npm test -- --filter=feature</automated>
-  </verify>
-  <done>[Criteria]</done>
-</task>
-```
-
-Exceptions where `tdd="true"` is not needed: `type="checkpoint:*"` tasks, configuration-only files, documentation, migration scripts, glue code wiring existing tested components, styling-only changes.
+**When `workflow.tdd_mode` is disabled (default):** Heuristic: can you write `expect(fn(input)).toBe(output)` before writing `fn`? Candidates: business logic with defined I/O, API endpoints with request/response contracts, data transformations, validation rules, algorithms, state machines. A candidate gets `tdd="true"` and a `<behavior>` test-case list inside an ordinary plan (RED→GREEN); dedicated `type: tdd` plans stay `tdd_mode`'s. Not for `checkpoint:*`, configuration-only files, documentation, migration scripts, glue code wiring tested components, styling-only or test-only tasks. Example and rules: `~/.claude/pp-core/references/test-substance.md`.
 
 `workflow.human_verify_mode=end-of-phase`: no `checkpoint:human-verify`; use `<verify><human-check>`.
 
@@ -289,26 +259,18 @@ See @~/.claude/pp-core/references/planner-guidance.md for dependency graph build
 
 ## Context Budget Rules
 
-Plans should complete within ~50% context (not 80%). No context anxiety, quality maintained start to finish, room for unexpected complexity.
-
-**Each plan: 2-3 tasks maximum.**
+Plans should complete within ~50% context (not 80%).
 
-| Context Weight | Tasks/Plan | Context/Task | Total |
-|----------------|------------|--------------|-------|
-| Light (CRUD, config) | 3 | ~10-15% | ~30-45% |
-| Medium (auth, payments) | 2 | ~20-30% | ~40-50% |
-| Heavy (migrations, multi-subsystem) | 1-2 | ~30-40% | ~30-50% |
+**Each plan: up to 6 tasks** (`max_tasks_per_plan`), added while the summed estimate stays within `plan_budget_tokens` (50% of `context_window`, from init). The count is an outcome of the estimate, never a target. Tasks stay ~20-60k tokens (10–30% at 200k) at any window: a larger window fits more tasks, not larger ones. Estimate per planner-guidance.md Task Sizing; record each plan's sum as `context_estimate`.
 
 ## Split Signals
 
 **ALWAYS split if:**
-- More than 3 tasks
-- Multiple subsystems (DB + API + UI = separate plans)
-- Any task with >5 file modifications
-- Checkpoint + implementation in same plan
-- Discovery + implementation in same plan
+- **Parallelism:** independent subsystems with disjoint `files_modified`, run in the same wave
+- **Budget:** merged, the work would exceed `plan_budget_tokens` or 6 tasks (a dedicated TDD plan and discovery + implementation are budget cases)
+- A task with >5 file modifications: split the task, not the plan
 
-**CONSIDER splitting:** >5 files total, natural semantic boundaries, context cost estimate exceeds 40% for a single plan. See `<planner_authority_limits>` for prohibited split reasons.
+Never split serial single-concern work to fit a task count — see "Plan-Split Anti-Patterns" in @~/.claude/pp-core/references/planner-antipatterns.md. Phase splits and gap-closure plans are separate mechanisms. See `<planner_authority_limits>` for prohibited split reasons.
 
 See @~/.claude/pp-core/references/planner-guidance.md for Granularity Calibration table (Coarse/Standard/Fine plans-per-phase).
 
@@ -329,6 +291,7 @@ files_modified: []          # Files this plan touches
 autonomous: true            # false if plan has checkpoints
 requirements: []            # REQUIRED — Requirement IDs from ROADMAP this plan addresses. MUST NOT be empty.
 user_setup: []              # Human-required setup (omit if empty)
+context_estimate: N         # REQUIRED — sum of task estimates in tokens: 90000 or 90k, no ~/units
 
 must_haves:
   truths: []                # Observable behaviors
@@ -362,11 +325,17 @@ Output: [Artifacts created]
 Its exact shape comes from `pp_run vault standards block`, per `pp-core/references/planner-vault-standards.md`.]
 </vault_standards>
 
+<discovery_extract>
+[Present ONLY when a `*-DISCOVERY-EXTRACT.md` is in your files to read — omitted entirely otherwise.
+The file's content verbatim, `<!-- discovery:auto -->` markers included; see <discovery_mode>.]
+</discovery_extract>
+
 <tasks>
 
 <task type="auto">
   <name>Task 1: [Action-oriented name]</name>
   <files>path/to/file.ext</files>
+  <behavior>[What the verify command asserts: input → expected output]</behavior>
   <action>[Specific implementation]</action>
   <verify>[Command or check]</verify>
   <done>[Acceptance criteria]</done>
@@ -577,6 +546,13 @@ start of execution when the injected `plan:pre -> into: planner` fragment for
 the vault capability is present in your context.
 </vault_standards_mode>
 
+<discovery_mode>
+See `pp-core/references/planner-discovery-extract.md`. Load this file at the
+start of execution when a `*-DISCOVERY-EXTRACT.md` is listed in your files to
+read: it is required reading, embedded verbatim as `<discovery_extract>`, and
+you never open a `.planning/discovery/session-NN.md`.
+</discovery_mode>
+
 <execution_flow>
 
 <step name="load_project_state" priority="first">
@@ -588,7 +564,7 @@ INIT=$(pp_run query init.plan-phase "${PHASE}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
-Extract from init JSON: `planner_model`, `researcher_model`, `checker_model`, `commit_docs`, `research_enabled`, `phase_dir`, `phase_number`, `has_research`, `has_context`.
+Extract from init JSON: `planner_model`, `researcher_model`, `checker_model`, `commit_docs`, `research_enabled`, `phase_dir`, `phase_number`, `has_research`, `has_context`, `context_window`, `plan_budget_tokens`, `task_tokens_min`, `task_tokens_max`, `max_tasks_per_plan`.
 
 Also load planning state (position, decisions, blockers) via the SDK — **use `node` to invoke the CLI** (not `npx`):
 ```bash
@@ -604,6 +580,7 @@ Check the invocation mode and load the relevant reference file:
 - If `<revision_context>` provided by orchestrator: Read `pp-core/references/planner-revision.md`
 - If `--reviews` flag present or reviews mode active: Read `pp-core/references/planner-reviews.md`
 - If the vault capability's `plan:pre` fragment is present: Read `pp-core/references/planner-vault-standards.md`
+- If a `*-DISCOVERY-EXTRACT.md` is in your files to read: Read `pp-core/references/planner-discovery-extract.md`
 - If task_breakdown identifies TDD candidates or TDD mode is active: Read `pp-core/references/planner-tdd.md`
 - Standard planning mode: no additional file to read
 
@@ -776,7 +753,7 @@ Rules:
 1. Same-wave tasks with no file conflicts → parallel plans
 2. Shared files → same plan or sequential plans (shared file = implicit dependency → later wave)
 3. Checkpoint tasks → `autonomous: false`
-4. Each plan: 2-3 tasks, single concern, ~50% context target
+4. Each plan: up to 6 tasks within `plan_budget_tokens`, single concern; split only for parallelism or budget
 </step>
 
 <step name="derive_must_haves">
@@ -798,7 +775,7 @@ UNREACHABLE (no path) → revise plan.
 </step>
 
 <step name="estimate_scope">
-Verify each plan fits context budget: 2-3 tasks, ~50% target. Split if necessary. Check granularity setting.
+Sum each plan's task estimates into `context_estimate`; it must fit `plan_budget_tokens` with at most 6 tasks. Merge serial plans whose sum fits; split only for parallelism or budget. Check granularity setting.
 </step>
 
 <step name="confirm_breakdown">
@@ -812,6 +789,8 @@ Use template structure for each PLAN.md.
 
 When the fragment IS present, follow `pp-core/references/planner-vault-standards.md` in full — select documents from the INDEX, read each in full, obtain the block from `pp_run vault standards block` once `files_modified` settles, embed it verbatim after `<context>` and before `<tasks>`, fill only the reason slots, and re-run it on revision.
 
+**Discovery extract block (only when a `*-DISCOVERY-EXTRACT.md` is in your files to read):** embed the file verbatim as `<discovery_extract>` after `<context>` (and after `<vault_standards>` when present), before `<tasks>`, per `<discovery_mode>`. Absent file → write no block.
+
 **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
 
 **Write contract (hard rules — must follow):**
@@ -879,6 +858,22 @@ Returns JSON: `{ valid, errors, warnings, task_count, tasks }`
 - Missing `<name>` in task → add name element
 - Missing `<action>` → add action element
 - Checkpoint/autonomous mismatch → update `autonomous: false`
+
+Then check sizing across the phase:
+
+```bash
+SIZING=$(pp_run check plan-sizing "$PHASE" --raw)
+```
+
+`phase_found` false: wrong phase, stop. Merge only the first `unjustified_splits` pair, estimate each `unestimated_serial` pair (rewrite each `unparseable_estimate` as an integer), split each unexecuted `over_ceiling` / `over_budget` plan (see "Plan-Split Anti-Patterns"), re-run; repeat until `block` is false (expect `min_plans` plans).
+
+Then:
+
+```bash
+SUBSTANCE=$(pp_run check test-substance "$PHASE" --raw)
+```
+
+Fix every finding on an unexecuted plan, re-run until `block` is false. Judge each `tdd_candidates_without_tdd` task by the heuristic; add `tdd="true"` to business logic. `enforced: false` (`nyquist_validation` off): findings advisory; still write `<behavior>`.
 </step>
 
 <step name="update_roadmap">
@@ -952,7 +947,8 @@ Phase planning complete when:
 - [ ] Each plan: depends_on, files_modified, autonomous, must_haves in frontmatter
 - [ ] Each plan: user_setup declared if external services involved
 - [ ] Each plan: Objective, context, tasks, verification, success criteria, output
-- [ ] Each plan: 2-3 tasks (~50% context)
+- [ ] Each plan: ≤ 6 tasks within `plan_budget_tokens`; `check plan-sizing` reports `block: false`
+- [ ] Each non-checkpoint task has a `<behavior>`; `check test-substance` reports `block: false`
 - [ ] Each task: Type, Files (if auto), Action, Verify, Done
 - [ ] Checkpoints properly structured
 - [ ] Wave structure maximizes parallelism

package/agents/pp-vault-reviewer.md

@@ -56,6 +56,8 @@ Forbidden, without exception, even when a finding seems to demand it:
 **Counts, never a score.** Report counts by verdict in the exact counts line the template shows. A ratio, percentage, letter grade or compliance number is prohibited anywhere in the artifact.
 
 A document the executor marked `not read: …` is still judged against the code; record the executor's reason in the row's evidence, because a standard nobody read is worth a reader's attention.
+
+**Deviations on file (`deviations[]` in the payload).** A Discovery Sprint records the client's agreed departures from the vault in `.planning/discovery/_deviations.md`; the CLI copies them into the payload (`pp-core/references/discovery-build-consumption.md` § `_deviations.md` read contract). Before writing `FAIL`, check the list: when a deviation whose `standard` names the document and whose `status` is `Approved` covers the clause the code breaks, the verdict is `N-A` with the reason `deviation on file: <id> (<decision>)` — the sponsor chose this departure and the document does not govern that clause here. A deviation in any other status (`Proposed`, `Rejected`, empty) leaves the `FAIL` standing; name the deviation and its status in the reason so the reader sees the gap between what was asked and what was approved. Never coin a verdict for it; `N-A` with that reason is the whole mechanism. An empty `deviations[]` changes nothing.
 </verdicts>
 
 <adversarial_stance>