@pareto4/pp-core 1.20.0 → 1.21.0

package/pp-core/bin/pp-tools.cjs

@@ -64,6 +64,19 @@
  *                                      Returns JSON { valid, errors[], slots: {role,capability,outcome} | null }
  *                                      --pick valid  Emit bare boolean (for workflow boolean checks)
  *
+ * Timeline (Phase 35):
+ *   timeline start <role> <phase>      Append a run record before an Agent() spawn; prints the run id
+ *     [--plan P] [--agent A] [--model M] [--source S]
+ *   timeline end <role> <phase> <outcome>  Close the most recent open run of that role (and plan)
+ *     [--plan P] [--id ID]
+ *   timeline summary <phase> [--banner]    Fold a phase's runs: wall-clock, agent time, longest
+ *
+ * Ceremony (Phase 37):
+ *   ceremony classify <phase> [--full] [--research] [--skip-research] [--skip-verify] [--write]
+ *                                      Classify a phase (trust boundary, codebase to match, single-concern), print the
+ *                                      verdict table; --write records it as {padded}-CEREMONY.md
+ *   ceremony get <phase>               Read the recorded verdict; full when none is recorded
+ *
  * Drift Guard (ADR-22):
  *   drift-guard authority                Resolve effective source-grounding authority
  *                                        (reads plan_review.source_grounding_authority + intel.enabled from config)
@@ -177,7 +190,7 @@
  *   learnings delete <id>                Delete a learning by ID
  *
  * Loop Extension Point Queries (ADR-857 phase 3c):
- *   loop render-hooks <point>            Resolve + render active Capability hooks at a loop point
+ *   loop render-hooks <point> [--phase <N>]  Resolve + render active Capability hooks at a loop point
  *                                        Returns JSON envelope { point, activeHooks, rendered }
  *                                        Valid points: discuss:pre/post, plan:pre/post,
  *                                        execute:pre/wave:pre/wave:post/post, verify:pre/post, ship:pre/post
@@ -212,6 +225,7 @@ const roadmap = require('./lib/roadmap.cjs');
 const verify = require('./lib/verify.cjs');
 const config = require('./lib/config.cjs');
 const platformBindings = require('./lib/platform-bindings.cjs');
+const timeline = require('./lib/timeline.cjs');
 const composeBindings = require('./lib/compose-bindings.cjs');
 const initContract = require('./lib/init-contract.cjs');
 const initInteractive = require('./lib/init-interactive.cjs');
@@ -529,9 +543,9 @@ async function main() {
     'current-timestamp, detect-custom-files, discovery, docs-init, drift-guard, effort, extract-messages, find-phase, ' +
     'from-gsd2, frontmatter, gap-analysis, generate-claude-md, generate-claude-profile, ' +
     'generate-client-context, generate-dev-preferences, generate-slug, graphify, history-digest, init, init-contract, intel, ' +
-    'capability, classify-confidence, git, learnings, list-todos, loop, milestone, package-legitimacy, phase, phase-plan-index, phases, platform-bindings, platform-latest-tag, profile-questionnaire, ' +
+    'capability, ceremony, classify-confidence, git, learnings, list-todos, loop, milestone, package-legitimacy, phase, phase-plan-index, phases, platform-bindings, platform-latest-tag, profile-questionnaire, ' +
     'profile-sample, progress, prompt-budget, requirements, research-plan, research-store, resolve-granularity, resolve-model, roadmap, scaffold, state, ' +
-    'task, template, user-story, validate, validate-bindings, verify, verify-path-exists, verify-summary, workstream, worktree\n\n' +
+    'task, template, timeline, user-story, validate, validate-bindings, verify, verify-path-exists, verify-summary, workstream, worktree\n\n' +
     'Global flags:\n' +
     '  --raw              Emit raw output without post-processing\n' +
     '  --pick <field>     Extract a single field from JSON output (dot/bracket notation)\n' +
@@ -788,6 +802,32 @@ function makePlatformBindingsPresentResolver(cwd) {
   };
 }
 
+/**
+ * Phase 37 D-14: the ceremony verdict `loop render-hooks --phase <N>` injects,
+ * built here at the CLI entry so the pure resolver imports no ceremony code.
+ * Returns `(phase) => gateFn`; gateFn reads the phase's recorded verdict once
+ * (any throw is a null verdict) and answers `ceremonyGateOpen(verdict, gate)`.
+ * Every failure answers true (T-37-13): a missing, unreadable or unknown-phase
+ * verdict leaves the hook rendered, so a doubt never lowers ceremony.
+ */
+function makeCeremonyGateResolver(cwd) {
+  return (phase) => {
+    let verdict = null;
+    try {
+      verdict = require('./lib/ceremony.cjs').readRecordedVerdict(cwd, phase);
+    } catch {
+      verdict = null;
+    }
+    return (gate) => {
+      try {
+        return require('./lib/ceremony.cjs').ceremonyGateOpen(verdict, gate) !== false;
+      } catch {
+        return true;
+      }
+    };
+  };
+}
+
 async function runCommand(command, args, cwd, raw, defaultValue, originalCommand, workstreamContext = null) {
   switch (command) {
     case 'agent': {
@@ -821,6 +861,18 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       break;
     }
 
+    case 'timeline': {
+      timeline.cmdTimeline(cwd, args.slice(1), raw);
+      break;
+    }
+
+    case 'ceremony': {
+      // WR-04: loaded here, not at the top, so a missing ceremony-gates.json fails
+      // only the ceremony command, never every pp-tools command.
+      require('./lib/ceremony.cjs').cmdCeremony(cwd, args.slice(1), raw);
+      break;
+    }
+
     case 'platform-latest-tag': {
       // quick 261003-my0: the init.md / new-project.md preflights read
       // `--pick latest` from here instead of composing the platform URL in
@@ -1655,7 +1707,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
     }
 
     case 'loop': {
-      // loop render-hooks <point> [--config-dir <dir>] [--active-cap <capId>] [--into <role>]
+      // loop render-hooks <point> [--config-dir <dir>] [--active-cap <capId>] [--into <role>] [--phase <N>]
       const loopSubcommand = args[1];
       if (loopSubcommand === 'render-hooks') {
         let loopConfigDir = null;
@@ -1703,10 +1755,25 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
           }
           loopInto = value;
         }
+        // --phase <N>: read the phase's recorded ceremony verdict (Phase 37 D-14).
+        // Unlike the flags above, a missing, empty or `--`-prefixed value is NOT an
+        // error: a workflow whose phase variable is unset must keep today's hooks (T-37-13).
+        let loopPhase = undefined;
+        const phaseEqArg = args.find(arg => arg.startsWith('--phase='));
+        const phaseIdx = args.indexOf('--phase');
+        if (phaseEqArg) {
+          const value = phaseEqArg.slice('--phase='.length).trim();
+          if (value) loopPhase = value;
+        } else if (phaseIdx !== -1) {
+          const value = (args[phaseIdx + 1] || '').trim();
+          if (value && !value.startsWith('--')) loopPhase = value;
+        }
         loopResolver.cmdLoopRenderHooks(cwd, args[2], raw, {
           configDir: loopConfigDir ? path.resolve(loopConfigDir) : undefined,
           activeCap: loopActiveCap,
           into: loopInto,
+          phase: loopPhase,
+          resolveCeremonyGate: makeCeremonyGateResolver(cwd),
           resolveRecordedArtifacts: makeRecordedArtifactsResolver(cwd),
           resolvePlatformBindingsPresent: makePlatformBindingsPresentResolver(cwd),
         });

package/pp-core/bin/shared/ceremony-gates.json

@@ -0,0 +1,17 @@
+{
+  "_comment": "The single gate vocabulary for per-phase ceremony (Phase 37). Read by src/ceremony.cts (table order), src/capability-activation.cts and scripts/gen-capability-registry.cjs (validation of `ceremony.<gate>` conjuncts). Keys are in verdict-table order; add a gate here and nowhere else.",
+  "schema_version": 1,
+  "gates": [
+    { "key": "research", "label": "Researcher" },
+    { "key": "pattern_mapper", "label": "Pattern mapper" },
+    { "key": "threat_model", "label": "Threat model" },
+    { "key": "plan_check", "label": "Plan checker" },
+    { "key": "code_review", "label": "Code review" },
+    { "key": "verifier", "label": "Verifier" },
+    { "key": "security_review", "label": "Security review" },
+    { "key": "nyquist", "label": "Nyquist audit" },
+    { "key": "ui_review", "label": "UI review" },
+    { "key": "ui", "label": "UI contract" },
+    { "key": "vault", "label": "Vault" }
+  ]
+}

package/pp-core/bin/shared/config-schema.manifest.json

@@ -33,6 +33,7 @@
     "workflow.plan_bounce_passes",
     "workflow.plan_chunked",
     "workflow.plan_review_convergence",
+    "workflow.ceremony",
     "code_quality.fallow.enabled",
     "code_quality.fallow.scope",
     "code_quality.fallow.profile",

package/pp-core/references/ceremony.md

@@ -0,0 +1,81 @@
+# Phase Ceremony
+
+Before any agent runs, plan-phase classifies the phase from what it touches (`/pp-plan-phase` writes the verdict in the classify step, ahead of research). Only `pp_run ceremony classify` computes a verdict; every other workflow, hook and agent reads the recorded one. The verdict is a pure function of the phase's ROADMAP section, its mapped REQUIREMENTS lines, its CONTEXT.md, the git file inventory, the completion state of other phases and the gate keys in `.planning/config.json`. No model judgment and no client identity is involved. It is recorded as `{padded}-CEREMONY.md`, and the same table is printed by the CLI.
+
+The verdict only ever lowers ceremony relative to config. A gate that config turns off stays `off (config)`. The full gate stack is one flag (`--full`), one config key (`workflow.ceremony: full`) or one ROADMAP line (`**Ceremony:** full`, or `**Ceremony**: full`, anywhere in the phase section) away, and full mode runs every gate exactly as config says today. A `**Ceremony**` line with any other value is ignored with a warning line.
+
+## The three questions
+
+1. **Trust boundary crossed?** The ROADMAP section (up to its Plans list), the mapped REQUIREMENTS lines and CONTEXT.md (without its `<deferred>` block) are matched, case-insensitively on word boundaries, against four conservative term sets: authentication and authorization, secrets and crypto, personal and payment data, untrusted input. The security verbs also match their inflections and negations (encrypted, unencrypted, authenticated, unauthorized, uploaded, deserialization). "Log in" and "sign in" match only in their authentication sense (users log in, can sign in, allow log in, log in with, a logged-in or logged in user, not signed in, the login page, a sign in page, the log in screen), so logging prose such as "write the logs in JSON" or "structured logging" does not. Any match is "crossed", and the matched terms with their source are the evidence. A bare "token" does not match, because pp-core's own phases talk about context tokens. Over-match is accepted where it only adds ceremony: "logged in" or "signed in" followed by anything but a place or format word (the, a, its, CI, JSON, …), such as "decisions logged in STATE.md", reads as authentication. Detection only pushes a phase up. The residual risk is a phase worded without any trigger term, which reads as no trust boundary; `--full`, `workflow.ceremony: full` or a `**Ceremony:** full` ROADMAP line restore the full stack.
+2. **Codebase to match?** Yes when the repository tracks at least 20 source files outside `.planning/` (vendored and generated directories excluded), or another roadmap phase or an archived milestone is complete. No git means yes (fails toward ceremony). A freshly generated scaffold stays below the threshold. The counts are the evidence.
+3. **Serial single-concern?** Yes when the phase maps at most 3 requirement IDs sharing one category prefix, lists at most 4 success criteria, and does not span a UI surface plus a non-UI surface. `**UI:** none` counts as no UI. Requirement IDs and success criteria are read from the same line or from a numbered or bulleted list under the header. Only ID-shaped tokens (`SLUG-01`) count; other words on the line are dropped, and a range (`DATA-01 – DATA-03`, `to`, `through`) expands into every ID in it, up to 50.
+
+Input the classifier cannot read fails toward ceremony and is named in a warning line. A missing ROADMAP section, no parseable requirement IDs (including `TBD` and `None`), a requirement ID with no REQUIREMENTS.md line, no parseable success criteria or a failed frontend check make the phase not single-concern, so it plans at least standard. An explicit `TBD`/`None`/`N/A` claims nothing; a ROADMAP section that is missing or unreadable, or a mapped requirement ID with no REQUIREMENTS.md line (REQUIREMENTS.md missing included), cannot rule out a trust boundary, so the answer is yes (`phase section unreadable — failing toward ceremony`, `requirement text unread for <IDs> — failing toward ceremony`) and the phase plans heavy. So a phase created by `/pp-phase add` or `insert` (`**Requirements**: TBD`) plans standard until its requirements are mapped, and heavy only when its wording names a trust term.
+
+## Tiers
+
+| Tier | When | Effect |
+|------|------|--------|
+| light | serial single-concern and no trust boundary | one blockers-only checker round, light verifier, quick code review, Nyquist audit and UI review skipped |
+| heavy | not single-concern and a trust boundary crossed | up to 3 checker rounds, full verifier, configured review depth |
+| standard | everything else | same as heavy |
+
+"Codebase to match" never changes the tier; it gates the researcher and the pattern mapper directly. The tier names are the routing tiers' light, standard and heavy vocabulary, and the verdict has no effect on model routing.
+
+## Gate rules
+
+Every gate appears in the verdict with a decision (`run`, `skip` or `off`) and a reason. The hook conjunct is the `ceremony.<gate>` term a capability `when` may carry; it is false only for a `skip` in proportional mode.
+
+| Gate key | Proportional rule | Full mode | Hook conjunct |
+|----------|-------------------|-----------|---------------|
+| `research` | runs only with a codebase to match; `--research` forces, `--skip-research` skips | runs if config enables it | `research` hook |
+| `pattern_mapper` | runs only with a codebase to match | runs if config enables it | `pattern-mapper` hook |
+| `threat_model` | runs only when a trust boundary is crossed, at any tier | runs if config enables it | `security` hook (threat-model contribution) |
+| `plan_check` | light: one blockers-only round; standard and heavy: up to 3 rounds; `--skip-verify` skips | up to 3 rounds | none (read as `plan_check_rounds`, `plan_check_mode`) |
+| `code_review` | light: `quick` depth; otherwise the configured depth, read live (a recorded depth never lowers review below current config) | configured depth | none (read as `code_review_depth`) |
+| `verifier` | light and no trust boundary: `light` depth; otherwise `full` | `full` | none (read as `verifier_depth`) |
+| `security_review` | runs only when a trust boundary is crossed | runs if config enables it | `security` hook (`secure-phase`, ship gate) |
+| `nyquist` | skipped at light; runs at standard and heavy | runs if config enables it | `nyquist` hook |
+| `ui_review` | skipped at light; runs otherwise | runs if config enables it | `ui` hook (`ui-review` step only) |
+| `ui` | follows frontend detection exactly as today | same | none |
+| `vault` | always runs when the vault is enabled | same | none |
+
+A gate that config turns off is listed `off (config)` in every mode. If `workflow.security_enforcement` is off on a trust-boundary phase, the verdict adds a warning line. Deterministic checks (requirements coverage, decision coverage, plan-sizing, test substance, schema and codebase drift) always run. The vault gates and the UI design-contract gates (`ui-phase`, the UI plan gate and the UI safety gate) never depend on the tier. Plan-time VALIDATION.md is built from RESEARCH.md's Validation Architecture section, so when the verdict skips research (no codebase to match) it skips with it, and the research row's reason says so. The checker's Nyquist dimension (Dimension 8) runs with or without RESEARCH.md at every tier, light included, through `check test-substance`; only its VALIDATION.md check (8e) needs the Validation Architecture section. The post-execution Nyquist audit follows its own `nyquist` row.
+
+## Verifier depth
+
+`full` is today's verifier. `light` skips Step 4b (the data-flow trace, Level 4) and the Step 7b behavioural spot-check sweep. Must-haves, artifacts at levels 1-3, key links, requirements coverage, the Step 7 anti-pattern scan and the Step 7c probes always run. A behaviour-dependent truth still needs Step 3's single named passing test or routes to human verification: light depth never turns presence into VERIFIED. Light depth is reachable only at light tier, which has no trust boundary, so a trust-boundary phase is always verified at full depth.
+
+## Blockers-only checker mode
+
+`plan_check_mode: blockers-only` is used for the single light-tier round. The checker runs every dimension but reports only BLOCKER issues, never warnings or info, and returns `## VERIFICATION PASSED` when there is no blocker. If it returns blockers, the orchestrator runs one targeted revision for those blockers and does not re-check. Requirements coverage, decision coverage, plan-sizing and test substance still run deterministically in the planner's own validation. Every `check test-substance` finding is a BLOCKER, so it survives the single blockers-only round. `plan_check_mode: standard` is today's loop of up to 3 iterations.
+
+## Lifecycle
+
+The verdict is rewritten on every plan-phase run until the phase has its first SUMMARY.md, then reused: `--gaps` replans and execute-phase read the recorded verdict, so the phase's own code never flips "codebase to match" between planning and gap closure. `--full` always rewrites the verdict as full. `--skip-research` and `--skip-verify` decide only the run that passes them: the printed table shows them, the recorded verdict never does, and a recorded verdict that carries either reason does not parse. A phase with no CEREMONY.md, or one that does not parse, is treated as full, which is today's behaviour; this covers phases planned before this release and phases that skipped plan-phase.
+
+`/pp-execute-phase` has no `--full`: re-plan with it. A `--full` verdict lasts only until the next plan-phase run without `--full` before the first SUMMARY. That run, a `--reviews` replan included, re-classifies the phase proportionally. Pass `--full` on every re-plan that should stay full; `/pp-autonomous --full` and `/pp-plan-review-convergence --full` forward it to every plan-phase call they make.
+
+## Reading the verdict
+
+No workflow parses CEREMONY.md or evaluates the verdict itself.
+
+- **Init keys.** `pp_run query init.plan-phase` and `pp_run query init.execute-phase` return `ceremony_tier`, `ceremony_mode`, `plan_check_rounds` (1 or 3), `plan_check_mode` (`blockers-only` or `standard`), `verifier_depth` (`light` or `full`) and `code_review_depth`; `init.plan-phase` also returns `research_enabled` already folded through the verdict. `code-review` resolves its depth in the order `--depth` flag, then the verdict, then config. In proportional mode a gate the verdict skips is skipped without prompting; plan-phase's interactive research question is not asked. `--research` and `--full` are the overrides.
+- **Hooks.** `pp_run loop render-hooks <point> --phase <N>` supplies the phase to the `when` evaluator. An empty or unknown phase, or no recorded file, leaves every `ceremony.*` conjunct true, so callers without a phase (`/pp-quick`, `/pp-debug`) are unchanged.
+- **Direct read.** `pp_run ceremony get <N> [--pick <field>]` returns the recorded verdict, else the full default. Each gate carries a `report` string: `run`, `off (config)` or `skipped (ceremony: <reason>)`.
+- **Ship and milestone audit** report a skipped gate as `skipped (ceremony: <reason>)`, never as missing and never as a ship block. Hand-invoked `/pp-secure-phase` and `/pp-validate-phase` always run, since that is an explicit request.
+- A failed read falls back to full, never to less ceremony.
+
+## CEREMONY.md
+
+`{phase_dir}/{padded}-CEREMONY.md` is committed with the phase's planning docs. The YAML frontmatter is the machine contract; the body is the table the CLI printed. A frontmatter whose rows do not follow from its own answers, tier and mode (a hand edit or a half-resolved merge that skips a gate the rules would run) does not parse, so it reads as full. `ceremony get` and a reused `classify` print the table rendered from the frontmatter, not the stored body. There is no timestamp, so identical inputs give a byte-identical file.
+
+| Field | Meaning |
+|-------|---------|
+| `schema_version` | `1` |
+| `phase` | the padded phase token |
+| `mode` | `proportional` or `full` |
+| `forced_by` | `flag`, `config` or `roadmap` when full was forced; `none` otherwise |
+| `tier` | `light`, `standard` or `heavy` |
+| `answers` | `trust_boundary`, `codebase_to_match`, `serial_single_concern`, each `{ value, evidence }` |
+| `gates` | one key per gate in the Gate rules table, each `{ decision: run\|skip\|off, depth?, rounds?, mode?, reason }` |

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