@pareto4/pp-core 1.20.0 → 1.21.1

package/pp-core/references/test-substance.md

@@ -0,0 +1,324 @@
+# Test substance
+
+Extracted from `agents/pp-planner.md` to keep that file inside its size budget.
+**Read by** the planner (task anatomy and `validate_plan`), the plan checker
+(Dimension 8) and the Nyquist auditor (`asserts_nothing` gaps). The rules are
+enforced by `pp_run check test-substance <phase>` (plans) and
+`pp_run check test-substance --scan <file...>` (test files), both in
+`src/test-substance.cts`. A parity test ties every rule constant named below to
+that module, so a rule added in code must be added here.
+
+A test that passes proves nothing unless it ran an assertion of the behaviour the
+task is about. Node's test runner exits 0 on an empty test body, on a
+`--test-name-pattern` that matches no test, and on a file with zero tests
+(verified on Node 25.9.0), so a green `<automated>` command alone is not
+evidence. The rules below make the plan say what is asserted and let code reject
+the shapes that cannot assert.
+
+## Behaviour statement
+
+Every non-checkpoint task has a `<behavior>` element (D-01).
+
+- An ordinary task: one line naming what its `<automated>` command asserts.
+- A documentation or configuration task: the state its check reads.
+- A `tdd="true"` task: its list of test cases.
+
+A behaviour is an observable outcome the command fails without (D-02). Write it
+as input → expected output, or as condition → result.
+
+Good:
+- `ceremony classify` on an empty repository returns tier light
+- `slugify('Hello World')` returns `hello-world`; an empty string returns an empty string
+
+Bad:
+- tests pass
+- the login route works
+
+Deterministic floor: a statement shorter than `20` characters or with fewer than
+`4` words is `behavior_generic`. A statement that equals, after normalisation, any
+of these phrases is also `behavior_generic` (whole-statement matches, never
+substrings): `tests pass`, `test passes`, `the tests pass`, `all tests pass`,
+`all the tests pass`, `it works`, `works`, `works as expected`,
+`it works as expected`, `everything works`, `file exists`, `the file exists`,
+`files exist`, `is implemented`, `it is implemented`, `implemented`, `done`,
+`passes`, `complete`, `build passes`, `the build passes`.
+Filler words (`all`, `of`, `the`, `now`, `correctly`, ...) are dropped before the
+compare, and up to two other words may lead the phrase, so "All of the tests
+pass now." and "the feature is implemented correctly" match. The list is
+deliberately narrow. A statement that still holds a template placeholder such as
+`[expected behavior]` is `behavior_generic` too.
+
+The floor catches filler. It cannot tell whether a statement names what the
+command really asserts; the plan checker judges that.
+
+## Scaffold shape
+
+When no test exists yet, a scaffold carries the task's real assertion (D-03). It
+is created in one of two places:
+
+- by the task itself, only when it is `tdd="true"`: its RED step writes and runs
+  the test;
+- by an earlier task of the same plan, which must be test infrastructure or a
+  `tdd="true"` RED task. Any other earlier task's own verify would fail on the
+  still-failing assertion. The verb accepts any earlier task; the checker judges
+  this one.
+
+Either way the file exists when the task's verify runs, so `<automated>` is that
+file's real test command. The marker `MISSING — Wave 0 must create {test_file} first`
+is never a final verify: the executor has no MISSING handling and would run it
+as a command. Every marker is a `scaffold_uncreated` finding, in any case and
+whatever wraps it (backticks, quotes, a list dash, `(`, `>`) or follows it
+(`MISSING.`, `MISSING-…`, `|| true` included); its detail names the fix. `marker_not_replaced`: the file is
+created by this task or an earlier one, so write the real command. `later_task`,
+`other_plan:<id>` or `no_creator`: move the scaffold before the task. `no_path`:
+the marker names no file.
+
+The same order check covers every real `<automated>` command. The verb reads the
+test files a command runs: a token with a directory and a test-file name, an
+option value such as `--files=…`, or a pytest `path::case`. After a leading
+`cd <dir> &&` the paths are read under `<dir>`. A file already on disk is never a
+finding. A file not on disk must be listed by the task itself, by an earlier task
+of its plan, or by a plan of an earlier wave. Otherwise it is `scaffold_uncreated`:
+
+- `later_task`: only a later task of the plan lists it. Move the creating task
+  first, or list the file in this task under `tdd="true"`.
+- `other_plan:<id>`: only a plan in the same or a later wave lists it. Create the
+  file in this plan, or give its creator an earlier wave if it is test
+  infrastructure.
+- `no_creator`: no plan lists it. List the file in the `<files>` of the task that
+  writes it.
+
+At most `20` test paths per command are read (`MAX_ORDER_PATHS`). The verb skips,
+and the checker reads for:
+
+- the whole command for any other `cd` or `pushd`, and these working-directory
+  options: `--prefix`, `--cwd`, `--root`, `--dir`, `--chdir`, `--workspace`,
+  `-C`, `--rootDir`, `--project`, `--projects`, `--testFile`;
+- the step alone (later steps at the root are still read) for a workspace runner
+  or container, also behind `npx`, `pnpm exec` or `yarn dlx`: `nx`, `turbo`,
+  `lerna`, `docker`, `docker-compose`, `podman`; for `yarn workspace`, `npm -w`,
+  `pnpm -F` and `pnpm --filter`; and for a child shell's `-c` script
+  (`bash -c "cd app && ..."`), whose quoted text is never read as steps;
+- a step whose verb names a path without running it, or writes one: `grep`, `rg`,
+  `echo`, `printf`, `test`, `[`, `ls`, `cat`, `head`, `tail`, `wc`, `git`, `cmp`,
+  `diff`, `stat`, `find`, `tee`, `cp`, `mv`, `touch`;
+- a file the command writes: the word after `>`, `>>` or `2>`, and the value of an
+  option whose name holds `destination`, `output` or `junit`
+  (`--test-reporter-destination`, `--outputFile`);
+- a glob, a `$` or `~` path, a token with `:`, a bare file name, and a path
+  outside the project.
+
+A real assertion fails until the code exists, and no wave may merge a failing test
+into the post-merge gate. So the test that carries a task's own assertion is
+created in that task's plan. Cross-wave Wave 0 work is reserved for test
+infrastructure (framework install, config, shared fixtures) that carries no
+behaviour assertion. An earlier-wave plan may also create a test that passes with
+its own code in that wave, which a later task runs. The verb accepts every
+earlier-wave creator, and the plan checker judges which kind it is (Dimension 8,
+check 8d).
+
+A scaffold is never vacuous. A scaffold action that describes one of these is
+`scaffold_empty`: `empty_body`, `placeholder`, `todo`, `skip` or `tautology`. A
+tautology is one of these literals (matched after collapsing whitespace):
+`assert.ok(true)`, `assert(true)`, `expect(true).toBe(true)`,
+`expect(true).toBeTruthy()`, `assert.equal(1, 1)`, `assert.strictEqual(1, 1)`,
+`assert True`, `self.assertTrue(True)`, `assert.True(t, true)`.
+The action is read sentence by sentence: a prose form needs a writing verb
+(write, create, add, leave, ...) within four words of it (eight for
+"placeholder test"), so "counts skipped tests" does not block. A placeholder
+phrase governed by a removing verb, with only determiners between ("replaces
+the placeholder test", "in place of the placeholder test", "removing every
+placeholder test"), is the remedy and does not block; "replaces it with a
+placeholder test" still does. A match is skipped when a negation (`never`, `not`,
+`no`, `don't`, `dont`, `without`, `avoid`, `instead of`; not a `no-` compound)
+sits earlier in its own clause or in the three words right before the phrase, so
+"never a placeholder test" and "write no placeholder tests" do not block. A
+new clause starts at "then" or "but", so "does not crash, then add a placeholder
+test" still blocks, while "never a placeholder test, `test.skip` or
+`assert.ok(true)`" negates the whole list. A negation earlier in the same clause
+("does not crash and add a placeholder test") hides the match: a residual the
+checker reads for.
+
+## Commands that pass without asserting
+
+An `<automated>` command can exit 0 without running an assertion (D-06). The
+verb flags a command whose every segment is one of these (`verify_vacuous`):
+
+| Kind | Command shape |
+|------|---------------|
+| `existence_only` | `test -f`, `[ -f ... ]`, `[[ -f ... ]]`, `ls`: the file exists, nothing ran |
+| `grep_test_file` | a `grep` over a test file: the text is there, the test never ran |
+| `or_true` | `... \|\| true`, or an `\|\|` fallback that checks nothing (below): the exit status is discarded |
+| `semicolon_true` | `...; true`, or a last `;`/newline segment that checks nothing: the exit status is discarded |
+| `exit_zero` | `exit 0`, also `exit "0"`, `exit '0'` or `exit 00` |
+| `pass_with_no_tests` | `--passWithNoTests` or `--pass-with-no-tests` |
+| `echo_only` | `echo ...` alone, or `env` / `printenv` with nothing to run |
+| `no_command` | an `<automated>` that is empty or holds only `cd`, `export`, `set`, a `VAR=val` or a comment: nothing runs |
+
+Segment rule: a shell comment (an unquoted `#` that starts a word) is dropped to
+the end of its line, then the command is split on `&&`, `;`, `||` and newline; a
+pipeline stays one segment. An existence check or an echo flags the command only when
+every segment is vacuous, so `test -f a.test.cjs && node --test a.test.cjs` is
+not flagged, and an `echo` or `printf` piped into another command is not an
+echo. The discarding forms (`or_true`, `semicolon_true`) flag on their own. A
+segment that checks nothing is an echo, `true`, `:`, `/bin/true`, `! false`, an
+existence check, a grep over a test file, or `cat`, `head`, `tail`, `wc`,
+`pwd`, `date`, `sleep`, `env` with nothing to run, `printenv`, `whoami`, `sort`,
+`uniq`, `tee`, an `awk` without `exit`, a `sed` without a `q` exit code, or a
+`git` `status`, `log`, `show`, `branch`, `add` or `diff` (without `--exit-code`,
+`--quiet` or `--check`). A bare `VAR=val` discards the status as the last step,
+not as an `||` fallback, where `|| rc=1` records the failure. A step is judged
+by the command it runs: a leading `env [VAR=val ...]` or `VAR=val` prefix is
+dropped, and a pipeline checks nothing only when its first
+and last stages both check nothing (a `|` inside quotes or escaped is not a
+stage), so `cat out.txt | grep -q ok` keeps the status. A real
+last step (`node --test b.test.cjs`, `exit $?`) keeps the status. So does a guard
+right after the last real step that exits non-zero when it fails, followed only
+by steps that check nothing: `|| exit 1`, `|| exit $?`, `|| { echo FAIL; exit 1; }`
+or `if [ $? -ne 0 ]; then exit 1; fi`. An `exit` inside a `( ... )` subshell
+leaves only the subshell and does not count. So does a
+`set -e` (or `set -o errexit`) before the first real step, for `;` only, and
+only where errexit stops the script: an `&&` or `||` list, a pipe without
+`pipefail`, a `!`, `if`, `elif`, `while` or `until` condition, a background `&`,
+an `export X=$(...)`, a `set +e`, a `<(...)` process substitution or a child
+shell (`bash -c`, `sh -c`) whose quoted script holds a `;` or newline anywhere in
+the command withdraws it.
+
+Named residuals the verb does not detect; the checker reads for them:
+
+- a `--test-name-pattern` that matches nothing;
+- a pipe to `tail`, `head`, `wc` or `tee` without `pipefail`, which hides a red;
+- `node --test` on a file with zero tests;
+- a `;true` or `|| true` quoted inside a `node -e "..."` string is flagged
+  (the scan is textual), a false positive to rephrase.
+
+## The check
+
+```bash
+SUBSTANCE=$(pp_run check test-substance "$PHASE" --raw)
+```
+
+Report keys: `phase_found`, `enforced`, `block`, `finding_count`, `plans[]` with
+`executed`, `findings` and `tasks[].findings[]` (each with `code` and `detail`),
+and `tdd_candidates_without_tdd`.
+
+Finding codes, all blockers (D-07), so they survive the light tier's
+blockers-only round:
+
+- `behavior_missing`: a non-checkpoint task has no `<behavior>` or an empty one,
+  or the plan has no task element at all (`no_xml_tasks`).
+- `behavior_generic`: the statement fails the floor or matches a denylist phrase.
+- `verify_vacuous`: the `<automated>` command is one of the kinds above.
+- `scaffold_uncreated`: a MISSING marker left as the verify, or a test file a real
+  command runs that is not on disk and has no earlier creator (see Scaffold shape).
+- `scaffold_empty`: the scaffold action describes a vacuous test.
+- `over_cap`: a plan or command is over the size cap, so it was not analysed; a
+  PLAN.md file over `MAX_PLAN_BYTES` bytes is not read at all.
+- `unreadable`: a plan file that is not a regular file (a symlink, FIFO or directory,
+  never read) or could not be read, or a phase directory that could not be read
+  (`read_error`), or the phase has no PLAN.md (`no_plans`); never clean.
+
+`block` follows `workflow.nyquist_validation` (D-08). When it is `false` the verb
+reports `enforced: false`, lists the findings and sets `block: false`; the
+planner still writes behaviour statements. A plan that already has a SUMMARY is
+reported but not counted. An unknown phase blocks (`phase_found: false`).
+
+`tdd_candidates_without_tdd` lists tasks that touch non-test source files but lack
+`tdd="true"`. It is information that never blocks by itself (D-12): the planner
+and the checker judge each against the heuristic in the next section.
+
+## TDD by default
+
+With `workflow.tdd_mode` off (the default), a task that passes the heuristic gets
+`tdd="true"` and a test-case `<behavior>` inside an ordinary plan (D-10).
+
+Heuristic: can you write `expect(fn(input)).toBe(output)` before writing `fn`?
+Candidates are business logic with defined I/O, API endpoints with
+request/response contracts, data transformations, validation rules, algorithms
+and state machines.
+
+Dedicated `type: tdd` plans stay `tdd_mode`'s: their ~40% context budget would undo
+the plan-count gains on small phases.
+
+Exclusions (D-11): `checkpoint:*` tasks, configuration-only files, documentation,
+migration scripts, glue code wiring already-tested components, styling-only
+changes and test-only tasks.
+
+The executor's RED → GREEN → optional REFACTOR flow applies to a default
+`tdd="true"` task unchanged (D-13). The extras stay tied to `tdd_mode`: the
+execute:post `tdd.review-checkpoint` gate, the MVP+TDD runtime gate and the
+plan-level gate sequence. The cost is one extra commit per business-logic task.
+
+Task-level example:
+
+```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>
+```
+
+## Assertion-free tests at validation
+
+`validate-phase` runs the scanner over the test files it mapped to requirements
+(D-14):
+
+```bash
+pp_run check test-substance --scan <file...> --raw
+```
+
+Report: `mode`, `files[]` and `totals`. Each case has a state in `asserts`,
+`asserts_nothing`, `todo` or `skip`; each file has a state in `ok`, `no_cases` or
+`unknown`. The scan covers at most 200 files, each under 1 MB, inside the project.
+
+Recognised assertion forms (D-16):
+
+- JS/TS: `assert(`, `assert.*`, `t.assert`, `expect(`, `.should`, `assert*()`,
+  `expect*()`
+- Python: `assert`, `self.assert*`, `pytest.raises`, `assert*()`, `expect*()`
+- Go: `t.Error*`, `t.Fatal*`, `t.Fail*`, `assert.*`, `require.*`, `assert*()`,
+  `expect*()`
+
+A literal tautology counts as asserting nothing. Any other language reports
+`unknown` and the auditor judges.
+
+Named residuals; the auditor reads the case before acting:
+
+- a helper whose name does not start with `assert` or `expect` hides its assertion
+  (`expected*` and `expectation*` are fixture builders and do not count; a JS
+  `expect(x)` counts only with a `.matcher`);
+- forms outside the lists above read as nothing (tape and ava `t.is`, Python
+  `self.fail`, ESLint `RuleTester.run`);
+- `test.each` / `test.concurrent` / `test.skip.each` tables, `describe`-only
+  files, `test(name, fnReference)`, a named call with a callback on another
+  object or member (`Deno.test`, `tap.test`, `test.fixme`), mocha
+  `specify` / `context`, testify
+  suite methods and a Python `class Test*` with no `def test*` report the file
+  `unknown`, even when other cases in it parse (those stay listed). Hooks,
+  steps and configuration on `test` (`test.beforeEach`, `test.step`,
+  `test.use`), a regex `.test('x')` and a variable named `it` are not cases;
+- a nested subtest credits its container;
+- a conditional `t.Skip` on an asserting Go test, or `t.skip()` / `t.todo()` on
+  a JS case's callback parameter, is listed under `skipped` (a node:test
+  `{ skip }` / `{ todo }` option counts only with a literal truthy value).
+
+Gap handling (D-14 to D-17):
+
+- A case with zero assertions leaves its requirement PARTIAL with gap type
+  `asserts_nothing`.
+- The auditor reads each case first: an assertion made inside a helper clears it.
+- It fills the gap by adding an assertion of the requirement's behaviour to the
+  existing test. It never deletes or weakens the test.
+- An assertion that still fails after 3 debug iterations is an implementation bug
+  and is escalated.
+- An assertion-free test is no coverage. `nyquist_compliant: true` requires zero
+  `asserts_nothing` gaps; the alternative is manual-only with a reason.

package/pp-core/references/verifier-stub-patterns.md

@@ -0,0 +1,51 @@
+# Verifier stub patterns
+
+The verifier reads this at Step 7 (anti-pattern scan) to recognise stub red flags.
+
+## 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"
+```
+

package/pp-core/templates/VALIDATION.md

@@ -71,6 +71,7 @@ created: {date}
 - [ ] Wave 0 covers all MISSING references
 - [ ] No watch-mode flags
 - [ ] Feedback latency < {N}s
+- [ ] No test that asserts nothing (`asserts_nothing` gaps: 0)
 - [ ] `nyquist_compliant: true` set in frontmatter
 
 **Approval:** {pending / approved YYYY-MM-DD}

package/pp-core/templates/phase-prompt.md

@@ -22,6 +22,7 @@ files_modified: []          # Files this plan modifies.
 autonomous: true            # false if plan has checkpoints requiring user interaction
 requirements: []            # REQUIRED — Requirement IDs from ROADMAP this plan addresses. MUST NOT be empty.
 user_setup: []              # Human-required setup Claude cannot automate (see below)
+context_estimate: N         # REQUIRED — sum of task estimates in tokens: 90000 or 90k, no ~/units
 
 # Goal-backward verification (derived during planning, verified after execution)
 must_haves:
@@ -63,6 +64,7 @@ Output: [What artifacts will be created]
 <task type="auto">
   <name>Task 1: [Action-oriented name]</name>
   <files>path/to/file.ext, another/file.ext</files>
+  <behavior>[One line: input → expected output that the verify command asserts. For a tdd="true" task, list its test cases.]</behavior>
   <read_first>path/to/reference.ext, path/to/source-of-truth.ext</read_first>
   <action>[Specific implementation - what to do, how to do it, what to avoid and WHY. Include CONCRETE values: exact identifiers, parameters, expected outputs, file paths, command arguments. Never say "align X with Y" without specifying the exact target state.]</action>
   <verify>[Command or check to prove it worked]</verify>
@@ -76,6 +78,7 @@ Output: [What artifacts will be created]
 <task type="auto">
   <name>Task 2: [Action-oriented name]</name>
   <files>path/to/file.ext</files>
+  <behavior>[One line: input → expected output that the verify command asserts]</behavior>
   <read_first>path/to/reference.ext</read_first>
   <action>[Specific implementation with concrete values]</action>
   <verify>[Command or check]</verify>
@@ -140,6 +143,7 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 | `autonomous` | Yes | `true` if no checkpoints, `false` if has checkpoints |
 | `requirements` | Yes | **MUST** list requirement IDs from ROADMAP. Every roadmap requirement MUST appear in at least one plan. |
 | `user_setup` | No | Array of human-required setup items (external services) |
+| `context_estimate` | No (schema) / always written by the planner | Estimated context cost of the plan in tokens (a bare integer or `90k`) — the sum of its task estimates; must fit the per-plan budget (50% of `context_window`) |
 | `must_haves` | Yes | Goal-backward verification criteria (see below) |
 
 **Wave is pre-computed:** Wave numbers are assigned during `/pp:plan-phase`. Execute-phase reads `wave` directly from frontmatter and groups plans by wave number. No runtime dependency analysis needed.
@@ -246,16 +250,16 @@ Wave 3 runs after Waves 1 and 2. Pauses at checkpoint, orchestrator presents to
 
 **Plan sizing:**
 
-- 2-3 tasks per plan
+- Size each plan from the estimated context cost of its tasks: up to 6 tasks while the summed estimate (`context_estimate`) stays within ~50% of `context_window`
 - ~50% context usage maximum
-- Complex phases: Multiple focused plans, not one large plan
+- The task count follows the estimate, never a target
 
 **When to split:**
 
-- Different subsystems (auth vs API vs UI)
-- >3 tasks
-- Risk of context overflow
-- TDD candidates - separate plans
+- Parallelism: independent subsystems with disjoint `files_modified` that run in the same wave
+- Budget: merged, the work would exceed ~50% of `context_window` or 6 tasks (a dedicated TDD plan is a budget case)
+
+Never split serial single-concern work to fit a task count.
 
 **Vertical slices preferred:**
 
@@ -332,6 +336,7 @@ Output: User model, API endpoints, and UI components.
 <task type="auto">
   <name>Task 1: Create User model</name>
   <files>src/features/user/model.ts</files>
+  <behavior>tsc --noEmit fails when User lacks id, email, name or createdAt, and passes once the interface exports all four</behavior>
   <action>Define User type with id, email, name, createdAt. Export TypeScript interface.</action>
   <verify>tsc --noEmit passes</verify>
   <done>User type exported and usable</done>
@@ -340,6 +345,7 @@ Output: User model, API endpoints, and UI components.
 <task type="auto">
   <name>Task 2: Create User API endpoints</name>
   <files>src/features/user/api.ts</files>
+  <behavior>GET /users returns 200 with the seeded users; GET /users/:id returns 404 for an unknown id; POST /users returns 201 and the created user</behavior>
   <action>GET /users (list), GET /users/:id (single), POST /users (create). Use User type from model.</action>
   <verify>fetch tests pass for all endpoints</verify>
   <done>All CRUD operations work</done>
@@ -398,6 +404,7 @@ Output: Working dashboard component.
 <task type="auto">
   <name>Task 1: Build Dashboard layout</name>
   <files>src/components/Dashboard.tsx</files>
+  <behavior>npm run build exits non-zero if Dashboard imports a missing component, and exits 0 once UserList and ProductList resolve</behavior>
   <action>Create responsive grid with UserList and ProductList components. Use Tailwind for styling.</action>
   <verify>npm run build succeeds</verify>
   <done>Dashboard renders without errors</done>
@@ -406,6 +413,7 @@ Output: Working dashboard component.
 <!-- Checkpoint pattern: Claude starts server, user visits URL. See checkpoints.md for full patterns. -->
 <task type="auto">
   <name>Start dev server</name>
+  <behavior>GET http://localhost:3000 returns 200 once the dev server is ready</behavior>
   <action>Run `npm run dev` in background, wait for ready</action>
   <verify>fetch http://localhost:3000 returns 200</verify>
 </task>
@@ -460,6 +468,8 @@ files_modified: [...]
 ```xml
 <task type="auto">
   <name>Set up authentication</name>
+  <behavior>auth works</behavior>
+  <!-- Generic behavior: no input, no expected output -->
   <action>Add auth to the app</action>
 </task>
 ```
@@ -469,6 +479,7 @@ files_modified: [...]
 <task type="auto">
   <name>Update database config</name>
   <files>src/config/database.ts</files>
+  <behavior>pool config is read from the environment</behavior>
   <!-- No read_first! Executor doesn't know current state or conventions -->
   <action>Update the database config to match production settings</action>
 </task>
@@ -487,6 +498,7 @@ files_modified: [...]
 <task type="auto">
   <name>Update database config for connection pooling</name>
   <files>src/config/database.ts</files>
+  <behavior>importing database.ts with NODE_ENV=production yields a pool with max 20 and ssl.rejectUnauthorized true</behavior>
   <read_first>src/config/database.ts, .env.example, docker-compose.yml</read_first>
   <action>Add pool configuration: min=2, max=20, idleTimeoutMs=30000. Add SSL config: rejectUnauthorized=true when NODE_ENV=production. Add .env.example entry: DATABASE_POOL_MAX=20.</action>
   <acceptance_criteria>
@@ -506,7 +518,7 @@ files_modified: [...]
 - Prefer vertical slices over horizontal layers
 - Only reference prior SUMMARYs when genuinely needed
 - Group checkpoints with related auto tasks in same plan
-- 2-3 tasks per plan, ~50% context max
+- Up to 6 tasks per plan within ~50% of `context_window`; split only for parallelism or budget
 
 ---
 

package/pp-core/templates/roadmap.md

@@ -107,7 +107,7 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 **Initial planning (v1.0):**
 - Phase count depends on granularity setting (coarse: 3-5, standard: 5-8, fine: 8-12)
 - Each phase delivers something coherent
-- Phases can have 1+ plans (split if >3 tasks or multiple subsystems)
+- Phases can have 1+ plans (split only for parallelism across independent subsystems or when the work exceeds the per-plan context budget; up to 6 tasks per plan)
 - Plans use naming: {phase}-{plan}-PLAN.md (e.g., 01-02-PLAN.md)
 - No time estimates (this isn't enterprise PM)
 - Progress table updated by execute workflow

package/pp-core/templates/verification-report.md

@@ -209,7 +209,7 @@ None — all verifiable items checked programmatically.
 **Fix plan generation:**
 - Only generate if gaps_found
 - Group related fixes into single plans
-- Keep to 2-3 tasks per plan
+- Size each fix plan by estimated context cost (up to 6 tasks per plan)
 - Include verification task in each plan
 
 ---

package/pp-core/workflows/audit-milestone.md

@@ -163,8 +163,11 @@ Classify per phase:
 | COMPLIANT | `nyquist_compliant: true` and all tasks green |
 | PARTIAL | VALIDATION.md exists, `nyquist_compliant: false` or red/pending |
 | MISSING | No VALIDATION.md |
+| SKIPPED | No VALIDATION.md and the phase verdict skipped the Nyquist audit — report `skipped (ceremony: <reason>)`, never MISSING |
 
-Add to audit YAML: `nyquist: { compliant_phases, partial_phases, missing_phases, overall }`
+Before marking a phase MISSING, read `pp_run ceremony get "<phase number>" --pick gates.nyquist.report`; when it starts with `skipped (ceremony:` the status is SKIPPED. A failed read leaves the phase MISSING. A SKIPPED phase does not lower `overall`.
+
+Add to audit YAML: `nyquist: { compliant_phases, partial_phases, missing_phases, skipped_phases, overall }`
 
 Discovery only — never auto-calls `/pp:validate-phase`.
 

package/pp-core/workflows/autonomous.md

@@ -16,7 +16,7 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 ## 1. Initialize
 
-Parse `$ARGUMENTS` for `--from N`, `--to N`, `--only N`, `--interactive`, `--supervised`, `--converge`/`--cross-ai`, reviewer selector flags, and `--max-cycles N`:
+Parse `$ARGUMENTS` for `--from N`, `--to N`, `--only N`, `--interactive`, `--supervised`, `--converge`/`--cross-ai`, `--full`, reviewer selector flags, and `--max-cycles N`:
 
 ```bash
 FROM_PHASE=""
@@ -44,6 +44,8 @@ SUPERVISED=""
 if echo "$ARGUMENTS" | grep -q '\-\-supervised'; then SUPERVISED="true"; fi
 UNATTENDED_ARG=""
 if [ -z "$SUPERVISED" ]; then UNATTENDED_ARG=" --unattended"; fi
+FULL_ARG=""
+if echo "$ARGUMENTS" | grep -qE '(^|[[:space:]])--full([[:space:]]|$)'; then FULL_ARG=" --full"; fi
 
 PLAN_STRATEGY="local"
 if echo "$ARGUMENTS" | grep -qE '(^|[[:space:]])\-\-(converge|cross-ai)([[:space:]]|$)'; then
@@ -62,11 +64,12 @@ if echo "$ARGUMENTS" | grep -qE '\-\-max-cycles\s+[0-9]+'; then
   MAX_CYCLES_ARG=$(echo "$ARGUMENTS" | grep -oE '\-\-max-cycles\s+[0-9]+' | awk '{print $2}')
   CONVERGENCE_ARGS="${CONVERGENCE_ARGS} --max-cycles ${MAX_CYCLES_ARG}"
 fi
+CONVERGENCE_ARGS="${CONVERGENCE_ARGS}${FULL_ARG}"
 ```
 
 When `--interactive` is set, discuss runs inline with questions (not auto-answered). On runtimes where a backgrounded agent can spawn subagents, plan and execute are dispatched as background agents — keeping the main context lean (only discuss conversations accumulate) and enabling overlap. On Claude Code, where a backgrounded agent cannot nest subagents, plan and execute run inline to preserve worktree isolation and independent verification, so they run sequentially and their work accumulates in the main context. Either way, user input is preserved on all design decisions.
 
-When `PLAN_STRATEGY=converge`, the planning step MUST invoke the plan-review convergence workflow instead of `pp-plan-phase`. `--cross-ai` is an alias for `--converge`. Forward `CONVERGENCE_ARGS` exactly as parsed so reviewer flags and `--max-cycles N` retain the same meaning as they have on `/pp:plan-review-convergence`.
+When `PLAN_STRATEGY=converge`, the planning step MUST invoke the plan-review convergence workflow instead of `pp-plan-phase`. `--cross-ai` is an alias for `--converge`. Forward `CONVERGENCE_ARGS` exactly as parsed so reviewer flags and `--max-cycles N` retain the same meaning as they have on `/pp:plan-review-convergence`. `--full` is forwarded the same way and reaches every plan-phase call the convergence loop makes; it is never passed to execute-phase.
 
 With `--supervised` every prompt appears as before; otherwise each decision is best-effort and recorded (reference § Rules). `--interactive` only moves discuss inline.
 
@@ -286,7 +289,7 @@ Resolve active `plan:pre` hooks:
 ```bash
 [ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
-HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw)
+HOOKS_JSON=$(pp_run loop render-hooks plan:pre --raw --phase "${PHASE_NUM}")
 printf '%s' "$HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 ```
 
@@ -404,7 +407,7 @@ RUNTIME=$(pp_run query config-get runtime --default claude --raw 2>/dev/null ||
   - Otherwise (local planning):
 
   ```
-  Skill(skill="pp-plan-phase", args="${PHASE_NUM}${UNATTENDED_ARG}")
+  Skill(skill="pp-plan-phase", args="${PHASE_NUM}${UNATTENDED_ARG}${FULL_ARG}")
   ```
 
 - **On other runtimes:** Dispatch plan as a background agent to keep the main context lean. While plan runs, the workflow can immediately start discussing the next phase (see step 4).
@@ -425,7 +428,7 @@ RUNTIME=$(pp_run query config-get runtime --default claude --raw 2>/dev/null ||
   Agent(
     description="Plan phase ${PHASE_NUM}: ${PHASE_NAME}",
     run_in_background=true,
-    prompt="Run plan-phase for phase ${PHASE_NUM}: Skill(skill=\"pp-plan-phase\", args=\"${PHASE_NUM}${UNATTENDED_ARG}\")"
+    prompt="Run plan-phase for phase ${PHASE_NUM}: Skill(skill=\"pp-plan-phase\", args=\"${PHASE_NUM}${UNATTENDED_ARG}${FULL_ARG}\")"
   )
   ```
 
@@ -442,7 +445,7 @@ Skill(skill="pp-plan-review-convergence", args="${PHASE_NUM} ${CONVERGENCE_ARGS}
 If `PLAN_STRATEGY=local`, run the regular planner:
 
 ```
-Skill(skill="pp-plan-phase", args="${PHASE_NUM}${UNATTENDED_ARG}")
+Skill(skill="pp-plan-phase", args="${PHASE_NUM}${UNATTENDED_ARG}${FULL_ARG}")
 ```
 
 Verify plan produced output — re-run `init phase-op` and check `has_plans`. If false → go to handle_blocker: "Plan phase ${PHASE_NUM} did not produce any plans."
@@ -535,7 +538,7 @@ Phase ${PHASE_NUM} ✅ ${PHASE_NAME} — Verification passed
 **If `gaps_found`:** rule A-3 — one closure attempt:
 
 ```
-Skill(skill="pp-plan-phase", args="${PHASE_NUM} --gaps${UNATTENDED_ARG}")
+Skill(skill="pp-plan-phase", args="${PHASE_NUM} --gaps${UNATTENDED_ARG}${FULL_ARG}")
 ```
 
 Verify gap plans were created — re-run `init phase-op ${PHASE_NUM}` and check `has_plans`. If no new gap plans → go to handle_blocker: "Gap closure planning for phase ${PHASE_NUM} did not produce plans."
@@ -561,7 +564,7 @@ Resolve the active post-verification hooks and the UI-SPEC gate:
 ```bash
 [ -z "${ZSH_VERSION:-}" ] || emulate -R sh
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
-HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw)
+HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw --phase "${PHASE_NUM}")
 ```
 
 Read the `activeHooks` array directly from the `HOOKS_JSON` value already in context (do not invoke a shell `jq` pipeline — parse as the JSON object it is). **If `activeHooks` is empty or absent:** skip silently to the iterate step.