okstra 0.207.0 → 0.208.0

package/runtime/python/okstra_ctl/coverage_census.py

@@ -0,0 +1,596 @@
+"""Coverage census: the fixed worklist every analysis worker judges cell by cell.
+
+A worker used to decide for itself what to look at, so two runs of the same
+model on the same input differed by 12-30% in the findings they raised. The
+census fixes the worklist in code: the phase profile's `Census aspects` block
+names the questions, the brief's end-state ids (and, per phase, the changed
+files or the improvement lenses) name the subjects, and every analyser returns
+one verdict per cell. A worker cannot add, drop, or reinterpret a cell.
+
+Nothing here can stop a run. A profile without the block has no census, a brief
+without end-state ids has no requirement cells, and a cell a worker leaves
+without a verdict becomes a warning, never a failure.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from .convergence_provenance import id_occurs_wordbounded
+from .json_boundary import JsonBoundaryError, load_owned_object
+from .phases.improvement_discovery.lenses import LENSES
+from .scope_provenance import brief_end_state_id_sequence
+
+
+CENSUS_SCHEMA_VERSION = "1.0"
+CENSUS_ASPECTS_LINE = "- Census aspects:"
+SCOPES = ("requirement", "task", "file", "lens")
+_ASPECT_RE = re.compile(
+    r"^  - (?P<scope>[a-z]+) (?P<slug>[a-z0-9]+(?:-[a-z0-9]+)*):\s*(?P<question>\S.*)$"
+)
+
+
+class CensusError(ValueError):
+    """A profile's `Census aspects` block cannot be read."""
+
+
+@dataclass(frozen=True)
+class Aspect:
+    scope: str
+    slug: str
+    question: str
+
+
+def parse_census_aspects(profile_text: str) -> tuple[Aspect, ...]:
+    """The aspects a profile declares, in order. No block means no census.
+
+    The block is a top-level bullet followed by two-space nested bullets, the
+    same layout `analysis_packet._extract_bullet_sections` reads.
+    """
+    lines = profile_text.splitlines()
+    try:
+        start = next(
+            index for index, line in enumerate(lines)
+            if line.rstrip() == CENSUS_ASPECTS_LINE
+        )
+    except StopIteration:
+        # expected-miss: a phase without the block runs without a census.
+        return ()
+    aspects: list[Aspect] = []
+    for line in lines[start + 1:]:
+        if not line.strip():
+            continue
+        if not line.startswith("  "):
+            break
+        match = _ASPECT_RE.match(line.rstrip())
+        if match is None:
+            raise CensusError(f"census aspect line is malformed: {line.strip()!r}")
+        scope = match.group("scope")
+        if scope not in SCOPES:
+            raise CensusError(
+                f"census aspect scope {scope!r} is not one of {', '.join(SCOPES)}"
+            )
+        aspects.append(Aspect(scope, match.group("slug"), match.group("question").strip()))
+    keys = [(aspect.scope, aspect.slug) for aspect in aspects]
+    if len(keys) != len(set(keys)):
+        raise CensusError("census aspects repeat a scope and slug pair")
+    if sum(aspect.scope == "lens" for aspect in aspects) > 1:
+        # A lens cell id carries the lens alone (`C-L-<lens>`), so a second lens
+        # aspect would mint the same ids twice.
+        raise CensusError("census aspects declare more than one lens aspect")
+    return tuple(aspects)
+
+
+def build_census(
+    *,
+    task_type: str,
+    aspects: Sequence[Aspect],
+    requirement_ids: Sequence[str],
+    changed_files: Sequence[str] = (),
+) -> dict[str, Any]:
+    """Every cell for this run, in the order a worker should walk them."""
+    cells: list[dict[str, str]] = []
+
+    def add(cell_id: str, aspect: Aspect, subject: str) -> None:
+        cells.append({
+            "id": cell_id,
+            "scope": aspect.scope,
+            "aspect": aspect.slug,
+            "subject": subject,
+            "question": aspect.question,
+        })
+
+    by_scope = {
+        scope: [aspect for aspect in aspects if aspect.scope == scope]
+        for scope in SCOPES
+    }
+    for requirement in dict.fromkeys(requirement_ids):
+        for aspect in by_scope["requirement"]:
+            add(f"C-{requirement}-{aspect.slug}", aspect, requirement)
+    for aspect in by_scope["task"]:
+        add(f"C-T-{aspect.slug}", aspect, "task")
+    for index, path in enumerate(sorted(set(filter(None, changed_files))), start=1):
+        for aspect in by_scope["file"]:
+            add(f"C-F-{index:03d}-{aspect.slug}", aspect, path)
+    for aspect in by_scope["lens"]:
+        for lens in LENSES:
+            add(f"C-L-{lens}", aspect, lens)
+    return {
+        "schemaVersion": CENSUS_SCHEMA_VERSION,
+        "taskType": task_type,
+        "cells": cells,
+    }
+
+
+def census_for_run(
+    *,
+    task_type: str,
+    profile_text: str,
+    brief_path: Path,
+    changed_files: Sequence[str] = (),
+) -> dict[str, Any] | None:
+    """The run's census, or ``None`` when the phase profile declares none."""
+    aspects = parse_census_aspects(profile_text)
+    if not aspects:
+        return None
+    return build_census(
+        task_type=task_type,
+        aspects=aspects,
+        requirement_ids=brief_end_state_id_sequence(brief_path),
+        changed_files=changed_files,
+    )
+
+
+def census_filename(task_type: str, state_sequence: str) -> str:
+    return f"coverage-census-{task_type}-{state_sequence}.json"
+
+
+def census_state_paths(
+    project_root: Path, manifest: Mapping[str, Any],
+) -> tuple[Path, Path] | None:
+    """This run's (census, audit) paths, or ``None`` when the manifest cannot
+    name them. Either file may still be absent."""
+    run_dir = manifest.get("runDirectoryPath")
+    task_type = manifest.get("taskType")
+    sequences = manifest.get("runSequencesByCategory")
+    sequence = sequences.get("state") if isinstance(sequences, Mapping) else None
+    if not all(isinstance(value, str) and value for value in (run_dir, task_type, sequence)):
+        return None
+    state_dir = Path(project_root) / str(run_dir) / "state"
+    return (
+        state_dir / census_filename(str(task_type), str(sequence)),
+        state_dir / audit_filename(str(task_type), str(sequence)),
+    )
+
+
+def _cell_text(value: str) -> str:
+    return value.replace("|", "\\|")
+
+
+def render_census_section(census: Mapping[str, Any], census_rel_path: str) -> str:
+    """The packet's `## Coverage Census` block. Empty when there is no cell."""
+    cells = [cell for cell in census.get("cells") or [] if isinstance(cell, Mapping)]
+    if not cells:
+        return ""
+    rows = [
+        "## Coverage Census",
+        "",
+        "The fixed worklist for this run. okstra built it from the phase "
+        "profile's `Census aspects` and the brief's end-state ids; do not add, "
+        "drop, rename, or reinterpret a cell. Judge every cell and return one "
+        "line per cell under `Coverage Verdicts` in your result (worker preamble "
+        "§\"Worker output sections\"). A cell with no line is sent back to you "
+        "once, alone.",
+        "",
+        f"- Cell count: {len(cells)}",
+        f"- Canonical copy: `{census_rel_path}`",
+        "",
+        "| Cell | Scope | Subject | Question |",
+        "|---|---|---|---|",
+    ]
+    for cell in cells:
+        rows.append(
+            f"| `{cell['id']}` | {cell['scope']} | `{_cell_text(str(cell['subject']))}` "
+            f"| {_cell_text(str(cell['question']))} |"
+        )
+    return "\n".join(rows)
+
+
+_VERDICTS_HEADING_RE = re.compile(
+    r"^#{1,6}\s+(?:\d+\.\s*)?Coverage Verdicts\b", re.IGNORECASE
+)
+_HEADING_RE = re.compile(r"^#{1,6}\s")
+_VERDICT_LINE_RE = re.compile(
+    r"^\s*[-*]\s+`?(?P<cell>C-[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*)`?\s*:\s*"
+    r"(?P<kind>clean|finding|n/a)(?![A-Za-z0-9/])(?P<rest>.*)$",
+    re.IGNORECASE,
+)
+# Some models write the section as a table (`| cell | verdict |`); a cited
+# verdict must not be dropped for its layout.
+_VERDICT_ROW_RE = re.compile(
+    r"^\s*\|\s*`?(?P<cell>C-[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*)`?\s*\|\s*"
+    r"(?P<kind>clean|finding|n/a)(?![A-Za-z0-9/])(?P<rest>.*?)\|?\s*$",
+    re.IGNORECASE,
+)
+_SEPARATORS = " \t—–-:|"
+_CITATION_RE = re.compile(r"[^\s`]+:\d+")
+_ITEM_ID_RE = re.compile(r"[`\[]?(?P<id>[A-Za-z0-9][A-Za-z0-9._-]*?)[`\]]?(?=$|[\s,;.)])")
+
+
+@dataclass(frozen=True)
+class CellVerdicts:
+    """One result's reading of its census cells.
+
+    ``verdicts`` maps a judged cell to ``(kind, detail)``; ``missing`` maps an
+    unjudged cell to why it counts as unjudged; ``unknown`` lists cell ids the
+    result named that the census does not carry.
+    """
+
+    verdicts: dict[str, tuple[str, str]]
+    missing: dict[str, str]
+    unknown: tuple[str, ...]
+
+
+def _split_verdict_section(text: str) -> tuple[list[str], str]:
+    """The Coverage Verdicts lines, and the rest of the result."""
+    lines = text.splitlines()
+    start = next(
+        (index for index, line in enumerate(lines) if _VERDICTS_HEADING_RE.match(line)),
+        None,
+    )
+    if start is None:
+        return [], text
+    end = next(
+        (index for index in range(start + 1, len(lines)) if _HEADING_RE.match(lines[index])),
+        len(lines),
+    )
+    return lines[start + 1:end], "\n".join(lines[:start] + lines[end:])
+
+
+def _judge(kind: str, rest: str, body_texts: Sequence[str]) -> tuple[str, str] | str:
+    """``(kind, detail)`` for a usable verdict, otherwise why it is unusable."""
+    detail = rest.strip().lstrip(_SEPARATORS).strip()
+    if kind == "clean":
+        if not _CITATION_RE.search(detail):
+            return "clean without a path:line citation"
+        return kind, detail
+    if kind == "n/a":
+        if not detail:
+            return "n/a without a reason"
+        return kind, detail
+    match = _ITEM_ID_RE.match(detail)
+    if match is None:
+        return "finding without an item id"
+    item_id = match.group("id")
+    if not any(id_occurs_wordbounded(text, item_id) for text in body_texts):
+        return f"finding cites `{item_id}`, which the result does not contain"
+    return kind, item_id
+
+
+def parse_cell_verdicts(
+    result_text: str,
+    cell_ids: Sequence[str],
+    *,
+    reference_texts: Sequence[str] = (),
+) -> CellVerdicts:
+    """Read a result's `Coverage Verdicts` section against ``cell_ids``.
+
+    ``reference_texts`` are other results a `finding` may point into: a
+    gap-fill result can cite an item its worker's first result already raised.
+    The first usable line for a cell wins.
+    """
+    section, body = _split_verdict_section(result_text)
+    wanted = list(dict.fromkeys(cell_ids))
+    known = set(wanted)
+    verdicts: dict[str, tuple[str, str]] = {}
+    reasons: dict[str, str] = {}
+    unknown: list[str] = []
+    for line in section:
+        match = _VERDICT_LINE_RE.match(line) or _VERDICT_ROW_RE.match(line)
+        if match is None:
+            continue
+        cell = match.group("cell")
+        if cell not in known:
+            if cell not in unknown:
+                unknown.append(cell)
+            continue
+        if cell in verdicts:
+            continue
+        judged = _judge(
+            match.group("kind").lower(), match.group("rest"), (body, *reference_texts)
+        )
+        if isinstance(judged, tuple):
+            verdicts[cell] = judged
+            reasons.pop(cell, None)
+        else:
+            reasons.setdefault(cell, judged)
+    no_section = "no Coverage Verdicts section" if not section else "no verdict line"
+    missing = {
+        cell: reasons.get(cell, no_section)
+        for cell in wanted if cell not in verdicts
+    }
+    return CellVerdicts(verdicts, missing, tuple(unknown))
+
+
+AUDIT_SCHEMA_VERSION = "1.0"
+UNVERDICTED = "unverdicted"
+
+
+def audit_filename(task_type: str, state_sequence: str) -> str:
+    return f"coverage-census-audit-{task_type}-{state_sequence}.json"
+
+
+def audit_census(
+    census: Mapping[str, Any],
+    results: Mapping[str, str | None],
+    gapfills: Mapping[str, str | None] | None = None,
+) -> dict[str, Any]:
+    """Per-worker coverage of ``census``, the cell x worker matrix, and the
+    cells two workers judged in opposite directions.
+
+    ``results`` maps each analysis worker to its result text (``None``: the
+    file is missing). ``gapfills`` does the same for the one gap-fill dispatch;
+    a worker absent from it was not sent one. Whatever stays unjudged after
+    both is ``unverdicted`` — recorded, never raised.
+    """
+    gapfills = gapfills or {}
+    cell_ids = [str(cell["id"]) for cell in census.get("cells") or []]
+    workers: list[dict[str, Any]] = []
+    judged: dict[str, dict[str, tuple[str, str]]] = {}
+    for worker, text in results.items():
+        first = parse_cell_verdicts(text or "", cell_ids)
+        verdicts = dict(first.verdicts)
+        missing = dict(first.missing)
+        if text is None:
+            missing = dict.fromkeys(cell_ids, "result file is missing")
+        gapfill_status = "not-sent"
+        if worker in gapfills:
+            gapfill_text = gapfills[worker]
+            gapfill_status = "missing" if gapfill_text is None else "read"
+            if gapfill_text is not None and missing:
+                second = parse_cell_verdicts(
+                    gapfill_text, list(missing), reference_texts=(text or "",)
+                )
+                verdicts.update(second.verdicts)
+                missing = {
+                    cell: second.missing.get(cell, reason)
+                    for cell, reason in missing.items() if cell not in second.verdicts
+                }
+        judged[worker] = verdicts
+        workers.append({
+            "workerId": worker,
+            "result": "missing" if text is None else "read",
+            "gapfill": gapfill_status,
+            "verdictCount": len(verdicts),
+            UNVERDICTED: list(missing),
+            "unverdictedReasons": missing,
+            "unknownCellIds": list(first.unknown),
+        })
+    matrix = [
+        {
+            "cellId": cell,
+            "verdicts": {
+                worker: judged[worker][cell][0] if cell in judged[worker] else UNVERDICTED
+                for worker in judged
+            },
+        }
+        for cell in cell_ids
+    ]
+    disagreements = []
+    suggestions = []
+    for cell in cell_ids:
+        findings = [
+            {"worker": worker, "itemId": verdicts[cell][1]}
+            for worker, verdicts in judged.items()
+            if verdicts.get(cell, ("",))[0] == "finding"
+        ]
+        clean = [
+            worker for worker, verdicts in judged.items()
+            if verdicts.get(cell, ("",))[0] == "clean"
+        ]
+        if findings:
+            suggestions.append({"cellId": cell, "items": findings})
+        if findings and clean:
+            disagreements.append({"cellId": cell, "finding": findings, "clean": clean})
+    return {
+        "schemaVersion": AUDIT_SCHEMA_VERSION,
+        "taskType": census.get("taskType"),
+        "cellCount": len(cell_ids),
+        # A single analyser still gets its matrix; there is just no second
+        # model to disagree with, and the report says so instead of the run
+        # being refused.
+        "crossCheck": "cell" if len(results) > 1 else "none",
+        "workers": workers,
+        "gapfillNeeded": [
+            row["workerId"] for row in workers
+            if row[UNVERDICTED] and row["gapfill"] == "not-sent"
+        ],
+        "matrix": matrix,
+        "disagreements": disagreements,
+        "cellSuggestions": suggestions,
+    }
+
+
+PROMPT_DELIVERY_MODE = "eager-include"
+_IDS_PER_LINE = 6
+
+_GAPFILL_MANDATE = """
+Your first result left the cells below without a usable verdict. Judge each
+one now against its question in the packet's `## Coverage Census` table. This
+is the only gap-fill pass: a cell left unjudged here is reported as
+unverdicted.
+
+Write your result with the frontmatter and headers the worker preamble
+requires, and only these two sections:
+
+- `## 1. Findings` — the new items a `finding` verdict below points to, each
+  with a worker-local ID your first result does not use and file:line
+  evidence. Write `- none` when there is none. A `finding` may also cite an
+  item ID from your first result.
+- `## 6. Coverage Verdicts` — one line per cell listed below, in the
+  preamble's form: `clean — <path:line>`, `finding <ID>`, or `n/a — <reason>`.
+
+Do not judge cells that are not listed, and do not repeat your first result.
+""".strip()
+
+
+def gapfill_prompt_body(
+    audit: Mapping[str, Any],
+    worker: str,
+    *,
+    task_key: str,
+    analysis_packet_path: str,
+    census_path: str,
+) -> str:
+    """The `census-gapfill` instruction body for one worker. Same input, same bytes."""
+    row = next(
+        (row for row in audit.get("workers") or [] if row.get("workerId") == worker),
+        None,
+    )
+    if row is None:
+        raise CensusError(f"the census audit has no worker `{worker}`")
+    if row.get("gapfill") != "not-sent":
+        raise CensusError(
+            f"`{worker}` already had its one census gap-fill; the retry is fixed at one"
+        )
+    missing: Mapping[str, str] = row.get("unverdictedReasons") or {}
+    if not missing:
+        raise CensusError(f"`{worker}` left no census cell unjudged")
+    if not analysis_packet_path.endswith("analysis-packet.md"):
+        raise CensusError(
+            "run manifest analysisPacketPath must name analysis-packet.md; "
+            f"found `{analysis_packet_path}`"
+        )
+    by_reason: dict[str, list[str]] = {}
+    for cell, reason in missing.items():
+        by_reason.setdefault(reason, []).append(cell)
+    rows = [
+        f"**Prompt Delivery Mode:** {PROMPT_DELIVERY_MODE}",
+        "",
+        f"# Coverage census gap-fill — {task_key}",
+        "",
+        "## Inputs",
+        f"- Primary analysis packet: `{analysis_packet_path}`",
+        f"- Coverage census: `{census_path}`",
+    ]
+    if row.get("resultPath"):
+        rows.append(f"- Your first result: `{row['resultPath']}`")
+    rows.extend(["", "## Mandate", "", _GAPFILL_MANDATE, "", "## Cells to judge", ""])
+    rows.append(f"- Cell count: {len(missing)}")
+    for reason, cells in by_reason.items():
+        rows.append(f"- Why unjudged: {reason}")
+        for start in range(0, len(cells), _IDS_PER_LINE):
+            chunk = cells[start:start + _IDS_PER_LINE]
+            rows.append("  - " + ", ".join(f"`{cell}`" for cell in chunk))
+    return "\n".join(rows) + "\n"
+
+
+UNVERDICTED_SOURCE = "census-unverdicted"
+
+
+@dataclass(frozen=True)
+class CensusState:
+    """A finished run's census audit as the report and the validator see it.
+
+    ``audit`` is ``None`` when the census exists but its audit cannot be read;
+    ``problem`` then says why.
+    """
+
+    audit: Mapping[str, Any] | None
+    problem: str
+
+
+def read_census_state(
+    project_root: Path, manifest: Mapping[str, Any],
+) -> CensusState | None:
+    """``None`` when this run has no census at all."""
+    paths = census_state_paths(project_root, manifest)
+    if paths is None or not paths[0].is_file():
+        return None
+    audit_path = paths[1]
+    if not audit_path.is_file():
+        return CensusState(None, f"the census audit was not run ({audit_path.name} is missing)")
+    try:
+        audit = load_owned_object(audit_path, artifact="coverage census audit")
+    except JsonBoundaryError as exc:
+        return CensusState(None, f"the census audit is unreadable ({exc})")
+    return CensusState(audit, "")
+
+
+def _unverdicted_by_worker(audit: Mapping[str, Any]) -> dict[str, list[str]]:
+    return {
+        str(row.get("workerId")): [str(cell) for cell in row.get(UNVERDICTED) or []]
+        for row in audit.get("workers") or []
+        if isinstance(row, Mapping)
+    }
+
+
+def census_warning_rows(state: CensusState, *, ticket_id: str) -> list[dict[str, str]]:
+    """`missingInformation` rows, without ids: the assembler numbers them."""
+    audit = state.audit
+    if audit is None:
+        return []
+    rows: list[dict[str, str]] = []
+    cell_count = audit.get("cellCount")
+    for worker, cells in _unverdicted_by_worker(audit).items():
+        if not cells:
+            continue
+        rows.append({
+            "ticketId": ticket_id,
+            "item": (
+                f"Coverage census: `{worker}` left {len(cells)} of {cell_count} "
+                f"cells without a verdict: {', '.join(cells)}"
+            ),
+            "risk": (
+                "This worker did not judge these cells, so their coverage rests "
+                "on the other analysers' verdicts alone, or on none where every "
+                "analyser missed them."
+            ),
+            "owner": "Okstra lead",
+            "source": UNVERDICTED_SOURCE,
+        })
+    return rows
+
+
+def census_warnings(state: CensusState) -> dict[str, Any]:
+    """The one-line summary the lead reports at completion."""
+    if state.audit is None:
+        return {"auditProblem": state.problem}
+    unverdicted = _unverdicted_by_worker(state.audit)
+    return {
+        "cellCount": state.audit.get("cellCount"),
+        "unverdicted": {worker: len(cells) for worker, cells in unverdicted.items()},
+        "crossCheck": state.audit.get("crossCheck"),
+    }
+
+
+def census_advisories(
+    state: CensusState, missing_information: Sequence[Any],
+) -> list[str]:
+    """`validate-run` failures for the census. `blocking_checks` carries no
+    fragment for any of them, so every one stays advisory."""
+    if state.audit is None:
+        return [f"coverage census: {state.problem}; no cell verdicts were recorded"]
+    advisories: list[str] = []
+    unverdicted = {
+        worker: cells for worker, cells in _unverdicted_by_worker(state.audit).items()
+        if cells
+    }
+    for worker, cells in unverdicted.items():
+        advisories.append(
+            f"coverage census: `{worker}` left {len(cells)} cell(s) unverdicted: "
+            f"{', '.join(cells)}"
+        )
+    rows = [
+        row for row in missing_information
+        if isinstance(row, Mapping) and row.get("source") == UNVERDICTED_SOURCE
+    ]
+    if len(rows) != len(unverdicted):
+        advisories.append(
+            f"coverage census: the audit has {len(unverdicted)} worker(s) with "
+            f"unverdicted cells but the report carries {len(rows)} "
+            f"`{UNVERDICTED_SOURCE}` row(s)"
+        )
+    return advisories

package/runtime/python/okstra_ctl/design_surfaces.py

@@ -319,6 +319,10 @@ def _stages_for_selected_path(
     seen: set[int] = set()
     for part in declared:
         hits = _stages_touching_path(part, stages)
+        if not hits and "qa/scripts/" in part:
+            # 적합성 스크립트는 executor 가 역할 권한으로 쓴다(write_policy
+            # `_role_qa_artifact_paths`). 계획 step 의 files 칸에는 원래 없다.
+            continue
         if not hits:
             raise DesignSurfaceError(
                 f"selected option path {part!r} is not mapped to a stage"

package/runtime/python/okstra_ctl/direct_work.py

@@ -36,7 +36,7 @@ def find_brief_tasks(project_root: Path, token: str, task_group: str) -> list[di
             group = frontmatter.get("task-group") or folder.name
             if slugify_task_segment(group) != folder.name:
                 raise ValueError(f"Brief task-group does not match its directory: {brief['brief']}")
-            task_id = slugify_task_segment(brief["brief_id"])
+            task_id = brief["task_id"]
             root = task_dir(project_root, slugify_task_segment(group), task_id)
             matches.append({
                 "_briefVerified": True,

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -221,18 +221,22 @@ def verify_served_model(
     pool: ModelPool,
 ) -> ServedModelAttestation:
     """Reject observed substitution while preserving unobservable attempts."""
+    return verify_served_model_ref(role_execution.model_ref, attestation, pool=pool)
+
+
+def verify_served_model_ref(model_ref: str | None, attestation: ServedModelAttestation, *, pool: ModelPool) -> ServedModelAttestation:
     if attestation.level == "unknown":
         return attestation
-    if role_execution.model_ref is None or not attestation.normalized_model_ref:
+    if model_ref is None or not attestation.normalized_model_ref:
         raise DispatchError("served model differs from selected model")
     # An unregistered ref and a genuine substitution are different failures.
     # Folding both into "differs from selected" hid which one happened, and a
     # catalog gap reads as a provider swapping the model out from under us.
     try:
-        selected = pool.resolve(role_execution.model_ref)
+        selected = pool.resolve(model_ref)
     except ValueError as exc:
         raise DispatchError(
-            f"selected model is not in the catalog: {role_execution.model_ref}"
+            f"selected model is not in the catalog: {model_ref}"
         ) from exc
     try:
         observed = pool.resolve(attestation.normalized_model_ref)

package/runtime/python/okstra_ctl/doctor.py

@@ -13,9 +13,9 @@ from okstra_project.resolver import resolve_review_rule_packs
 
 from . import worktree_registry
 from .phases.improvement_discovery import lenses as improvement_lenses
-from .models import provider_wrappers
+from .models import provider_ids, provider_wrappers
 from .phases.catalog import PhaseAssetError, UnknownTaskType, profile_markdown
-from .workers import resolve_profile_workers
+from .role_requirements import RoleProfileError, load_role_profile
 from .worktree import is_git_work_tree, main_worktree_path
 from .json_boundary import JsonBoundaryError, load_owned_object
 
@@ -317,11 +317,17 @@ def _worker_dispatch_checks(
     host_runtime: str,
 ) -> list[DoctorCheck]:
     try:
-        workers = resolve_profile_workers(_profile_path(workspace, phase))
-    except PhaseAssetError as exc:
+        profile = load_role_profile(_profile_path(workspace, phase))
+    except (PhaseAssetError, RoleProfileError) as exc:
         return [_fail("worker dispatch", str(exc))]
-    if not workers:
-        return [_ok("worker dispatch", "no workers required")]
+    roles = {requirement.role for requirement in profile.roles}
+    if not roles:
+        return [_ok("worker dispatch", "profile declares no worker roles")]
+    # The user picks the providers when the run starts, so every provider that
+    # can fill an analysis role must be dispatchable.
+    workers = list(provider_ids("analyser"))
+    if "report-writer" in roles:
+        workers.append("report-writer")
     if not host_runtime:
         return [_fail("worker dispatch", "resolved host runtime is required")]
 

package/runtime/python/okstra_ctl/domain/role.py

@@ -58,6 +58,7 @@ DUTY_ROLE_IDS = {
     "reverification-worker": "verifier",
     "code-reviewer": "verifier",
     "schedule-verifier": "verifier",
+    "business-flow-investigator": "analyser",
     "report-writer": "report-writer",
     "translator": "translator",
 }