okstra 0.224.0 → 0.225.1

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

@@ -263,6 +263,11 @@ class GrokExecution:
         cwd = request.worktree_path or request.project_root
         # `-p` 기본 `plain` 은 종료 시에만 stdout 에 쓴다. 러너는 파이프라
         # TUI 도 열리지 않고, `--no-alt-screen` 도 그 침묵을 바꾸지 않는다.
+        effort = (
+            ("--reasoning-effort", request.reasoning_effort)
+            if request.reasoning_effort
+            else ()
+        )
         return ExecCommand(
             argv=(
                 "grok",
@@ -270,6 +275,7 @@ class GrokExecution:
                 request.prompt_text,
                 "-m",
                 request.model,
+                *effort,
                 "--cwd",
                 str(cwd),
                 "--output-format",

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

@@ -83,7 +83,11 @@ def _read_zai_api_key() -> str:
 class ZaiExecution:
     def build_command(self, request: WorkerExecRequest) -> ExecCommand:
         api_key = _read_zai_api_key()
-        command = ClaudeExecution().build_command(request)
+        # z.ai 의 Anthropic 호환 엔드포인트가 Claude Code 의 effort 를 받는지
+        # 확인되지 않았으므로 run 의 강도를 넘기지 않는다.
+        command = ClaudeExecution().build_command(
+            replace(request, reasoning_effort="")
+        )
         return replace(
             command,
             # 설정 파일의 env 가 자식 환경을 다시 덮어쓰지 않게 한다.

package/runtime/python/okstra_ctl/agent/prompt_cli/results.py

@@ -7,6 +7,7 @@ materialize 가 만든 명세에 대해, 이 층은 그 뒤에 오는 것들을
 from __future__ import annotations
 
 import argparse
+import json
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -87,6 +88,30 @@ def _link_result(args: argparse.Namespace) -> None:
         dispatch_id=args.dispatch_id,
         result_path=_project_input(project_root, args.result, "agent result"),
     )
+    from ...dispatch_core import existing_dispatch_plan
+    from ...paths import RUN_VALIDATOR_RELATIVE, find_asset_root
+    from ...phases.implementation_planning.round_completion import complete_ready_plan_round
+    from ...worker_prompt_policy import is_plan_verify_dispatch_kind
+
+    manifest_path = _project_input(project_root, args.run_manifest, "run manifest")
+    manifest = _read_json_object(manifest_path, "run manifest")
+    if manifest.get("taskType") == "implementation-planning":
+        team = _read_json_object(project_root / manifest["teamStatePath"], "team-state")
+        records = [row for collection in ("workerDispatches", "agentDispatches")
+                   for row in team.get(collection, []) if row.get("dispatchId") == args.dispatch_id]
+        if len(records) == 1 and is_plan_verify_dispatch_kind(str(records[0].get("kind") or records[0].get("dispatchKind", ""))):
+            assets = find_asset_root(RUN_VALIDATOR_RELATIVE)
+            if assets is None:
+                raise AgentPromptCliError("plan-body validator is unavailable")
+            completion = complete_ready_plan_round(existing_dispatch_plan(
+                project_root, assets, manifest_path, manifest,
+            ))
+            if completion:
+                link["planVerification"] = completion
+                if completion["status"] == "failed":
+                    raise AgentPromptCliError(completion["reason"])
+                if not args.json:
+                    print(json.dumps({"planVerification": completion}, ensure_ascii=False))
     _emit(link, args.json)
 
 

package/runtime/python/okstra_ctl/cmux.py

@@ -539,7 +539,7 @@ def spawn_worker_surface(
         # 호출이 반환되기 전에는 명부에 창 식별자가 없다. 여기서 정리하지
         # 않으면 대체 실행으로 전환된 뒤에도 회수할 수 없는 창이 남는다.
         try:
-            closed = run_cmux(["close-surface", "--surface", surface_uuid])
+            closed = run_cmux(["close-surface", "--surface", surface_uuid, "--force"])
             if closed.returncode != 0:
                 raise RuntimeError(closed.stderr.strip() or "cmux close failed")
         except (RuntimeError, OSError, subprocess.SubprocessError) as cleanup_error:
@@ -610,8 +610,10 @@ def rename_lead_surface(title: str) -> str:
 
 def close_surface(surface_uuid: str) -> None:
     """Close an okstra-created surface, killing whatever still runs inside it."""
+    # cmux 는 살아 있는 프로세스가 있는 창을 `--force` 없이 닫지 않는다
+    # (`confirmation_required`). 막 분할된 창의 로그인 셸도 그 프로세스로 센다.
     try:
-        run_cmux(["close-surface", "--surface", surface_uuid])
+        run_cmux(["close-surface", "--surface", surface_uuid, "--force"])
     except (OSError, subprocess.SubprocessError):
         return
 

package/runtime/python/okstra_ctl/code_review_coverage.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+from .agent.invocation import AgentInvocationError, verify_standalone_completion
+from .convergence_provenance import id_occurs_wordbounded
+from .coverage_census import CellVerdicts, split_coverage_verdict_section
+from .json_boundary import load_owned_object
+
+
+@dataclass(frozen=True)
+class ReviewCell:
+    target: str
+    group: str
+
+
+@dataclass(frozen=True)
+class ReviewCensus:
+    rules: dict[str, tuple[str, ...]]
+    cells: dict[str, ReviewCell]
+
+
+def _table_fields(line: str) -> list[str]:
+    return [field.strip() for field in line.strip().strip("|").split("|")]
+
+
+def read_review_census(path: Path) -> ReviewCensus:
+    rules: dict[str, list[str]] = {}
+    cells: dict[str, ReviewCell] = {}
+    rule_ids: set[str] = set()
+    pairs: set[tuple[str, str]] = set()
+    references: set[tuple[str, str]] = set()
+    section = ""
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if line.startswith("## "):
+            section = line.strip()
+        if section not in ("## Rules", "## Cells") or not line.strip().startswith("|"):
+            continue
+        fields = _table_fields(line)
+        header = fields[0] in ("Rule", "Cell")
+        if header or all(re.fullmatch(r"[-:]+", f) for f in fields):
+            continue
+        if len(fields) != 3 or not all(fields):
+            raise ValueError("malformed grouped census row")
+        identity, value, reference = fields
+        if section == "## Rules":
+            if not re.fullmatch(r"[A-Z][A-Z0-9]*", identity) or identity in rule_ids:
+                raise ValueError("invalid or duplicate rule ID")
+            if (value, reference) in references:
+                raise ValueError("duplicate group and rule reference")
+            if value not in ("structural", "semantic", "state-and-tests", "general"):
+                raise ValueError("unknown rule group")
+            rule_ids.add(identity)
+            references.add((value, reference))
+            rules.setdefault(value, []).append(identity)
+        else:
+            if not re.fullmatch(r"C-CR-[0-9]+", identity) or identity in cells:
+                raise ValueError("invalid or duplicate cell ID")
+            if (value, reference) in pairs:
+                raise ValueError("duplicate target and group")
+            target = PurePosixPath(value.partition(":")[0])
+            if target.is_absolute() or ".." in target.parts:
+                raise ValueError("target must be project-relative")
+            pairs.add((value, reference))
+            cells[identity] = ReviewCell(value, reference)
+    if not rules or not cells:
+        raise ValueError("census needs Rules and Cells tables")
+    if any(cell.group not in rules for cell in cells.values()):
+        raise ValueError("cell names an unknown rule group")
+    return ReviewCensus({group: tuple(ids) for group, ids in rules.items()}, cells)
+
+
+def _keyed_values(text: str) -> dict[str, str]:
+    values: dict[str, str] = {}
+    if text == "-":
+        return values
+    for entry in text.split(";"):
+        key, separator, value = entry.partition("=")
+        key, value = key.strip(), value.strip()
+        if not separator or not key or not value or key in values:
+            raise ValueError("empty or duplicate rule assignment")
+        values[key] = value
+    return values
+
+
+def _source_evidence(project_root: Path, cell: ReviewCell, evidence: str) -> str:
+    match = re.fullmatch(r"(.+?):([1-9][0-9]*)`?(?: — .+)?", evidence.strip("`"))
+    target = cell.target.partition(":")[0]
+    if match is None or match[1] != target:
+        raise ValueError("evidence must cite the target source path:line")
+    relative = PurePosixPath(target)
+    source = (project_root / target).resolve()
+    if (relative.is_absolute() or ".." in relative.parts
+            or not source.is_relative_to(project_root.resolve())):
+        raise ValueError("source evidence escapes project")
+    if not source.is_file():
+        raise ValueError("source evidence file does not exist")
+    if int(match[2]) > len(source.read_text(encoding="utf-8").splitlines()):
+        raise ValueError("source evidence line does not exist")
+    return evidence
+
+
+def _checked_rule_evidence(
+    project_root: Path, cell: ReviewCell, checked: Sequence[str], text: str,
+) -> str:
+    anchor, _, raw = text.partition(" :: ")
+    _source_evidence(project_root, cell, anchor)
+    observations = _keyed_values(raw.strip() or "-")
+    required = set(checked) & {"G2", "G3", "G5"} if cell.group == "general" else set()
+    missing = required - observations.keys()
+    if missing:
+        raise ValueError("missing clean check evidence: " + ", ".join(sorted(missing)))
+    if observations.keys() - set(checked):
+        raise ValueError("clean check evidence names an unchecked rule")
+    for observation in observations.values():
+        match = re.fullmatch(r"(`?.+?:[1-9][0-9]*`?) (.+)", observation)
+        if match is None:
+            raise ValueError("clean check evidence needs source path:line and an observation")
+        if re.fullmatch(r"(?:checked|clean|no issues?|none|n/?a)", match[2], re.I):
+            raise ValueError("clean check evidence needs an observation, not a verdict label")
+        citation = match[1].strip("`")
+        source_cell = ReviewCell(citation.partition(":")[0], cell.group)
+        _source_evidence(project_root, source_cell, citation)
+    return text
+
+
+def _group_verdict(
+    fields: Sequence[str], expected: Sequence[str], cell: ReviewCell,
+    project_root: Path, references: Sequence[str],
+) -> tuple[str, str]:
+    if len(fields) != 5:
+        raise ValueError("expected Cell, Checked, N/A, Findings, Evidence columns")
+    checked = [] if fields[1] == "-" else [rule.strip() for rule in fields[1].split(",")]
+    excluded = _keyed_values(fields[2])
+    findings = _keyed_values(fields[3])
+    assigned = checked + list(excluded) + list(findings)
+    if len(set(assigned)) != len(assigned):
+        raise ValueError("duplicate or conflicting rule verdicts")
+    unknown = set(assigned) - set(expected)
+    if unknown:
+        raise ValueError("unknown rules: " + ", ".join(sorted(unknown)))
+    missing = set(expected) - set(assigned)
+    if missing:
+        raise ValueError("unchecked rules: " + ", ".join(sorted(missing)))
+    for reason in excluded.values():
+        if re.fullmatch(r"(?:[A-Z][0-9]+|[a-z]+:[0-9]+)", reason):
+            raise ValueError("n/a needs an inline applicability reason, not an alias")
+    for ids in findings.values():
+        for item in ids.split(","):
+            item = item.strip()
+            if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", item):
+                raise ValueError("invalid finding ID")
+            if not any(id_occurs_wordbounded(body, item) for body in references):
+                raise ValueError(f"finding {item} has no finding body")
+    evidence = _checked_rule_evidence(project_root, cell, checked, fields[4])
+    if findings:
+        return "finding", "; ".join(findings.values())
+    if checked:
+        return "clean", evidence
+    return "n/a", "; ".join(excluded.values())
+
+
+def _group_results(
+    body: str, census: ReviewCensus, project_root: Path, references: Sequence[str],
+) -> CellVerdicts:
+    section, _ = split_coverage_verdict_section(body)
+    verdicts: dict[str, tuple[str, str]] = {}
+    reasons: dict[str, str] = {}
+    seen: set[str] = set()
+    unknown: list[str] = []
+    for line in section:
+        if not line.strip().startswith("|"):
+            continue
+        fields = _table_fields(line)
+        identity = fields[0]
+        if identity not in census.cells:
+            if identity.startswith("C-") and identity not in unknown:
+                unknown.append(identity)
+            continue
+        if identity in seen:
+            verdicts.pop(identity, None)
+            reasons[identity] = "duplicate cell row"
+            continue
+        seen.add(identity)
+        cell = census.cells[identity]
+        try:
+            verdicts[identity] = _group_verdict(
+                fields, census.rules[cell.group], cell, project_root, references,
+            )
+        except (OSError, ValueError) as exc:
+            reasons[identity] = str(exc)
+    return CellVerdicts(
+        verdicts,
+        {key: reasons.get(key, "no grouped verdict row") for key in census.cells if key not in verdicts},
+        tuple(unknown),
+    )
+
+
+def check_review_coverage(
+    project_root: Path, census_path: Path, completions: Sequence[Path],
+) -> CellVerdicts:
+    census = read_review_census(census_path)
+    if not completions or len(set(completions)) != len(completions):
+        raise ValueError("pass distinct completion paths for one reviewer")
+    bodies: list[str] = []
+    assignment: object = None
+    for path in completions:
+        verified = verify_standalone_completion(
+            path, project_root=project_root, expected_purpose="code-review",
+        )
+        metadata = load_owned_object(
+            verified.prompt_metadata_path, artifact="agent invocation metadata",
+        )
+        if metadata["audience"] != "code-reviewer":
+            raise AgentInvocationError("completion is not a code reviewer")
+        current = metadata["modelAssignment"]
+        if assignment is not None and current != assignment:
+            raise AgentInvocationError("coverage cannot mix reviewer model assignments")
+        assignment = current
+        bodies.append(verified.returned_body)
+    verdicts: dict[str, tuple[str, str]] = {}
+    missing: dict[str, str] = {}
+    unknown: list[str] = []
+    references = [split_coverage_verdict_section(body)[1] for body in bodies]
+    for body in bodies:
+        parsed = _group_results(body, census, project_root, references)
+        unknown.extend(key for key in parsed.unknown if key not in unknown)
+        for key, verdict in parsed.verdicts.items():
+            verdicts.setdefault(key, verdict)
+        missing.update(parsed.missing)
+    return CellVerdicts(
+        verdicts, {key: missing[key] for key in census.cells if key not in verdicts},
+        tuple(unknown),
+    )

package/runtime/python/okstra_ctl/code_review_target.py

@@ -102,6 +102,7 @@ def _branch_snapshot(repo: Path, branch: str, base: str, review_date: str) -> di
 _CLI_EPILOG = r"""Usage:
   okstra code-review target --task-key <k> --stage <N> [--base <ref>] [--project-root <dir>] [--cwd <dir>] --json
   okstra code-review target --branch <name> [--base <ref>] [--date <YYYY-MM-DD>] [--project-root <dir>] --json
+  okstra code-review check-coverage --census <table-path> --completion <completion-path> [--completion ...] [--project-root <dir>]
   okstra code-review check-lines --base <ref> --head <ref> --cite <path:line> [--cite ...] [--project-root <dir>]
 
 Output: JSON { ok, mode, worktreePath, branch, baseCommit, headCommit,
@@ -111,7 +112,8 @@ any citation is not a line the range changed. `--base` sets the base in either m
 mode reads the base commit from the stage registry row and branch mode falls
 back to the merge-base with the default branch. An empty worktreePath means the review reads the branch ref
 instead of a checked-out tree. This is read-only — it never creates
-directories or files.
+directories or files. `check-coverage` prints covered cells, missing rules and unknown cells;
+it exits 1 for incomplete coverage and 2 for invalid input or completion evidence.
 """
 
 
@@ -122,7 +124,7 @@ def _build_parser() -> argparse.ArgumentParser:
         prog="okstra code-review",
         description="Resolve a code review's diff range and result file path, or check finding citations."
     )
-    parser.add_argument("command", choices=("target", "check-lines"))
+    parser.add_argument("command", choices=("target", "check-lines", "check-coverage"))
     parser.add_argument("--task-key", default="", help="project-id:task-group:task-id")
     parser.add_argument("--stage", type=int, default=0, help="stage number to review")
     parser.add_argument("--branch", default="", help="branch to review")
@@ -135,6 +137,9 @@ def _build_parser() -> argparse.ArgumentParser:
         "--cite", action="append", default=[],
         help="check-lines: a finding's `path:line` (repeatable)",
     )
+    parser.add_argument("--census", default="", help="check-coverage: shared Rules and grouped Cells tables")
+    parser.add_argument("--completion", action="append", default=[],
+                        help="check-coverage: verified reviewer completion (repeat for gap-fills)")
     parser.add_argument("--date", default="", help="YYYY-MM-DD for branch result naming")
     parser.add_argument("--project-root", default="", help="explicit project root")
     parser.add_argument("--cwd", default=".", help="cwd for project root resolution")
@@ -249,6 +254,28 @@ def _check_lines(args: argparse.Namespace, project_root: Path) -> int:
     return 0 if all_ok else 1
 
 
+def _check_coverage(args: argparse.Namespace, project_root: Path) -> int:
+    from .agent.invocation import AgentInvocationError
+    from .code_review_coverage import check_review_coverage
+
+    if not args.census or not args.completion:
+        print("check-coverage: pass --census and at least one --completion", file=sys.stderr)
+        return 2
+    try:
+        result = check_review_coverage(
+            project_root, Path(args.census), [Path(path) for path in args.completion],
+        )
+    except (OSError, ValueError, AgentInvocationError) as exc:
+        print(f"check-coverage: {exc}", file=sys.stderr)
+        return 2
+    print(f"Covered cells: {len(result.verdicts)}")
+    for key, reason in result.missing.items():
+        print(f"Missing: {key} — {reason}")
+    for key in result.unknown:
+        print(f"Unknown: {key}")
+    return 1 if result.missing or result.unknown else 0
+
+
 def main(argv: list[str] | None = None) -> int:
     args = _build_parser().parse_args(argv)
     try:
@@ -260,6 +287,8 @@ def main(argv: list[str] | None = None) -> int:
         print(render_code_review_target_text(payload) if args.text else json.dumps(payload))
         return 2
 
+    if args.command == "check-coverage":
+        return _check_coverage(args, Path(project_root))
     if args.command == "check-lines":
         return _check_lines(args, Path(project_root))
     try:

package/runtime/python/okstra_ctl/coverage_census.py

@@ -233,7 +233,7 @@ class CellVerdicts:
     unknown: tuple[str, ...]
 
 
-def _split_verdict_section(text: str) -> tuple[list[str], str]:
+def split_coverage_verdict_section(text: str) -> tuple[list[str], str]:
     """The Coverage Verdicts lines, and the rest of the result."""
     lines = text.splitlines()
     start = next(
@@ -288,7 +288,7 @@ def parse_cell_verdicts(
     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)
+    section, body = split_coverage_verdict_section(result_text)
     wanted = list(dict.fromkeys(cell_ids))
     known = set(wanted)
     verdicts: dict[str, tuple[str, str]] = {}

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -335,6 +335,21 @@ class DispatchPlan:
         return payload
 
 
+def existing_dispatch_plan(
+    project_root: Path, workspace_root: Path, run_manifest_path: Path,
+    manifest: Mapping[str, Any],
+) -> DispatchPlan:
+    root = project_root.resolve()
+    return DispatchPlan(
+        project_root=root, workspace_root=workspace_root.resolve(),
+        manifest_path=_resolve_project_path(root, str(run_manifest_path)),
+        team_state_path=_resolve_required_path(root, manifest, "teamStatePath"),
+        lead_events_path=_resolve_required_path(root, manifest, "leadEventsPath"),
+        manifest=manifest, jobs=(),
+        default_backend=str(manifest.get("terminalBackend") or BACKEND_CLI_WRAPPER),
+    )
+
+
 @dataclass(frozen=True)
 class _BuildOptions:
     okstra_bin: Path | None

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

@@ -18,6 +18,9 @@ SERVED_MODEL_MISMATCH_EXIT_CODE = 78
 # JSON 이벤트 스트림이 result 이벤트 없이 깨끗하게(exit 0) 끝난 run.
 # CLI 가 성공을 주장했지만 답을 내지 않았다 — sysexits 의 EX_PROTOCOL.
 NO_RESULT_EXIT_CODE = 76
+# run 하나에 한 단계, okstra-run 위저드에서 고른다. 강도를 받는 CLI 들이 이 넷을
+# 공통으로 받으므로 각 전략은 철자만 옮긴다.
+REASONING_EFFORTS = ("low", "medium", "high", "xhigh")
 
 
 @dataclass(frozen=True)
@@ -62,6 +65,9 @@ class WorkerExecRequest:
     # issue its own, so the recorded id and the session's own jsonl are
     # guaranteed to name the same session.
     session_id: str = ""
+    # `REASONING_EFFORTS` 중 하나. run 이 고르지 않았으면 빈 값이고, 그때 CLI 는
+    # 자기 설정을 따른다.
+    reasoning_effort: str = ""
 
 
 @dataclass(frozen=True)

package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py

@@ -11,8 +11,10 @@ from . import plan_body
 
 import argparse
 import copy
+from dataclasses import dataclass
 import json
 import re
+import subprocess
 from collections.abc import Mapping, Sequence
 from datetime import datetime, timezone
 from pathlib import Path
@@ -25,6 +27,7 @@ from okstra_ctl.convergence import (
     validated_run_authority,
 )
 from okstra_ctl.convergence_store import write_json_atomic
+from okstra_ctl.paths import RUN_VALIDATOR_RELATIVE, find_asset_root
 from okstra_ctl.incremental_carry import sync_prepared_dispatch_queue
 from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
 from okstra_ctl.report_finalize import task_manifest_path
@@ -1146,6 +1149,69 @@ def _validate_prepared(args: argparse.Namespace) -> dict[str, Any]:
     return {"ok": True, "operation": "validate-prepared", "path": str(path)}
 
 
+@dataclass(frozen=True)
+class PreparedPlanReview:
+    manifest: Path
+    state: Path
+    items: Path
+    narrative: Path
+
+
+def validate_current_review(run_manifest: Path) -> PreparedPlanReview:
+    authority = validated_run_authority(run_manifest)
+    state = canonical_run_state_artifact(
+        authority, manifest_field="planBodyVerificationPath",
+        prefix="plan-body-verification", label="plan body verification path",
+    )
+    name = authority.payload.get("reportNarrativePath")
+    if not isinstance(name, str) or not name:
+        raise PlanItemContractError("reportNarrativePath is missing")
+    narrative = (authority.project_root / name).resolve(strict=True)
+    if not narrative.is_relative_to(authority.run_dir):
+        raise PlanItemContractError("plan narrative must stay inside the current run")
+    items_path = _prepared_items_path(run_manifest, require_regular=True)
+    prepared = _load_json_object(items_path)
+    source = _plan_source(argparse.Namespace(data=None, narrative=narrative))
+    items = _envelope(source)["items"]
+    if prepared.get("items") != items:
+        raise PlanItemContractError("prepared plan items do not match the current narrative")
+    inputs = _checked_review_inputs(run_manifest)
+    current = _review_inputs(items, _planning(source), run_manifest, [])
+    if inputs.get("context") != current.get("context"):
+        raise PlanItemContractError("prepared review context changed; prepare and verify again")
+    return PreparedPlanReview(run_manifest, state, items_path, narrative)
+
+
+def finish_verification_round(
+    review: PreparedPlanReview, results: Sequence[str], round_number: int,
+) -> dict[str, Any]:
+    common = ["--state", str(review.state), "--run-manifest", str(review.manifest),
+              "--items", str(review.items), "--round", str(round_number)]
+    apply_args = ["apply-verdicts", *common]
+    for result in results:
+        apply_args.extend(["--result", result])
+    if results and all(is_critic_worker(value.split("=", 1)[0]) for value in results):
+        apply_args.append("--append")
+    _apply_verdicts(_parser().parse_args(apply_args))
+    assets = find_asset_root(RUN_VALIDATOR_RELATIVE)
+    if assets is None:
+        raise PlanItemContractError("plan-body validator is unavailable")
+    verified = subprocess.run(
+        [sys.executable, str(assets.joinpath(*RUN_VALIDATOR_RELATIVE)),
+         "--section", "plan-body", "--narrative", str(review.narrative),
+         "--state", str(review.state)],
+        capture_output=True, text=True, check=False, timeout=60,
+    )
+    if verified.returncode:
+        raise PlanItemContractError(
+            f"plan-verify failed: {verified.stdout.strip()} {verified.stderr.strip()}"
+        )
+    validation = json.loads(verified.stdout)
+    validate_current_review(review.manifest)
+    completed = _complete_round(_parser().parse_args(["complete-round", *common]))
+    return {**completed, "verification": validation}
+
+
 def _split_result_arg(raw: str) -> tuple[str, Path]:
     worker, separator, path = raw.partition("=")
     if not separator or not worker.strip() or not path.strip():

package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md

@@ -424,7 +424,11 @@ For contract 3.0, `prepare` checks the selected-direction draft with the same se
 3. Dispatch uses the same wrapper infrastructure as finding convergence, so the `--role-slug` is the same canonical `<role>-worker` that convergence uses — not a round-specific slug. Result file path: `runs/<task-type>/worker-results/<role>-worker-plan-verify-r<N>-implementation-planning-<seq>.md` (e.g. `codex-worker-plan-verify-r1-implementation-planning-003.md`). **`<seq>` is the report's sequence** — the one in this run's `final-report-<task-type>-<seq>` filename, NOT the `workerResults` sequence the initial analysis results carry. The two are equal in most runs and diverge in some (`reports: 004` alongside `workerResults: 005` is a real case). Provenance no longer globs by either seq: it resolves the expected filenames from this run's team-state `workerDispatches[]` rows — the paths the dispatches actually recorded — and falls back to the seq glob only when no team-state is readable, saying so in its finding. The `-worker-` token is load-bearing twice over: §"Plan-body reverify prompt" requires the same anchor headers as convergence, whose `**Audit sidecar path:**` is derived by `okstra_ctl.worker_artifact_paths.audit_sidecar_rel()` inserting `-audit-` after that token — a slug without it makes the header underivable and the helper raises. Record each `planItems[].verdicts[].worker` as the same `<role>-worker` string, because provenance compares it to this filename's prefix. **Enforced:** `tests/contract/test_reverify_dispatch_anchors.py` derives the sidecar from the documented name and re-extracts the prefix the provenance resolver uses.
    **Verdict provenance.** Every verdict recorded in `planItems[].verdicts[]` MUST trace back to a dispatch that actually returned a result file. The whole gate — classification, self-fix eligibility, promotion, `gateBlockedBy` — is computed from these votes, so an unbacked vote lets the round be skipped while the gate still reads `passed`. **Enforced (advisory):** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_plan_body_verdict_provenance` reports any `verdicts[].worker` with no recorded reverify dispatch whose result file exists; the finding is not in the blocking allowlist, so it surfaces as an advisory rather than failing the run — record it, never dismiss it. Recording a `verification-error` for a dispatch that produced no result is the correct way to represent a failed worker — inventing an `AGREE` is a contract violation, and renaming a result file to make provenance match destroys the link the check reads.
 
-4. After all dispatches return, lead aggregates verdicts per `P-*` item across workers and classifies each:
+4. After all dispatches return, first read `planVerification` in the `worker-dispatch`, `team await --json`, or `agent-prompt link-result --json` response. When its `status` is `completed`, the runtime has already parsed all accepted verifier results, run the plan-body contract validator, and recorded the round. Use its `gateResult`, `verification` (including advisories), and `nextDispatch`; skip the separate collect/apply/plan-verify/complete/next-dispatch calls and continue with the decisions and self-fix procedure below. `pending` means the complete prepared verifier roster has not returned. `failed` stops automatic completion and returns the error; preserve the result files and repair the named defect. `needs-lead`, or a response without this field, uses the manual procedure below. In particular, self-fix re-verification retains the lead-owned cause groups and completion metadata. **Enforced:** `phases/implementation_planning/round_completion.py` and the automatic-round and execution-boundary tests in `tests/run/test_plan_items.py`.
+
+   A critic correction sharing the analysers' round also returns `needs-lead`; retain the original round queue and use the manual `--append` procedure. The automatic-round tests in `tests/run/test_plan_items.py` enforce this boundary.
+
+   In the manual procedure, lead aggregates verdicts per `P-*` item across workers and classifies each:
 
    **Every in-scope item carries at least one verdict row (BLOCKING).** Aggregation covers the dispatch queue, not deferred or observed stages. An in-scope item left with an empty `verdicts[]` is not a weak signal the gate can discount — it classifies `all-non-result`, states as `needs-reverify`, and folds into `passed-with-dissent` next to items two verifiers actually agreed on, so a plan item nobody judged reads as a passing one. This is the shape a self-fix round produces when the planner adds an in-scope item and the targeted round-N queue never picks it up. A worker that returned nothing is a `verification-error` row (step 3), not a missing row; if an in-scope item was never dispatched, dispatch it before scoring the round. **Enforced:** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_round_recorded_verdicts` fails any run whose `roundCount` ≥ 1 leaves an in-scope item with no verdict row.
 

package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md

@@ -292,6 +292,7 @@ For a new `implementation-planning` run, the fixed order is initial verification
 
    An `AGREE` response records the considered counterexample and exclusion reason in its note; unverified external material is `verification-error`, not `DISAGREE`.
 2. Dispatch a single plan-body reverify round to every analyser worker in the run's roster. `Report writer worker` is NOT a participant in this round.
+   Read `planVerification` in the dispatch, await, or native result-link response. `status=completed` means the runtime has already applied the accepted results, checked the plan-body contract, and completed the round. Use its gate, advisories, and next dispatch and skip steps 3–4. `pending` waits for the remaining verifiers; `failed` stops for the returned defect; `needs-lead` retains the manual path, including self-fix cause-group recording. Enforcement: `phases/implementation_planning/round_completion.py` and automatic-round integration tests in `tests/run/test_plan_items.py`.
 3. Record each verifier Markdown result through `okstra plan-items apply-verdicts --state <plan-body-verification.json> --result <worker-id>=<result.md> --round <N>`. Python validates every submitted `P-*` identifier against the current convergence state and overwrites only that round's verdicts. Then resolve the gate result to one of `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`.
 4. After `okstra plan-verify` succeeds, run `okstra plan-items complete-round --state <plan-body-verification.json> --run-manifest <current-run-manifest.json> --round <N>`. Python reads the current worker assignments, atomically appends the convergence-owned history, and updates its nested final projection. This state is the only plan-verification input report assembly reads.
 5. Record every *in-scope execution* `majority-disagree` decision through `okstra approval-decision`; record its plan and clarification links only on activities. Do not promote `observed` / `deferred` / `record` items, and do not append `clarificationItems[]` directly.