okstra 0.207.1 → 0.209.0

package/runtime/python/okstra_ctl/convergence.py

@@ -60,6 +60,14 @@ from .convergence_store import (
     write_final_state_atomic,
     write_json_atomic,
 )
+from .coverage_census import (
+    CensusError,
+    audit_census,
+    audit_filename,
+    census_filename,
+    gapfill_prompt_body,
+)
+from .path_resolve import relative_to_project_root
 from .execution_identity import ExecutionManifest
 from .execution_manifest import read_execution_manifest_view
 from .final_report_schema import load_named_schema, validate as validate_schema
@@ -323,6 +331,10 @@ _CLI_EPILOG = r"""Usage:
   okstra convergence reverify-prompt --run-manifest <path> --plan <path> \
     --worker <worker-id>
   okstra convergence apply-critic-gaps --work-state <path> --results <path>
+  okstra convergence census-audit --run-manifest <path> \
+    --result <worker>=<path>... [--gapfill <worker>=<path>...]
+  okstra convergence census-gapfill-prompt --run-manifest <path> \
+    --worker <worker-id>
   okstra convergence apply-acceptance-critic --work-state <path> \
     --results <path>
   okstra convergence finalize --work-state <path> --output <path>
@@ -475,6 +487,51 @@ def _parser() -> argparse.ArgumentParser:
     )
     critic_verify_prompt.add_argument("--worker", required=True)
 
+    census_audit = subparsers.add_parser(
+        "census-audit",
+        help="audit each analyser's coverage-census verdicts",
+        description=(
+            "Read every analysis worker's `Coverage Verdicts` against this run's "
+            "coverage census and write state/coverage-census-audit-<task-type>-"
+            "<seq>.json: per worker the cells still without a usable verdict, "
+            "the cell x worker matrix, the cells one worker judged `finding` and "
+            "another `clean`, and per-cell grouping suggestions. Run it after the "
+            "initial batch, and again with `--gapfill` after the one gap-fill "
+            "dispatch. Cells left unjudged are recorded as warnings; they never "
+            "change the exit code. A run whose profile has no census writes "
+            "nothing and exits 0."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    census_audit.add_argument("--run-manifest", type=Path, required=True)
+    census_audit.add_argument(
+        "--result", action="append", default=[], required=True,
+        metavar="<worker>=<path>",
+        help="one analysis worker's initial result file (repeatable); a path "
+             "that does not exist counts as a missing result",
+    )
+    census_audit.add_argument(
+        "--gapfill", action="append", default=[], metavar="<worker>=<path>",
+        help="that worker's census-gapfill result file (repeatable); a path that "
+             "does not exist records a failed gap-fill",
+    )
+
+    census_gapfill_prompt = subparsers.add_parser(
+        "census-gapfill-prompt",
+        help="render one analyser's census gap-fill instructions to stdout",
+        description=(
+            "Print the census gap-fill instruction body for one analysis worker "
+            "from the latest `census-audit`: only the cells that worker left "
+            "without a usable verdict, grouped by why. The lead writes it "
+            "verbatim to the file the prompt materializer's `--instruction` "
+            "takes, with `--dispatch-kind census-gapfill`. Refused for a worker "
+            "with no unjudged cell or one that already had its single gap-fill."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    census_gapfill_prompt.add_argument("--run-manifest", type=Path, required=True)
+    census_gapfill_prompt.add_argument("--worker", required=True)
+
     apply_critic = subparsers.add_parser(
         "apply-critic-gaps",
         help="apply one coverage-critic verification batch",
@@ -1325,7 +1382,7 @@ def _group_from_fields(
     origin_worker, separator, origin_item = scalar.get("origin", "").partition(":")
     if not separator or discovered.get(origin_worker, {}).get("itemId") != origin_item:
         raise ConvergenceContractError("Origin must identify one Source item")
-    return {
+    group = {
         "findingId": finding_id, "summary": scalar.get("summary", ""),
         "category": scalar.get("category", ""),
         "ticketIds": [item.strip() for item in scalar.get("tickets", "").split(",") if item.strip()],
@@ -1334,6 +1391,10 @@ def _group_from_fields(
         "discoveredBy": discovered,
         "sourceItems": source_items,
     }
+    cells = [cell.strip() for cell in scalar.get("cells", "").split(",") if cell.strip()]
+    if cells:
+        group["cellRefs"] = list(dict.fromkeys(cells))
+    return group
 
 
 def _group_source_provenance(
@@ -1579,6 +1640,7 @@ def _critic_verify_prompt(args: argparse.Namespace) -> str:
     result_path, audit_path = critic_result_paths(
         groups, critic_provider=provider,
         project_root=authority.project_root, run_dir=authority.run_dir,
+        recorded_result=_settled_critic_result(authority.payload),
     )
     return critic_verify_prompt_body(
         task_key=task_key,
@@ -1589,6 +1651,109 @@ def _critic_verify_prompt(args: argparse.Namespace) -> str:
     )
 
 
+def _worker_paths(raw_pairs: list[str], label: str) -> dict[str, Path]:
+    paths: dict[str, Path] = {}
+    for raw in raw_pairs:
+        worker, value = _split_pair(raw, label)
+        if worker in paths:
+            raise ConvergenceContractError(f"{label} names `{worker}` twice")
+        paths[worker] = Path(value)
+    return paths
+
+
+def _read_if_present(path: Path) -> str | None:
+    return path.read_text(encoding="utf-8") if path.is_file() else None
+
+
+def _census_audit(args: argparse.Namespace) -> dict[str, Any]:
+    """Audit the census verdicts. Unjudged cells are data, never an error."""
+    authority = validated_run_authority(args.run_manifest)
+    state_dir = authority.run_dir / "state"
+    census_path = state_dir / census_filename(
+        authority.task_type, authority.state_sequence
+    )
+    summary: dict[str, Any] = {"ok": True, "operation": "census-audit"}
+    if not census_path.is_file():
+        return {**summary, "census": "absent"}
+    census = load_owned_json_object(census_path)
+    result_paths = _worker_paths(args.result, "--result")
+    gapfill_paths = _worker_paths(args.gapfill, "--gapfill")
+    unrostered = sorted(set(gapfill_paths) - set(result_paths))
+    if unrostered:
+        raise ConvergenceContractError(
+            f"--gapfill names {unrostered}, which no --result names"
+        )
+    audit = audit_census(
+        census,
+        {worker: _read_if_present(path) for worker, path in result_paths.items()},
+        {worker: _read_if_present(path) for worker, path in gapfill_paths.items()},
+    )
+    for row in audit["workers"]:
+        row["resultPath"] = relative_to_project_root(
+            result_paths[row["workerId"]], authority.project_root
+        )
+        if row["workerId"] in gapfill_paths:
+            row["gapfillPath"] = relative_to_project_root(
+                gapfill_paths[row["workerId"]], authority.project_root
+            )
+    output = state_dir / audit_filename(authority.task_type, authority.state_sequence)
+    write_json_atomic(output, audit)
+    return {
+        **summary,
+        "census": "present",
+        "path": str(output),
+        "crossCheck": audit["crossCheck"],
+        "gapfillNeeded": audit["gapfillNeeded"],
+        "unverdicted": {
+            row["workerId"]: len(row["unverdicted"]) for row in audit["workers"]
+        },
+        "disagreements": len(audit["disagreements"]),
+    }
+
+
+def _census_gapfill_prompt(args: argparse.Namespace) -> str:
+    authority = validated_run_authority(args.run_manifest)
+    state_dir = authority.run_dir / "state"
+    audit_path = state_dir / audit_filename(authority.task_type, authority.state_sequence)
+    if not audit_path.is_file():
+        raise ConvergenceContractError(
+            "the gap-fill prompt reads the census audit; run "
+            f"`okstra convergence census-audit` first: {audit_path}"
+        )
+    census_path = state_dir / census_filename(authority.task_type, authority.state_sequence)
+    return gapfill_prompt_body(
+        load_owned_json_object(audit_path),
+        args.worker,
+        task_key=authority.task_key,
+        analysis_packet_path=_manifest_authority_string(
+            authority.payload, "analysisPacketPath"
+        ),
+        census_path=relative_to_project_root(census_path, authority.project_root),
+    )
+
+
+def _settled_critic_result(manifest: Mapping[str, Any]) -> str:
+    """critic dispatch 의 가장 최근 `ok` attempt 가 기록한 resultPath. 없으면 ''."""
+    invocations = manifest.get("invocations")
+    attempts = manifest.get("attempts")
+    if not isinstance(invocations, list) or not isinstance(attempts, list):
+        return ""
+    critic_refs = {
+        row.get("invocationRef") for row in invocations
+        if isinstance(row, Mapping) and row.get("dispatchKind") == "critic"
+    }
+    settled = [
+        row for row in attempts
+        if isinstance(row, Mapping) and row.get("invocationRef") in critic_refs
+        and row.get("status") == "ok"
+        and isinstance(row.get("resultPath"), str) and row["resultPath"]
+    ]
+    if not settled:
+        return ""
+    latest = max(settled, key=lambda row: (str(row.get("finishedAt") or ""), row.get("attempt") or 0))
+    return latest["resultPath"]
+
+
 def _execute(args: argparse.Namespace) -> tuple[str, Path]:
     operations: dict[str, Any] = {
         "prepare-groups": _prepare_groups,
@@ -1626,9 +1791,15 @@ def main(argv: list[str] | None = None) -> int:
         if args.operation == "critic-verify-prompt":
             print(_critic_verify_prompt(args), end="")
             return 0
+        if args.operation == "census-audit":
+            print(json.dumps(_census_audit(args), ensure_ascii=False))
+            return 0
+        if args.operation == "census-gapfill-prompt":
+            print(_census_gapfill_prompt(args), end="")
+            return 0
         action, path = _execute(args)
     except (ConvergenceContractError, VerdictBlockError, ReverifyPromptError,
-            CriticVerifyPromptError,
+            CriticVerifyPromptError, CensusError,
             json.JSONDecodeError, ValueError) as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 2

package/runtime/python/okstra_ctl/convergence_critic_verify_prompt.py

@@ -77,6 +77,7 @@ def critic_result_paths(
     critic_provider: str,
     project_root: Path,
     run_dir: Path,
+    recorded_result: str = "",
 ) -> tuple[str, str]:
     """critic 결과 파일과 그 감사 사이드카의 프로젝트 상대 경로.
 
@@ -85,7 +86,24 @@ def critic_result_paths(
     §"Coverage critic pass"). 접미사는 분석자 결과와 같은 규칙으로 그룹의
     `runManifestPath` 에서 읽는다. 파일이 없으면 critic 결과가 아직 수집되지
     않은 것이라 거절한다 — gap 검증은 critic 결과 뒤에만 온다.
+
+    `recorded_result` 는 매니페스트 attempt 원장이 critic 의 마지막 `ok` attempt
+    에 적은 경로다. 있으면 이름 규칙보다 먼저 쓴다 — 리드가 run seq 로 이름을
+    붙여도(실측 2026-10-03, fontsninja-v3-site dev-11118 requirements-discovery
+    002: prompts 002, workerResults 001) 실제로 수집된 파일을 가리킨다.
     """
+    if recorded_result:
+        recorded = Path(recorded_result)
+        result = recorded if recorded.is_absolute() else Path(project_root) / recorded
+        if not result.is_file():
+            raise CriticVerifyPromptError(
+                f"the critic attempt recorded {result} but the file is missing"
+            )
+        result_rel = _project_relative(project_root, result)
+        try:
+            return result_rel, audit_sidecar_rel(result_rel)
+        except WorkerArtifactPathError as exc:
+            raise CriticVerifyPromptError(str(exc)) from exc
     if not _nonempty_string(critic_provider):
         raise CriticVerifyPromptError("run manifest has no critic assignment provider")
     suffix = worker_result_suffix(Path(run_dir), groups)

package/runtime/python/okstra_ctl/convergence_provenance.py

@@ -26,6 +26,7 @@ from okstra_ctl.execution_manifest import read_execution_manifest_view
 from okstra_ctl.json_boundary import (
     load_owned_object,
 )
+from okstra_ctl.worker_prompt_policy import CENSUS_GAPFILL_DISPATCH_KIND
 
 GROUPS_BASENAME_RE = re.compile(
     r"^convergence-groups-(?P<suffix>[a-z][a-z-]*?-\d{3})\.json$"
@@ -223,6 +224,13 @@ def provenance_errors(
         text = contents[worker]
         if text is None or id_occurs_wordbounded(text, item_id):
             continue
+        gapfill = read_canonical_worker_result(
+            worker_results_dir, worker, f"{CENSUS_GAPFILL_DISPATCH_KIND}-{suffix}"
+        )
+        # A finding the census gap-fill raised lives in that worker's gap-fill
+        # result, not in its first one.
+        if gapfill is not None and id_occurs_wordbounded(gapfill, item_id):
+            continue
         errors.append(
             f"convergence groups `{groups_label}` group {finding_id} "
             f"cites source item `{worker}:{item_id}`, but that ID does not "