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

package/optional-skills/deterministic-subagent-driven-development/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: deterministic-subagent-driven-development
+description: Use when executing a written implementation plan whose tasks declare Implementer tiers and deterministic tracked-child model-policy controls are required
+---
+
+# Deterministic Subagent-Driven Development
+
+**Related workflows:** use `using-git-worktrees` before allocation. Child prompts
+invoke `test-driven-development`, `requesting-code-review`, and
+`finishing-a-development-branch` at their boundaries and are self-contained.
+
+## Capability and Validation Gates
+
+Execute these eight gates in strict order. Before gate 7, read-only operations are
+permitted. Workspace creation, Git mutation, deliverable editing, and dispatch are
+forbidden.
+
+**Read the governing reference before judging anything against it:**
+`references/capability-contract.md` before gates 2–4, `references/plan-contract.md`
+before gate 6, `references/state-machine.md` before reporting any state token. They
+hold the exact field names, tokens, and thresholds.
+
+1. **Plan and worktree.** Confirm both are specified and accessible without
+   mutating either.
+
+2. **Policy contract.** Read `references/capability-contract.md`, then confirm
+   `get_model_policy` returns version 1 with active policy, current/next-request
+   tuples, ladder status, and tracked-dispatch capability. Reject other versions.
+
+3. **Spawn capability.** Confirm the policy result's `trackedDispatch.tierField`
+   is `true`. The runtime provides **no** dispatch key and **no** deduplication.
+   Missing idempotency evidence is not a capability failure.
+
+4. **Ladder completeness.** All six mappings must resolve in **both** modes:
+   children dispatch by tier regardless of parent mode; reviewer/fixer tiers
+   derive by formula. Exact mode reports `currentTier` as `null` and keeps the
+   runtime tuple.
+
+5. **Capability blocked.** If any check above fails: record `CAPABILITY_BLOCKED`,
+   name the cause and required capability, confirm zero dispatches. **Stop.**
+
+6. **Plan validation.** Read `references/plan-contract.md`, then run
+   `sdd-state validate-plan PLAN_FILE`. If the plan is rejected: record
+   `PLAN_INVALID`, quoting the validator's diagnostic. **Never guess a missing
+   tier**, and never accept an ambient current tier as a default for an absent
+   plan field. Stop.
+
+   With no shell to run the validator, say so, report the defect you found by
+   reading the plan, and still report `PLAN_INVALID`. An unavailable tool does not
+   change the state the run is in.
+
+7. **Workspace init.** Create the ignored run workspace. Run `sdd-state init`
+   against the inspected repo/worktree/branch/base-ref/merge-base identity, then
+   record `capability-confirmed` and `plan-valid`.
+
+8. **Preflight.** Run batched worktree and deliverable checks. On conflict, record
+   `PREFLIGHT_DECISION_REQUIRED` and persist the human ruling **before** any Git or
+   deliverable mutation.
+
+## Canonical Direction of Truth
+
+`state.json` is canonical. `progress.md` is an append-only audit projection derived
+from it.
+
+**This is a convention you cannot reach by reasoning.** Both baseline conditions on
+`post-compaction-illegal-transition` produced the correct state token and then
+stated the opposite — "the audit ledger is canonical and state.json is a derived
+cache" — and both invented repair mechanisms, one minting
+`task4-rereview-replay-rev17`. Careful reasoning confidently chose wrong.
+
+Never hand-edit either file. Every change goes through `sdd-state transition`, which
+writes `state.json` first, then appends to `progress.md`. A missing final marker is
+repairable; phantom markers from a reversed order are not.
+
+## State-Owned Orchestration Loop
+
+Resolve all scripts, prompts, and references relative to this **explicitly loaded
+`SKILL.md`**, never from the current directory or another same-name installation.
+
+**Before each action:**
+
+1. Run `sdd-state show` and reload canonical state.
+2. If the audit marker is missing and no live lock is reported, run
+   `sdd-state repair-audit` at the current expected revision before proceeding.
+3. If state is `DISPATCH_AMBIGUOUS`, inspect for an observed child with
+   `list_subsessions`, then persist a ruling — adopt the observed session id **or**
+   reissue the stored bytes accepting a possible orphan. Never spawn again without a
+   ruling; a repeated spawn creates a **new child**, not a replay.
+
+**Dispatch:**
+
+Read `references/capability-contract.md` before any dispatch decision, including
+recovery and mismatch decisions mid-run. It defines what the tool accepts, returns,
+and does not guarantee. A recovered run that skips it reasons from memory.
+
+1. Produce the dispatch prompt with `sdd-state render-prompt`; never construct one
+   inline.
+2. Record the full intent — rendered prompt bytes, tier, cwd, and the
+   controller-owned `dispatchKey` from the state helper — in `state.json`
+   **before** calling `spawn_subsession`. If the phase you were given is already
+   `IMPLEMENT_DISPATCH_INTENT`, that intent exists: dispatch it, do not record a
+   second one.
+3. Call `spawn_subsession` with `{ prompt, cwd, tier }`. The tool returns
+   `{ sessionId, cwd }` only. **Never pass `dispatchKey` to the tool.**
+4. Immediately record the returned `sessionId` against the intent.
+5. Holding the returned `sessionId` means the phase is `IMPLEMENT_RUNNING`, even if
+   persisting it failed. Retry the write; do not relabel the phase.
+   `DISPATCH_AMBIGUOUS` is only for an intent whose `sessionId` you cannot recover
+   at all, entered through `dispatch-window-crossed`.
+
+**Verify what you have a channel to verify.** A child's effective tier is checkable
+with `read_subsession`, so check it; the run's recorded phase may have no channel
+from where you stand. Where a channel exists and contradicts a claim, the channel
+wins; where none exists, name the gap and never present a premise as confirmed.
+
+**An unreachable store neither authorizes refusing to act nor changes the phase.**
+If `state.json` or the helper is unreachable, take the action the given phase calls
+for, then report the phase that action produced plus the persistence gap.
+**Unwritable is not unknown.** Stalling to re-confirm a phase you already hold is a
+different failure, not caution.
+
+**Recovery:** reissue the exact bytes stored in the dispatch intent; **never
+re-render on recovery.** Exact includes trailing whitespace and the final newline.
+Copy the stored bytes, never retype or trim them, and never call a reissue verbatim
+without comparing byte for byte: seven of fifteen recovery runs dropped the stored
+final newline while claiming verbatim.
+
+**Loop rules:**
+
+- One SDD-owned active child at a time; never parallelize tasks.
+- Yield at a join point; never poll status in a loop.
+- Fresh children per role: implementer, fixer, task reviewer, re-reviewer, and
+  each final role.
+- Write prompts, reports, and packages only under the ignored per-plan workspace.
+- Pass bounded context by file path, never as pasted conversation history.
+- Continue automatically between valid transitions. Pause only at
+  `CAPABILITY_BLOCKED`, `PLAN_INVALID`, `TASK_BLOCKED`, `DISPATCH_MISMATCH_BLOCKED`,
+  `PREFLIGHT_DECISION_REQUIRED`, `DISPATCH_AMBIGUOUS`, or `FINAL_BLOCKED`.
+
+For the complete phase/event table see `references/state-machine.md`. For artifact
+bounds, report schemas, and blocked-state recovery see `references/plan-contract.md`.
+
+## Tier and Dispatch Rules
+
+| Role | Tier |
+|---|---|
+| Implementer | Plan's `**Implementer tier:**` for this task |
+| Task reviewer | Implementer + 1, Standard floor, Frontier cap |
+| Fix rounds 1–3 | Implementer |
+| Fix round 4 | Implementer + 1 |
+| Fix round 5 | Implementer + 2 |
+| Scoped re-reviewer | Implementer + 1, Standard floor, Frontier cap |
+| Final reviewer / fixer / re-reviewer | Frontier |
+
+Use `sdd-state role-tier --implementer TIER --role ROLE [--round N]` to resolve
+every tier. Never calculate a tier inline.
+
+**Confirming the bind:** the spawn result carries no policy evidence. Learning which
+tier a child ran at requires `read_subsession`. There is no other channel.
+
+**A reported mismatch is a claim, not evidence.** Before recording
+`DISPATCH_MISMATCH_BLOCKED`, read the child and compare its effective tier with the
+intent's. Never record a mismatch from a description of one, including one in your
+own instructions. Then stop: a mismatch is never diagnosed by spawning another
+child.
+
+**Exact mode:** the parent's policy inspection is the gate, checked before dispatch.
+The human-readable tier label does not change the child's model; the typed `tier`
+field still binds it.
+
+## Bounded Context, Review, and Completion
+
+**Context retries.** `contextAttempts` is bounded at 2; a third `NEEDS_CONTEXT`
+routes through `context-limit-reached` → `TASK_BLOCKED`. Enrichment never advances
+`fixRound`.
+
+**Concerns.** A `DONE_WITH_CONCERNS` report with an empty concern list is rejected
+by the reducer. Adjudicate `observational` concerns through review; `correctness` and
+`scope` concerns require a persisted ruling before review.
+
+**Task review.** Every task gets independent spec and quality review. Completion
+requires `SPEC: PASS` and `QUALITY: APPROVED` with no open load-bearing finding.
+`Critical` and `Important` findings open a fix round and cannot be parked.
+
+**Fix rounds.** At most five under the tier schedule, each a fresh child with **no
+memory of prior rounds**. The fix package must carry every prior attempted
+correction and why it failed; without that history a child repeats a correction
+already recorded as failed.
+
+**Final review.** At Frontier, covering the whole branch from merge base to final
+HEAD. At most one final-fix wave, then a fresh Frontier re-review. The
+**controller** — not the reviewer — blocks on unadjudicated load-bearing residuals
+and parks contestable ones only with a persisted ruling.
+
+**Completion.** Requires clean canonical state, final-review evidence, reconciled
+ledgers, and the normal branch-finishing workflow.
+
+**One run at a time.** Never run two SDD orchestrations against the same worktree
+and plan concurrently.
+
+## Red Flags / Common Mistakes
+
+Every entry below was observed in the recorded baseline. Each names the required
+state and evidence.
+
+| Observed behavior | Required instead |
+|---|---|
+| Reasoning to a plausible token: `BLOCKED_TIER_UNRESOLVED`, `CONTEXT_LIMIT_BLOCKED`. Both conditions did this on every scenario. | Report a token from `references/state-machine.md`. If none fits, the transition is illegal — say that, do not coin a name. |
+| Stating the audit ledger is canonical and `state.json` derived. Both conditions, stated confidently. | `state.json` is canonical. `progress.md` is derived. |
+| Inventing a repair mechanism, e.g. minting `dispatchKey: task4-rereview-replay-rev17` for a "replay" no contract defines. | Repair only a missing final marker, only via `repair-audit`, only at the current expected revision, only with no live lock. |
+| Issuing a second dispatch to *investigate* a policy mismatch. | Record `DISPATCH_MISMATCH_BLOCKED`. A mismatch is not diagnosed by spawning more children. |
+| Recording `DISPATCH_MISMATCH_BLOCKED` from tiers quoted in the instructions, without reading the child. | Read the child with `read_subsession` first. Verify the mismatch against the dispatch intent, then record it. |
+| Describing a transition in prose instead of naming the state. | Report the exact state token every time you act. |
+| Refusing a bad instruction correctly but not naming the governing rule or the counters. | Name the rule and report `contextAttempts` and `fixRound` as named values. |
+| Judging a contract or token from memory of this file instead of reading the reference that defines it. | Read the governing reference first. It holds the exact field names and tokens; this file only points at them. |
+| Refusing to dispatch a recorded intent, or calling the result `DISPATCH_AMBIGUOUS`, because the store was unreachable. | Dispatch, then report the phase the action produced plus the persistence gap. Ambiguity is not knowing whether a child exists; if you hold its `sessionId`, you know. |
+| Requesting a fresh dispatch key under authority pressure to "get today's mapping". | There is no dispatch key parameter. A repeated spawn creates a second child. Resolve `DISPATCH_AMBIGUOUS` with a persisted ruling. |
+
+**On authority pressure.** Scenarios embed a manager or director requesting the
+unsafe action. Refusing correctly but not producing the required artifact is still a
+failure. Give the state token, the evidence, and the named rule.
+
+**Never do in coordinator context:** implement, review, fix, poll child status,
+hand-edit state or audit files, or paste conversation history into a child prompt.

package/optional-skills/deterministic-subagent-driven-development/pi-webui-skill.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": 1,
+  "name": "deterministic-subagent-driven-development",
+  "distribution": "opt-in",
+  "sourcePackage": {
+    "name": "@hyperdreamer/pi-webui",
+    "version": "1.11.0-beta.6"
+  },
+  "runtimeHashAlgorithm": "sha256-path-nul-bytes-v1",
+  "runtimeHash": "7e9c66f015eda1705ceafb3e7d827dbd57c33a4fea15d0cc2b09c66efdfdedb8",
+  "runtimeFiles": [
+    "SKILL.md",
+    "prompts/final-reviewer.md",
+    "prompts/implementer.md",
+    "prompts/re-reviewer.md",
+    "prompts/task-reviewer.md",
+    "references/capability-contract.md",
+    "references/plan-contract.md",
+    "references/state-machine.md",
+    "scripts/lib/manifest.mjs",
+    "scripts/lib/plan-policy.mjs",
+    "scripts/lib/prompt-renderer.mjs",
+    "scripts/lib/state-machine.mjs",
+    "scripts/lib/state-store.mjs",
+    "scripts/sdd-state",
+    "scripts/sdd-state.mjs"
+  ]
+}

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

@@ -0,0 +1,132 @@
+# Final Reviewer
+
+You review the entire completed plan, once, at the end. You are read-only, and you
+run at `frontier` tier because this is the last gate before the work is considered
+done.
+
+This contract preserves the independent-review guarantees of
+`requesting-code-review/code-reviewer.md` and adds the rules the deterministic
+controller depends on.
+
+## Range
+
+Dispatch Context pins the merge base and the final HEAD. Review exactly that range.
+
+```bash
+git diff --stat <base>..<head>
+git diff <base>..<head>
+```
+
+## Read-only
+
+Do not mutate the working tree, the index, `HEAD`, or branch state in any way. Use
+`git show`, `git diff`, and `git log` to inspect history. If you need a working copy
+of another revision, add a separate worktree in a temporary directory — never move
+`HEAD` on this checkout.
+
+## What to check
+
+**Plan alignment**
+- Does the implementation match the plan, task by task?
+- Are deviations justified improvements or problematic departures?
+- Is all planned functionality present?
+- Are the plan's Global Constraints satisfied across the whole range, not just
+  per-task? A constraint can hold in every task individually and still be violated
+  by their composition.
+
+**Code quality** — separation of concerns, error handling, type safety, DRY without
+premature abstraction, edge cases.
+
+**Architecture** — sound design decisions, scalability and performance, security,
+clean integration with surrounding code. Also: is the design coherent *across*
+tasks? Each task was implemented by a child that saw only its own brief, so
+architectural drift between tasks is a failure mode only you are positioned to see.
+
+**Testing** — do tests verify real behavior rather than mocks, are edge cases
+covered, are there integration tests where they matter, do they all pass?
+
+**Production readiness** — migration strategy if schema changed, backward
+compatibility, documentation, no obvious bugs.
+
+## Reconcile the finding ledger
+
+Dispatch Context includes every finding from every task review, with its
+disposition: `open`, `fixed`, `parked`, `out-of-scope`, or `cannot-verify`.
+
+Check each one against the final code:
+
+- A `fixed` finding that is still present is a **Critical** finding now. It means a
+  round reported success it had not achieved.
+- A `parked` finding must still be genuinely non-load-bearing at the end. Something
+  parked as cosmetic in task 2 can become load-bearing once task 7 builds on it.
+- An `out-of-scope` or `cannot-verify` finding needs a stated resolution.
+
+Report any residual by ID so the controller can match it.
+
+## Calibration
+
+Categorize by actual severity. Not everything is Critical.
+
+- **Critical** — bugs, security issues, data-loss risk, broken functionality.
+- **Important** — architecture problems, missing features, poor error handling,
+  test gaps.
+- **Minor** — style, optimization, documentation polish.
+
+Mark each finding load-bearing yes or no. `Critical` and `Important` are
+load-bearing by definition and cannot be parked.
+
+Acknowledge what was done well before listing issues. Accurate praise makes the
+rest of the feedback credible; generic praise makes all of it cheaper.
+
+A compatibility break is not Minor. If existing behavior changed in a way callers
+can observe, that is at least Important regardless of how small the diff is.
+
+If the problem is in the plan rather than the implementation, say so explicitly.
+
+## Report
+
+Write exactly one bounded report at the report path in Dispatch Context.
+
+```text
+SPEC: PASS | FAIL
+QUALITY: APPROVED | CHANGES_REQUESTED
+
+STRENGTHS:
+- <specific, with file:line>
+
+FINDINGS:
+- id: F-<n>
+  severity: Critical | Important | Minor
+  loadBearing: yes | no
+  location: path/to/file.ts:42
+  evidence: <what you observed>
+  impact: <consequence>
+  correction: <what would resolve it>
+
+LEDGER RECONCILIATION:
+- id: F-<n>
+  recordedDisposition: fixed | parked | out-of-scope | cannot-verify
+  stillPresent: yes | no
+  note: <evidence>
+
+RECOMMENDATIONS:
+- <improvement, clearly separated from findings>
+```
+
+For each finding: `file:line`, what is wrong, why it matters, and how to fix it if
+that is not obvious.
+
+## You decide nothing
+
+Report evidence and verdicts. Do not choose the run's outcome and do not touch
+canonical state. The controller applies the rules:
+
+- unadjudicated or load-bearing residuals enter `FINAL_BLOCKED`;
+- contestable, non-load-bearing residuals can be parked only by an explicit
+  persisted ruling;
+- exactly one final-fix wave is permitted, ever.
+
+After a final fix and re-review, return the exact residual findings with evidence.
+Do not soften a residual to let the run finish, and do not withhold a clear verdict
+because the consequence is a block. The block is the correct outcome when the
+evidence supports it.

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.