okstra 0.169.0 → 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. |
+| `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.0",
+  "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.0",
-  "builtAt": "2026-08-13T13:31:24.833Z",
+  "package": "0.170.0",
+  "builtAt": "2026-08-14T06:32:18.506Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/bin/okstra-error-log.py

@@ -1,296 +1,52 @@
 #!/usr/bin/env python3
-"""OKSTRA error log helper.
+"""OKSTRA error log helper — CLI adapter.
 
-Single writer for runs/<task-type>/logs/errors-<task-type>-<seq>.jsonl.
+The writer itself lives in `okstra_ctl.error_log_write`, which the deterministic
+dispatcher also calls in-process. This file is the argparse surface over it and
+re-exports the writer's names so the contract tests keep reading one module.
 """
 from __future__ import annotations
 
 import argparse
-import datetime as dt
 import json
-import os
 from pathlib import Path
 
-STDERR_EXCERPT_MAX_BYTES = 2048
-TRUNCATION_SUFFIX = "...[truncated]"
-PIPE_BUF_BYTES = 4096
-
-ALLOWED_ERROR_TYPES = {"tool-failure", "cli-failure", "contract-violation"}
-ALLOWED_AGENTS = {
-    "claude-lead", "claude-worker", "codex-worker",
-    "antigravity-worker", "report-writer",
-}
-ALLOWED_AGENT_ROLES = {"lead", "worker", "report-writer"}
-SUPPORTED_SIDECAR_SCHEMA_VERSIONS = {1}
-
-ALLOWED_CAUSES = {
-    "sandbox-denied", "service-unavailable", "auth-failed", "unknown",
-}
-# A `sandbox-denied` claim is only admissible with both probes attached.
-CAUSE_EVIDENCE_FIELDS = ("targetProbe", "controlProbe")
-# Both probes share a record's PIPE_BUF_BYTES budget with stderrExcerpt, so
-# they cannot reuse the 2048 cap that assumes stderrExcerpt owns it alone.
-CAUSE_PROBE_MAX_BYTES = 256
-# Backstop vocabulary: scanned in `message` only — never in stderrExcerpt,
-# where a kernel's real "Operation not permitted" is legitimate content.
-# Deliberately excludes bare "blocked"/"blocks": everyday English that would
-# reject honest records like "test blocked on upstream dependency".
-_BLOCKING_CLAIM_TERMS = (
-    "sandbox", "not permitted", "permission denied", "eperm",
+from okstra_ctl.error_log_write import (
+    ALLOWED_AGENT_ROLES,
+    ALLOWED_AGENTS,
+    ALLOWED_CAUSES,
+    ALLOWED_ERROR_TYPES,
+    CAUSE_EVIDENCE_FIELDS,
+    CAUSE_PROBE_MAX_BYTES,
+    PIPE_BUF_BYTES,
+    STDERR_EXCERPT_MAX_BYTES,
+    SUPPORTED_SIDECAR_SCHEMA_VERSIONS,
+    TRUNCATION_SUFFIX,
+    append_jsonl_line,
+    append_observed,
+    dump_from_worker_sidecar,
+    normalize_cause_context,
+    truncate_stderr,
 )
-# The backstop targets *unclassified* blocking claims. A worker that declared
-# a specific cause has already done the honest work — `auth-failed` legitimately
-# reads "permission denied" (MySQL 1045).
-_UNCLASSIFIED_CAUSES = (None, "unknown")
-
-
-def _now_utc():
-    return dt.datetime.now(dt.timezone.utc)
-
-
-def _iso(t):
-    return t.isoformat()
-
-
-def _truncate_utf8(s, limit):
-    """Truncate to `limit` bytes without splitting a multibyte character."""
-    if s is None:
-        return None
-    encoded = s.encode("utf-8")
-    if len(encoded) <= limit:
-        return s
-    cut = encoded[:limit]
-    while cut:
-        try:
-            return cut.decode("utf-8") + TRUNCATION_SUFFIX
-        except UnicodeDecodeError:
-            cut = cut[:-1]
-    return TRUNCATION_SUFFIX
-
-
-def truncate_stderr(s):
-    """Truncate stderr text to STDERR_EXCERPT_MAX_BYTES, multibyte-safe."""
-    return _truncate_utf8(s, STDERR_EXCERPT_MAX_BYTES)
-
-
-def normalize_cause_context(context, *, message):
-    """Validate a record's cause claim and return the normalized context.
-
-    Raises ValueError on three conditions:
-    - `cause` is set to a value outside ALLOWED_CAUSES;
-    - `cause` is 'sandbox-denied' but the two probes are missing or blank —
-      those probes are what distinguish a real denial from an unreachable
-      or auth-gated target, the misdiagnosis this gate exists to stop;
-    - `message` asserts a block in prose while the record left its cause
-      unclassified, which would smuggle the same claim past the gate.
-    """
-    cause = context.get("cause") if isinstance(context, dict) else None
-
-    if cause is not None and cause not in ALLOWED_CAUSES:
-        raise ValueError(
-            f"invalid cause: {cause!r} (allowed: {sorted(ALLOWED_CAUSES)})"
-        )
-
-    if cause == "sandbox-denied":
-        evidence = context.get("causeEvidence")
-        if not isinstance(evidence, dict):
-            raise ValueError(
-                "cause 'sandbox-denied' requires context.causeEvidence with "
-                f"{list(CAUSE_EVIDENCE_FIELDS)}"
-            )
-        normalized_evidence = {}
-        for field in CAUSE_EVIDENCE_FIELDS:
-            value = evidence.get(field)
-            if not isinstance(value, str) or not value.strip():
-                raise ValueError(
-                    f"cause 'sandbox-denied' requires a non-empty "
-                    f"context.causeEvidence.{field}: record the command and "
-                    f"its raw output that proves the claim"
-                )
-            normalized_evidence[field] = _truncate_utf8(
-                value, CAUSE_PROBE_MAX_BYTES
-            )
-        return {**context, "causeEvidence": normalized_evidence}
 
-    if message and cause in _UNCLASSIFIED_CAUSES:
-        lowered = message.lower()
-        hit = next((t for t in _BLOCKING_CLAIM_TERMS if t in lowered), None)
-        if hit:
-            raise ValueError(
-                f"message asserts a blocking claim ({hit!r}) without "
-                "context.cause='sandbox-denied' + context.causeEvidence. "
-                "Either attach the two probes, or state the cause you "
-                "actually verified."
-            )
-
-    return context
-
-
-def append_jsonl_line(path, record):
-    """Append a single JSON record as one line to ``path``.
-
-    Atomicity guarantee (POSIX only):
-        With ``O_APPEND`` and a single ``write()`` syscall, the kernel
-        appends the entire payload as one indivisible operation as long as
-        the payload size is at most ``PIPE_BUF`` (4096 bytes on Linux and
-        macOS). Larger payloads may be split across syscalls and interleave
-        with concurrent writers, so this helper rejects them with
-        ``ValueError`` rather than silently losing atomicity.
-
-    The atomicity contract holds only on POSIX filesystems with O_APPEND
-    semantics. Concurrent writers using ``O_TRUNC``, ``unlink``, or
-    non-append modes against the same path break the contract and are
-    out of scope for this helper.
-
-    Caller responsibilities:
-    - Keep records small (this module's stderr excerpt cap of
-      ``STDERR_EXCERPT_MAX_BYTES`` exists to keep records well under
-      ``PIPE_BUF_BYTES``).
-    - Handle ``TypeError`` from ``json.dumps`` for non-serializable values.
-
-    Creates parent directories as needed.
-    """
-    p = Path(path)
-    p.parent.mkdir(parents=True, exist_ok=True)
-    # ensure_ascii=False keeps UTF-8 compact (no \uXXXX escapes).
-    # json.dumps escapes literal newlines inside string values, so the
-    # only unescaped newline is the record separator we append below.
-    line = json.dumps(record, ensure_ascii=False, separators=(",", ":")) + "\n"
-    data = line.encode("utf-8")
-    if len(data) > PIPE_BUF_BYTES:
-        raise ValueError(
-            f"record too large for atomic append: {len(data)} bytes > "
-            f"PIPE_BUF ({PIPE_BUF_BYTES})"
-        )
-    # mode 0o644: owner read/write, group/world read-only.
-    fd = os.open(str(p), os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o644)
-    try:
-        os.write(fd, data)
-    finally:
-        os.close(fd)
-
-
-def append_observed(
-    *,
-    out_path,
-    task_key,
-    phase,
-    agent,
-    agent_role,
-    model,
-    error_type,
-    command,
-    command_kind,
-    exit_code,
-    duration_ms,
-    message,
-    stderr_excerpt,
-    context,
-    now=None,
-):
-    """Append a lead-observed error event to errors.jsonl."""
-    if error_type not in ALLOWED_ERROR_TYPES:
-        raise ValueError(f"invalid errorType: {error_type!r}")
-    if agent not in ALLOWED_AGENTS:
-        raise ValueError(f"invalid agent: {agent!r}")
-    if agent_role not in ALLOWED_AGENT_ROLES:
-        raise ValueError(f"invalid agentRole: {agent_role!r}")
-    # Runs before append_jsonl_line so a rejected claim leaves no trace in the
-    # log: a written-then-flagged record is still a record someone can cite.
-    context = normalize_cause_context(context, message=message)
-    ts = _iso(now or _now_utc())
-    rec = {
-        "ts": ts,
-        "recordedAt": ts,
-        "taskKey": task_key,
-        "phase": str(phase),
-        "agent": agent,
-        "agentRole": agent_role,
-        "model": model,
-        "source": "lead-observed",
-        "errorType": error_type,
-        "command": command,
-        "commandKind": command_kind,
-        "exitCode": exit_code,
-        "durationMs": duration_ms,
-        "message": message,
-        "stderrExcerpt": truncate_stderr(stderr_excerpt),
-        "context": context,
-    }
-    append_jsonl_line(out_path, rec)
-    return rec
-
-
-def dump_from_worker_sidecar(
-    *,
-    sidecar_path,
-    out_path,
-    task_key,
-    agent,
-    agent_role,
-    model,
-    now=None,
-):
-    """Read worker sidecar errors[] and append each to errors.jsonl with
-    Lead-side metadata filled in. Returns number of records appended.
-
-    Raises ValueError if:
-      - ``agent`` or ``agent_role`` is not in the allow-lists
-      - sidecar ``schemaVersion`` is not in ``SUPPORTED_SIDECAR_SCHEMA_VERSIONS``
-      - any entry's ``errorType`` is not in ``ALLOWED_ERROR_TYPES``
-      - any entry asserts a blocking cause without its required evidence
-
-    Returns 0 (no-op) if the sidecar file does not exist or its
-    ``errors`` list is empty.
-
-    Partial-failure semantics: entries are validated and appended in
-    order. If entry N fails validation, entries 0..N-1 have already
-    been written to ``out_path`` and are NOT rolled back. Callers that
-    require atomicity must validate the sidecar payload before invoking
-    this function.
-    """
-    if agent not in ALLOWED_AGENTS:
-        raise ValueError(f"invalid agent: {agent!r}")
-    if agent_role not in ALLOWED_AGENT_ROLES:
-        raise ValueError(f"invalid agentRole: {agent_role!r}")
-    p = Path(sidecar_path)
-    if not p.exists():
-        return 0
-    payload = json.loads(p.read_text())
-    schema = payload.get("schemaVersion")
-    if schema not in SUPPORTED_SIDECAR_SCHEMA_VERSIONS:
-        raise ValueError(f"unsupported sidecar schemaVersion: {schema!r}")
-    entries = payload.get("errors") or []
-    recorded_at = _iso(now or _now_utc())
-    count = 0
-    for e in entries:
-        et = e.get("errorType")
-        if et not in ALLOWED_ERROR_TYPES:
-            raise ValueError(f"invalid errorType in sidecar: {et!r}")
-        entry_context = normalize_cause_context(
-            e.get("context"), message=e.get("message")
-        )
-        rec = {
-            "ts": e.get("ts"),
-            "recordedAt": recorded_at,
-            "taskKey": task_key,
-            "phase": str(e.get("phase")) if e.get("phase") is not None else None,
-            "agent": agent,
-            "agentRole": agent_role,
-            "model": model,
-            "source": "worker-reported",
-            "errorType": et,
-            "command": e.get("command"),
-            "commandKind": e.get("commandKind"),
-            "exitCode": e.get("exitCode"),
-            "durationMs": e.get("durationMs"),
-            "message": e.get("message"),
-            "stderrExcerpt": truncate_stderr(e.get("stderrExcerpt")),
-            "context": entry_context,
-        }
-        append_jsonl_line(out_path, rec)
-        count += 1
-    return count
+__all__ = [
+    "ALLOWED_AGENT_ROLES",
+    "ALLOWED_AGENTS",
+    "ALLOWED_CAUSES",
+    "ALLOWED_ERROR_TYPES",
+    "CAUSE_EVIDENCE_FIELDS",
+    "CAUSE_PROBE_MAX_BYTES",
+    "PIPE_BUF_BYTES",
+    "STDERR_EXCERPT_MAX_BYTES",
+    "SUPPORTED_SIDECAR_SCHEMA_VERSIONS",
+    "TRUNCATION_SUFFIX",
+    "append_jsonl_line",
+    "append_observed",
+    "dump_from_worker_sidecar",
+    "main",
+    "normalize_cause_context",
+    "truncate_stderr",
+]
 
 
 def _build_parser():

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.