okstra 0.169.1 → 0.170.1

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -33,6 +33,11 @@ from .agent_invocation import (
     agent_model_assignment_from_payload,
     verify_agent_invocation,
 )
+from .final_report_paths import (
+    final_report_data_path,
+    final_report_markdown_path,
+)
+from .worker_prompt_body import REPORT_WRITER_WORKER_ID
 from .worker_prompt_contract import (
     PromptRecord,
     validate_initial_prompt_records,
@@ -504,9 +509,20 @@ def link_agent_dispatch_result(
             item for item in links
             if isinstance(item, Mapping) and item.get("resultPath") == result_relative
         ]
-        if same_result and any(dict(item) != link for item in same_result):
+        # A superseded link is the record of a result the lead rejected, kept so
+        # the chain shows the corrective round happened rather than hiding it.
+        # It no longer owns the path, so the re-dispatch may claim it.
+        live_conflicts = [
+            item for item in same_result
+            if not item.get("supersededBy") and dict(item) != link
+        ]
+        if live_conflicts:
             raise DispatchError(
-                f"agent result is already linked to another dispatch: {result_relative}"
+                f"agent result is already linked to another dispatch: "
+                f"{result_relative}. If that result was rejected and re-dispatched, "
+                f"record the rejection with `okstra agent-prompt reject-result "
+                f"--dispatch-id {live_conflicts[0].get('dispatchId')} "
+                f"--superseded-by {dispatch_id}` first"
             )
         if any(
             isinstance(item, Mapping)
@@ -523,6 +539,69 @@ def link_agent_dispatch_result(
     return link
 
 
+def reject_agent_dispatch_result(
+    *,
+    project_root: Path,
+    run_manifest_path: Path,
+    dispatch_id: str,
+    superseded_by: str,
+    reason: str,
+) -> dict[str, str]:
+    """Record that a linked result was rejected and re-dispatched.
+
+    The contract tells the lead to re-dispatch a worker whose answer violated the
+    response format, with a correction paragraph appended. That path did not
+    finish: the prompt is immutable and already dispatched, so
+    `--replace-undispatched` refuses (correctly), and a fresh invocation id
+    produces a worker that writes the same result path — where `link-result`
+    refused because the path already belonged to the first dispatch. The worker
+    ran, wrote a good result, and the ledger could not accept it.
+
+    Rejection is a fact worth recording rather than routing around, so it is
+    written rather than allowed implicitly: the first link stays in the ledger
+    marked `supersededBy` with the lead's reason, and only then may the
+    re-dispatch claim the path. Nothing is deleted, so the chain still shows both
+    attempts and why the second exists.
+    """
+    if not superseded_by.strip():
+        raise DispatchError("superseding dispatch ID is required")
+    if not reason.strip():
+        raise DispatchError(
+            "a rejection reason is required — the ledger has to say why a "
+            "returned result was not accepted"
+        )
+    project_root = project_root.resolve()
+    manifest_path = resolve_project_path(
+        project_root, str(run_manifest_path)
+    ).resolve(strict=True)
+    manifest = load_json_object(manifest_path, "run manifest")
+    team_state_path = resolve_required_path(project_root, manifest, "teamStatePath")
+    with _team_state_lock(team_state_path):
+        team_state = load_json_object(team_state_path, "team-state")
+        links = team_state.get("agentResultLinks")
+        if not isinstance(links, list):
+            raise DispatchError("team-state agentResultLinks must be an array")
+        matches = [
+            item for item in links
+            if isinstance(item, Mapping) and item.get("dispatchId") == dispatch_id
+        ]
+        if len(matches) != 1:
+            raise DispatchError(
+                f"expected exactly one agent result link for {dispatch_id}, "
+                f"found {len(matches)}"
+            )
+        row = matches[0]
+        if row.get("supersededBy"):
+            raise DispatchError(
+                f"agent result link is already superseded by "
+                f"{row['supersededBy']}: {dispatch_id}"
+            )
+        row["supersededBy"] = superseded_by
+        row["rejectionReason"] = reason
+        write_json(team_state_path, team_state)
+    return dict(row)
+
+
 def _relative_project_path(project_root: Path, path: Path) -> str:
     try:
         return path.resolve(strict=False).relative_to(project_root).as_posix()
@@ -644,6 +723,54 @@ def missing_completion_paths(job: WorkerJob) -> tuple[Path, ...]:
     return tuple(path for path in job.completion_paths if not path.is_file())
 
 
+def dispatch_result_path(
+    worker_id: str,
+    worker_result_path: Path,
+    manifest: Mapping[str, Any],
+    project_root: Path,
+) -> Path:
+    """What `resultPath` means for this worker.
+
+    For everyone but the report writer it is the worker-result file. The report
+    writer authors three artifacts and its canonical result is the final-report
+    data.json, not its own `.md` pointer — a distinction that is not cosmetic:
+    `dispatch_core` hands `job.result_path` to report finalization as the data
+    path, so a `.md` there is parsed as JSON and a complete report settles
+    `error`.
+
+    This lives beside `worker_jobs_from_file` because both job constructors must
+    apply it. It was `dispatch_core`-private while the roster path applied it and
+    the `--jobs-file` path took whatever the file said, which is how the two
+    produced different jobs for the same worker.
+    """
+    if worker_id != REPORT_WRITER_WORKER_ID:
+        return worker_result_path
+    return final_report_data_path(
+        resolve_required_path(project_root, manifest, "expectedReportPath")
+    )
+
+
+def dispatch_completion_paths(
+    worker_id: str,
+    worker_result_path: Path,
+    manifest: Mapping[str, Any],
+    project_root: Path,
+) -> tuple[Path, ...]:
+    """Every artifact that must exist before this worker counts as done.
+
+    The report writer's three are the data.json, its rendered Markdown sibling,
+    and the worker-result pointer (`prompts/lead/report-writer.md` §"Completion
+    detection"). Same reason as `dispatch_result_path`: both constructors need
+    the same answer.
+    """
+    if worker_id != REPORT_WRITER_WORKER_ID:
+        return (worker_result_path,)
+    data_json = final_report_data_path(
+        resolve_required_path(project_root, manifest, "expectedReportPath")
+    )
+    return (data_json, final_report_markdown_path(data_json), worker_result_path)
+
+
 def validate_initial_prompts(
     manifest: Mapping[str, Any], jobs: Sequence[WorkerJob]
 ) -> None:
@@ -798,6 +925,7 @@ def worker_jobs_from_file(
     project_root: Path,
     jobs_file: Path,
     *,
+    manifest: Mapping[str, Any],
     backend: str,
     idle_timeout_seconds: int,
     default_dispatch_kind: str,
@@ -816,6 +944,7 @@ def worker_jobs_from_file(
         _worker_job_from_file(
             project_root,
             item,
+            manifest=manifest,
             backend=backend,
             idle_timeout_seconds=idle_timeout_seconds,
             dispatch_kind=dispatch_kind,
@@ -831,6 +960,7 @@ def _worker_job_from_file(
     project_root: Path,
     item: Mapping[str, Any],
     *,
+    manifest: Mapping[str, Any],
     backend: str,
     idle_timeout_seconds: int,
     dispatch_kind: str,
@@ -842,16 +972,20 @@ def _worker_job_from_file(
     prompt_path = resolve_project_path(
         project_root, require_string(item, "promptPath")
     )
-    result_path = resolve_project_path(
-        project_root, require_string(item, "resultPath")
-    )
     worker_result_path = resolve_project_path(
         project_root, require_string(item, "workerResultPath")
     )
-    completion_paths = tuple(
-        resolve_project_path(project_root, path)
-        for path in string_list(item.get("completionPaths"))
-    ) or (result_path,)
+    # The file's own `resultPath` / `completionPaths` are advisory: the same
+    # derivation the roster path applies decides them, so a jobs-file dispatch
+    # and a roster dispatch of one worker cannot disagree about which artifact
+    # is the result. A file that names the report writer's `.md` as its result
+    # used to reach report finalization as the data path.
+    result_path = dispatch_result_path(
+        worker_id, worker_result_path, manifest, project_root
+    )
+    completion_paths = dispatch_completion_paths(
+        worker_id, worker_result_path, manifest, project_root
+    )
     digests = item.get("digests")
     digest_values = digests if isinstance(digests, Mapping) else {}
     host_model_value = item.get("hostModelValue")

package/runtime/python/okstra_ctl/doctor.py

@@ -9,6 +9,7 @@ from pathlib import Path
 from typing import Iterable
 
 from okstra_project import ResolverError, project_json_path, resolve_project_root
+from okstra_project.resolver import resolve_review_rule_packs
 
 from . import improvement_lenses, worktree_registry
 from .models import provider_wrappers
@@ -99,6 +100,9 @@ def _project_checks(cwd: Path) -> tuple[Path | None, list[DoctorCheck]]:
     architecture = _architecture_declaration_check(project_root)
     if architecture is not None:
         checks.append(architecture)
+    review_packs = _review_rule_pack_check(project_root)
+    if review_packs is not None:
+        checks.append(review_packs)
     return project_root, checks
 
 
@@ -158,6 +162,33 @@ def _architecture_declaration_check(project_root: Path) -> DoctorCheck | None:
     )
 
 
+def _review_rule_pack_check(project_root: Path) -> DoctorCheck | None:
+    """Report a declared review rule pack that no worker will be able to open.
+
+    `reviewRulePacks` is what makes a project's own review standard apply
+    without every brief citing it, so a stale path costs the whole pack in
+    silence: the phase records `project-review-rules: declared <path>
+    unreadable` at best, and a run that reviewed against nothing still passes.
+    Absent declaration stays quiet — brief-cited packs remain the other, equally
+    valid, channel.
+
+    What this cannot check is whether a pack that does resolve was actually read
+    and applied; that stays the worker's own `project-review-rules:` record.
+    """
+    declared = resolve_review_rule_packs(project_root)
+    if not declared:
+        return None
+    missing = [path for path in declared if not Path(path).is_file()]
+    if not missing:
+        return _ok("review rule packs", f"{len(declared)} declared, all readable")
+    return _fail(
+        "review rule packs",
+        f"declared but not readable: {', '.join(missing)} — phases skip a pack "
+        "they cannot open, so the run reviews against fewer rules than declared. "
+        f"Fix the path in {project_json_path(project_root)} or drop the entry.",
+    )
+
+
 def _profile_check(workspace: Path, phase: str) -> DoctorCheck:
     profile = _profile_path(workspace, phase)
     if profile.is_file():

package/runtime/python/okstra_ctl/plan_derivations.py

@@ -0,0 +1,94 @@
+"""Find the statements an answered clarification may have just falsified.
+
+`_common-contract.md` §"Supersession" and `report-writer.md` §"Self-fix rewrite"
+both say the same thing: an answer does not merely add a decision, it invalidates
+whatever the plan wrote under the opposite assumption, so before editing you must
+"grep the constant, the symbol, the path, the requirement ID across the whole
+plan body". Both leave that grep to the author's diligence, and it is the step
+that gets skipped — in one observed run, 17 of 23 blocked plan items were a
+recorded decision whose derivations were never swept.
+
+This does the grep. It is deliberately advisory: it returns candidate locations,
+never a verdict about which ones are now false. Deciding that is the author's
+job, and a tool that guessed would be trading one silent failure for another.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Iterator, Mapping, Sequence
+
+# A backticked span is how both contracts tell an author to write a symbol, a
+# path, or a constant, so it is the highest-signal thing to extract. Bare prose
+# words are deliberately not extracted: they match everywhere and would bury the
+# hits that matter.
+_BACKTICKED_RE = re.compile(r"`([^`\n]+)`")
+# Ids the plan carries in its own rows (`R-001`, `P-Step-3`, `VC-002`) and the
+# ticket ids the brief uses (`DEV-10174`, `PROD-1623`).
+_ID_RE = re.compile(r"\b(?:[A-Z][A-Za-z]*-[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*)\b")
+# Below this length a token matches too much to be worth reading: `id`, `db`,
+# and `ko` each hit dozens of unrelated rows.
+_MIN_TOKEN_LENGTH = 3
+_EXCERPT_MAX = 160
+
+
+def extract_tokens(text: str) -> list[str]:
+    """The symbols, paths, and ids an answer names, longest first.
+
+    Longest first so a caller reading the report sees the specific token before
+    the general one it contains (`src/domains/font` before `src/domains`).
+    """
+    found: set[str] = set()
+    for raw in _BACKTICKED_RE.findall(text):
+        token = raw.strip()
+        # A backticked sentence is prose in code font, not a symbol.
+        if len(token) >= _MIN_TOKEN_LENGTH and " " not in token:
+            found.add(token)
+    for token in _ID_RE.findall(text):
+        if len(token) >= _MIN_TOKEN_LENGTH:
+            found.add(token)
+    return sorted(found, key=lambda token: (-len(token), token))
+
+
+def _string_leaves(node: Any, pointer: str = "") -> Iterator[tuple[str, str]]:
+    if isinstance(node, str):
+        yield pointer, node
+    elif isinstance(node, Mapping):
+        for key, value in node.items():
+            yield from _string_leaves(value, f"{pointer}/{key}")
+    elif isinstance(node, Sequence) and not isinstance(node, (str, bytes)):
+        for index, value in enumerate(node):
+            yield from _string_leaves(value, f"{pointer}/{index}")
+
+
+def _excerpt(text: str, token: str) -> str:
+    index = text.find(token)
+    if index < 0:
+        return text[:_EXCERPT_MAX]
+    start = max(0, index - _EXCERPT_MAX // 3)
+    excerpt = text[start:start + _EXCERPT_MAX]
+    return ("…" if start else "") + excerpt + ("…" if len(text) > start + _EXCERPT_MAX else "")
+
+
+def find_derivations(
+    plan: Mapping[str, Any],
+    tokens: Sequence[str],
+    *,
+    exclude_pointer_prefix: str = "",
+) -> list[dict[str, str]]:
+    """Every string in *plan* that mentions one of *tokens*.
+
+    One hit per (pointer, token): a row naming two affected symbols is two things
+    to re-check, not one.
+    """
+    hits: list[dict[str, str]] = []
+    for pointer, text in _string_leaves(plan):
+        if exclude_pointer_prefix and pointer.startswith(exclude_pointer_prefix):
+            continue
+        for token in tokens:
+            if token in text:
+                hits.append({
+                    "token": token,
+                    "pointer": pointer,
+                    "excerpt": _excerpt(text, token),
+                })
+    return hits

package/runtime/python/okstra_ctl/plan_items_cli.py

@@ -14,8 +14,15 @@ import sys
 from typing import Any
 
 from .convergence_store import write_json_atomic
+from .plan_derivations import extract_tokens, find_derivations
 from .plan_items import PlanItemContractError, extract_plan_items
-from .verdict_blocks import VerdictBlock, VerdictBlockError, parse_verdict_blocks
+from .user_response import parse_user_response_entries
+from .verdict_blocks import (
+    PLAN_ITEM_VERDICTS,
+    VerdictBlock,
+    VerdictBlockError,
+    parse_verdict_blocks,
+)
 
 
 def _load_json_object(path: Path) -> dict[str, Any]:
@@ -64,12 +71,31 @@ def _parser() -> argparse.ArgumentParser:
                          help="one worker's plan-verify result file (repeatable)")
     collect.add_argument("--items", type=Path, required=True)
     collect.add_argument("--output", type=Path, required=True)
+    derivations = commands.add_parser(
+        "derivations",
+        help="list plan statements an answered clarification may have falsified",
+    )
+    derivations.add_argument("--data", type=Path, required=True)
+    derivations.add_argument("--response", type=Path, required=True,
+                             help="the user-responses sidecar for this run")
+    derivations.add_argument("--clarification", default=None,
+                             help="only this C-id (default: every answered one)")
+    seed = commands.add_parser(
+        "seed",
+        help="create the planBodyVerification.planItems[] rows a round lands in",
+    )
+    seed.add_argument("--data", type=Path, required=True)
     apply_verdicts = commands.add_parser(
         "apply-verdicts",
         help="overwrite planBodyVerification.planItems[].verdicts in data.json",
     )
     apply_verdicts.add_argument("--data", type=Path, required=True)
     apply_verdicts.add_argument("--verdicts", type=Path, required=True)
+    apply_verdicts.add_argument(
+        "--round", type=int, required=True, dest="round_number",
+        help="the verification round these verdicts were cast in; stamped on "
+             "every row so a later self-fix can be told from a current judgement",
+    )
     return parser
 
 
@@ -112,8 +138,18 @@ def _assigned_item_ids(items_path: Path) -> list[str]:
 
 def _verdict_row(worker: str, block: VerdictBlock) -> dict[str, Any]:
     """One `planItems[].verdicts[]` row. Optional fields stay absent when empty
-    so the recorded table shows what the worker actually said."""
-    row: dict[str, Any] = {"worker": worker, "verdict": block.verdict}
+    so the recorded table shows what the worker actually said.
+
+    The verdict crosses a vocabulary boundary here: a worker answers
+    `UNVERIFIABLE`, and the schema persists that as `verification-error`
+    (`PLAN_ITEM_VERDICTS`). Writing the worker's token straight through produced
+    a data.json its own schema rejects, and the mapping the contract prescribes
+    had to be applied by hand every round.
+    """
+    row: dict[str, Any] = {
+        "worker": worker,
+        "verdict": PLAN_ITEM_VERDICTS[block.verdict],
+    }
     for key, value in (
         ("breakageKind", block.breakage_kind),
         ("fixability", block.fixability),
@@ -194,6 +230,84 @@ def _plan_body_items(data: dict[str, Any], data_path: Path) -> list[dict[str, An
     return items
 
 
+def _derivations(args: argparse.Namespace) -> dict[str, Any]:
+    """Candidate statements each answered clarification may have falsified.
+
+    Advisory by construction: it reports where a decision's subject is mentioned
+    and never which mentions are now wrong. Both contracts require the author to
+    enumerate before editing; this supplies the enumeration, which is the half
+    that was being skipped, and leaves the judgement where it belongs.
+    """
+    try:
+        sidecar = args.response.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise PlanItemContractError(
+            f"cannot read user-response sidecar {args.response}: {exc}"
+        ) from exc
+    planning = _planning(_load_json_object(args.data))
+    entries = [
+        entry for entry in parse_user_response_entries(sidecar)
+        if args.clarification is None or entry.response_id == args.clarification
+    ]
+    if args.clarification is not None and not entries:
+        raise PlanItemContractError(
+            f"{args.response} has no response block for {args.clarification}"
+        )
+    clarifications = []
+    for entry in entries:
+        tokens = extract_tokens(f"{entry.value}\n{entry.rationale or ''}")
+        clarifications.append({
+            "id": entry.response_id,
+            "disposition": entry.disposition,
+            "tokens": tokens,
+            "candidates": find_derivations(planning, tokens),
+        })
+    return {
+        "ok": True,
+        "operation": "derivations",
+        "advisory": True,
+        "clarifications": clarifications,
+    }
+
+
+def _seed(args: argparse.Namespace) -> dict[str, Any]:
+    """Create the `planBodyVerification.planItems[]` rows a round lands in.
+
+    `apply-verdicts` refuses a verdict whose item has no row — correctly, since
+    the gate is re-derived from that table and a verdict with nowhere to land
+    would score as never cast. But nothing created the rows: the report writer
+    leaves `planItems: []` (§5.5.9 is a lead substep that runs after it), and
+    there was no step, in code or in the contract, that filled them. Every round
+    had to be hand-seeded before the CLI would accept its own output.
+
+    Idempotent by id. An existing row keeps everything it carries — verdicts
+    already applied, `carriedForwardFromSeq`, `selfFixNote` — because a re-seed
+    between rounds must not erase the round before it.
+    """
+    extracted = _envelope(_load_json_object(args.data))["items"]
+    data = _load_json_object(args.data)
+    recorded = _plan_body_items(data, args.data)
+    known = {
+        item.get("id")
+        for item in recorded
+        if isinstance(item, Mapping)
+    }
+    added = [
+        {**item, "verdicts": []}
+        for item in extracted
+        if item["id"] not in known
+    ]
+    recorded.extend(added)
+    write_json_atomic(args.data, data)
+    return {
+        "ok": True,
+        "operation": "seed",
+        "path": str(args.data),
+        "seeded": len(added),
+        "existing": len(known),
+    }
+
+
 def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
     data = _load_json_object(args.data)
     incoming = _load_json_object(args.verdicts).get("planItems")
@@ -213,11 +327,22 @@ def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
             f"gate is re-derived from that table, so a verdict with nowhere to "
             f"land would be scored as if it were never cast"
         )
+    if args.round_number < 1:
+        raise PlanItemContractError("--round must be 1 or greater")
     for item in recorded:
         if isinstance(item, Mapping) and item.get("id") in rows:
             # Overwrite, never merge: the contract records one round at a time,
             # and a merged table lets a previous round's votes keep voting.
-            item["verdicts"] = rows[item["id"]]
+            #
+            # Each row carries the round it was cast in. A self-fix round
+            # rewrites the plan *after* a verification round, so an item left out
+            # of a later round keeps a verdict on text that has since changed —
+            # invisibly, because the gate reads the table without knowing any
+            # row's vintage. Stamping it here is what lets the validator tell a
+            # current judgement from one two rewrites old.
+            item["verdicts"] = [
+                {**row, "round": args.round_number} for row in rows[item["id"]]
+            ]
     write_json_atomic(args.data, data)
     return {"ok": True, "operation": "apply-verdicts", "path": str(args.data)}
 
@@ -226,6 +351,8 @@ _HANDLERS = {
     "extract": _extract,
     "validate": _validate,
     "collect-verdicts": _collect_verdicts,
+    "derivations": _derivations,
+    "seed": _seed,
     "apply-verdicts": _apply_verdicts,
 }
 

package/runtime/python/okstra_ctl/run.py

@@ -68,6 +68,7 @@ from .domain.host import (
     ProviderUnavailable,
 )
 from .model_discovery import normalize_execution_for_dispatch
+from .worker_prompt_policy import ANALYSIS_DUTY_BY_TASK_TYPE
 from .models import (
     ModelAssignment,
     UnknownProviderError,
@@ -2523,7 +2524,12 @@ def _allowed_agent_audiences(
     elif inp.task_type == "final-verification":
         audiences.add("acceptance-verifier")
     else:
-        audiences.add("analysis-worker")
+        # Same map the prompt policy resolves the duty from. Allowing a
+        # different audience here than the one the policy will ask for makes
+        # every worker prompt in the phase fail materialization.
+        audiences.add(
+            ANALYSIS_DUTY_BY_TASK_TYPE.get(inp.task_type, "analysis-worker")
+        )
     if models.critic_choice not in {"", "off"}:
         audiences.update({"scope-critic", "acceptance-critic"})
     return sorted(audiences)

package/runtime/python/okstra_ctl/schema_excerpt.py

@@ -23,6 +23,7 @@ from __future__ import annotations
 
 import json
 import re
+from pathlib import Path
 
 from .report_contract import TASK_TYPE_DATA_PROPERTY
 
@@ -78,6 +79,39 @@ def excerpt_cut_from_version(excerpt: dict) -> str:
     return value if isinstance(value, str) else ""
 
 
+def excerpt_version_skew(excerpt_path: Path, installed: str) -> str:
+    """The version the bundle excerpt was cut from, when it is not *installed*.
+
+    Empty means no actionable skew: the file is absent or unreadable, carries no
+    stamp, or matches. A non-empty return is the older version, which the caller
+    turns into its own message.
+
+    The comparison used to live only in the renderer's error decorator, so it ran
+    in Phase 6 — after a worker had already authored a whole report against a
+    stale excerpt. The same two values are available much earlier, and the fix
+    (re-prepare the bundle) is the same either way.
+    """
+    if not installed:
+        return ""
+    try:
+        excerpt = json.loads(excerpt_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return ""
+    if not isinstance(excerpt, dict):
+        return ""
+    cut_from = excerpt_cut_from_version(excerpt)
+    return cut_from if cut_from and cut_from != installed else ""
+
+
+def bundle_excerpt_path(start: Path) -> Path | None:
+    """The task bundle's schema excerpt, found by walking up from *start*."""
+    for ancestor in Path(start).resolve().parents:
+        candidate = ancestor / "instruction-set" / "final-report-schema.json"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
 def build_schema_excerpt(schema: dict, task_type: str, cut_from_version: str = "") -> dict:
     """Return a task-type-scoped copy of *schema*.
 

package/runtime/python/okstra_ctl/verdict_blocks.py

@@ -38,6 +38,23 @@ ADVERSARIAL_VERDICTS = {
     "UNVERIFIABLE": "unverifiable",
     "VERIFICATION-ERROR": "verification-error",
 }
+# Plan-body verdicts persist in their own vocabulary, which is NOT the
+# convergence one above: the schema keeps the first three tokens uppercase
+# (`$defs/PlanBodyVerification/properties/planItems/items/properties/verdicts/
+# items/properties/verdict`) and has no `UNVERIFIABLE` member at all.
+# `plan-body-verification.md` §"Planning-time environment gap" states the
+# mapping — "Recording `UNVERIFIABLE` is the honest outcome — it is persisted as
+# `verification-error`" — and it lives here rather than inside the transcription
+# CLI so the worker-facing token and the persisted token are decided in one
+# place. Writing the raw token through put a value in data.json that its own
+# schema rejects.
+PLAN_ITEM_VERDICTS = {
+    "AGREE": "AGREE",
+    "DISAGREE": "DISAGREE",
+    "SUPPLEMENT": "SUPPLEMENT",
+    "UNVERIFIABLE": "verification-error",
+    "VERIFICATION-ERROR": "verification-error",
+}
 DISAGREE_BASES = frozenset({"counter-evidence", "burden-not-met"})
 
 _ITEM_RE = re.compile(r"^###[ \t]+(?P<id>[^\s:]+)[ \t]*:?.*$", re.MULTILINE)

package/runtime/python/okstra_ctl/worker_prompt_policy.py

@@ -58,6 +58,17 @@ SUPPORTED_TASK_TYPES = frozenset({
     "release-handoff",
     *ANALYSIS_TASK_TYPES,
 })
+# One duty per analysis ROLE, not per phase. Phases that ask their worker for the
+# same kind of judgement share a contract — requirements- and improvement-discovery
+# both hand over candidates they do not start — and a phase whose worker decides
+# something else gets its own. A task type absent from this map takes the
+# observational default below: describe the area, do not design for it.
+ANALYSIS_DUTY_BY_TASK_TYPE: dict[str, AgentAudience] = {
+    "requirements-discovery": "discovery-worker",
+    "improvement-discovery": "discovery-worker",
+    "error-analysis": "diagnosis-worker",
+    "implementation-planning": "planning-worker",
+}
 WORKER_PREAMBLE_FILENAME_BY_AUDIENCE = {
     "analysis": "worker-prompt-preamble.md",
     "implementation-executor": "implementation-worker-preamble.md",
@@ -113,7 +124,7 @@ def resolve_prompt_plan(
         if dispatch_kind == "critic"
         else "acceptance-verifier"
         if task_type == "final-verification"
-        else "analysis-worker"
+        else ANALYSIS_DUTY_BY_TASK_TYPE.get(task_type, "analysis-worker")
     )
     if task_type == "implementation" and not executor_worker_id:
         raise ValueError("implementation executor worker ID is required")