@pareto4/pp-core 1.20.0 → 1.21.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pp-core",
   "displayName": "PP Core",
-  "version": "1.20.0",
+  "version": "1.21.1",
   "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-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
@@ -372,6 +335,7 @@ The file's content verbatim, `<!-- discovery:auto -->` markers included; see <di
 <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>
@@ -600,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
@@ -789,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">
@@ -811,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">
@@ -894,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">
@@ -967,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-verifier.md

@@ -70,6 +70,8 @@ Then verify each level against the actual codebase.
 
 <verification_process>
 
+**Depth.** When the prompt says `Verifier depth: light`, Read `~/.claude/pp-core/references/ceremony.md` § `## Verifier depth` before Step 0 and skip only the steps it names. Any other value, or none, is full depth.
+
 At verification decision points, apply structured reasoning:
 @~/.claude/pp-core/references/thinking-models-verification.md
 
@@ -463,7 +465,7 @@ grep -n -E "=\{(\[\]|\{\}|null|undefined|''|\"\")\}" "$file" 2>/dev/null
 grep -n -B 2 -A 2 "console\.log" "$file" 2>/dev/null | grep -E "^\s*(const|function|=>)"
 ```
 
-**Stub classification:** A grep match is a STUB only when the value flows to rendering or user-visible output AND no other code path populates it with real data. A test helper, type default, or initial state that gets overwritten by a fetch/store is NOT a stub. Check for data-fetching (useEffect, fetch, query, useSWR, useQuery, subscribe) that writes to the same variable before flagging.
+**Stub classification:** A grep match is a STUB only when the value flows to rendering or user-visible output AND no other code path populates it with real data. A test helper, type default, or initial state that gets overwritten by a fetch/store is NOT a stub. Check for data-fetching (useEffect, fetch, query, useSWR, useQuery, subscribe) that writes to the same variable before flagging. Red-flag examples (component, API route and wiring stubs): `~/.claude/pp-core/references/verifier-stub-patterns.md`.
 
 **Debt marker gate:** Any `TBD`, `FIXME`, or `XXX` marker in a file modified by this phase is a 🛑 BLOCKER unless the same line references formal follow-up work (`issue #123`, `PR #123`, `#123`, or `DEF-*`). Unreferenced markers mean completion is not auditable; set `status: gaps_found` and list each marker under `gaps`.
 
@@ -907,57 +909,6 @@ Automated checks passed. Awaiting human verification.
 
 </critical_rules>
 
-<stub_detection_patterns>
-
-## React Component Stubs
-
-```javascript
-// RED FLAGS:
-return <div>Component</div>
-return <div>Placeholder</div>
-return <div>{/* TODO */}</div>
-return null
-return <></>
-
-// Empty handlers:
-onClick={() => {}}
-onChange={() => console.log('clicked')}
-onSubmit={(e) => e.preventDefault()}  // Only prevents default
-```
-
-## API Route Stubs
-
-```typescript
-// RED FLAGS:
-export async function POST() {
-  return Response.json({ message: "Not implemented" });
-}
-
-export async function GET() {
-  return Response.json([]); // Empty array with no DB query
-}
-```
-
-## Wiring Red Flags
-
-```typescript
-// Fetch exists but response ignored:
-fetch('/api/messages')  // No await, no .then, no assignment
-
-// Query exists but result not returned:
-await prisma.message.findMany()
-return Response.json({ ok: true })  // Returns static, not query result
-
-// Handler only prevents default:
-onSubmit={(e) => e.preventDefault()}
-
-// State exists but not rendered:
-const [messages, setMessages] = useState([])
-return <div>No messages</div>  // Always shows "no messages"
-```
-
-</stub_detection_patterns>
-
 <success_criteria>
 
 - [ ] Previous VERIFICATION.md checked (Step 0)

package/commands/pp-autonomous.md

@@ -1,7 +1,7 @@
 ---
 name: pp:autonomous
 description: Run the next phase autonomously (best-effort) — discuss→plan→execute; --from/--to for a range
-argument-hint: "[--from N] [--to N] [--only N] [--supervised] [--interactive] [--converge]"
+argument-hint: "[--from N] [--to N] [--only N] [--supervised] [--interactive] [--converge] [--full]"
 effort: max
 allowed-tools:
   - Read
@@ -41,6 +41,7 @@ Optional flags:
 - `--interactive` — run discuss inline with questions (not auto-answered), then dispatch plan→execute as background agents. Keeps the main context lean while preserving user input on decisions.
 - `--converge` — run each phase's planning step through `pp-plan-review-convergence` instead of plain `pp-plan-phase`. Requires `workflow.plan_review_convergence=true`.
 - `--cross-ai` — compatibility alias for `--converge`.
+- `--full` — plan every phase with the full gate stack: forwarded to every /pp-plan-phase call, through /pp-plan-review-convergence under --converge; never to execute. A later plan-phase run without --full re-classifies the phase (references/ceremony.md, Lifecycle).
 
 When `--converge` or `--cross-ai` is set, reviewer selector flags supported by `pp-plan-review-convergence` may be passed through: `--codex`, `--gemini`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--all`, and `--max-cycles N`.
 

package/commands/pp-plan-phase.md

@@ -1,7 +1,7 @@
 ---
 name: pp:plan-phase
 description: Create detailed phase plan (PLAN.md) with verification loop
-argument-hint: "[phase] [--auto] [--research] [--skip-research] [--research-phase <N>] [--view] [--gaps] [--skip-verify] [--prd <file>] [--ingest <path-or-glob>] [--ingest-format <auto|nygard|madr|narrative>] [--reviews] [--text] [--tdd] [--mvp]"
+argument-hint: "[phase] [--auto] [--research] [--skip-research] [--research-phase <N>] [--view] [--gaps] [--skip-verify] [--full] [--prd <file>] [--ingest <path-or-glob>] [--ingest-format <auto|nygard|madr|narrative>] [--reviews] [--text] [--tdd] [--mvp]"
 effort: max
 allowed-tools:
   - Read
@@ -47,6 +47,7 @@ Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omit
 - `--skip-research` — Skip research, go straight to planning
 - `--gaps` — Gap closure mode (reads VERIFICATION.md, skips research)
 - `--skip-verify` — Skip verification loop
+- `--full` — Force every gate for this phase (ceremony mode full; rewrites the recorded verdict). Until the phase's first SUMMARY, a later plan-phase run without --full re-classifies it proportionally (D-12), so repeat --full on every re-plan that should stay full
 - `--prd <file>` — Use a PRD/acceptance criteria file instead of discuss-phase. Parses requirements into CONTEXT.md automatically. Skips discuss-phase entirely.
 - `--ingest <path-or-glob>` — Use one or more ADR files instead of discuss-phase. Parses locked decisions + scope fences into CONTEXT.md automatically. Skips discuss-phase entirely.
 - `--ingest-format <auto|nygard|madr|narrative>` — Optional ADR parser format override (`auto` default).

package/commands/pp-plan-review-convergence.md

@@ -1,7 +1,7 @@
 ---
 name: pp:plan-review-convergence
 description: "Cross-AI plan convergence - replan until review concerns are resolved."
-argument-hint: "<phase> [--codex] [--gemini] [--claude] [--opencode] [--ollama] [--lm-studio] [--llama-cpp] [--text] [--ws <name>] [--all] [--max-cycles N]"
+argument-hint: "<phase> [--codex] [--gemini] [--claude] [--opencode] [--ollama] [--lm-studio] [--llama-cpp] [--text] [--ws <name>] [--all] [--max-cycles N] [--full]"
 allowed-tools:
   - Read
   - Write
@@ -49,6 +49,7 @@ Phase number: extracted from $ARGUMENTS (required)
 - `--llama-cpp` — Use local llama.cpp server as reviewer (OpenAI-compatible, default host `http://localhost:8080`; configure model via `review.models.llama_cpp`)
 - `--all` — Use all available CLIs and running local model servers
 - `--max-cycles N` — Maximum replan→review cycles (default: 3)
+- `--full` — pass --full to the initial plan-phase run and to every --reviews replan, so the phase keeps the full gate stack
 
 **Feature gate:** This command requires `workflow.plan_review_convergence=true`. Enable with:
 `pp config-set workflow.plan_review_convergence true`

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "pp-core",
-  "version": "1.20.0",
+  "version": "1.21.1",
   "description": "PP Core — a meta-prompting, context engineering, and spec-driven development system for AI coding agents. Loads pp-core's operating context into every Gemini CLI session.",
   "contextFileName": "GEMINI.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pareto4/pp-core",
-  "version": "1.20.0",
+  "version": "1.21.1",
   "description": "Pareto pp-core — The Pareto Project's AI-assisted engineering framework: meta-prompting, context engineering, and spec-driven development for AI coding agents.",
   "bin": {
     "pp-core": "bin/install.js",