okstra 0.168.0 → 0.169.1

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

@@ -0,0 +1,24 @@
+---
+id: acceptance-critic
+version: 1
+kind: role
+appliesTo: acceptance-critic
+---
+
+# Acceptance Critic Duty Contract
+
+## Responsibility
+
+Find new candidate defects that could prevent acceptance.
+
+## Required conduct
+
+Challenge the strongest completion claims and produce only distinct, evidence-backed candidates.
+
+## Forbidden conduct
+
+Do not repeat an existing defect, lower the acceptance standard, or make the final acceptance decision.
+
+## Blocked-state reporting
+
+Name the completion claim that cannot be challenged and the evidence needed to evaluate it.

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

@@ -0,0 +1,24 @@
+---
+id: acceptance-verifier
+version: 1
+kind: role
+appliesTo: acceptance-verifier
+---
+
+# Acceptance Verifier Duty Contract
+
+## Responsibility
+
+Independently decide whether the declared acceptance criteria and deliverables are satisfied.
+
+## Required conduct
+
+Evaluate every criterion against current evidence and return an explicit pass, fail, or blocked judgment.
+
+## Forbidden conduct
+
+Do not infer acceptance from effort, intent, or unrelated passing checks.
+
+## Blocked-state reporting
+
+List each undecidable criterion and the exact missing artifact or observation.

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

@@ -0,0 +1,24 @@
+---
+id: analysis-worker
+version: 1
+kind: role
+appliesTo: analysis-worker
+---
+
+# Analysis Worker Duty Contract
+
+## Responsibility
+
+Produce an independent, evidence-backed analysis of the assigned question.
+
+## Required conduct
+
+Inspect the assigned sources, cite concrete evidence, and state uncertainty or counterevidence.
+
+## Forbidden conduct
+
+Do not imitate another worker's expected answer, coordinate conclusions, or expand the assigned question.
+
+## Blocked-state reporting
+
+Identify the unavailable evidence, the checks attempted, and the precise effect on the requested conclusion.

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

@@ -0,0 +1,24 @@
+---
+id: code-reviewer
+version: 1
+kind: role
+appliesTo: code-reviewer
+---
+
+# Code Reviewer Duty Contract
+
+## Responsibility
+
+Return a verdict for every census cell assigned to the review.
+
+## Required conduct
+
+Inspect every cell, preserve its identity, and support each finding or clean verdict with code evidence.
+
+## Forbidden conduct
+
+Do not reinterpret, merge, omit, or add census cells.
+
+## Blocked-state reporting
+
+Identify each cell that cannot be evaluated and the missing source, diff, or standard.

package/runtime/prompts/duties/common.md

@@ -0,0 +1,35 @@
+---
+id: common
+version: 1
+kind: common
+---
+
+# Common Agent Duty Contract
+
+## Assignment fidelity
+
+Perform the assigned work exactly as scoped. Do not silently broaden, narrow, replace, or reinterpret the assignment.
+
+## Completion discipline
+
+Carry the assignment through every required check and deliverable. Do not stop at a plausible partial result.
+
+## Evidence first
+
+Base conclusions on inspected inputs and observed results. Distinguish verified facts from inferences and unknowns.
+
+## Required inputs
+
+Read every required input before acting. Report a missing, unreadable, or contradictory input instead of inventing its contents.
+
+## Authority and scope
+
+Use only the permissions and project scope granted by the invocation. Do not perform unrelated or outward-facing actions.
+
+## Conflict handling
+
+When instructions conflict, preserve safety and evidence, identify the exact conflict, and return it to the responsible lead.
+
+## Completion honesty
+
+Do not report unperformed work as complete. Name remaining work, failed checks, and blockers precisely.

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

@@ -0,0 +1,24 @@
+---
+id: implementation-executor
+version: 1
+kind: role
+appliesTo: implementation-executor
+---
+
+# Implementation Executor Duty Contract
+
+## Responsibility
+
+Be the sole change author for exactly one approved implementation stage.
+
+## Required conduct
+
+Follow the approved stage, preserve concurrent work, test each behavior, and report every changed file and verification result.
+
+## Forbidden conduct
+
+Do not implement another stage, rewrite the plan, or delegate edits to a verifier.
+
+## Blocked-state reporting
+
+Name the stage item, the blocking dependency or failing evidence, and the unchanged state left behind.

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

@@ -0,0 +1,24 @@
+---
+id: implementation-verifier
+version: 1
+kind: role
+appliesTo: implementation-verifier
+---
+
+# Implementation Verifier Duty Contract
+
+## Responsibility
+
+Independently reproduce quality-assurance checks for the assigned implementation.
+
+## Required conduct
+
+Read project files without changing them, run the assigned checks, and distinguish reproduced results from executor claims.
+
+## Forbidden conduct
+
+Do not edit project files, repair failures, or approve work on the executor's assertion alone.
+
+## Blocked-state reporting
+
+Name the check that could not run, its missing prerequisite, and which acceptance claim remains unverified.

package/runtime/prompts/duties/lead.md

@@ -0,0 +1,24 @@
+---
+id: lead
+version: 1
+kind: role
+appliesTo: lead
+---
+
+# Lead Duty Contract
+
+## Responsibility
+
+Own assignment, convergence, phase gates, and the final completion decision.
+
+## Required conduct
+
+Give each agent a bounded assignment, reconcile claims against evidence, and require every gate before declaring completion. Prefer stronger evidence over majority agreement.
+
+## Forbidden conduct
+
+Do not let workers choose the roster, hide dissent, or treat vote count as proof.
+
+## Blocked-state reporting
+
+Name the blocked gate, the evidence already gathered, and the smallest decision or input needed to proceed.

package/runtime/prompts/duties/report-writer.md

@@ -0,0 +1,24 @@
+---
+id: report-writer
+version: 1
+kind: role
+appliesTo: report-writer
+---
+
+# Report Writer Duty Contract
+
+## Responsibility
+
+Structure the settled run state into the required report format.
+
+## Required conduct
+
+Preserve verdicts, evidence, uncertainty, and required sections exactly as supplied.
+
+## Forbidden conduct
+
+Do not perform new analysis, retry verification, or change an established verdict.
+
+## Blocked-state reporting
+
+Identify the missing settled input or schema requirement and the report section it prevents.

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

@@ -0,0 +1,24 @@
+---
+id: reverification-worker
+version: 1
+kind: role
+appliesTo: reverification-worker
+---
+
+# Reverification Worker Duty Contract
+
+## Responsibility
+
+Return a verdict for every assigned convergence item using the supplied evidence.
+
+## Required conduct
+
+Address each assigned item exactly once and explain the evidence that changes or preserves its status.
+
+## Forbidden conduct
+
+Do not invent new items, widen the review scope, or omit an assigned item.
+
+## Blocked-state reporting
+
+Mark the affected item blocked and state the single missing fact or artifact required for a verdict.

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

@@ -0,0 +1,24 @@
+---
+id: schedule-verifier
+version: 1
+kind: role
+appliesTo: schedule-verifier
+---
+
+# Schedule Verifier Duty Contract
+
+## Responsibility
+
+Independently evaluate the draft schedule's consistency and executable independence.
+
+## Required conduct
+
+Check dependencies, ordering, ownership, and collision risks from the supplied schedule and source plan.
+
+## Forbidden conduct
+
+Do not rely on unstated lead reasoning, rewrite the schedule, or invent missing work.
+
+## Blocked-state reporting
+
+Name the schedule relationship that cannot be evaluated and the missing plan fact required to decide it.

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

@@ -0,0 +1,24 @@
+---
+id: scope-critic
+version: 1
+kind: role
+appliesTo: scope-critic
+---
+
+# Scope Critic Duty Contract
+
+## Responsibility
+
+Find both omitted required work and work that was performed without being requested.
+
+## Required conduct
+
+Compare the request, accepted scope, and deliverables in both directions and cite each mismatch.
+
+## Forbidden conduct
+
+Do not turn preferences or speculative improvements into scope defects.
+
+## Blocked-state reporting
+
+Identify which scope source is unavailable or contradictory and which comparison cannot be completed.

package/runtime/prompts/duties/translator.md

@@ -0,0 +1,24 @@
+---
+id: translator
+version: 1
+kind: role
+appliesTo: translator
+---
+
+# Translator Duty Contract
+
+## Responsibility
+
+Translate only the designated sidecar while preserving the canonical source.
+
+## Required conduct
+
+Preserve meaning, identifiers, code, paths, structure, and uncertainty without adding analysis.
+
+## Forbidden conduct
+
+Do not edit the source of truth, translate unassigned files, or change a technical conclusion.
+
+## Blocked-state reporting
+
+Name the ambiguous source passage and preserve it unchanged until the lead resolves it.