@hyperdreamer/pi-webui 1.11.0-beta.1 → 1.11.0-beta.10

package/optional-skills/deterministic-subagent-driven-development/references/capability-contract.md

@@ -0,0 +1,174 @@
+# Version-1 Capability and Spawn-Result Contract
+
+This file is the canonical handoff to the backend plan that implements these
+capabilities. It is frozen at version 1: every later task validates against the
+shapes defined here rather than against a live backend.
+
+This reference is **not** loaded into no-guidance or original-skill evaluation
+controls. It describes tool contracts, not controller procedure.
+
+Wire tiers are lowercase. Plan documents keep title case (`**Implementer tier:**
+Capable`). Canonical order is Economy, Fast, Standard, Advanced, Capable,
+Frontier.
+
+## `get_model_policy`
+
+A zero-parameter, read-only tool. It never mutates policy, never applies a tier,
+and never returns credentials or endpoints.
+
+It advertises no tier slash commands. An earlier draft of this file listed
+`/tier-economy`...`/tier-frontier` plus `/tier-up` and `/tier-down`. No such
+command is registered in the runtime: tier selection is the typed `tier` field on
+`spawn_subsession` and nothing else. The rendered `Model tier: <tier>` line is a
+human-readable consistency label, not a command.
+
+```ts
+type ModelTier = "economy" | "fast" | "standard" | "advanced" | "capable" | "frontier";
+
+interface ExactModelSelection {
+  model: { provider: string; id: string };
+  thinkingLevel: string;
+}
+
+interface GetModelPolicyV1 {
+  contractVersion: 1;
+  policy: {
+    mode: "exact" | "tiered";
+    rememberedTier: ModelTier | null;
+    currentTier: ModelTier | null;
+    currentRuntime: ExactModelSelection;
+    nextRequestResolved: ExactModelSelection | null;
+    blockedReason: string | null;
+  };
+  ladder: { valid: boolean; revision: string | null; blockedReason: string | null };
+  trackedDispatch: {
+    contractVersion: 1;
+    tierField: true;
+    scope: "parent-session";
+    canonicalInputs: readonly ["cwd", "prompt", "tier"];
+    returnsSessionId: true;
+  };
+}
+```
+
+### Conditional invariants
+
+Tuples use the `ExactModelSelection` shape `{ model: { provider, id },
+thinkingLevel }` and carry model identity and supported thinking only.
+
+| Condition | Requirement |
+| --- | --- |
+| Exact mode | `currentTier` is `null`; `currentRuntime` and `nextRequestResolved` are both non-null and equal |
+| Valid tiered mode | `currentTier` is non-null; ladder is complete and valid; latest resolved tuple is non-null |
+| Invalid tiered mode | `nextRequestResolved` may be `null` only when `ladder.blockedReason` is a non-empty actionable reason; this state is capability-blocking |
+| Any policy blocked reason | Capability-blocking regardless of mode |
+| Invalid ladder, either mode | Capability-blocking. Children are dispatched *by tier* whatever the parent's mode, and reviewer/fixer tiers are derived by formula, so any unresolvable rung can fail a later round |
+
+A capability-blocking state yields `CAPABILITY_BLOCKED` before any worktree
+mutation, plan mutation, or dispatch.
+
+## `spawn_subsession` success details
+
+This section describes the **implemented** runtime, verified against
+`src/server/sessions/spawnSubsessionTool.ts` and
+`src/server/sessions/piSessionService.ts`. Earlier drafts of this file specified
+server-side dispatch keying and replay deduplication. The runtime has neither.
+
+```ts
+interface SpawnSubsessionParamsV1 {
+  prompt: string;
+  cwd?: string;
+  tier?: ModelTier;
+}
+
+interface SpawnSubsessionDetailsV1 {
+  sessionId: string;
+  cwd: string;
+}
+```
+
+There is no `dispatchKey` parameter, no `reused` flag, and no returned
+`policyApplication`. Parent→child lineage is durable through the parent session's
+`pi-webui.subsession.spawned` custom entry, which `listSubsessions` rehydrates
+from the persisted session file, so lineage survives a daemon restart. What the
+runtime does not provide is *correlation of a repeated call to an earlier child*.
+
+### Tier binding
+
+`tier` is the binding channel. A supplied tier resolves through the machine's
+configured ladder to an exact model and thinking level, applied as model-then-
+thinking before the child's first request. An unresolvable tier fails the spawn
+without creating a child and without substituting a neighbouring tier. An omitted
+`tier` inherits the parent's model.
+
+Prompt text never selects a model. The runtime does not scan prompt bytes for
+model-selection commands, so a `Model tier: <tier>` line is a human-readable echo
+with zero control effect. A test fake that recovers a tier from this label is
+exercising a channel the runtime does not implement, and cannot detect a child
+that ignored the typed field.
+
+The one exception is a guard, not a mechanism: a leading label that *disagrees*
+with the typed `tier` is rejected before child creation, so a stale rendered
+prompt cannot silently imply a tier that was not requested.
+
+### No dispatch idempotency
+
+Repeating a spawn call creates a second child. The contract that consumers may
+rely on is therefore **detectable** non-idempotency, not prevented duplication:
+
+- `dispatchKey` is controller-owned. It names a row in the controller's own
+  dispatch ledger, is never sent to the tool, and exists so recovery can
+  correlate a recorded intent to the `sessionId` the tool returned.
+- A crash between the spawn call and the ledger write can orphan a child. This
+  window cannot be closed client-side. It must be *visible*: an intent without a
+  recorded `sessionId` is ambiguous and requires an explicit ruling.
+- Authority for whether work happened is commits and artifacts, never session
+  identity. A lost correlation degrades to inspecting `git log` and report files,
+  not to an unrecoverable run.
+
+### Fail-closed conditions
+
+Missing required fields, unknown tier values, a tier absent from the configured
+ladder, an unavailable model, and a leading tier label disagreeing with the typed
+tier all fail before a child is created.
+
+## Recovery-input properties
+
+**Recovery must never re-render the prompt.** Dispatch intent stores the rendered
+prompt bytes, and a ruling to reissue sends those stored bytes verbatim.
+Re-rendering couples recovery to renderer output, so any drift — including
+interior drift such as an added blank line, which trimming cannot absorb — changes
+what the child receives on a path whose whole purpose is exactness.
+
+Storing the bytes is the entire mitigation. Earlier drafts additionally
+fingerprinted `cwd` and prompt bytes for identity comparison and specified
+normalization of byte-order marks, CRLF, and outer whitespace. With no
+server-side deduplication there is nothing to compare against, so both the
+fingerprint and its normalization rules are removed rather than kept as unused
+ceremony.
+
+## Resolved divergence: the eval fake once modelled the withdrawn dedup contract
+
+`evals/fake-sdd-tools.mjs` originally implemented an earlier draft of this file: a
+`dispatchKey` parameter, a `reused` flag, conflicting-reuse rejection, and a
+returned `policyApplication`. None of that exists in the runtime, so a fake
+asserting it could only manufacture confidence in a channel the runtime never had.
+
+That divergence is **closed**. The fake was realigned to the real contract before
+the controller GREEN run: `spawn_subsession` takes `{ prompt, cwd, tier }`, returns
+`{ sessionId, cwd }`, and creates a new child on every call with no deduplication.
+The two controller scenarios that referenced the withdrawn fields
+(`missing-capability-contract`, `dispatch-intent-crash-recovery`) were regenerated
+against the real contract at the same time.
+
+The prerequisite this section once stated -- realign the fake and regenerate those
+scenarios before certifying controller behavior -- was therefore satisfied, not
+waived. It is kept here as history because the reasoning still governs: a fake that
+validates a channel the runtime does not implement must never be used to certify
+controller behavior, and the version-1 field list above remains the authority on
+what the fake is allowed to model.
+
+The consequence for evidence is that controller results predating the realignment
+are not comparable to results after it. The baseline reported in
+`evals/baseline-report.md` was recorded against the older fake; `evals/green-report.md`
+notes that limitation rather than presenting the two as a matched pair.

package/optional-skills/deterministic-subagent-driven-development/references/plan-contract.md

@@ -0,0 +1,268 @@
+# Plan and Artifact Contract
+
+What a plan must contain for the deterministic controller to run it, and what each
+artifact may hold. The grammar here is **copied from** `scripts/lib/plan-policy.mjs`
+and never widened; that module is the authority. Transitions live in
+[`state-machine.md`](state-machine.md) and are not restated here.
+
+## Contents
+
+- [Plan grammar](#plan-grammar)
+- [Tiers and role formulas](#tiers-and-role-formulas)
+  - [Choosing the implementer tier](#choosing-the-implementer-tier)
+- [Identity pinning](#identity-pinning)
+- [Preflight](#preflight)
+- [Report schemas](#report-schemas)
+- [The fix package](#the-fix-package)
+- [Artifact separation](#artifact-separation)
+- [Bounds](#bounds)
+- [Blocked-state recovery](#blocked-state-recovery)
+
+## Plan grammar
+
+A task heading is exactly:
+
+```text
+## Task <N>: <Title>
+```
+
+`<N>` starts at 1 and increases by 1 with no gaps. Any other task-like ATX heading
+outside a code fence is an error, including `### Task 1:`. This matters in practice
+because the `writing-plans` skill currently emits `### Task N:` with no tier field,
+so a plan from that skill must be converted before this controller will accept it.
+`validate-plan` names the depth found, the depth required, and the repair.
+
+Each task carries exactly one tier field, outside any code fence:
+
+```text
+**Implementer tier:** Advanced
+```
+
+Title case in the plan document, lowercase on the wire. The parser normalizes at
+that boundary so no dispatch site has to remember to.
+
+An optional `## Global Constraints` section precedes the first task and appears at
+most once. When present it is included in **every** task brief, because a child
+that never sees the plan cannot infer a constraint stated only there.
+
+Fence handling follows the parser exactly: fenced content is inert, so a fenced
+`## Task 1:` example is not a task. Indented four-space blocks are ordinary
+content.
+
+**A tier-annotated plan is a precondition, not an inference.** A plan missing a
+tier enters `PLAN_INVALID` with a diagnostic naming the repair. The controller
+never guesses a tier: guessing is precisely what the typed `tier` parameter exists
+to eliminate.
+
+## Tiers and role formulas
+
+Six tiers, ascending: `economy`, `fast`, `standard`, `advanced`, `capable`,
+`frontier`.
+
+| Role | Tier |
+| --- | --- |
+| Implementer | the plan's `**Implementer tier:**` for that task |
+| Task reviewer | implementer + 1, floored at `standard`, capped at `frontier` |
+| Re-reviewer | same formula as the task reviewer |
+| Fixer | implementer, + 1 rung at fix round 4, + 2 rungs at round 5 |
+| Final reviewer, final fixer, final re-reviewer | always `frontier` |
+
+### Choosing the implementer tier
+
+The controller never picks this value; a human does, while writing the plan and
+seeing every task at once. Only the implementer is annotated, because the five
+other roles derive from it. A plan that also names reviewer or fixer tiers invites
+disagreement with `role-tier`, which is authoritative.
+
+| Task shape | Tier |
+| --- | --- |
+| Plan text contains the complete code; the work is transcription plus running tests | `economy` |
+| Single-file mechanical change against an exact spec | `fast` |
+| One or two files, complete spec, no integration concerns | `standard` |
+| Several files with integration concerns, or behavior described in prose rather than code | `advanced` |
+| Requires design judgement or broad codebase understanding | `capable` |
+| Not chosen by hand; final review always runs here | `frontier` |
+
+Two rules override the table.
+
+**`standard` is the floor whenever the implementer must decide anything.** Wall-clock
+and context cost scale with turns taken, and the cheapest models routinely take two
+to three times the turns on multi-step work, costing more in total than the tier
+saved. `economy` is correct only when the plan hands over literal code to transcribe.
+
+**A wrong tier is a cost and latency defect, not a correctness one.** Review gates,
+not tier, are what catch bad implementations. Choose for throughput and spend, and
+do not treat the annotation as a quality lever.
+
+The escalation map is `{1:0, 2:0, 3:0, 4:1, 5:2}`. A consequence worth stating:
+at round 5 the fixer can sit one rung **above** the re-reviewer, because the
+re-reviewer formula takes no round. That is pinned in tests as a deliberate
+decision; changing it requires changing this contract.
+
+`tier` is the binding channel. The rendered prompt also opens with
+`Model tier: <lowercase>` as a human-readable echo. The echo carries no control
+effect — the runtime never parses prompt text to select a model — but PI WEBUI
+rejects a leading label that *disagrees* with the typed tier, so the echo works as
+a cross-check. An absent echo is not an error; a disagreeing one is.
+
+## Identity pinning
+
+At init the run pins: the plan's SHA-256 digest, repo root, worktree, run root,
+branch, base ref, and merge base. Then
+
+```text
+runId = sha256(planDigest ⁰ worktree ⁰ branch ⁰ mergeBase ⁰ createdAt)
+dispatchKey = <runId>:task-<n>:<role>:attempt-<n>[:round-<n>]
+```
+
+(`⁰` is a NUL byte; no component may contain one.)
+
+`dispatchKey` is **controller-owned**. It is never passed to `spawn_subsession`,
+which accepts only `{ prompt, cwd, tier }` and returns `{ sessionId, cwd }`. The
+key names a row in this run's own ledger so recovery can correlate an intent to
+the session the tool returned. It buys correlation, not idempotency.
+
+Every mutation recomputes the plan digest. Drift fails closed with exit 4: a plan
+edited mid-run invalidates every tier already dispatched, so the run stops for a
+human decision rather than continuing against a plan nobody reviewed.
+
+**Ground truth for "was this work done" is Git commits and artifacts on disk**,
+not session identity. This is inherited from the original SDD skill, and it is why
+a lost correlation degrades to reading `git log` and report files rather than to an
+unrecoverable run.
+
+## Preflight
+
+The run wants a fresh worktree at a known merge base. If the tree is dirty or the
+branch has unexpected commits, preflight reports a conflict and the run enters
+`PREFLIGHT_DECISION_REQUIRED`. Leaving it needs a persisted ruling naming a
+decision and a reason. Untracked build output is usually fine to proceed past;
+uncommitted source changes usually are not. The controller does not decide that
+silently.
+
+## Report schemas
+
+Every child writes exactly one bounded report at the report path it was given, and
+returns exactly one status.
+
+**Implementer and fixer:**
+
+```text
+STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
+
+CHANGES:
+- <file>: <what changed and why>
+
+TESTS:
+- <command>: <result, with counts>
+
+CONCERNS:            (required when DONE_WITH_CONCERNS; the reducer rejects an
+                      empty list, so a hedged status must name something)
+- kind: observational | correctness | scope
+  note: <one line>
+
+COMMIT: <sha>        (when the role commits)
+```
+
+`observational` concerns pass to review. A `correctness` or `scope` concern routes
+to `CONCERN_DECISION_REQUIRED` and needs a ruling, because those two are findings
+wearing a softer word.
+
+`NEEDS_CONTEXT` must name what is missing and why it is load-bearing. Two
+enrichments are allowed at the planned tier; a third blocks. Enrichment is not a
+fix round and never touches `fixRound`.
+
+**Task reviewer and re-reviewer:**
+
+```text
+SPEC: PASS | FAIL
+QUALITY: APPROVED | CHANGES_REQUESTED
+FINDINGS:
+- id: F-<n>
+  severity: Critical | Important | Minor
+  loadBearing: yes | no
+  location: <file>:<line>
+  evidence: <what was observed, not what was assumed>
+  impact: <consequence>
+  correction: <what would resolve it>
+```
+
+Both axes are required and independent. Task completion needs `PASS` **and**
+`APPROVED` with no open load-bearing finding.
+
+`Critical` and `Important` are load-bearing: they open a fix round and can never be
+parked. `Minor` is contestable and may be parked with a ruling that names evidence.
+Severity is fixed when first reported and cannot be re-reported lower, which closes
+the obvious route to dismissing a finding.
+
+A re-reviewer returns one verdict per open finding — `RESOLVED`, `STILL_PRESENT`,
+`REGRESSION`, or `NEEDS_CONTEXT` — scoped to that fix's Git range. It may report a
+regression the fix introduced. It may not expand into a fresh whole-task review.
+
+## The fix package
+
+Every fix round dispatches a **fresh child with no memory of prior rounds**. The
+package must therefore carry:
+
+1. the task brief, including Global Constraints;
+2. the persistent implementer report;
+3. the exact open findings, by ID, with evidence;
+4. **each prior attempted correction and why it failed**;
+5. the relevant tests;
+6. the scoped diff for the range under repair.
+
+Item 4 is the one that is easy to omit and expensive to omit. Without it, round 3
+can re-apply the fix that failed in round 2, spend a full review cycle, and arrive
+back at the same finding. The child must read that history and must not repeat a
+correction already recorded as failed.
+
+## Artifact separation
+
+| Artifact | Location | Writer |
+| --- | --- | --- |
+| Deliverables | the worktree | implementer, fixer |
+| Reports | run root | each child, one file each |
+| Task briefs | run root | `task-brief` |
+| Review packages | run root | `review-package` |
+| Rendered prompts | run root | `render-prompt` |
+| `state.json` | run root | the store, under lock |
+| `progress.md` | run root | the store, append-only |
+
+`state.json` is canonical; `progress.md` is derived. Never hand-edit either. A
+hand-edited state is indistinguishable from a corrupted one, and the reducer is
+built to refuse exactly the plausible-looking repair a stuck controller would
+otherwise invent.
+
+## Bounds
+
+Each tested at the limit and one byte past it.
+
+| Thing | Bound |
+| --- | --- |
+| Task brief | 256 KiB |
+| Rendered prompt | 384 KiB |
+| Child or reviewer report | 64 KiB |
+| `state.json` | 1 MiB |
+| One audit line | 8 KiB |
+| Finding records | 256 |
+| Any single path | 4096 UTF-8 bytes |
+| Any recorded human string | 256 characters, single line |
+
+Recorded strings reject control characters and the audit marker outright rather
+than escaping them, so no reason text can forge a transition record.
+
+## Blocked-state recovery
+
+| State | What it means | What clears it |
+| --- | --- | --- |
+| `CAPABILITY_BLOCKED` | tier resolution or the policy tool is unavailable | fix the environment; re-init |
+| `PLAN_INVALID` | grammar, tier, or digest failure | repair the plan; re-init, since the digest changed |
+| `PREFLIGHT_DECISION_REQUIRED` | the tree is not in the expected shape | a persisted preflight ruling |
+| `DISPATCH_AMBIGUOUS` | the spawn/correlate window was crossed | a ruling: adopt an observed session, or reissue stored bytes |
+| `DISPATCH_MISMATCH_BLOCKED` | a dispatch did not match its intent | human inspection; no automatic path |
+| `TASK_BLOCKED` / `FINAL_BLOCKED` | terminal | a human decision outside the run |
+
+`DISPATCH_AMBIGUOUS` deserves emphasis: the runtime offers no dispatch
+idempotency, so a crash between the spawn call and the ledger write can orphan a
+child. That window cannot be closed from the controller. The guarantee is that it
+is always **visible** and never silently resolved.

package/optional-skills/deterministic-subagent-driven-development/references/state-machine.md

@@ -0,0 +1,177 @@
+# SDD State Machine Reference
+
+The reducer in `scripts/lib/state-machine.mjs` is the authority. This document
+describes it; it never redefines it. `TRANSITIONS` and `PHASES` are exported and
+the test suite asserts this table against them, so drift fails a test rather than
+misleading a reader.
+
+## Contents
+
+- [Two rules that shape everything](#two-rules-that-shape-everything)
+- [Canonical direction of truth](#canonical-direction-of-truth)
+- [Phases](#phases)
+- [Transitions](#transitions)
+- [Counters and their bounds](#counters-and-their-bounds)
+- [The finding ledger](#the-finding-ledger)
+- [Dispatch identity and the ambiguity window](#dispatch-identity-and-the-ambiguity-window)
+- [Recovery authority](#recovery-authority)
+
+## Two rules that shape everything
+
+**Recording a result and deciding what it means are separate transitions.** A
+`*-finished` event only pins a bounded artifact and a verdict. A separate,
+explicit controller event selects the next phase. A child's report can never
+choose the phase it leads to.
+
+**Nothing is inferred from absence.** Every branch a human would call a judgement
+call requires a persisted ruling naming a decision and a reason. The reducer never
+picks the agreeable option by default.
+
+Both rules come from measured failure, not taste. In the recorded baseline, both
+conditions on `post-compaction-illegal-transition` produced the correct phase
+token and then inverted the canonical-artifact rule and invented repair
+mechanisms. One minted a fabricated dispatch key.
+
+## Canonical direction of truth
+
+`state.json` is canonical. The progress ledger is an append-only audit trail
+**derived from it**. This direction is not negotiable.
+
+Authority for whether work actually happened is Git commits and artifacts on
+disk, inherited from the original SDD skill: trust the ledger and `git log` over
+your own recollection. A lost correlation between a dispatch and a session
+degrades to inspecting commits and reports, never to an unrecoverable run.
+
+## Phases
+
+30 phases. Six are terminal and accept no continuation event.
+
+| Group | Phases |
+| --- | --- |
+| Gates | `CAPABILITY_CHECK`, `PLAN_VALIDATE`, `PREFLIGHT_DECISION_REQUIRED`, `WORKSPACE_READY` |
+| Task loop | `IMPLEMENT_DISPATCH_INTENT`, `IMPLEMENT_RUNNING`, `IMPLEMENT_RESULT`, `CONTEXT_REQUIRED`, `CONCERN_DECISION_REQUIRED` |
+| Review loop | `TASK_REVIEW_DISPATCH_INTENT`, `TASK_REVIEW_RUNNING`, `TASK_REVIEW_DECISION` |
+| Fix loop | `FIX_DISPATCH_INTENT`, `FIX_RUNNING`, `REREVIEW_DISPATCH_INTENT`, `REREVIEW_RUNNING`, `TASK_COMPLETE` |
+| Final loop | `FINAL_REVIEW_DISPATCH_INTENT`, `FINAL_REVIEW_RUNNING`, `FINAL_FIX_DISPATCH_INTENT`, `FINAL_FIX_RUNNING`, `FINAL_REREVIEW_DISPATCH_INTENT`, `FINAL_REREVIEW_RUNNING` |
+| Ambiguity | `DISPATCH_AMBIGUOUS` |
+| Terminal | `CAPABILITY_BLOCKED`, `PLAN_INVALID`, `TASK_BLOCKED`, `DISPATCH_MISMATCH_BLOCKED`, `FINAL_BLOCKED`, `COMPLETE` |
+
+## Transitions
+
+61 registered `(phase, event)` pairs. Any pair absent from this table is an
+illegal transition.
+
+| Source | Event | Destination |
+| --- | --- | --- |
+| any nonterminal | `recovery-ruling-recorded` | same phase; requires reason and receipt |
+| `CAPABILITY_CHECK` | `capability-confirmed` | `PLAN_VALIDATE` |
+| `CAPABILITY_CHECK` | `capability-missing` | `CAPABILITY_BLOCKED` |
+| `PLAN_VALIDATE` | `plan-valid` | `PLAN_VALIDATE`, validation pinned |
+| `PLAN_VALIDATE` | `plan-invalid` / `plan-conflict` | `PLAN_INVALID` |
+| `PLAN_VALIDATE` | `preflight-clean` | `WORKSPACE_READY` |
+| `PLAN_VALIDATE` | `preflight-conflict` | `PREFLIGHT_DECISION_REQUIRED` |
+| `PREFLIGHT_DECISION_REQUIRED` | `preflight-approved` | `WORKSPACE_READY` |
+| `PREFLIGHT_DECISION_REQUIRED` | `preflight-rejected` | `FINAL_BLOCKED` |
+| `WORKSPACE_READY` | `implement-dispatch-intended` | `IMPLEMENT_DISPATCH_INTENT` |
+| any `*_DISPATCH_INTENT` | `dispatch-started` | matching `*_RUNNING` |
+| any `*_DISPATCH_INTENT` | `dispatch-mismatch` | `DISPATCH_MISMATCH_BLOCKED` |
+| any `*_DISPATCH_INTENT` | `dispatch-window-crossed` | `DISPATCH_AMBIGUOUS` |
+| `DISPATCH_AMBIGUOUS` | `dispatch-ruling-recorded` | the recorded intent's running phase (adopt) or intent phase (reissue) |
+| `IMPLEMENT_RUNNING` | `implementer-finished` | `IMPLEMENT_RESULT` |
+| `IMPLEMENT_RESULT` | `implementer-status-recorded` | status-pinned `IMPLEMENT_RESULT`, `CONTEXT_REQUIRED`, `CONCERN_DECISION_REQUIRED`, or `TASK_BLOCKED` |
+| status-pinned `IMPLEMENT_RESULT` | `task-review-dispatch-intended` | `TASK_REVIEW_DISPATCH_INTENT` |
+| `CONTEXT_REQUIRED` | `context-dispatch-intended` | `IMPLEMENT_DISPATCH_INTENT` |
+| `CONTEXT_REQUIRED` | `context-limit-reached` | `TASK_BLOCKED` |
+| `CONCERN_DECISION_REQUIRED` | `concern-ruling-recorded` | status-pinned `IMPLEMENT_RESULT` or `TASK_BLOCKED` |
+| `TASK_REVIEW_RUNNING` | `task-review-finished` | `TASK_REVIEW_DECISION` |
+| `TASK_REVIEW_DECISION` | `review-approved` | `TASK_COMPLETE` |
+| `TASK_REVIEW_DECISION` | `fix-dispatch-intended` | `FIX_DISPATCH_INTENT` |
+| `TASK_REVIEW_DECISION` | `review-blocked` | `TASK_BLOCKED` |
+| `FIX_RUNNING` | `rereview-dispatch-intended` | `REREVIEW_DISPATCH_INTENT` |
+| `FIX_RUNNING` | `fixer-blocked` | `TASK_BLOCKED` |
+| `REREVIEW_RUNNING` | `rereview-finished` | result-pinned `REREVIEW_RUNNING` |
+| result-pinned `REREVIEW_RUNNING` | `rereview-approved` | `TASK_COMPLETE` |
+| result-pinned `REREVIEW_RUNNING` | `task-park-ruling-recorded` | result-pinned `REREVIEW_RUNNING` |
+| result-pinned `REREVIEW_RUNNING` | `next-fix-dispatch-intended` | `FIX_DISPATCH_INTENT` |
+| result-pinned `REREVIEW_RUNNING` | `rereview-blocked` | `TASK_BLOCKED` |
+| `TASK_COMPLETE` | `next-task-ready` | `WORKSPACE_READY` at the next task |
+| `TASK_COMPLETE` | `final-review-dispatch-intended` | `FINAL_REVIEW_DISPATCH_INTENT` |
+| `FINAL_REVIEW_RUNNING` | `final-review-finished` | result-pinned `FINAL_REVIEW_RUNNING` |
+| result-pinned `FINAL_REVIEW_RUNNING` | `final-complete` | `COMPLETE` |
+| result-pinned `FINAL_REVIEW_RUNNING` | `final-fix-dispatch-intended` | `FINAL_FIX_DISPATCH_INTENT` |
+| result-pinned `FINAL_REVIEW_RUNNING` | `final-blocked` | `FINAL_BLOCKED` |
+| `FINAL_FIX_RUNNING` | `final-rereview-dispatch-intended` | `FINAL_REREVIEW_DISPATCH_INTENT` |
+| `FINAL_FIX_RUNNING` | `final-fixer-blocked` | `FINAL_BLOCKED` |
+| `FINAL_REREVIEW_RUNNING` | `final-rereview-finished` | result-pinned `FINAL_REREVIEW_RUNNING` |
+| result-pinned `FINAL_REREVIEW_RUNNING` | `final-complete` | `COMPLETE` |
+| result-pinned `FINAL_REREVIEW_RUNNING` | `final-park-ruling-recorded` | result-pinned `FINAL_REREVIEW_RUNNING` |
+| result-pinned `FINAL_REREVIEW_RUNNING` | `final-blocked` | `FINAL_BLOCKED` |
+
+Every `*-dispatch-intended` event carries a full dispatch intent and enters its
+named intent phase **before** any spawn. Task completion requires spec `PASS` and
+quality `APPROVED` together, with no open load-bearing finding.
+
+## Counters and their bounds
+
+| Field | Bound | Notes |
+| --- | --- | --- |
+| `contextAttempts` | 0–2 | A third `NEEDS_CONTEXT` must block. Never touches `fixRound`. |
+| `fixRound` | 0–5 | The fixer tier escalates one rung at round 4 and two at round 5. A load-bearing residual at round 5 blocks. |
+| `finalFixUsed` | one wave | A second final-fix wave is not legal. |
+| `revision` | +1 per transition | Exactly one increment, including recovery rulings. |
+| `recoveryRulings` | unbounded | Counted so interventions are visible in the audit trail. |
+
+`currentImplementerTier` is derived **only** from the immutable task index
+captured at initialization, never from a live re-parse.
+
+## The finding ledger
+
+Findings are keyed by immutable ID. Severity is recorded at report time and can
+never be re-reported at a different level, so a finding cannot be downgraded on
+its way to being dismissed.
+
+`Critical` and `Important` are load-bearing: they open a fix round and can never
+be parked. `Minor` is contestable and may be parked with a persisted ruling that
+names evidence.
+
+Reporting is additive and may grow the ledger. Adjudication is a set operation
+that may change dispositions but can neither add nor remove entries, which is the
+retention guarantee: no event can silently drop an open, deferred, or parked
+finding. Every disposition requires evidence.
+
+## Dispatch identity and the ambiguity window
+
+`dispatchKey` is controller-owned, composed as
+`<runId>:task-<n>:<role>:attempt-<n>[:round-<n>]`. It is **never** passed to
+`spawn_subsession`, which accepts only `{ prompt, cwd, tier }` and returns
+`{ sessionId, cwd }`.
+
+The runtime provides no deduplication, so the key buys **correlation, not
+idempotency**. A crash between the spawn call and the correlation write can orphan
+a child. That window cannot be closed from here; it can only be made visible.
+`DISPATCH_AMBIGUOUS` does exactly that, and leaving it requires an explicit
+ruling: `adopt` names an observed session id, `reissue` sends the stored prompt
+bytes and accepts a possible orphan. The reducer never picks.
+
+An intent stores the exact rendered prompt bytes, bounded at 384 KiB, before any
+session exists. Recovery reissues those bytes verbatim and never re-renders,
+because re-rendering couples recovery to renderer output.
+
+The typed `tier` selects the model. A leading `Model tier: <tier>` line is a
+human-readable echo with no control effect: absent is fine, and disagreement with
+the typed tier is reported as renderer/formula divergence.
+
+## Recovery authority
+
+`recovery-ruling-recorded` is legal in any nonterminal phase, never changes the
+phase, and requires both a reason and a receipt. It exists so an intervention
+appears in the audit trail instead of hiding.
+
+Terminal phases accept no continuation event. Recovery from a terminal phase is a
+human decision made outside the run.
+
+**Never hand-edit `state.json` or the progress ledger.** Every change goes through
+a transition so the revision, audit line, and validation all advance together. A
+hand-edited state is indistinguishable from a corrupted one, and the reducer is
+built to refuse exactly the kind of plausible-looking repair a stuck controller
+would otherwise invent.