@pareto4/pp-core 1.19.0 → 1.21.0

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-discovery-conformance.md

@@ -0,0 +1,36 @@
+# Discovery conformance — the verifier contract (R3)
+
+**Load this file from pp-verifier Step 6d on a project that ran the Discovery Sprint** (contract:
+`references/discovery-build-consumption.md`). Planning read the Discovery registers; verification
+is where conformance is enforced — "did we build what was signed" is answered per phase.
+
+```bash
+DISCOVERY_CONFORMANCE=$(pp_run query discovery.for-phase "$PHASE_NUM" --conformance-template 2>/dev/null || true)
+```
+
+Empty output means no `.planning/discovery/` — write no block and stop here. A non-zero exit is a
+structural fault in a discovery register: record it as a gap naming the fault list.
+
+Otherwise the output is the **Discovery conformance** block: one row per Discovery register row
+that cites this phase's requirement IDs (`_requirements.md`, `_stories.md`, `_processes.md` steps,
+`_entities.md`, `_rules.md`, `_screens.md`, roles, integrations), every row `missed`. Fill it:
+
+1. **The acceptance criteria ARE the UAT.** Each `_requirements.md` and `_stories.md` row's
+   acceptance criteria is a truth in Step 3 — add any the plans' `must_haves` omitted — verified
+   by the same evidence rules as every other truth.
+2. **One status per row**, exactly one of:
+   - `honoured` — evidence that the build realises the row (`file:line`, a test name) in `Evidence`;
+   - `amended (D-P<nn>-<n>)` — the register cell carries `→ amended by` that decision and the build
+     matches the amended cell; name the cell in `Evidence`;
+   - `missed` — no evidence, or the build contradicts the row; say which in `Evidence`.
+3. **Never add, remove or rename a row**; never open a `.planning/discovery/session-NN.md` — the
+   register row is the fact, and `--verify` refuses an unknown or missing row.
+4. **A `missed` row is a gap.** It fires rule 1 of Step 9 (`gaps_found`) and appears in the Gaps
+   Summary with its row key (`_rules.md BR-02`).
+5. **Paste the filled block into VERIFICATION.md** under `### Discovery conformance`, markers
+   included, after Requirements Coverage. Then run
+
+   `pp_run query discovery.for-phase "$PHASE_NUM" --verify "$REPORT_PATH"`
+
+   and repair the block until it exits 0 (markers once each, header, every row present once, legal
+   statuses). A `missed` count is never a fault of the block.

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
 
 ---