okstra 0.178.0 → 0.179.0

package/runtime/python/okstra_ctl/adapters/providers/grok/adapter.py

@@ -1,5 +1,9 @@
 """Bundled Grok provider catalog."""
+import json
+from pathlib import Path
 from typing import Any, Mapping
+from urllib.parse import quote
+
 from okstra_ctl.domain.provider import (
     LeadLaunchSpec,
     ModelSpec,
@@ -8,12 +12,11 @@ from okstra_ctl.domain.provider import (
 )
 from okstra_ctl.domain.role import ALL_ROLE_TOKENS
 from okstra_ctl.domain.worker_exec import (
-    STREAM_JSON,
     ExecCommand,
     PolicySupport,
     WorkerExecRequest,
 )
-from okstra_ctl.domain.worker_stream import content_block_events
+from okstra_ctl.domain.worker_presentation import MergedText
 
 
 GROK = {
@@ -23,23 +26,86 @@ GROK = {
 }
 
 
+def _catalog_model_id(observed: str) -> str:
+    """Undo the `-build` suffix grok reports its served model under.
+
+    Measured on grok 1.x: asking for `grok-4.6` closes with
+    `modelUsage: {"grok-4.6-build": ...}`, and `grok-4.5` with
+    `grok-4.5-build`. The catalog holds the requested ids, so reading the
+    reported one as-is would fail the served-model gate on the very model
+    okstra asked for. A catalog entry that already carries the suffix
+    (`grok-build-0.1`) is matched first and left alone.
+    """
+    if observed in GROK:
+        return observed
+    bare = observed.removesuffix("-build")
+    return bare if bare != observed and bare in GROK else observed
+
+
 def normalise_served_model(raw_model: str | None) -> ServedModelAttestation:
     if not raw_model or not raw_model.strip():
         return ServedModelAttestation.unknown()
     model_id = raw_model.strip().lower().removeprefix("grok/")
     return ServedModelAttestation(
-        raw_model, f"grok/{model_id}", "exact", "provider-output"
+        raw_model,
+        f"grok/{_catalog_model_id(model_id)}",
+        "exact",
+        "provider-output",
     )
 
 
+def served_model_from_session(
+    session_id: str, cwd: Path, *, home: Path | None = None
+) -> str | None:
+    """세션 기록에서 실제로 서빙된 모델을 읽는다.
+
+    grok 은 일하는 동안 어느 이벤트에도 모델을 적지 않고, 닫는 기록에만
+    남긴다. 스트림을 해석하지 않는 경로에서는 여기가 유일한 관측 지점이다.
+    디렉터리 이름은 cwd 를 퍼센트 인코딩한 것이다.
+    """
+    root = (home or Path.home() / ".grok") / "sessions"
+    encoded = quote(str(cwd), safe="")
+    history = root / encoded / session_id / "chat_history.jsonl"
+    if not history.is_file():
+        return None
+    try:
+        for line in history.read_text(encoding="utf-8", errors="replace").splitlines():
+            if not line.strip():
+                continue
+            record = json.loads(line)
+            model = record.get("model_id") if isinstance(record, Mapping) else None
+            if isinstance(model, str) and model.strip():
+                return model
+    except (OSError, ValueError):
+        return None
+    return None
+
+
 def observe_served_model(event: Mapping[str, Any]) -> str | None:
+    """Read the model grok actually served from its closing `end` event.
+
+    grok names no model on the events it streams as it works; the only place
+    it states one is `end.modelUsage`, keyed by model. Looking for a top-level
+    `model` field — Claude's shape — found nothing on every event, so the run
+    recorded `servedModelAttestation: unknown` and the served-model gate had
+    nothing to check.
+    """
     model = event.get("model")
     if isinstance(model, str) and model.strip():
         return model
     message = event.get("message")
     if isinstance(message, Mapping):
         model = message.get("model")
-        return model if isinstance(model, str) and model.strip() else None
+        if isinstance(model, str) and model.strip():
+            return model
+    if event.get("type") == "end":
+        usage = event.get("modelUsage")
+        if isinstance(usage, Mapping):
+            names = [name for name in usage if isinstance(name, str) and name.strip()]
+            # More than one model in a single turn means the CLI switched
+            # mid-run; naming either one would be a guess, so report neither.
+            if len(names) == 1:
+                return names[0]
     return None
 
 GROK_LEAD_LAUNCH = LeadLaunchSpec(
@@ -66,16 +132,12 @@ class GrokExecution:
                 request.prompt_text,
                 "-m",
                 request.model,
-                "--output-format",
-                "streaming-json",
                 "--cwd",
                 str(cwd),
             ),
             stdin_text=None,
-            stream_format=STREAM_JSON,
-            normalise=content_block_events,
-            observe_served_model=observe_served_model,
             cwd=cwd,
+            presentation=MergedText(served_model_at_exit=served_model_from_session),
         )
 
     def policy_support(self) -> PolicySupport:

package/runtime/python/okstra_ctl/adapters/providers/kimi/adapter.py

@@ -8,11 +8,11 @@ from okstra_ctl.domain.provider import (
 )
 from okstra_ctl.domain.role import ALL_ROLE_TOKENS
 from okstra_ctl.domain.worker_exec import (
-    STREAM_JSON,
     ExecCommand,
     PolicySupport,
     WorkerExecRequest,
 )
+from okstra_ctl.domain.worker_presentation import JsonEvents
 from okstra_ctl.domain.worker_stream import content_block_events
 
 
@@ -72,10 +72,11 @@ class KimiExecution:
                 "stream-json",
             ),
             stdin_text=None,
-            stream_format=STREAM_JSON,
-            normalise=content_block_events,
-            observe_served_model=observe_served_model,
             cwd=cwd,
+            presentation=JsonEvents(
+                normalise=content_block_events,
+                observe=observe_served_model,
+            ),
         )
 
     def policy_support(self) -> PolicySupport:

package/runtime/python/okstra_ctl/agent_prompt_cli.py

@@ -43,7 +43,11 @@ from .assignment_resolver import AssignmentContext, resolve_dispatch_assignment
 from .path_hints import hydrate_active_run_context
 from .worker_prompt_headers import WorkerPromptHeaderError, worker_prompt_headers
 from .worker_artifact_paths import audit_sidecar_rel
-from .wrapper_status import log_path_for_prompt, status_path_for_prompt
+from .wrapper_status import (
+    log_path_for_prompt,
+    prompt_derived_paths,
+    status_path_for_prompt,
+)
 from .worker_prompt_policy import resolve_prompt_plan_for_manifest
 from .dispatch_state import (
     BACKEND_CLI_WRAPPER,
@@ -489,8 +493,7 @@ def _dynamic_verifier_artifact_paths(
         result_path,
         audit_source_path,
         project_root / audit_sidecar_rel(audit_rel),
-        status_path_for_prompt(prompt_path),
-        log_path_for_prompt(prompt_path),
+        *prompt_derived_paths(prompt_path),
     }
     error_logs = active_context.get("errorLogs")
     sidecars = error_logs.get("sidecarsByWorkerId") if isinstance(error_logs, Mapping) else None
@@ -628,12 +631,61 @@ def _validate_run_identity(
             ).duty_audience
         except ValueError as exc:
             raise AgentPromptCliError(str(exc)) from exc
+        if audience != expected and _manifest_issued_role_execution(
+            manifest, audience=audience, assignment_ref=assignment_ref
+        ):
+            # The prompt plan names a worker's role by worker id, so on an
+            # implementation run the executor's provider resolves to the
+            # executor role no matter which role execution is being targeted.
+            # But the manifest issues one role execution per role, and a
+            # provider serving as both executor and verifier gets two — a
+            # normal roster, since the verifier contract accepts reusing the
+            # executor's model behind its own session. Refusing the second
+            # audience made a role execution okstra had itself issued
+            # undispatchable, which costs the run an independent verifier.
+            expected = audience
     if audience != expected:
         raise AgentPromptCliError(
             f"audience {audience!r} does not match required audience {expected!r}"
         )
 
 
+def _manifest_issued_role_execution(
+    manifest: Mapping[str, Any],
+    *,
+    audience: str,
+    assignment_ref: str,
+) -> bool:
+    """Whether this run issued a role execution for that audience's role.
+
+    Keyed on the manifest's own rows, not on what the prompt plan infers from
+    a worker id: the question is whether okstra created the execution being
+    targeted, and only the manifest answers that.
+    """
+    from .domain.role import RoleCatalogError, role_for_duty
+
+    try:
+        role = role_for_duty(audience)
+    except RoleCatalogError:
+        return False
+    assignments = manifest.get("invocationAssignments")
+    assignment = (
+        assignments.get(assignment_ref) if isinstance(assignments, Mapping) else None
+    )
+    provider = (
+        assignment.get("provider") if isinstance(assignment, Mapping) else None
+    )
+    if not provider:
+        return False
+    executions = manifest.get("roleExecutions")
+    return any(
+        isinstance(row, Mapping)
+        and row.get("role") == role
+        and row.get("provider") == provider
+        for row in (executions if isinstance(executions, list) else [])
+    )
+
+
 def _materialize_standalone(
     args: argparse.Namespace,
     project_root: Path,

package/runtime/python/okstra_ctl/analysis_inputs.py

@@ -69,7 +69,9 @@ _EVIDENCE_RELATION_BY_TYPES = {
     ("change-impact-analysis", "project-analysis"): "project-context",
     ("change-impact-analysis", "feature-analysis"): "feature-baseline",
 }
-_REPORT_NAME_RE = re.compile(r"^final-report-.+-(?P<run_seq>[^-]+)\.md$")
+_REPORT_NAME_RE = re.compile(
+    r"^final-report-.+-(?P<run_seq>[^-]+)\.data\.json$"
+)
 _FEATURE_ID_RE = re.compile(r"PF-\d{3}")
 _FULL_COMMIT_RE = re.compile(r"[0-9a-f]{40}")
 _RUN_SEQ_RE = re.compile(r"[0-9]{3}")
@@ -242,7 +244,7 @@ def load_analysis_report_candidate(
         raise AnalysisInputError("data.json header.taskKey does not match task manifest")
     if task_type != path_task_type:
         raise AnalysisInputError("data.json header.taskType does not match report path")
-    if filename != f"final-report-{task_type}-{run_seq}.md":
+    if filename != f"final-report-{task_type}-{run_seq}.data.json":
         raise AnalysisInputError("data.json analysisCommon.runSeq does not match report filename")
     feature_index: Sequence[object] = ()
     if task_type == "project-analysis":
@@ -289,7 +291,7 @@ def list_evidence_candidates(
         return []
     reports_root = root / ".okstra" / "tasks"
     candidates: list[AnalysisReportCandidate] = []
-    for report in reports_root.glob("*/*/runs/*/reports/*.md"):
+    for report in reports_root.glob("*/*/runs/*/reports/*.data.json"):
         try:
             candidate = load_analysis_report_candidate(root, report)
         except AnalysisInputError:

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -100,6 +100,7 @@ def build_analysis_packet(
     directive: str,
     instruction_set_relative_path: str,
     fix_history_text: str = "",
+    stage_ledger_json: str = "",
 ) -> str:
     """Return the primary compact input for Claude/Codex/Antigravity analysers."""
     brief_text = task_brief_path.read_text(encoding="utf-8")
@@ -122,6 +123,7 @@ def build_analysis_packet(
     parts.extend(_profile_block(task_type, profile_text))
     parts.extend(_reference_block(reference_text))
     parts.extend(_fix_history_block(fix_history_text))
+    parts.extend(_stage_ledger_block(stage_ledger_json))
     parts.extend(_clarification_block(clarification_text))
     parts.extend(_directive_block(directive))
     return "\n".join(part.rstrip() for part in parts).rstrip() + "\n"
@@ -229,6 +231,25 @@ def _fix_history_block(fix_history_text: str) -> list[str]:
     ]
 
 
+def _stage_ledger_block(stage_ledger_json: str) -> list[str]:
+    if not stage_ledger_json.strip():
+        return []
+    return [
+        "",
+        "## Stage Ledger",
+        "",
+        "Facts about this task's stages as they stand on disk — not a plan.",
+        "A stage whose `status` is `done` is already implemented and will not",
+        "be executed again, so do not rewrite its plan body. Stage numbers",
+        "already listed here are taken; never reuse or renumber them.",
+        "",
+        "```json",
+        stage_ledger_json.strip(),
+        "```",
+        "",
+    ]
+
+
 def _clarification_block(clarification_text: str) -> list[str]:
     if not clarification_text.strip():
         return []

package/runtime/python/okstra_ctl/backfill.py

@@ -162,13 +162,20 @@ def backfill_project(home: Path, project_id: str, project_root: Path) -> int:
                         continue
                     # 실제 okstra.sh 가 쓰는 manifest 키:
                     #   - runDirectoryPath (디렉터리)
-                    #   - expectedReportPath (보고서, 호환: reportPath)
+                    #   - expectedReportRecordPath (보고서, 호환: reportPath)
                     #   - validation: { status, passed, ... } 중첩 dict
                     run_dir_rel = (manifest.get("runDirectoryPath")
                                    or manifest.get("runDirPath", ""))
-                    final_rel = (manifest.get("expectedReportPath")
-                                 or manifest.get("reportPath")
-                                 or manifest.get("finalReportPath", ""))
+                    from .final_report_paths import report_record_rel_from_legacy_pointer
+
+                    final_rel = report_record_rel_from_legacy_pointer(
+                        manifest.get("expectedReportRecordPath")
+                        or manifest.get("expectedReportPath")
+                        or manifest.get("reportPath")
+                        or manifest.get("finalReportRecordPath")
+                        or manifest.get("finalReportPath")
+                        or ""
+                    )
                     # status 파일 경로는 RUN_STATUS_SEQ 기반이라 manifest seq
                     # 와 어긋날 수 있다. tail 이 정확한 파일을 추적하도록
                     # 매니페스트가 기록한 expectedStatusPath /
@@ -223,7 +230,7 @@ def backfill_project(home: Path, project_id: str, project_root: Path) -> int:
                         finished_at=None if is_non_terminal else finished_at,
                         workers=raw_workers, lead_model=raw_lead_model,
                         validation=validation_status, run_dir_rel=run_dir_rel,
-                        final_report_rel=final_rel,
+                        final_report_record_rel=final_rel,
                         final_status_rel=final_status_rel)
                     if is_non_terminal:
                         append_jsonl(home / "active.jsonl", row)

package/runtime/python/okstra_ctl/consumers.py

@@ -10,6 +10,8 @@ from __future__ import annotations
 
 import json
 import re
+import subprocess
+import sys
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Dict, List, Optional
@@ -68,13 +70,25 @@ def read_consumers(plan_run_root: Path) -> List[Dict[str, Any]]:
 
 
 def latest_done_by_stage(rows: List[Dict[str, Any]]) -> Dict[int, Dict[str, Any]]:
-    """stage → 마지막 done row. 보정(reconciled) row 가 같은 stage 에
-    재-append 되므로 done 읽기의 유일한 의미는 last-wins 다."""
+    """stage → 마지막 done row. 리드가 `failed` 로 철회한 stage 는 제외한다.
+
+    보정(reconciled) row 가 같은 stage 에 재-append 되므로 done 들 사이에서는
+    last-wins 다. done 행만 훑던 동안은 뒤에 붙은 `failed` 가 아무 효과가 없어
+    한 번 done 이 기록된 stage 를 되열 수단이 없었다 — `--stage N` 은 계속
+    거부되고, 되돌리기가 필요해진 stage 를 okstra 밖에서 처리한 뒤 원장을 손으로
+    맞춰야 했다. 그 보정을 놓치면 다음 stage 가 되돌리기 이전 트리에서 갈라진다.
+
+    `started` 는 여기서 stage 를 내리지 않는다. fix run 이 done 인 stage 에
+    `started` 를 다시 기록하는 것은 정상 흐름이고(`_equivalent_row_exists`),
+    그동안 의존 stage 는 종전대로 마지막 done head 에서 base 를 잡는다.
+    철회는 리드의 명시적 판정인 `failed` 하나로만 일어난다.
+    """
+    last = last_lifecycle_status_by_stage(rows)
     out: Dict[int, Dict[str, Any]] = {}
     for r in rows:
         if r.get("status") == "done" and isinstance(r.get("stage"), int):
             out[r["stage"]] = r
-    return out
+    return {stage: row for stage, row in out.items() if last.get(stage) != "failed"}
 
 
 def read_stage_consumer_state(
@@ -132,6 +146,8 @@ def append_consumer(plan_run_root: Path, *, impl_task_key: str, stage: int,
                 **fields,
             }
             _append_row(plan_run_root, record)
+    if status == "done":
+        _tag_stage_exit(plan_run_root, stage, fields.get("head_commit"))
     # 종결 status 는 점유 해제 이벤트이기도 하다 — 중복 append(no-op)에서도 풀어야
     # release 없이 done 만 기록된 과거 run 의 잔존 점유가 다음 호출에서 치유된다.
     if status == "done":
@@ -140,6 +156,57 @@ def append_consumer(plan_run_root: Path, *, impl_task_key: str, stage: int,
         _release_stage_occupancy_keeping_branch(impl_task_key, stage)
 
 
+STAGE_EXIT_TAG = "stage-{stage}-exit"
+
+
+def _repo_root(start: Path) -> Optional[Path]:
+    for candidate in [start, *start.parents]:
+        if (candidate / ".git").exists():
+            return candidate
+    return None
+
+
+def _tag_stage_exit(plan_run_root: Path, stage: int, head_commit: Any) -> None:
+    """Move `stage-<N>-exit` to the commit this ledger row records.
+
+    The tag used to be a plan step, so it was written while the stage was still
+    running — before the carry evidence the ledger reads. A stage then had three
+    exit points that could disagree: the tag, the recorded `head_commit`, and
+    the branch tip. okstra writes the tag at the moment it settles the stage, so
+    the tag and the ledger cannot drift apart.
+
+    Best effort by design: the ledger is the record and a tag is a convenience
+    for the reader. A tree that is not a git repository, or a commit git cannot
+    resolve, leaves the row written and says so on stderr.
+    """
+    if not isinstance(head_commit, str) or not head_commit.strip():
+        return
+    root = _repo_root(Path(plan_run_root).resolve())
+    if root is None:
+        return
+    commit = head_commit.strip()
+    tag = STAGE_EXIT_TAG.format(stage=stage)
+    try:
+        exists = subprocess.run(
+            ["git", "-C", str(root), "cat-file", "-e", f"{commit}^{{commit}}"],
+            capture_output=True,
+        )
+        if exists.returncode != 0:
+            print(
+                f"okstra: stage {stage} done recorded, but {commit[:12]} is not "
+                f"a commit in {root} — `{tag}` not moved",
+                file=sys.stderr,
+            )
+            return
+        subprocess.run(
+            ["git", "-C", str(root), "tag", "-f", tag, commit],
+            capture_output=True,
+            check=True,
+        )
+    except (OSError, subprocess.CalledProcessError) as exc:
+        print(f"okstra: could not move `{tag}` to {commit[:12]}: {exc}", file=sys.stderr)
+
+
 def _equivalent_row_exists(plan_run_root: Path, impl_task_key: str, stage: int,
                            status: str, force_reappend: bool,
                            head_commit: Any) -> bool:

package/runtime/python/okstra_ctl/convergence_engine.py

@@ -13,7 +13,12 @@ WORKING_SCHEMA_VERSION = "1.0"
 V2_WORKING_SCHEMA_VERSION = "2.0"
 EXECUTION_IDENTITY_VERSION = 2
 FINAL_SCHEMA_VERSION = "1.3"
-_AUDIENCES = {"analysis", "report-writer"}
+_AUDIENCES = {"analysis", "lead", "report-writer"}
+# 발견을 낼 수 있는 audience. 리드는 계약상 Phase 6 자체 리뷰를 수행하므로
+# 출처가 될 수 있지만, 교차검증 표는 아니다 — 합의 수는 아래에서 분석 워커만
+# 센다. 리드를 분석 워커로 위장 선언하는 것을 계약이 금지하는 이상, 리드의
+# 발견을 담을 자리가 없으면 그 리뷰 결과는 어디에도 못 간다.
+_FINDING_SOURCE_AUDIENCES = {"analysis", "lead"}
 _AUDIENCE_SOURCE_ROLES = {
     "analysis": frozenset({"analyser", "designer", "planner", "verifier"}),
     "report-writer": frozenset({"report-writer"}),
@@ -79,6 +84,11 @@ def seed_working_state(
     analysis_workers = [
         worker["workerId"] for worker in workers if worker["audience"] == "analysis"
     ]
+    finding_sources = [
+        worker["workerId"]
+        for worker in workers
+        if worker["audience"] in _FINDING_SOURCE_AUDIENCES
+    ]
     state = {
         "schemaVersion": source["schemaVersion"],
         "taskKey": task_key,
@@ -104,7 +114,10 @@ def seed_working_state(
         return state
 
     findings, queue = _parse_groups(
-        source.get("groups"), analysis_workers, adversarial=config["adversarial"]
+        source.get("groups"),
+        analysis_workers,
+        finding_sources,
+        adversarial=config["adversarial"],
     )
     state["findings"] = findings
     state["queueFindingIds"] = queue
@@ -602,7 +615,8 @@ def validate_working_state(state: Mapping[str, Any]) -> list[str]:
                 errors.append(
                     f"workers[{index}].audience is unsupported: {audience!r}. "
                     "Finding-producing workers (implementation verifiers included) "
-                    "use 'analysis'; only the report author uses 'report-writer'. "
+                    "use 'analysis'; the okstra lead's own review uses 'lead'; "
+                    "only the report author uses 'report-writer'. "
                     f"Allowed: {sorted(_AUDIENCES)}."
                 )
             participant_ref = worker.get("participantRef")
@@ -2042,8 +2056,9 @@ def _parse_workers(value: Any, identity_version: int) -> list[dict[str, str]]:
                 f"workers[{index}] has unsupported audience: {audience}. "
                 "Convergence audience is a functional role, not a phase label: "
                 "every finding-producing worker uses 'analysis' (an "
-                "implementation run's verifiers included), and only the report "
-                f"author uses 'report-writer'. Allowed: {sorted(_AUDIENCES)}."
+                "implementation run's verifiers included), the okstra lead's own "
+                "review uses 'lead', and only the report author uses "
+                f"'report-writer'. Allowed: {sorted(_AUDIENCES)}."
             )
         if worker_id in seen:
             raise ConvergenceContractError(f"duplicate workerId: {worker_id}")
@@ -2125,6 +2140,7 @@ def _validate_worker_execution_identity(
 def _parse_groups(
     value: Any,
     analysis_workers: list[str],
+    finding_sources: list[str],
     *,
     adversarial: bool,
 ) -> tuple[list[dict[str, Any]], list[str]]:
@@ -2139,7 +2155,9 @@ def _parse_groups(
         if finding_id in seen_ids:
             raise ConvergenceContractError(f"duplicate findingId: {finding_id}")
         seen_ids.add(finding_id)
-        finding, source_workers = _parse_group(group, index, analysis_workers)
+        finding, source_workers = _parse_group(
+            group, index, analysis_workers, finding_sources
+        )
         if len(source_workers) >= 2 and not adversarial:
             finding["classification"] = "full-consensus"
         else:
@@ -2152,23 +2170,30 @@ def _parse_group(
     group: Mapping[str, Any],
     index: int,
     analysis_workers: list[str],
+    finding_sources: list[str],
 ) -> tuple[dict[str, Any], list[str]]:
+    """그룹 하나를 읽는다. 출처는 발견을 낼 수 있는 모두, 합의는 분석 워커만.
+
+    두 목록을 따로 받는 이유가 이 함수의 전부다. 리드도 발견을 낼 수 있어야
+    하지만 그 발견이 교차검증 표로 세어지면, 독립 검증자 없이 해소된 것처럼
+    보이는 findings 가 생긴다.
+    """
     label = f"groups[{index}]"
     origin = _required_string(group, "originWorker", label)
-    if origin not in analysis_workers:
+    if origin not in finding_sources:
         raise ConvergenceContractError(
-            f"{label}.originWorker is outside the analysis roster: {origin}"
+            f"{label}.originWorker cannot produce findings in this run: {origin}"
         )
     origin_evidence = _required_string(group, "originEvidence", label)
     discovered_by = _parse_discovered_by(
-        group.get("discoveredBy"), label, analysis_workers
+        group.get("discoveredBy"), label, finding_sources
     )
     if origin not in discovered_by:
         raise ConvergenceContractError(
             f"{label}.originWorker must appear in discoveredBy"
         )
     source_items = _parse_source_items(
-        group.get("sourceItems"), label, analysis_workers
+        group.get("sourceItems"), label, finding_sources
     )
     source_workers = [
         worker_id
@@ -2243,14 +2268,15 @@ def _is_normalized_okstra_path(path: str) -> bool:
 def _parse_discovered_by(
     value: Any,
     label: str,
-    analysis_workers: list[str],
+    finding_sources: list[str],
 ) -> dict[str, dict[str, str]]:
     raw = _object(value, f"{label}.discoveredBy")
     parsed: dict[str, dict[str, str]] = {}
     for worker_id, details_value in raw.items():
-        if worker_id not in analysis_workers:
+        if worker_id not in finding_sources:
             raise ConvergenceContractError(
-                f"{label}.discoveredBy contains non-analysis worker: {worker_id}"
+                f"{label}.discoveredBy contains a worker that produces no "
+                f"findings in this run: {worker_id}"
             )
         details = _object(details_value, f"{label}.discoveredBy.{worker_id}")
         parsed[worker_id] = {
@@ -2269,7 +2295,7 @@ def _parse_discovered_by(
 def _parse_source_items(
     value: Any,
     label: str,
-    analysis_workers: list[str],
+    finding_sources: list[str],
 ) -> list[dict[str, str]]:
     if not isinstance(value, list) or not value:
         raise ConvergenceContractError(f"{label}.sourceItems must be a non-empty array")
@@ -2277,10 +2303,10 @@ def _parse_source_items(
     for index, raw in enumerate(value):
         item = _object(raw, f"{label}.sourceItems[{index}]")
         worker = _required_string(item, "worker", f"{label}.sourceItems[{index}]")
-        if worker not in analysis_workers:
+        if worker not in finding_sources:
             raise ConvergenceContractError(
-                f"{label}.sourceItems contains non-analysis worker {worker}; "
-                "report-writer never votes"
+                f"{label}.sourceItems contains {worker}, which produces no "
+                "findings in this run; report-writer never votes"
             )
         items.append(
             {