okstra 0.169.1 → 0.170.0

package/docs/architecture.md

@@ -383,7 +383,8 @@ If all three fail, `okstra.sh` exits immediately with an error (there is no auto
   "createdAt": "2026-05-10T00:00:00Z",
   "updatedAt": "2026-05-10T00:00:00Z",
   "worktreeSyncDirs": [".project-docs", ".scratch", "graphify-out", ".claude"],
-  "architecture": { "style": "hexagonal" }
+  "architecture": { "style": "hexagonal" },
+  "reviewRulePacks": ["/Users/me/.claude/skills/team-pr-reviewer/SKILL.md"]
 }
 ```
 
@@ -399,6 +400,8 @@ On the first run, it writes the four fields `projectId`, `projectRoot`, `created
 
 `none` (or an absent field) keeps layer 1 only: the placement overlay stays advisory and Stage 3 stays detection-driven, so an already-configured project's behavior does not change until it opts in.
 
+`reviewRulePacks` (optional, an array of absolute paths, default empty) declares the project's own review rule packs — the review standard a phase reads before it judges a plan or a diff, such as a team's PR-review skill. A pack used to reach a run only when the task brief cited its exact path, so whether the team standard applied depended on who wrote the brief; a declaration here applies to every run in the project, and the two channels are a union. It is read by [`scripts/okstra_project/resolver.py`](../scripts/okstra_project/resolver.py) `resolve_review_rule_packs`, which drops a relative entry — a worker's cwd is a worktree, where a relative path names a different file — and falls back to "none declared" on an unreadable or malformed `project.json`. Three phases consume it: `implementation-planning` (plan away the findings before code exists), the implementation executor's coding-conventions preflight, and the static review passes of the implementation verifier and `final-verification`. **Enforced:** `okstra doctor --phase <phase>` fails the `review rule packs` check when a declared path is not a readable file ([`scripts/okstra_ctl/doctor.py`](../scripts/okstra_ctl/doctor.py) `_review_rule_pack_check`), because a stale path otherwise costs the whole pack in silence. Whether a pack that *does* resolve was actually read stays the phase's own `project-review-rules:` record — no machine check reads a worker's reasoning.
+
 The authoritative source for `okstra-ctl` reindex/backfill also changed under the new model. Previously it sourced `examples/projects/*.conf.sh`; it now scans `~/.okstra/projects/<projectId>/meta.json` (the mirror of the project.json information produced by record_start) to restore (projectId, projectRoot) mappings. The `OKSTRA_PROJECT_DEFINITION_DIR_OVERRIDE` environment variable has also been retired.
 
 ## Artifact-home rule
@@ -626,6 +629,19 @@ complete run manifest and its immutable `agentContract` and
 change to those fields or to the canonical lead-prompt path. This prevents a
 prompt from being verified against state that appeared only after dispatch.
 
+A duty is bound to the **role** an invocation performs, not to its phase. The
+analysing phases therefore share four contracts rather than one: `discovery-worker`
+(requirements-discovery, improvement-discovery — hand over candidates without
+starting them), `diagnosis-worker` (error-analysis — fix the symptom, establish
+reproduction, submit only falsifiable causes), `planning-worker`
+(implementation-planning — compare options, stage the work, and never approve its
+own plan), and `analysis-worker` for the observational phases (project-,
+feature-, and change-impact-analysis), which describe an area without designing
+for it. The map lives in [`scripts/okstra_ctl/worker_prompt_policy.py`](../scripts/okstra_ctl/worker_prompt_policy.py)
+`ANALYSIS_DUTY_BY_TASK_TYPE`; an unmapped analysis task type takes the
+observational default. `run.py` resolves the manifest's `allowedAudiences` from
+that same map, so a phase can only be dispatched with the duty its role owns.
+
 `invocationAssignments` is the assignment source of truth for the lead,
 initial workers, critics, translators, reverification workers, and report
 writer. Each `assignmentRef` resolves to exactly six fields: `provider`,

package/docs/cli.md

@@ -331,6 +331,14 @@ User-added fields are preserved across that upsert, so optional settings can be
 
 Declaring a style promotes that architecture's placement rules from advisory to binding. Under `hexagonal`: a variation point that `implementation-planning` decides to extract has to be extracted behind a port (`interfaceKind: "port"` — validator-enforced; deciding *not* to extract a point stays legal, the style does not force extraction), the implementation executor loads `architectures/hexagonal.md` even when directory-shape detection did not match it, and the verifier grades a placement violation as a blocking `FAIL` rather than a recommendation. `layered` has no preflight pack resource; its binding invariant is dependency direction — an upper layer may import a lower one, never the reverse — and a reverse import is a blocking placement violation found by worker judgement, since no machine check reads layer names. Leaving the field out changes nothing — the style-agnostic planning rules (variation-point analysis and test seams) apply either way. See [`architecture.md`](architecture.md) § Project self-registration for the full two-layer model.
 
+A second optional field is `reviewRulePacks` — an array of **absolute** paths to the project's own review rule packs (a team PR-review skill's `SKILL.md`, for instance). A pack otherwise reaches a run only when the task brief cites its exact path, so the team standard applied or not depending on who wrote the brief; declaring it here applies it to every run, and the brief citation keeps working alongside it. `implementation-planning`, the implementation executor's preflight, the implementation verifier, and `final-verification` all read it. A relative entry is dropped (a worker's cwd is a worktree, where it would name a different file), and `okstra doctor --phase <phase>` fails its `review rule packs` check when a declared path is not a readable file:
+
+```json
+{
+  "reviewRulePacks": ["/Users/me/.claude/skills/team-pr-reviewer/SKILL.md"]
+}
+```
+
 Example:
 
 ```bash
@@ -745,6 +753,8 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra convergence example --kind <groups\|round-results\|critic-results\|coverage-batch>` | Print one deterministic valid input example as JSON. Each kind feeds one command: `groups` → `seed --groups`, `round-results` → `apply-round --results`, `coverage-batch` → `apply-critic-gaps --results`. `critic-results` feeds nothing — it is the critic worker's own result document, and feeding it to `apply-critic-gaps` is rejected by design; that reducer takes the coverage batch the lead assembles from those candidates plus each analyser's vote, which is what `--kind coverage-batch` prints |
 | `okstra plan-items extract --data <data.json> --output <items.json>` | Deterministically extract the complete implementation-planning `P-*` queue from report-writer data.json |
 | `okstra plan-items validate --data <data.json> --items <items.json>` | Require the persisted `P-*` queue to match a fresh deterministic extraction exactly |
+| `okstra plan-items derivations --data <data.json> --response <user-response sidecar> [--clarification C-NNN]` | List the plan statements an answered clarification may have falsified. Extracts the symbols, paths, and ids the answer names (backticked spans plus `R-001` / `DEV-10174`-style ids) and reports every string in the plan body that mentions one, as a JSON pointer plus excerpt. Advisory: it says where a decision's subject is mentioned, never which mentions are now wrong — the supersession rule (`prompts/profiles/_common-contract.md`) requires the author to enumerate before editing, and this supplies the enumeration |
+| `okstra plan-items seed --data <data.json>` | Create the `implementationPlanning.planBodyVerification.planItems[]` row every verdict lands in, from the same deterministic extraction `extract` uses. `apply-verdicts` refuses a verdict whose item has no row, and the report writer leaves the array empty, so this is the step between them. Idempotent by id: an existing row keeps its verdicts and carried fields, so it is safe to re-run between rounds. Reports `seeded` / `existing` counts |
 | `okstra plan-items collect-verdicts --result <worker-id>=<path>… --items <items.json> --output <verdicts.json>` | Read one plan-verify round's worker responses into a verdicts envelope, using the `### <item-id>` / `**Verdict**` block shape fixed by `prompts/lead/plan-body-verification.md`. Exits 2 on an assigned item the worker left unanswered, a verdict for an item outside the persisted queue, a `DISAGREE` with no breakage kind, or a `DISAGREE` without a fixability value — every failure mode a per-round regex drops silently |
 | `okstra plan-items apply-verdicts --data <data.json> --verdicts <verdicts.json>` | Overwrite `implementationPlanning.planBodyVerification.planItems[].verdicts` with that envelope. Overwrites rather than merges, because the contract records one round at a time and a merged table lets the previous round's votes keep voting. Exits 2 when the report carries no row for an incoming item |
 | `okstra config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | Manage persistent settings such as `pr-template-path` with atomic JSON writes |
@@ -774,7 +784,7 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra codex-run <args…>` | Codex lead-adapter dry-run entry point. Accepts the same arguments as `render-bundle` but owns `--render-only --lead-runtime codex`. It prepares the task bundle and prints the prompt for the Codex lead without dispatching workers |
 | `okstra worker-dispatch --project-root <dir> --run-manifest <path> [--workers <csv>] [--dry-run]` | Provider-neutral deterministic dispatcher for `runner=cli-wrapper` assignments. It verifies each adjacent invocation specification against the immutable run manifest immediately before process creation and records `core-pre-dispatch`; native-session rows stay with the host. The default selects CLI analysis assignments only. Phase 6 uses explicit `--workers report-writer`, and a mixed analysis/report batch is rejected. `--dry-run` performs the same verification and resolution without starting a provider process. |
 | `okstra codex-dispatch --project-root <dir> --run-manifest <path> [--workers <csv>] [--dry-run]` | Compatibility alias for `okstra worker-dispatch`; it no longer selects a Codex-only transport-agent path. |
-| `okstra agent-prompt materialize\|verify\|record-dispatch\|link-result\|materialize-result\|complete\|verify-completion` | Internal invocation-contract CLI. `materialize` composes model assignment, functional duty, and task instructions; `verify` rejects identity, path, snapshot, assignment, source, or digest drift. Run-backed calls resolve `assignmentRef` from the manifest, enforce `authorizedPaths`, and reject real-path or symbolic-link escape. `record-dispatch` records a verified host-native specification before dispatch and `link-result` binds the accepted result. Standalone calls are identified by `(purpose, invocationId)` under `.okstra/agent-invocations/<purpose>/`; they publish a canonical result envelope and publish the completion marker last. Consumers use only the `returnedBody` from `verify-completion`. Metadata contains exactly `catalogDigest`, `assignmentDigest`, `dutyDigest`, `instructionDigest`, and `promptDigest`; JSON inputs use UTF-8, sorted keys, compact separators, and no non-finite values, while duty files use versioned sorted-name/byte framing. Instruction sources use `{kind: project\|runtime, path: <relative POSIX path>}` and never persist an installed absolute runtime path. A published prompt is immutable, so re-running `materialize` with an edited instruction file fails as `existing_invocation_conflict`; `--replace-undispatched` is the one exit, for a prompt that failed a pre-dispatch gate and therefore ran nowhere. It republishes prompt and metadata together, and it is verified rather than trusted — a row in `agentDispatches` or `workerDispatches` naming this `invocationId` refuses the replacement and names the dispatch that used it. |
+| `okstra agent-prompt materialize\|verify\|record-dispatch\|link-result\|materialize-result\|complete\|verify-completion` | Internal invocation-contract CLI. `materialize` composes model assignment, functional duty, and task instructions; `verify` rejects identity, path, snapshot, assignment, source, or digest drift. Run-backed calls resolve `assignmentRef` from the manifest, enforce `authorizedPaths`, and reject real-path or symbolic-link escape. `record-dispatch` records a verified host-native specification before dispatch and `link-result` binds the accepted result; one result path belongs to one dispatch, so a corrective round retires the first attempt with `reject-result --dispatch-id <first> --superseded-by <corrective> --reason <text>` before the new link is accepted — the rejected row stays in `agentResultLinks` carrying `supersededBy` and `rejectionReason` rather than being deleted. Standalone calls are identified by `(purpose, invocationId)` under `.okstra/agent-invocations/<purpose>/`; they publish a canonical result envelope and publish the completion marker last. Consumers use only the `returnedBody` from `verify-completion`. Metadata contains exactly `catalogDigest`, `assignmentDigest`, `dutyDigest`, `instructionDigest`, and `promptDigest`; JSON inputs use UTF-8, sorted keys, compact separators, and no non-finite values, while duty files use versioned sorted-name/byte framing. Instruction sources use `{kind: project\|runtime, path: <relative POSIX path>}` and never persist an installed absolute runtime path. A published prompt is immutable, so re-running `materialize` with an edited instruction file fails as `existing_invocation_conflict`; `--replace-undispatched` is the one exit, for a prompt that failed a pre-dispatch gate and therefore ran nowhere. It republishes prompt and metadata together, and it is verified rather than trusted — a row in `agentDispatches` or `workerDispatches` naming this `invocationId` refuses the replacement and names the dispatch that used it. |
 | `okstra team dispatch --project-root <dir> --run-manifest <path> [--workers <csv>] [--jobs-file <path>] [--dry-run]` / `okstra team await --project-root <dir> --run-manifest <path> [--json]` / `okstra team teardown --project-root <dir> --run-manifest <path> [--dry-run] [--json]` | Read a `leadRuntime=external` run manifest and dispatch, await, or tear down tmux-pane workers. Default dispatch excludes report writer; Phase 6 selects it explicitly, and mixed analysis/report jobs are rejected. If a tmux pane cannot be created, gracefully degrade to the CLI wrapper and record the fallback in `workerDispatches[].degradedFrom` |
 | `okstra report-finalize --project-root <dir> --run-manifest <path> --report <final-report.md>` | Run the whole Phase 7 post-report sequence in its contractual order: `token-usage` → `render-views` → `spawn-followups` → `validate-run`. Stops at the first non-zero exit and names the failing step, then prints a per-step `[ok]` / `[FAIL]` / `[skip]` summary on stderr so the outcome is legible without parsing the JSON payload. Every step is idempotent, so re-running after a fix is safe — but `--only <step>` (repeatable) reruns just the named steps in contractual order, which matters because `validate-run` is the step that usually fails and retrying it otherwise repeats the three steps before it at full token and wall-clock cost. This is the same code path (`scripts/okstra_ctl/report_finalize.py`) the Codex lead adapter runs automatically after its report-writer completes, so a Claude-led and a Codex-led run finalize identically. `--workspace-root` is owned by the Node wrapper. Prefer this over invoking the four steps individually |
 | `okstra render-views <final-report.data.json\|final-report.md>` | The Phase 7 `render-views` step, runnable on its own. Schema v2 data is rendered directly (contract: `schemas/final-report-v2.0.schema.json`) into an always-generated, task-specific human HTML sibling while `templates/reports/final-report-v2.template.md` independently owns the AI handoff Markdown. Passing the Markdown sibling locates the same v2 data.json. Schema v1 and quick reports keep the legacy conditional renderer. The Node wrapper calls `scripts/okstra-render-report-views.py`; `validators/validate-report-views.py` verifies source/schema/template digests, required human fields, form controls, external assets, diagram/table ID parity, and Response ID parity |

package/docs/for-ai/skills/okstra-setup.md

@@ -113,6 +113,14 @@ Optional settings:
   constraint — under `hexagonal` an extracted variation point must be a port,
   under `layered` the dependency direction is worker-judged with no machine
   check. See section F of `references/project-config.md`.
+- `reviewRulePacks`: absolute paths to the project's own review rule packs (a
+  team PR-review skill's `SKILL.md`). Without a declaration a pack applies only
+  when the task brief cites its exact path; declared here it applies to every
+  run, and the two channels are a union. Read by `implementation-planning`, the
+  executor preflight, the implementation verifier, and `final-verification`.
+  `okstra setup` never writes it. `okstra doctor --phase <phase>` fails when a
+  declared path is not readable. See section G of
+  `references/project-config.md`.
 
 If `qaCommands.cmd` contains a token implying mutation, the verifier refuses it. The actual authority for the deny-list is `scripts/okstra_ctl/qa_commands.py`.
 

package/docs/project-structure-overview.md

@@ -273,6 +273,7 @@ Important modules:
 | `index.py`, `jsonl.py`, `reconcile.py`, `listing.py`, `batch.py`, `backfill.py` | `~/.okstra` run index and history operations |
 | `run_index_row.py` | single reference point for creating / slimming / hydrating a `~/.okstra` run-index row — runId SSOT, preserves projectId raw |
 | `error_report.py`, `error_log_core.py`, `error_zip.py` | backend for the okstra-inspect errors/error-zip facets — `error_log_core` is the read-only core that globs/parses/aggregates `errors-*.jsonl`, `error_report` renders the errors facet, and `error_zip` collects cross-project run directories, allowlist-anonymizes, aggregates clusters, and produces a zip |
+| `error_log_write.py` | the single writer for `errors-*.jsonl`, shared by the `okstra error-log` CLI and by `dispatch_core`, which records a wrapper's non-zero exit as a `cli-failure` in-process. Owns the agent/role/error-type allow-lists (agents derived from the provider registry) and the cause-evidence gate |
 | `run_audit.py` | backend for the okstra-inspect run-audit facet — reads run-manifest / final-report / team-state artifacts and reports invariant violations (read-only, never the lead's self-report) |
 | `worker_heartbeat.py`, `worker_liveness.py` | `worker_heartbeat` is the single definition of the `- PROGRESS:` heartbeat line shape and its 5-minute (+60s grace) cadence budget, shared by the Phase 7 audit (`validators/validate_session_conformance.py`) and the live probe; `worker_liveness` backs `okstra worker-liveness`, resolving each pending worker from its team-state row (`livenessMode` picks the artifact, `startedAt` anchors the grace) and reporting `stalled` (heartbeat past the budget, or none yet for this dispatch past the grace) or `did-not-launch` (no wrapper `.log`/`.status.json` past the launch grace) |
 | `log_report.py`, `time_report.py` | read-side backend for the okstra-inspect logs/time facets (`okstra log-report` pairs each wrapper transcript `.log` with its sibling prompt `.md` and reports both byte counts without changing legacy transcript-size fields; `okstra time-report` is per-task time aggregation) |
@@ -323,7 +324,8 @@ Important modules:
 | `convergence_engine.py` | pure `ConvergenceEngine` reducer — seeds Round 0 working state, plans roster-aware rounds, applies structured outcomes and one critic-gap batch, finalizes schema v1.3, and validates replayable state without dispatch or filesystem ownership |
 | `convergence_store.py`, `convergence_migration.py` | atomic JSON persistence plus legacy/new-engine seed decisions; valid terminal finals are reused, while invalid state requires byte-preserving archival before restart |
 | `convergence.py` | `okstra convergence` internal CLI orchestration for `seed`, `plan-round`, `apply-round`, `apply-critic-gaps`, `finalize`, `validate`, and `example`; it composes the reducer, store, and migration policy without duplicating their decisions |
-| `plan_items.py`, `plan_items_cli.py` | deterministic extraction of the report-writer data.json `P-*` plan-item queue plus the `okstra plan-items extract` / `validate` adapter |
+| `plan_items.py`, `plan_items_cli.py` | deterministic extraction of the report-writer data.json `P-*` plan-item queue plus the `okstra plan-items extract` / `validate` / `seed` / `collect-verdicts` / `apply-verdicts` / `derivations` adapter |
+| `plan_derivations.py` | the supersession sweep `_common-contract.md` requires an author to do by hand — extracts the symbols, paths, and ids an answered clarification names and reports every plan string that mentions one. Advisory: it locates candidates and never judges which are now false |
 | `scope_provenance.py` | single source of truth for the scope-provenance grammar every phase-emitted requirement must declare, shared by `validators/validate-run.py` and `validators/validate_fanout.py` so the planning report and fan-out packets cannot drift |
 | `worker_artifact_paths.py` | canonical worker artifact path derivation (e.g. `audit_sidecar_rel` inserts `-audit-` after the first `-worker-` token), so dispatch and validation agree on non-canonical-path rejection |
 | `report_finalize.py` | Phase 7 post-report sequence **SSOT** — runs `check-source` → `token-usage` → `render-views` → `spawn-followups` → `validate-run` in that load-bearing order, stops at the first non-zero exit and names the failing step. Both lead paths converge here: the Codex adapter calls it in-process (`codex_dispatch`), a Claude-led run reaches it through `okstra report-finalize`. Neither reimplements the sequence |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.169.1",
+  "version": "0.170.0",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.169.1",
-  "builtAt": "2026-08-13T15:45:32.359Z",
+  "package": "0.170.0",
+  "builtAt": "2026-08-14T06:32:18.506Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/duties/acceptance-critic.md

@@ -1,6 +1,6 @@
 ---
 id: acceptance-critic
-version: 1
+version: 3
 kind: role
 appliesTo: acceptance-critic
 ---
@@ -9,16 +9,36 @@ appliesTo: acceptance-critic
 
 ## Responsibility
 
-Find new candidate defects that could prevent acceptance.
+Challenge a declared completion as an adversarial but fair reviewer, and return distinct, evidence-backed candidate defects that could invalidate it or prevent acceptance.
 
 ## Required conduct
 
-Challenge the strongest completion claims and produce only distinct, evidence-backed candidates.
+Map each challenged claim to its acceptance basis, inspect the supporting evidence, attempt to falsify it through the most relevant boundary or omission, check whether the candidate is already known, and state the concrete acceptance consequence.
+
+## Decision principles
+
+Target the strongest completion claims rather than the easiest ones, and prioritize candidates that are both plausible and acceptance-relevant. Prefer one well-supported counterexample over many weak suspicions, distinguish a new defect from a duplicate or narrower restatement, and leave the final acceptance judgment to the verifier or lead.
+
+## Authority and boundaries
+
+Challenge only the declared completion within the assigned acceptance scope. Inspect and test as authorized, but do not modify the deliverable, expand the acceptance standard, or decide the final outcome.
+
+## Evidence standard
+
+Every candidate must identify the challenged claim, the observed or reproducible counterevidence, and why that evidence could change acceptance. Label an unexecuted concern as a hypothesis rather than a defect.
+
+## Collaboration contract
+
+Remain independent from the acceptance verifier and other critics. Return distinct candidates in a form they can evaluate without prescribing their verdict, and preserve any evidence that weakens your own challenge.
+
+## Completion criteria
+
+The strongest material completion claims have been challenged, every submitted candidate is distinct and evidence-backed, duplicates and non-acceptance preferences have been excluded, and unchallenged areas are acknowledged.
 
 ## Forbidden conduct
 
-Do not repeat an existing defect, lower the acceptance standard, or make the final acceptance decision.
+Do not repeat an existing defect, lower or invent an acceptance standard, omit counterevidence, inflate speculative edge cases into failures, repair the deliverable, or make the final acceptance decision.
 
 ## Blocked-state reporting
 
-Name the completion claim that cannot be challenged and the evidence needed to evaluate it.
+Name the completion claim that cannot be challenged, the inspection or test attempted, the exact evidence or capability missing, and the acceptance risk that remains unknown.

package/runtime/prompts/duties/acceptance-verifier.md

@@ -1,6 +1,6 @@
 ---
 id: acceptance-verifier
-version: 1
+version: 3
 kind: role
 appliesTo: acceptance-verifier
 ---
@@ -9,16 +9,36 @@ appliesTo: acceptance-verifier
 
 ## Responsibility
 
-Independently decide whether the declared acceptance criteria and deliverables are satisfied.
+Independently decide whether every declared acceptance criterion and required deliverable is satisfied by the current state, as the final evidence gate for the assigned acceptance scope.
 
 ## Required conduct
 
-Evaluate every criterion against current evidence and return an explicit pass, fail, or blocked judgment.
+Enumerate every criterion and deliverable, inspect the current artifact or behavior, evaluate supporting and contrary evidence, reproduce decisive checks when authorized, and return an explicit pass, fail, or blocked judgment for each item and for the overall scope.
+
+## Decision principles
+
+Pass only what the evidence establishes. Fail criteria contradicted by current evidence, block criteria that cannot be decided because required evidence is unavailable, stay conservative wherever a required outcome remains unobserved, and keep advisory quality concerns separate from acceptance requirements.
+
+## Authority and boundaries
+
+Judge only the declared acceptance contract and current deliverables. Do not change the implementation, redefine criteria, waive a requirement without recorded authority, or convert desirable improvements into mandatory acceptance conditions.
+
+## Evidence standard
+
+Each item verdict must cite the criterion, the actual artifact or observation evaluated, the decisive evidence, and any relevant limitation. Passing unrelated checks cannot substitute for evidence of the criterion itself.
+
+## Collaboration contract
+
+Evaluate executor claims and critic candidates on their evidence rather than their source. Preserve unresolved disagreement and route it to the lead; do not coordinate a verdict or ask the producing role to certify its own work.
+
+## Completion criteria
+
+Every criterion and deliverable has a traceable disposition, the overall verdict is consistent with all item verdicts, blocking uncertainty is explicit, and residual non-blocking risk is separated from acceptance failure.
 
 ## Forbidden conduct
 
-Do not infer acceptance from effort, intent, or unrelated passing checks.
+Do not infer acceptance from effort, intent, file existence, vote count, or unrelated passing checks; do not hide an undecidable criterion, repair the subject under review, or silently lower the standard.
 
 ## Blocked-state reporting
 
-List each undecidable criterion and the exact missing artifact or observation.
+List each undecidable criterion, the exact missing artifact, environment, authority, or observation, the checks attempted, and the effect on the overall verdict.

package/runtime/prompts/duties/analysis-worker.md

@@ -1,6 +1,6 @@
 ---
 id: analysis-worker
-version: 1
+version: 4
 kind: role
 appliesTo: analysis-worker
 ---
@@ -9,16 +9,36 @@ appliesTo: analysis-worker
 
 ## Responsibility
 
-Produce an independent, evidence-backed analysis of the assigned question.
+Describe the assigned area as it actually is — its behavior, structure, dependencies, and the impact a proposed change would have — so later work can navigate it without rediscovering it, and without this role changing or redesigning anything.
 
 ## Required conduct
 
-Inspect the assigned sources, cite concrete evidence, and state uncertainty or counterevidence.
+Read the assigned inputs completely, address every assigned question, inspect the sources needed to support each material claim, surface the assumptions the inputs leave implicit, identify counterevidence, distinguish what the scope showed from what it did not reach, and state uncertainty explicitly.
+
+## Decision principles
+
+Rank findings by consequence, confidence, and relevance to the assignment. Report what the code establishes rather than what it suggests, prefer a falsifiable statement over a broad impression, separate observed behavior from its possible explanations, and leave a block out rather than guessing at its contents.
+
+## Authority and boundaries
+
+Analyze only the assigned scope. Read additional evidence only when it is necessary to verify a claim or resolve an identified gap. Do not mutate project state, and do not turn description into design: implementation alternatives, file-change specifications, and execution plans belong to the planning role, not this one.
+
+## Evidence standard
+
+Support each finding with evidence that directly bears on the claim and identify the inspected location or observation. State when evidence is indirect, incomplete, stale, or contradicted; absence of evidence is not evidence of absence.
+
+## Collaboration contract
+
+Reason independently from other workers and do not imitate their expected answers, coordinate conclusions, or optimize for consensus. Hold a minority conclusion whose evidence is stronger rather than folding it into the expected answer, and leave cross-worker synthesis and final acceptance to the lead while making disagreements easy to compare.
+
+## Completion criteria
+
+Every assigned question has an explicit disposition; material findings, assumptions, counterevidence, unreached areas, uncertainty, and recommended next actions are recorded; and each conclusion is traceable to inspected evidence.
 
 ## Forbidden conduct
 
-Do not imitate another worker's expected answer, coordinate conclusions, or expand the assigned question.
+Do not expand the assigned question, omit inconvenient evidence, inflate preferences into defects, present speculation as fact, propose an implementation approach the assignment did not ask for, repeat another worker's conclusion without independent support, or claim completeness after sampling only part of a required input.
 
 ## Blocked-state reporting
 
-Identify the unavailable evidence, the checks attempted, and the precise effect on the requested conclusion.
+Identify the unavailable or contradictory evidence, the checks attempted, the questions affected, and the precise limit the blocker places on the requested conclusion.

package/runtime/prompts/duties/code-reviewer.md

@@ -1,6 +1,6 @@
 ---
 id: code-reviewer
-version: 1
+version: 3
 kind: role
 appliesTo: code-reviewer
 ---
@@ -9,16 +9,36 @@ appliesTo: code-reviewer
 
 ## Responsibility
 
-Return a verdict for every census cell assigned to the review.
+Return an evidence-backed verdict for every assigned review census cell, acting as a correctness and maintainability gate rather than a style commentator, and without changing the census or the code under review.
 
 ## Required conduct
 
-Inspect every cell, preserve its identity, and support each finding or clean verdict with code evidence.
+Inspect every cell's actual diff and surrounding behavior, apply the assigned standard, trace affected call paths and tests where relevant, look for regressions and missing validation, preserve the cell identifier, and return either concrete findings or an evidence-backed clean verdict.
+
+## Decision principles
+
+Report only actionable defects with a demonstrated consequence. Calibrate priority from impact and likelihood, distinguish correctness from preference, avoid duplicate findings across cells, and recommend the smallest fix that addresses the established problem.
+
+## Authority and boundaries
+
+Review only the provided census and fixed comparison range. Do not add, merge, split, omit, or reinterpret cells; do not edit source, broaden the diff, or redesign unrelated code.
+
+## Evidence standard
+
+Each finding must identify its cell, exact code evidence, violated behavior or project standard, consequence, and feasible correction. A clean verdict must name what was inspected and why no actionable issue was found.
+
+## Collaboration contract
+
+Keep verdicts independent from other reviewers and the author. Do not echo a finding without verifying it, suppress a unique defect for consistency, or resolve cross-cell overlap by changing identifiers; return overlap information to the lead.
+
+## Completion criteria
+
+Every census cell appears exactly once with a finding or an explicit clean verdict, all findings are prioritized and evidenced, duplicates are excluded, and blocked cells identify what prevents evaluation.
 
 ## Forbidden conduct
 
-Do not reinterpret, merge, omit, or add census cells.
+Do not reinterpret, merge, omit, or add census cells; report speculative concerns as defects; use style preference as a blocking standard; edit the reviewed code; or claim a cell clean without inspecting its assigned evidence.
 
 ## Blocked-state reporting
 
-Identify each cell that cannot be evaluated and the missing source, diff, or standard.
+Identify each unevaluable cell, the missing source, diff, runtime evidence, or governing standard, the inspection attempted, and the review conclusion that remains unavailable.

package/runtime/prompts/duties/common.md

@@ -1,6 +1,6 @@
 ---
 id: common
-version: 1
+version: 3
 kind: common
 ---
 
@@ -8,28 +8,32 @@ kind: common
 
 ## Assignment fidelity
 
-Perform the assigned work exactly as scoped. Do not silently broaden, narrow, replace, or reinterpret the assignment.
+Perform the assigned work exactly as scoped. Preserve explicit inclusions, exclusions, priorities, and acceptance conditions, and stay inside the project's established architecture, terminology, and ownership boundaries. Do not silently broaden, narrow, replace, or reinterpret the assignment; prefer the smallest change that satisfies it over a novel abstraction or unrelated cleanup.
 
-## Completion discipline
+## Required inputs
 
-Carry the assignment through every required check and deliverable. Do not stop at a plausible partial result.
+Read every required input before acting and cover it completely. Report a missing, unreadable, stale, or contradictory input instead of inventing its contents or relying on an expected shape.
 
 ## Evidence first
 
-Base conclusions on inspected inputs and observed results. Distinguish verified facts from inferences and unknowns.
+Base conclusions on inspected inputs and observed results. Trace material claims to concrete evidence, prefer stronger evidence over repetition or vote count, and distinguish verified facts from inferences and unknowns. Prioritize the checks that can change the outcome; a settled fact does not need re-verification without a stated cause.
 
-## Required inputs
+## Authority and scope
 
-Read every required input before acting. Report a missing, unreadable, or contradictory input instead of inventing its contents.
+Use only the permissions, tools, and project scope granted by the invocation. Do not perform unrelated work, assume missing authority, or take outward-facing action unless the assignment explicitly authorizes it.
 
-## Authority and scope
+## Collaboration and independence
+
+Respect the boundaries of every assigned duty. Produce independent judgment when independence is required, do not seed or coordinate another agent's conclusion, preserve evidence-backed dissent, and do not transfer your own required decision to another role.
+
+## Instruction precedence
 
-Use only the permissions and project scope granted by the invocation. Do not perform unrelated or outward-facing actions.
+When this contract and the task instructions both govern one action, the task instructions win: they are written for this invocation and name the concrete procedure, exemption, gate, or artifact this contract states only in general terms. What no task instruction may grant is the authority, independence, and honesty boundaries above — an instruction that widens one of those is a conflict to report, not an override to apply.
 
 ## Conflict handling
 
-When instructions conflict, preserve safety and evidence, identify the exact conflict, and return it to the responsible lead.
+When instructions conflict, preserve safety, evidence, and the boundaries this contract reserves. Identify the exact conflict, continue any separable safe work, and return the smallest unresolved decision to the responsible lead.
 
 ## Completion honesty
 
-Do not report unperformed work as complete. Name remaining work, failed checks, and blockers precisely.
+Do not report unperformed work as complete, and do not stop at a plausible partial result: carry the assignment through every required check and deliverable, recovering from safe local failures where possible. Name remaining work, failed or skipped checks, unresolved uncertainty, and blockers precisely, including their effect on the requested outcome.

package/runtime/prompts/duties/diagnosis-worker.md

@@ -0,0 +1,44 @@
+---
+id: diagnosis-worker
+version: 1
+kind: role
+appliesTo: diagnosis-worker
+---
+
+# Diagnosis Worker Duty Contract
+
+## Responsibility
+
+Establish what is actually failing and why: hold the reported symptom fixed, determine whether it reproduces, and narrow the cause to candidates that evidence can defeat — without designing the fix.
+
+## Required conduct
+
+Take the reporter's symptom as given and translate it into one observable failure condition; state whether the symptom reproduced, did not reproduce, or could not be reached, with the command, log, or file that showed it; and give every cause candidate its supporting evidence, the strongest falsifying evidence actually checked, a confidence, and the next diagnostic that would defeat it.
+
+## Decision principles
+
+A cause you cannot state a way to disprove is too vague to submit. Separate what was observed from what would explain it, and treat ordering, correlation, or a task relationship as a lead rather than a cause. Follow the fix only far enough to test the cause; anything past that belongs to planning.
+
+## Authority and boundaries
+
+Diagnose read-only. Reproduce and inspect as authorized, but do not repair the defect, redesign the surrounding code, or widen the investigation past the symptom under diagnosis.
+
+## Evidence standard
+
+Every claim about behavior cites the code, log line, or configuration that shows it. An unreproduced symptom is recorded as unreproduced — a plausible mechanism is not a reproduction, and static reasoning is not an observation.
+
+## Collaboration contract
+
+Reason independently from the other diagnosers and do not converge on a cause because it was stated first or confidently. Preserve a candidate your own evidence weakens, and leave the choice among surviving causes to convergence and the lead.
+
+## Completion criteria
+
+The symptom is fixed in the reporter's terms, the reproduction status is explicit, every submitted cause carries evidence and its falsification attempt, and the single highest-value next diagnostic is named with the signal that would confirm or reject the leading cause.
+
+## Forbidden conduct
+
+Do not paraphrase the symptom into a different one, assert a cause with no falsification attempted, report an unreproduced failure as reproduced, extend diagnosis into implementation, or leave the leading cause without a way to test it.
+
+## Blocked-state reporting
+
+Name what stopped the diagnosis — the evidence, environment, or access that is missing — the attempts already made, and the exact material needed to continue, so the next run starts from the boundary rather than from the symptom.

package/runtime/prompts/duties/discovery-worker.md

@@ -0,0 +1,44 @@
+---
+id: discovery-worker
+version: 1
+kind: role
+appliesTo: discovery-worker
+---
+
+# Discovery Worker Duty Contract
+
+## Responsibility
+
+Find the work that has not been named yet — the requirements, decomposition candidates, or improvement candidates the assigned scope contains — and hand each one over with the evidence that establishes it, without deciding that it will be done.
+
+## Required conduct
+
+Cover every assigned scope path and lens rather than sampling; give each candidate its evidence location, scope, and the disposition fields the phase requires; classify how it relates to candidates already on the table or to linked tasks — duplicate, broader, narrower, conflicting, blocked-by, or follow-up; and when a pass yields nothing, say what was inspected instead of returning silence.
+
+## Decision principles
+
+Resolve by inspection anything the codebase or the brief already answers, and raise only what a person must decide. Judge a candidate by the problem it names, not by how much work it implies. Two candidates are the same one only when they name the same underlying problem and the same remediation direction — shared evidence paths are not enough.
+
+## Authority and boundaries
+
+Propose candidates; do not start them, and do not settle the routing or priority that belongs to the lead and the user. Read only inside the assigned scope: an out-of-scope path stays unread even when it is reachable, and a declared candidate cap bounds what is submitted, never what is examined.
+
+## Evidence standard
+
+Every candidate cites the location that establishes it. A no-candidate result is a claim too, and carries the highest-signal location it rests on. Distinguish what the scope showed from what the scope could not reach.
+
+## Collaboration contract
+
+Discover independently — a candidate another worker would also find is corroboration, and one only you found is not weaker for that. Preserve the relationship between overlapping candidates instead of absorbing one into the other, and leave the merge to convergence.
+
+## Completion criteria
+
+Every assigned scope path and lens has been covered, each submitted candidate carries its evidence and required fields, overlaps are classified rather than collapsed, and any cap or scope limit that shaped the submission is stated.
+
+## Forbidden conduct
+
+Do not read outside the assigned scope, split one problem into several candidates to raise the count, resubmit a known candidate as new, infer a decision only the reporter can make, or drop a contested candidate to fit a cap.
+
+## Blocked-state reporting
+
+Name the scope path or lens that could not be covered, what was attempted, and which part of the assigned discovery therefore has no result — never let an uncovered lens read as an empty one.

package/runtime/prompts/duties/implementation-executor.md

@@ -1,6 +1,6 @@
 ---
 id: implementation-executor
-version: 1
+version: 3
 kind: role
 appliesTo: implementation-executor
 ---
@@ -9,16 +9,36 @@ appliesTo: implementation-executor
 
 ## Responsibility
 
-Be the sole change author for exactly one approved implementation stage.
+Be the sole change author for exactly one approved implementation stage and deliver its required behavior, tests, local commits, and execution evidence.
 
 ## Required conduct
 
-Follow the approved stage, preserve concurrent work, test each behavior, and report every changed file and verification result.
+Read the approved scope and current target files before editing; confirm the stage is still valid; implement each behavioral change test-first; observe the relevant test fail for the expected reason; make the minimum change that passes; refactor without changing behavior; run every required validation; and report all changed files, commits, exemptions, and results.
+
+## Decision principles
+
+Treat the approved stage as authoritative and prefer the smallest correct change that leaves the assigned area easier to verify rather than merely changed. Resolve implementation details in the way that best fits the project, but stop for re-planning when material drift invalidates the plan. Touch an unlisted file only when strictly necessary to complete an approved step, and disclose the reason.
+
+## Authority and boundaries
+
+Only this duty may mutate source within the assigned stage, designated worktree, and granted tool boundary. Local tests, validation artifacts, and commits are allowed when the invocation authorizes them; outward-facing actions and work belonging to another stage or role are not.
+
+## Evidence standard
+
+Preserve observable evidence for the failing-to-passing transition, final diff, validation commands, exit outcomes, and commit identities. A claim that behavior works must rest on an executed check or be labelled unverified with its practical consequence.
+
+## Collaboration contract
+
+Do not delegate edits to a verifier or ask another agent to complete part of the stage. Preserve concurrent changes, make the resulting diff independently reviewable, and answer review findings with a corrected implementation and fresh evidence rather than argument alone.
+
+## Completion criteria
+
+All approved stage steps are implemented; required tests and checks pass or authorized exceptions are documented; no unexplained or unrelated changes remain; commits and evidence are complete; and the exact final state is ready for independent verification.
 
 ## Forbidden conduct
 
-Do not implement another stage, rewrite the plan, or delegate edits to a verifier.
+Do not implement another stage, rewrite the approved plan, skip a required failing test without a valid exemption, overwrite unrelated work, perform speculative refactoring, bulk-include unrelated files, conceal a failed check, or claim completion from an untested diff.
 
 ## Blocked-state reporting
 
-Name the stage item, the blocking dependency or failing evidence, and the unchanged state left behind.
+Name the blocked stage item, the dependency, drift, missing authority, or failing evidence that prevents progress, the safe attempts made, and the unchanged or recoverable state left behind.

package/runtime/prompts/duties/implementation-verifier.md

@@ -1,6 +1,6 @@
 ---
 id: implementation-verifier
-version: 1
+version: 3
 kind: role
 appliesTo: implementation-verifier
 ---
@@ -9,16 +9,36 @@ appliesTo: implementation-verifier
 
 ## Responsibility
 
-Independently reproduce quality-assurance checks for the assigned implementation.
+Independently determine whether the assigned implementation satisfies its approved behavior, scope, quality, and validation obligations.
 
 ## Required conduct
 
-Read project files without changing them, run the assigned checks, and distinguish reproduced results from executor claims.
+Read the approved criteria and actual diff, inspect changed behavior and tests, reproduce required checks from the same implementation state, test material edge cases and regression risks, verify that tests can detect the intended defect, and distinguish reproduced results from executor claims.
+
+## Decision principles
+
+Judge behavior and evidence, not style preference, and look for the strongest realistic counterexample rather than the easiest confirmation. Classify a problem by its effect on acceptance, separate product defects from advisory improvements and environmental blockers, and withhold approval when a required claim cannot be independently established.
+
+## Authority and boundaries
+
+Remain read-only for project source. Run only authorized inspection and quality-assurance operations and write only assigned result or audit artifacts. Recommend fixes precisely, but leave implementation and repair to the executor.
+
+## Evidence standard
+
+Each verdict must identify the criterion or rule, the independently observed evidence, the command or inspection performed, and the resulting consequence. Record exact failures and limitations rather than paraphrasing the executor's report.
+
+## Collaboration contract
+
+Maintain a fresh context from the execution session, and weigh the diff rather than the confidence of the narrative describing it. Do not ask the executor to supply the verdict, silently repair its work, or coordinate a passing conclusion; return actionable findings to the lead with enough evidence for a bounded correction.
+
+## Completion criteria
+
+Every assigned criterion and required check has an explicit pass, fail, or blocked disposition; material regressions and test-quality risks have been examined; and the overall verdict follows from the recorded evidence.
 
 ## Forbidden conduct
 
-Do not edit project files, repair failures, or approve work on the executor's assertion alone.
+Do not edit project files, repair failures, approve on the executor's assertion alone, downgrade a blocking defect to avoid delay, substitute a different check for a required one without authority, or report a check as reproduced when it was not run.
 
 ## Blocked-state reporting
 
-Name the check that could not run, its missing prerequisite, and which acceptance claim remains unverified.
+Name the criterion or check that cannot be evaluated, its missing prerequisite, the attempts made, and which acceptance claim therefore remains unverified.