@pareto4/pp-core 1.19.0 → 1.21.0

package/pp-core/references/discovery-standards.md

@@ -0,0 +1,107 @@
+# Discovery Standards First — `_deviations.md` Template, Parser Contract & the Standards Applied Table
+
+Single home for how the Discovery Sprint treats the client's standards once a vault is bound
+(Discovery Sprint improvement plan, Batch 3): the questions the vault already answers are not asked
+open-ended, every session from 4 to 10 records which standard governs each area in a **Standards
+Applied** table, and every departure from a standard is one `DEV-` row of `_deviations.md` — the
+register the charter § 7 copies, the handoff gates on, and `pp-vault-review` reads so an approved
+deviation is reported as a deviation on file, never as a violation. This file is Read lazily; it is
+never `@`-imported.
+
+## Standards first — the question rule
+
+When a session's `## Vault Context` record names a document that already fixes what a topic asks the
+client to decide, the facilitator does not ask the open question. The question becomes:
+
+> The vault fixes `<what>` — `[vault: <path>]`. Does this product deviate, and why?
+
+- **No deviation:** the Standards Applied row cites the standard, `Deviation` reads `none`. Nothing
+  else is written — the vault stays the single home of the standard (never copy its text).
+- **A deviation:** mint one `DEV-<nn>` row in `.planning/discovery/_deviations.md` (create the file
+  from the template below on first need), record the decision as a Key Decisions row `D-<ss>-<n>` and
+  write both IDs into the Standards Applied row (`Deviation` = the `DEV-nn`, `Decision` = the `D-ss-n`).
+- **No standard covers the area:** the Standards Applied row reads `not in vault`; the question stays
+  open-ended and the answer is a Key Decisions row; add an Action Items row for the vault owner when
+  the gap should be closed in the vault.
+- **No vault bound** (the session record says `Index: none`, or the project runs without the vault
+  capability): every question stays open-ended, Standards Applied rows read `not in vault`, and
+  `_deviations.md` is never created — there is no standard to deviate from.
+
+The session files phrase their stack and tooling questions in this shape; the vault document to cite
+is the one the session's `## Vault Context` record selected for that topic.
+
+## The Standards Applied table
+
+Every session from 4 to 10 carries one, in its Notes Template, with the areas the session decides:
+
+| Area | Standard | Deviation | Decision |
+|------|----------|-----------|----------|
+
+- **Standard** is the governing document's `[vault: <rel path>]` citation (several, space-separated,
+  when more than one applies), or `not in vault`.
+- **Deviation** is `none`, or the `DEV-<nn>` of the `_deviations.md` row.
+- **Decision** is `—`, or the `D-<ss>-<n>` that records the deviation or the decision taken for an
+  uncovered area.
+
+The charter § 7 reads `_deviations.md`, not these tables; the tables are where a reader of one
+session sees which standards bound it. Session 4 introduced the shape (frontend standards); Sessions
+5–10 follow it.
+
+## `_deviations.md`
+
+A deviation is a choice that goes against a standard the vault states. The vault's own rule
+(`architecture/deviations.md` in the Pareto vault, and its equivalent elsewhere): deviating is
+allowed, hiding it is not; an architect signs every one; only what is **hard to reverse** waits for
+the signature before the dependent work proceeds, and a security or compliance deviation is always
+hard. The register carries exactly that record.
+
+Illustration only — not part of the template:
+
+| ID | Standard | Choice | Reason | Reversible | Approver | Decision | Status |
+|---|---|---|---|---|---|---|---|
+| DEV-01 | [vault: pipeline/quality-gates.md] | Trivy and CodeQL instead of SonarCloud | Free plan, one-person team | easy | Architect | D-09-3 | Approved |
+
+Bootstrap template — the first session that records a deviation copies it verbatim to
+`.planning/discovery/_deviations.md`, replacing `[PROJECT_NAME]`:
+
+```markdown
+# Deviations from standards — [PROJECT_NAME]
+
+**Conventions:** pp-core reference `references/discovery-standards.md`. One `DEV-` row per departure from a vault standard: the standard as a `[vault: <path>]` citation, the choice made instead, why, whether it is `easy` or `hard` to reverse (a security or compliance deviation is always `hard`), who approves it (an approver of Session 1's Approval Matrix), the `D-<ss>-<n>` that recorded it and its status (`Proposed`, `Approved`, `Rejected`, `Superseded`). A hard deviation is approved before the handoff. Rows are never renumbered or deleted; a change after sign-off edits the row in place and appends `→ amended by D-<ss>-<n>`.
+
+## Deviations
+
+| ID | Standard | Choice | Reason | Reversible | Approver | Decision | Status |
+|----|----------|--------|--------|------------|----------|----------|--------|
+```
+
+### Parser contract — `pp_run query discovery.deviations-check [--require-approved]`
+
+No positional path. Faults name the artifact, the 1-based line, a validated ID or path, a column name
+and the reason code — never cell prose. Absent `_deviations.md` → exit 0, `present: false`.
+
+| Cell / field | Grammar | Fault when violated |
+|---|---|---|
+| `## Deviations` | once, holding one table with the template's columns | `missing_section`, `bad_table_shape` |
+| `ID` | `DEV-\d{2}`, unique, contiguous from 01 | `bad_id`, `duplicate_id`, `sequence_gap` naming the missing ID |
+| `Standard` | at least one `[vault: <path>]`; each path relative, no `..` or dot segment, ending `.md`, and present in the vault cache when `.planning/vault/` is on disk | `bad_standard` (no citation, or an unsafe path); `unknown_standard` naming the path. **Not resolved** while there is no cache |
+| `Choice`, `Reason` | non-empty | `empty_cell` naming the column |
+| `Reversible` | `easy` \| `hard` | `bad_reversible` |
+| `Approver` | non-empty; one of the `Approver` tokens of Session 1's **Approval Matrix** when that table is on file with rows | `empty_cell (Approver)`; `unknown_approver`. **Not resolved** while Session 1 has no matrix (an engagement that predates it) |
+| `Decision` | `—`, or `D-<ss>-<n>` / `D-P<nn>-<n>` (shape only — `charter-check` resolves it) | `bad_decision`; `decision_missing` when `Status` is `Approved` or `Rejected` and the cell is `—` |
+| `Status` | `Proposed` \| `Approved` \| `Rejected` \| `Superseded` | `bad_status` |
+| a `hard` row still `Proposed` | approved before the handoff | `hard_deviation_unapproved` under `--require-approved` only |
+| `session-01.md` present but unreadable | present-and-readable | `artifact_unreadable` naming the path |
+
+**Exit identity.** `discovery_deviations_check_failed` for structural faults;
+`discovery_deviations_unapproved` when every fault is a `hard_deviation_unapproved`. Payload: `ok`,
+`present`, `file`, `deviations`, `approved`, `unapproved_hard`.
+
+## Who reads it
+
+| Reader | Contract |
+|---|---|
+| Project Charter § 7 | copies every row; `charter-check` resolves `DEV-` IDs against this file alone and reports `deviation_missing` for a row the charter leaves out (`references/discovery-charter.md`) |
+| `/pp-discovery-to-build` | `deviations-check --require-approved` hard-blocks on a hard deviation still `Proposed` (`workflows/discovery-to-build/steps/handoff-gates.md`) |
+| `pp-vault-review` | reads `Standard` and `Status` by header name; an `Approved` row covering a failed clause turns the FAIL into `N-A` "deviation on file" (`references/discovery-build-consumption.md` § `_deviations.md` read contract) |
+| `discovery for-phase` | the register has no requirement column, so every extract lists it as not filterable — the planner reads it whole |

package/pp-core/references/discovery-traceability.md

@@ -14,8 +14,8 @@ does not restate them. Read that file when you need an ID's shape or the reserve
 
 ## When these files appear
 
-Both artifacts are bootstrapped **on first need**, exactly the way `_progress.md` and
-`_context.md` are in Flow 2 Step 1, and exactly the way the three research-track registers
+Both artifacts are bootstrapped **on first need**, exactly the way `_progress.md`
+is in Flow 2 Step 1, and exactly the way the three research-track registers
 are in `references/discovery-research-track.md`: if the file is absent when a session first
 has something to put in it, create it verbatim from the template below, then add the row.
 There is no sub-command and no setup step — an empty inventory is not a milestone, and an

package/pp-core/references/few-shot-examples/plan-checker.md

@@ -1,7 +1,7 @@
 ---
 component: plan-checker
-version: 1
-last_calibrated: 2026-03-24
+version: 2
+last_calibrated: 2026-10-27
 ---
 
 # Plan-Checker Few-Shot Examples
@@ -55,19 +55,19 @@ last_calibrated: 2026-03-24
 
 **Why this is bad:** The checker missed two violations. verification_derivation requires verify commands to be runnable and test actual output -- an empty verify block is a BLOCKER. Verify commands must distinguish pass from fail -- `echo "done"` always returns 0 regardless of implementation state. Both should have been flagged.
 
-### Example 2: False positive INFO for a correctly-sized plan
+### Example 2: False positive on a 6-task plan within limits, missed serial over-split
 
-**Input:** Plan with 3 tasks, 6 unique files, 1 dependency. All within limits.
+**Input:** Phase at `context_window: 1000000` (`plan_budget_tokens` 500000). Plan 01 has 6 tasks, 14 files, `context_estimate: 240000`, wave 1. Plan 02 (2 tasks, `context_estimate: 60000`) is alone in wave 2 and depends on 01. Plan 03 (3 tasks, `context_estimate: 70000`) is alone in wave 3 and depends on 02. `check plan-sizing` reports `over_ceiling: []` and `unjustified_splits: [02, 03]`.
 
 **Output:**
 
 > ```yaml
 > issues:
 >   - dimension: scope_sanity
->     severity: INFO
->     finding: "Plan has 3 tasks -- consider splitting into smaller plans for faster iteration"
+>     severity: WARNING
+>     finding: "Plan 01 has 6 tasks -- consider splitting into smaller plans"
 >     affected_field: "task count"
->     suggested_fix: "Split tasks into separate plans"
+>     suggested_fix: "Split plan 01 into separate plans"
 > ```
 
-**Why this is bad:** The checker flagged a non-issue. scope_sanity allows 2-3 tasks per plan -- 3 tasks is within limits. The checker applied a personal preference ("smaller is better") rather than the documented threshold. This wastes planner time on false positives and erodes trust in the checker's judgment. A correct check would produce no issue for this plan.
+**Why this is bad:** Both calls are wrong. 6 tasks is within the ceiling and 240000 fits the 500000 budget, so plan 01 has no issue (01 and 02 merged would be 8 tasks, so that split is justified). Plans 02 and 03 are a serial split with neither reason (merged 5 tasks / 130000 tokens), so a correct check raises one scope_sanity blocker for that pair with fix "merge 03 into 02" and nothing for plan 01.

package/pp-core/references/phase-timeline.md

@@ -0,0 +1,107 @@
+# Phase Timeline
+
+Every `Agent()` run that plan-phase, execute-phase and code-review spawn is recorded in `{phase_dir}/{padded}-TIMELINE.jsonl`, one JSON object per line, append-only. Only the orchestrator writes, on its own checkout, before and after each spawn. An executor never receives a timeline instruction, so a worktree executor is recorded like any other run and nothing is lost when its worktree is removed. The file is committed with the existing planning commits (plan-phase 13d, execute-phase `update_roadmap` and code-review `commit_review`), never per run. When `.planning/` is gitignored that commit reports `skipped_gitignored` by design and the file stays on disk.
+
+## Record
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `id` | string | `{phase}-{role}[-{plan}]-{n}`, minted by `start` |
+| `phase` | string | padded phase token, for example `35` |
+| `agent` | string | agent name, defaulted from the role table |
+| `role` | enum | `researcher`, `pattern-mapper`, `planner`, `plan-checker`, `executor`, `code-reviewer`, `verifier`, `other` |
+| `model` | string | the model the orchestrator passed to `Agent()`; `inherit` is recorded literally |
+| `plan` | string or null | plan id for executors, `null` for every other role |
+| `started_at` | string | ISO-8601 UTC |
+| `ended_at` | string or null | ISO-8601 UTC; `null` while the run is open |
+| `duration_ms` | number or null | `ended_at - started_at`, recomputed on read |
+| `outcome` | string or null | return marker mapped in Outcomes; `null` while open |
+| `source` | enum | `plan-phase`, `execute-phase` or `code-review` |
+
+`start` appends a full record with null end fields. `end` appends a second complete line with the same `id`. Readers keep the last line per `id`, sort by `started_at` and skip lines that do not parse, so a torn write loses at most one line. A record with `ended_at: null` is incomplete: it is shown as `incomplete` and excluded from wall-clock and agent time.
+
+## Commands
+
+```
+pp_run timeline start <role> <phase> [--plan P] [--agent A] [--model M] [--source S]
+pp_run timeline end <role> <phase> <outcome> [--plan P] [--id ID]
+pp_run timeline summary <phase> [--banner]
+```
+
+- `start` prints the new id. `end` closes the most recent open record with that role, and that plan when `--plan` is given, and prints the closed record.
+- Synonyms: `--phase`, `--role`, `--outcome` replace the positionals, and `end` takes `--id ID`, or an id positional together with `--outcome`, in place of the role.
+- Defaults: `agent` comes from the role table (`pp-phase-researcher`, `pp-pattern-mapper`, `pp-planner`, `pp-plan-checker`, `pp-executor`, `pp-code-reviewer`, `pp-verifier`); `model` comes from the model-profile resolver when `--model` is omitted; `source` is inferred from the role. Role `other` requires both `--agent` and `--source`.
+- `end` with nothing open exits 1 with reason `timeline_no_open_run`; an unknown or archived phase exits 1 with `phase_not_found`; bad flags exit 1 with `usage`. A failed call never changes the file.
+- Free text (outcome, agent, model) is sanitized and capped at 80 characters before it is written.
+- The clock comes from the CLI. Workflows never compute a duration with `date`.
+- `summary` reads live and archived phases. Plain `summary` prints JSON (or the footer line with `--raw`); `--banner` prints the two completion-block lines.
+
+## Call-site rules
+
+- Put `start` on the line before the `Agent()` fence and `end` where the return is handled.
+- Every call ends with `|| true`, so a timing failure can never break a phase, and carries no stderr redirection.
+- Key by role (and `--plan {plan_id}` for executors), never by an id held in a shell variable: each fenced block runs in its own shell (issue #381) and `Agent()` is not bash.
+- Pass `--model` only where the `Agent()` model differs from the resolver default: `"{researcher_model}"` for the pattern mapper, `"{executor_model}"` for executors, `inherit` where `Agent()` receives no `model=` (code reviewer, drift-gate mapper).
+- Worktree executors are dispatched in the background, so the executor `end` rides the plan-complete heartbeat in step 4, not the line after the fence.
+- Never put a timeline call inside an agent prompt.
+- Workflows reference this file by plain path, never with an `@` import, so it is read only when a rule is needed.
+
+## Sites
+
+| Workflow | Section | Role | Flags | End location |
+|----------|---------|------|-------|--------------|
+| plan-phase.md | 5.1 researcher | `researcher` | none | first line under `### Handle Researcher Return` |
+| plan-phase.md | 5.6 capability `ref.agent` dispatch | `other` | `--agent {capId} --source plan-phase` | after the dispatched agent returns |
+| plan-phase.md | 7.8 pattern mapper | `pattern-mapper` | `--model "{researcher_model}"` | under `**Handle return:**` |
+| plan-phase.md | 8 planner | `planner` | none | first line of `## 9. Handle Planner Return` |
+| plan-phase.md | 10 plan checker | `plan-checker` | none | first line of `## 11. Handle Checker Return` |
+| plan-phase.md | 12 revision planner | `planner` | none | on the `After planner returns` line |
+| chunked-planning.md | 8.5.1 outline planner | `planner` | none | under `Handle return:` |
+| chunked-planning.md | 8.5.2 per-plan planner | `planner` | none | step 4 `Verify disk`, before the Retry/Stop offer |
+| execute-phase.md | step 3/4 executor, worktree and sequential mode | `executor` | `--plan {plan_id} --model "{executor_model}"` | start after the plan-start heartbeat; end with the plan-complete heartbeat |
+| execute-phase.md | `verify_phase_goal` verifier | `verifier` | none | start in the `VERIFIER_SKILLS` fence; end in the `verification.status` fence with `"${STATUS:-failed}"` |
+| execute-phase/steps/codebase-drift-gate.md | optional mapper | `other` | `--agent pp-codebase-mapper --source execute-phase --model inherit` | after the mapper returns |
+| code-review.md | `pp-code-reviewer` | `code-reviewer` | `--model inherit` | last line of `commit_review`: `complete` only when REVIEW.md exists with valid frontmatter, else `failed`; `failed` on the agent-failure path |
+
+Chunked return path: chunked-planning.md hands `## PLANNING COMPLETE` to step 9 but skips step 9's planner `end` — both chunked runs are already closed, and a third `end` would only print `timeline_no_open_run`.
+
+Commit sites: plan-phase 13d, execute-phase `update_roadmap` and code-review `commit_review` add `{phase_dir}/*-TIMELINE.jsonl` to the existing planning commit, so a standalone `/pp-code-review` (or a `--fix` re-run) does not leave the reviewer's lines uncommitted. `cmdCommit` skips the glob when it matches nothing.
+
+Banner site: execute-phase `update_roadmap` runs `pp_run timeline summary {phase} --banner`, and the three completion blocks (`## PHASE COMPLETE` on the `--no-transition` path and both `## ✓ Phase {X}: {Name} Complete` blocks) print its stdout verbatim.
+
+## Outcomes
+
+| Run | Return | Outcome |
+|-----|--------|---------|
+| researcher | `## RESEARCH COMPLETE` | `complete` |
+| researcher | `## RESEARCH BLOCKED` | `blocked` |
+| pattern mapper | `## PATTERN MAPPING COMPLETE` | `complete` |
+| pattern mapper | error or empty | `failed` |
+| planner | `## PLANNING COMPLETE` | `complete` |
+| planner | `## PLANNING INCONCLUSIVE` | `inconclusive` |
+| planner | `## CHECKPOINT REACHED` | `checkpoint` |
+| planner | `## PHASE SPLIT RECOMMENDED` | `split_recommended` |
+| planner | `## ⚠ Source Audit` | `source_audit_gaps` |
+| planner | no marker (filesystem fallback) | `fallback` |
+| plan checker | `## VERIFICATION PASSED` | `passed` |
+| plan checker | `## ISSUES FOUND` | `issues_found` |
+| plan checker | no marker | `fallback` |
+| chunked outline | `## OUTLINE COMPLETE` | `complete`, otherwise `failed` |
+| chunked per-plan | plan file on disk | `complete`; missing: `failed` |
+| executor | plan-complete heartbeat word | `complete`, `failed` or `checkpoint`; `fallback` when the spot-check confirmed completion |
+| verifier | `$STATUS` verbatim | `passed`, `gaps_found`, `human_needed`, `missing` or `unknown`; empty: `failed` |
+| code reviewer, drift-gate mapper, capability agents | agent result | `complete` or `failed` |
+
+Free text is accepted and shown verbatim after sanitizing.
+
+## Wall-clock
+
+- Each source (`plan-phase`, `execute-phase`, `code-review`) gets one span: the latest `ended_at` minus the earliest `started_at` over that source's completed runs, so parallel executors count once.
+- Total wall-clock is the length of the union of those spans. It equals the plain sum when the spans are disjoint, so idle days between planning and executing are excluded, and a code review that runs inside the execute span counts once.
+- `elapsed` is the first start to the last end. It appears in the footer only when it differs from the total.
+- Agent time is the sum of completed run durations.
+- Durations are compact: `38s`, `45m 10s`, `1h 12m`, `3h 02m`. `Started` is local time `HH:MM`, with the date shown once per table (a run on another day carries `MM-DD HH:MM`).
+- Footer: `Total wall-clock: 2h 14m · agent time 3h 02m · 12 runs (1 incomplete)`, plus `· elapsed {duration}` when it differs.
+- Banner (two lines): `Wall-clock: 2h 14m (12 runs)` and `Longest: executor 35-03 (claude-opus-4-7) 41m · planner (opus) 22m · verifier (sonnet) 17m`. Each longest entry is `{role}[ {plan}][ ({model})] {duration}`; the model is omitted only when it is `inherit`. With fewer than three completed runs there are fewer entries.
+- No records (every phase executed before the timeline existed): pp-stats has no timeline section for the phase, the Wall-clock column shows `—`, plain `summary` prints `no recorded runs`, and `--banner` prints nothing and exits 0.
+- Known limit: a source whose runs are days apart (for example a re-plan after execution) forms one span and counts the idle gap.

package/pp-core/references/planner-antipatterns.md

@@ -88,6 +88,38 @@ A plan should not interleave multiple checkpoint types with implementation tasks
 
 If a decision from CONTEXT.md says "display cost calculated from billing table in impulses", the plan must deliver exactly that. Not "static label /min" as a "v1". If the phase is too complex, recommend a phase split instead of silently reducing scope.
 
+## Plan-Split Anti-Patterns
+
+A plan is split for exactly two reasons: **parallelism** (independent subsystems, disjoint `files_modified`, same wave) or **budget** (merged, the work exceeds `plan_budget_tokens` or 6 tasks). Anything else is over-splitting: every extra plan pays its own executor, review and verification run.
+
+### Bad — Serial single-concern work split to fit a task count
+
+"Add authentication" on an empty repository, `context_window: 200000` (`plan_budget_tokens` 100000), planned as three plans each alone in its wave:
+
+```yaml
+# 01-01  wave 1  schema      2 tasks  context_estimate: 35000
+# 01-02  wave 2  endpoints   2 tasks  context_estimate: 35000  depends_on: [01-01]
+# 01-03  wave 3  middleware  2 tasks  context_estimate: 35000  depends_on: [01-02]
+```
+
+**Why bad:** nothing runs in parallel and no plan is near the budget. 01-01 and 01-02 merge to 4 tasks / 70000 tokens, within both limits. `check plan-sizing` flags both pairs and reports `min_plans: 2`.
+
+### Good — Merge while the estimate fits; split only with a visible reason
+
+```yaml
+# One plan: 5 tasks, context_estimate: 90000   (fits 100000)
+# Honest estimate 105000 -> two plans, the budget reason is visible:
+#   01-01  4 tasks  context_estimate: 70000
+#   01-02  2 tasks  context_estimate: 35000  depends_on: [01-01]
+# At context_window: 1000000 the same 105000 fits one plan.
+```
+
+Two plans on independent subsystems with disjoint `files_modified` in the same wave are the parallelism reason.
+
+### Merging a flagged pair
+
+Merge one pair at a time: the first `unjustified_splits` pair in wave order. Fold the later plan's tasks, `files_modified`, `requirements`, `must_haves` and estimate into the earlier plan; delete the later PLAN.md; renumber later plans and fix every `depends_on` and `wave`; re-run `pp_run check plan-sizing <phase> --raw` and `pp_run query verify.plan-structure` on every renumbered or merged PLAN.md, check that every `depends_on` names a plan that still exists (neither command catches a dangling one), and repeat until `block` is false and no plan reports errors. Overlapping pairs share a plan (01→02→03 reports both (01, 02) and (02, 03)), so merging every reported pair at once can overshoot the budget; one at a time ends at `min_plans` plans. Plans in the same wave with disjoint files, and pairs whose merge exceeds 6 tasks or `plan_budget_tokens`, stay split. Gap-closure plans and phase splits (`## PHASE SPLIT RECOMMENDED`) are separate mechanisms.
+
 ## Comment-Text Discipline (HARD GATE)
 
 > Enforced at plan-write time by `verify.plan-structure` (the `validate_plan` step). Issue #429.

package/pp-core/references/planner-discovery-extract.md

@@ -0,0 +1,35 @@
+# Discovery extract — the planner and researcher contract (R1)
+
+**Load this file when a `{padded}-DISCOVERY-EXTRACT.md` is listed in your files to read** — the
+plan-phase orchestrator renders it with `pp_run query discovery.for-phase <N> --markdown` on a
+project that ran the Discovery Sprint (contract: `references/discovery-build-consumption.md`).
+When no such file is listed, nothing described here applies.
+
+The extract holds the rows of the Discovery registers (`_requirements.md`, `_stories.md`,
+`_processes.md`, `_entities.md`, `_rules.md`, `_screens.md`, roles, integrations) that cite this
+phase's requirement IDs. It is the client's signed-off fact base for this phase.
+
+## Planner
+
+1. **Required reading.** Read the extract in full before planning.
+2. **Never open `.planning/discovery/session-NN.md`.** The session files are the facilitation
+   record; the registers are the source of truth, amended in place. A fact you need that the
+   extract lacks is a question for the user — surface it under Claude's Discretion or the plan's
+   open questions — not a reason to read a transcript.
+3. **Cite rows, do not restate them.** A task that realises a step cites `MP-01 #3`; a validation
+   task cites `BR-02`; a data task cites the entity by name; a screen task cites `SCR-04`. Put the
+   row's acceptance criteria (`_requirements.md`, `_stories.md`) into the task's
+   `<acceptance_criteria>` verbatim — they are the verifier's UAT (R3).
+4. **Embed verbatim.** Copy the file's content byte for byte, `<!-- discovery:auto -->` markers
+   included, as the `<discovery_extract>` block of every PLAN.md of this phase, after `<context>`
+   (after `<vault_standards>` when present) and before `<tasks>`. Never edit a cell: a discovery
+   fact that must change is amended in the register by `/pp-discuss-phase` (R2), then re-rendered.
+5. **Contradictions are findings.** If the extract contradicts CONTEXT.md, the codebase or itself,
+   plan nothing on the contradiction — name both sides in the plan's open questions.
+
+## Researcher
+
+Research HOW to build what the rows say, never WHETHER: entities, rules, process steps, screens
+and acceptance criteria here are decided. List the entities, integrations and rules the extract
+names under `## User Constraints` as "Discovery facts (by row ID)" so the planner sees them beside
+the locked decisions. Rule 2 above applies in full.

package/pp-core/references/planner-guidance.md

@@ -24,7 +24,7 @@ PLAN.md IS the prompt (not a document that becomes one). Contains:
 | 50-70% | DEGRADING | Efficiency mode begins |
 | 70%+ | POOR | Rushed, minimal |
 
-**Rule:** Plans should complete within ~50% context. More plans, smaller scope, consistent quality. Each plan: 2-3 tasks max.
+**Rule:** Plans should complete within ~50% context. Each plan: up to 6 tasks while its summed estimate stays within `plan_budget_tokens` (50% of the configured `context_window`); the task count follows the estimate, never a target. Split only for parallelism or budget.
 
 ## Ship Fast
 
@@ -47,19 +47,20 @@ Plan -> Execute -> Ship -> Learn -> Repeat
 
 ## Task Sizing
 
-Each task targets **10–30% context consumption**.
+Each task targets **10–30% context consumption** at the 200k calibration — ~20-60k tokens, a band stated in tokens so it holds at every `context_window` (a larger window fits more tasks per plan, not larger tasks).
 
 | Context Cost | Action |
 |--------------|--------|
-| < 10% context | Too small — combine with a related task |
-| 10-30% context | Right size — proceed |
-| > 30% context | Too large — split into two tasks |
+| < 10% (< ~20k tokens) | Too small — combine with a related task |
+| 10-30% (~20-60k tokens) | Right size — proceed |
+| > 30% (> ~60k tokens) | Too large — split into two tasks |
 
 **Context cost signals (use these, not time estimates):**
-- Files modified: 0-3 = ~10-15%, 4-6 = ~20-30%, 7+ = ~40%+ (split)
-- New subsystem: ~25-35%
-- Migration + data transform: ~30-40%
-- Pure config/wiring: ~5-10%
+- Files modified: 0-3 = ~20-30k tokens, 4-6 = ~40-60k, 7+ = ~80k+ (split the task)
+- New subsystem: ~50-70k tokens
+- Migration + data transform: ~60-80k tokens
+- Pure config/wiring: ~10-20k tokens
+- A plan's `context_estimate` is the sum of its task estimates.
 
 **Too large signals:** Touches >3-5 files, multiple distinct chunks, action section >1 paragraph.
 
@@ -125,11 +126,13 @@ No overlap → can run parallel. File in multiple plans → later plan depends o
 
 The resolved granularity is provided in the planning context as `**Granularity:** <value>`. Read that value and apply the corresponding row below. When no explicit value is present, default to Standard.
 
-| Granularity | Typical Plans/Phase | Tasks/Plan |
-|-------------|---------------------|------------|
-| Coarse | 1-3 | 2-3 |
-| Standard | 3-5 | 2-3 |
-| Fine | 5-10 | 2-3 |
+| Granularity | Typical Plans/Phase |
+|-------------|---------------------|
+| Coarse | 1-3 |
+| Standard | 3-5 |
+| Fine | 5-10 |
+
+Plans/Phase is typical for phases with several independent subsystems. Granularity never splits serial single-concern work: such a phase is 1-2 plans at every granularity.
 
 Derive plans from actual work. Granularity determines compression tolerance, not a target.
 

package/pp-core/references/planner-revision.md

@@ -36,7 +36,7 @@ Group by plan, dimension, severity.
 | task_completeness | Add missing elements to existing task |
 | dependency_correctness | Fix depends_on, recompute waves |
 | key_links_planned | Add wiring task or update action |
-| scope_sanity | Split into multiple plans |
+| scope_sanity | Over the 6-task ceiling or `plan_budget_tokens` (`over_ceiling` / `over_budget`): split the unexecuted plan; an executed plan (`has_summary` true) is reported only. Flagged serial split (`unjustified_splits`): merge the pair (planner-antipatterns.md "Plan-Split Anti-Patterns"). Serial pair without an estimate (`unestimated_serial`): add `context_estimate` (an `unparseable_estimate` value: rewrite as a bare integer or `60k`), then merge or keep the split as the check reports |
 | must_haves_derivation | Derive and add must_haves to frontmatter |
 
 ### Step 4: Make Targeted Updates

package/pp-core/references/planning-config.md

@@ -236,7 +236,7 @@ Generated from `CONFIG_DEFAULTS` (configuration.cjs) and `VALID_CONFIG_KEYS` (co
 | `phase_naming` | string | `"sequential"` | `"sequential"`, `"custom"` | Phase numbering: auto-increment or arbitrary string IDs |
 | `project_code` | string\|null | `null` | Any short string | Prefix for phase dirs (e.g., `"CK"` produces `CK-01-foundation`) |
 | `response_language` | string\|null | `null` | Any language name | Language for user-facing prompts (e.g., `"Portuguese"`, `"Japanese"`) |
-| `context_window` | number | `200000` | `200000`, `1000000` | Context window size; set `1000000` for 1M-context models |
+| `context_window` | number | `200000` | `200000`, `1000000` | Context window size; set `1000000` for 1M-context models. Also sets the per-plan budget (`plan_budget_tokens` = 50% of the window), which the planner sizes plans to and `check plan-sizing` reads |
 | `resolve_model_ids` | boolean\|string | `false` | `false`, `true`, `"omit"` | Map model aliases to full Claude IDs; `"omit"` returns empty string |
 | `context` | string\|null | `null` | `"dev"`, `"research"`, `"review"` | Execution context profile that adjusts agent behavior: `"dev"` for development tasks, `"research"` for investigation/exploration, `"review"` for code review workflows |
 | `review.models.<cli>` | string\|null | `null` | Any model ID string | Per-CLI model override for /pp:review (e.g., `review.models.gemini`). Falls back to CLI default when null. |
@@ -268,7 +268,8 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 | `workflow.build_command` | string\|null | `null` | Any shell command | Build gate command run by the post-merge gate. Unset → build step auto-detected/skipped. |
 | `workflow.inline_plan_threshold` | number | `2` | `0`–`10` | Plans with ≤N tasks execute inline instead of spawning a subagent |
 | `workflow.code_review` | boolean | `true` | `true`, `false` | Enable built-in code review step in the ship workflow |
-| `workflow.code_review_depth` | string | `"standard"` | `"light"`, `"standard"`, `"deep"` | Depth level for code review analysis in the ship workflow |
+| `workflow.code_review_depth` | string | `"standard"` | `"quick"`, `"standard"`, `"deep"` | Depth level for code review analysis in the ship workflow |
+| `workflow.ceremony` | string | `"proportional"` | `"proportional"`, `"full"` | `proportional` classifies each phase at plan-phase time and skips gates the verdict does not need; `full` runs the whole gate stack as before. Override per phase with `--full` or a `**Ceremony:** full` ROADMAP line. See references/ceremony.md |
 | `workflow._auto_chain_active` | boolean | `false` | `true`, `false` | Internal: tracks whether autonomous chaining is active |
 | `workflow.security_enforcement` | boolean | `true` | `true`, `false` | Enable threat-model-anchored security verification via `/pp:secure-phase`. When `false`, security checks are skipped entirely |
 | `workflow.security_asvs_level` | number | `1` | `1`, `2`, `3` | OWASP ASVS verification level. Level 1 = opportunistic, Level 2 = standard, Level 3 = comprehensive |