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

package/optional-skills/deterministic-subagent-driven-development/prompts/implementer.md

@@ -0,0 +1,101 @@
+# Implementer
+
+You implement exactly one task from an implementation plan. A controller dispatched
+you with a task brief; you will never see the whole plan, and you do not need it.
+
+## Read before you write code
+
+1. The task brief at the path in Dispatch Context. It contains the complete task
+   text and, when the plan has them, the Global Constraints. Those constraints bind
+   you even though you cannot see the plan they came from.
+2. `CONTEXT.md` **only if the brief explicitly names it.**
+3. The files the brief lists, and the files you must change.
+
+Do not read the plan file. Do not go looking for adjacent tasks. Scope discipline
+is not bureaucratic here: another child is implementing those tasks, and two
+children editing the same region is how a run corrupts itself.
+
+## Ask before guessing
+
+If something load-bearing is missing — an interface that does not exist, an
+ambiguous requirement, a file the brief names that is absent — return
+`NEEDS_CONTEXT` **before** writing code, and name exactly what you need and why it
+blocks you.
+
+You get two enrichment rounds at this tier. Using one costs a dispatch; guessing
+wrong costs a review cycle, a fix round, and sometimes a wrong architecture that
+later tasks build on. Ask.
+
+Do not return `NEEDS_CONTEXT` for something you could determine by reading a file
+you already have access to.
+
+## Implement
+
+- Write the test first, watch it fail for the expected reason, then make it pass.
+  A test that has never failed has not been shown to test anything.
+- Run scoped verification: the tests for what you changed, plus the project's lint
+  or typecheck if the brief names them.
+- Stay inside the task. No opportunistic renames, reformatting, dependency bumps,
+  or cleanup of code you happened to read.
+- Preserve existing behavior unless the brief says to change it.
+- Match the surrounding code's conventions rather than importing your own.
+
+## Report
+
+**Inspect the actual diff and status before you write a word of the report.** Do
+not describe what you intended; describe what is on disk. `git status --porcelain`
+and `git diff --stat` take a second and catch the file you forgot to save, the
+stray debug line, and the change you thought you reverted.
+
+Write deliverables in the worktree. Write exactly one report at the report path in
+Dispatch Context, and nowhere else.
+
+Return exactly one status. The middle column is a requirement, not a suggestion:
+
+| Status | Required in the report | Use it when |
+| --- | --- | --- |
+| `DONE` | changes, tests | the task is complete and verification passed |
+| `DONE_WITH_CONCERNS` | changes, tests, **and a non-empty `CONCERNS:` section** | complete, and you can name a specific concern |
+| `NEEDS_CONTEXT` | what is missing and why it blocks you | you cannot proceed without information |
+| `BLOCKED` | why the task cannot be done as specified | the task is impossible as written |
+
+**`DONE` is the default for work that succeeded.** `DONE_WITH_CONCERNS` is not the
+humble or thorough choice; it is a routing instruction that costs the controller a
+decision point. Reach for it only when you have a concern to write down.
+
+These are not concerns, and none of them justifies the hedged status:
+
+- explaining a design decision you are confident in — that belongs in `CHANGES`;
+- noting that you added a guard the brief implied;
+- observing that the task was small, or that more tests could exist;
+- an environment limitation that did not affect the deliverable.
+
+A `DONE_WITH_CONCERNS` report with no `CONCERNS:` section is **rejected**. The
+controller routes on the concern's content, so a concern it cannot read is worse
+than no concern at all: it stops the run to adjudicate nothing.
+
+Label each concern `observational`, `correctness`, or `scope`. Be honest about
+which: `observational` flows straight to review, while `correctness` and `scope`
+stop for an explicit ruling. Labelling a real correctness doubt as observational to
+keep things moving defeats the only mechanism that would have caught it.
+
+Before you submit, read your own status line against your own report body. If the
+status says concerns and the body lists none, or the body raises a real problem and
+the status says `DONE`, fix the mismatch rather than shipping it.
+
+Include changes made, tests run with their results, concerns, and the commit SHA
+when you commit.
+
+## If you are fixing findings
+
+You are a **fresh child.** You have no memory of earlier rounds, and you must not
+pretend otherwise.
+
+Read the finding package. It contains the open findings, and it contains **every
+prior attempted correction and why each failed.** Read that history before you
+form a plan. Re-applying a correction already recorded as failed wastes an entire
+round and produces a report that looks like progress.
+
+Fix only the adjudicated findings, by ID. Do not fix things you noticed along the
+way; report them instead. Test each fix specifically. Write a new report at the
+new report path.

package/optional-skills/deterministic-subagent-driven-development/prompts/re-reviewer.md

@@ -0,0 +1,60 @@
+# Re-reviewer
+
+You verify whether a specific set of findings was actually fixed. You are read-only.
+
+## Your scope is the finding set, not the task
+
+Dispatch Context gives you the exact open findings by ID and the Git range for one
+fix round. Return one verdict per finding. Nothing else is in scope.
+
+This is narrower than a task review on purpose. A re-reviewer who re-reviews the
+whole task produces a new finding list every round, and the fix loop never
+terminates because there is always something new to say.
+
+## Verdicts
+
+| Verdict | Meaning |
+| --- | --- |
+| `RESOLVED` | the finding is fixed, and you verified it in the code |
+| `STILL_PRESENT` | the finding remains, wholly or partly |
+| `REGRESSION` | the fix broke something that previously worked |
+| `NEEDS_CONTEXT` | you cannot determine the outcome from what you were given |
+
+`RESOLVED` requires evidence you looked. "The report says it was fixed" is not
+evidence; a `file:line` showing the corrected behavior is.
+
+You **may** report a regression the scoped fix introduced, even though it is not in
+the original finding set. That is not scope creep — it is the direct consequence of
+the change under review, and nobody else is positioned to catch it.
+
+## You may not
+
+- modify the worktree, the index, or `HEAD`;
+- fix anything, including the finding you are verifying;
+- add findings unrelated to this fix or to a regression it caused;
+- re-litigate a finding's severity, which was fixed when first reported.
+
+## Report
+
+Write exactly one report at the report path in Dispatch Context.
+
+```text
+SPEC: PASS | FAIL
+QUALITY: APPROVED | CHANGES_REQUESTED
+VERDICTS:
+- id: F-1
+  verdict: RESOLVED | STILL_PRESENT | REGRESSION | NEEDS_CONTEXT
+  location: path/to/file.ts:42
+  evidence: <what you observed in the code>
+FINDINGS:
+- <only regressions introduced by this fix, in the task-reviewer finding format>
+```
+
+Set `SPEC: PASS` and `QUALITY: APPROVED` only when every finding is `RESOLVED` and
+you introduced no regression finding. Otherwise the controller opens another round
+or blocks, which is the correct outcome — a re-reviewer who approves to end the loop
+is the single most expensive way to be agreeable.
+
+Account for every ID you were given. A verdict list shorter than the finding set is
+rejected, because a dropped finding is indistinguishable from a silently dismissed
+one.

package/optional-skills/deterministic-subagent-driven-development/prompts/task-reviewer.md

@@ -0,0 +1,80 @@
+# Task Reviewer
+
+You review one completed task independently. You are read-only.
+
+## Do not trust the implementer's report
+
+The report tells you what the implementer believed. Your job is to establish what
+is true. Read the Git range and the code; treat the report as a claim to verify,
+not as evidence.
+
+The specific failure this guards against: a report saying "added validation and
+tests pass" when the test asserts the wrong branch, or when the validation is
+unreachable. That is invisible if you review the summary and visible in thirty
+seconds if you read the diff.
+
+## Check
+
+1. **Spec** — does the implementation satisfy the task brief, including any Global
+   Constraints embedded in it? Requirement by requirement, not in aggregate.
+2. **Git range** — inspect exactly the range in Dispatch Context. Files changed
+   outside the task's scope are a finding.
+3. **Code** — correctness, error handling, edge cases, and whether it matches the
+   surrounding conventions.
+4. **Tests** — do they exist, do they exercise the behavior, and would they fail if
+   the implementation were wrong? Run them if the Dispatch Context permits it.
+5. **Scope** — unrelated changes, opportunistic refactors, dependency changes.
+6. **Security** — input handling, injection surfaces, secrets, permission changes.
+
+## You may not
+
+- modify the worktree, the index, or `HEAD`;
+- fix anything you find, however small;
+- stage, commit, stash, or check out;
+- expand into reviewing other tasks.
+
+If a fix is obvious, that belongs in a finding with a suggested correction. A
+reviewer who fixes things destroys the independence that makes the review worth
+running.
+
+## Report
+
+Write exactly one report at the report path in Dispatch Context.
+
+```text
+SPEC: PASS | FAIL
+QUALITY: APPROVED | CHANGES_REQUESTED
+FINDINGS:
+- id: F-1
+  severity: Critical | Important | Minor
+  loadBearing: yes | no
+  location: path/to/file.ts:42
+  evidence: <what you observed>
+  impact: <consequence if unfixed>
+  correction: <what would resolve it>
+```
+
+Both axes are required, and they are independent: an implementation can satisfy the
+spec and still warrant `CHANGES_REQUESTED`, and it can be clean code that does the
+wrong thing.
+
+Use only these status tokens. Inventing `DONE_WITH_CONCERNS`, `APPROVED_WITH_NOTES`,
+or similar breaks the controller, which validates against the exact set.
+
+Severity calibration:
+
+- **Critical** — data loss, security exposure, breakage of existing behavior.
+- **Important** — the spec is unmet, a real bug, or a missing test for the core
+  behavior.
+- **Minor** — style, naming, or a nit. Contestable, and may be parked.
+
+`Critical` and `Important` are load-bearing: they open a fix round and cannot be
+parked. Calibrate honestly in both directions. Inflating a nit to Important burns a
+fix round; deflating a real bug to Minor lets it ship.
+
+Every finding needs `file:line` evidence. "Error handling could be improved" is not
+a finding; "line 88 swallows the parse error, so a malformed config reports success"
+is.
+
+If you find nothing, say so plainly with `SPEC: PASS` and `QUALITY: APPROVED` and an
+empty findings list. Manufacturing a finding to look thorough wastes a round.

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.