okstra 0.224.0 → 0.225.0

package/runtime/python/okstra_ctl/code_review_coverage.py

@@ -0,0 +1,213 @@
+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 _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 = _source_evidence(project_root, cell, 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.

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

@@ -0,0 +1,177 @@
+"""채택된 계획 검증 배치의 결정적 후처리."""
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+from collections.abc import Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from okstra_ctl.convergence import validated_run_authority
+from okstra_ctl.convergence_store import load_owned_json_object, write_json_atomic
+from okstra_ctl.dispatch_state import dispatch_worker_key
+from okstra_ctl.error_log_write import record_runtime_failure
+from okstra_ctl.plan_items import PlanItemContractError, analyser_key, critic_is_rostered
+from okstra_ctl.run_context import dir_flock
+from okstra_ctl.worker_prompt_policy import (
+    is_plan_verify_dispatch_kind, verification_dispatch_round,
+)
+from .authoring import finish_verification_round, validate_current_review
+
+if TYPE_CHECKING:
+    from okstra_ctl.dispatch_core import DispatchPlan
+
+
+def _verifier_key(row: Mapping[str, Any]) -> str:
+    if row.get("assignmentRef") == "critic/scope":
+        return "critic"
+    return analyser_key(dispatch_worker_key(row))
+
+
+def _round_dispatches(plan: DispatchPlan, team: Mapping[str, Any]) -> tuple[int, list[dict]] | None:
+    accepted = {row.get("dispatchId") for row in team.get("agentResultLinks", [])
+                if isinstance(row, Mapping) and not row.get("supersededBy")}
+    native = [{**row, "kind": row.get("dispatchKind", ""),
+               "status": "completed" if row.get("status") == "dispatched" and row.get("dispatchId") in accepted else row.get("status"),
+               "workerResultPath": row.get("workerResultPath") or next(
+                   (link.get("resultPath") for link in team.get("agentResultLinks", [])
+                    if link.get("dispatchId") == row.get("dispatchId") and not link.get("supersededBy")), "")}
+              for row in team.get("agentDispatches", []) if isinstance(row, dict)]
+    tails = [rows[-1] for rows in (team.get("workerDispatches", []), native) if rows]
+    if not plan.jobs and tails and all(
+        not is_plan_verify_dispatch_kind(str(row.get("kind", ""))) for row in tails
+    ):
+        return None
+    rows = [row for row in [*team.get("workerDispatches", []), *native] if isinstance(row, dict)
+            and is_plan_verify_dispatch_kind(str(row.get("kind", "")))]
+    targets = {verification_dispatch_round(job.dispatch_kind) for job in plan.jobs
+               if is_plan_verify_dispatch_kind(job.dispatch_kind)}
+    if plan.jobs and not targets:
+        return None
+    if not rows:
+        return None
+    if len(targets) > 1:
+        raise PlanItemContractError("one plan-verification batch cannot span multiple rounds")
+    number = next(iter(targets)) if targets else max(
+        verification_dispatch_round(row["kind"]) for row in rows
+    )
+    superseded = {row.get("dispatchId") for row in team.get("agentResultLinks", [])
+                  if isinstance(row, Mapping) and row.get("supersededBy")}
+    latest: dict[str, dict] = {}
+    for row in rows:
+        if verification_dispatch_round(row["kind"]) != number or row.get("dispatchId") in superseded:
+            continue
+        key = _verifier_key(row)
+        previous = latest.get(key)
+        identity = row.get("invocationRef") or row.get("invocationId")
+        if previous and (not identity or identity != (previous.get("invocationRef") or previous.get("invocationId"))):
+            raise PlanItemContractError(f"ambiguous plan-verification invocations for {key}")
+        if previous is None or row.get("attempt", 1) > previous.get("attempt", 1):
+            latest[key] = row
+    return int(number), list(latest.values())
+
+
+def _accepted_results(plan: DispatchPlan, team: Mapping[str, Any], rows: list[dict]) -> list[str]:
+    authority = validated_run_authority(plan.manifest_path)
+    execution = authority.execution_manifest
+    results = []
+    for row in rows:
+        declared_path = plan.project_root / str(row.get("workerResultPath", ""))
+        path = declared_path.resolve(strict=True)
+        if declared_path.is_symlink():
+            raise PlanItemContractError("plan-verification result must not be a symlink")
+        if not path.is_relative_to(authority.run_dir / "worker-results") or not path.is_file():
+            raise PlanItemContractError("plan-verification result must stay inside this run's worker-results")
+        links = [link for link in team.get("agentResultLinks", []) if isinstance(link, Mapping)
+                 and link.get("dispatchId") == row.get("dispatchId") and not link.get("supersededBy")]
+        if len(links) != 1 or (plan.project_root / str(links[0].get("resultPath", ""))).resolve() != path:
+            raise PlanItemContractError("plan-verification result has no unique accepted result link")
+        if execution is not None:
+            attempts = [attempt for attempt in execution.attempts
+                        if attempt.invocation_ref == row.get("invocationRef")
+                        and attempt.attempt == row.get("attempt")]
+            if len(attempts) != 1 or attempts[0].status != "ok":
+                raise PlanItemContractError("plan-verification attempt is not accepted")
+            if (plan.project_root / str(attempts[0].result_path or "")).resolve() != path:
+                raise PlanItemContractError("accepted attempt result path does not match the dispatch")
+        token = f'-plan-verify-r{verification_dispatch_round(row["kind"])}-'
+        if token not in path.name:
+            raise PlanItemContractError("plan-verification result filename has the wrong round")
+        worker = path.name.split(token, 1)[0]
+        if analyser_key(worker) != _verifier_key(row):
+            raise PlanItemContractError("plan-verification result has the wrong worker")
+        results.append(f"{worker}={path}")
+    return sorted(results)
+
+
+def _completion_receipt(plan: DispatchPlan, number: int, results: list[str]) -> dict[str, Any]:
+    review = validate_current_review(plan.manifest_path)
+    digest = hashlib.sha256()
+    for path in [review.items, review.narrative, *(Path(value.split("=", 1)[1]) for value in results)]:
+        digest.update(str(path).encode())
+        digest.update(path.read_bytes())
+    digest.update(json.dumps(results).encode())
+    fingerprint = digest.hexdigest()
+    receipt = review.state.with_name(f"plan-round-completion-r{number}-{review.state.name.removeprefix('plan-body-verification-')}")
+    state = load_owned_json_object(review.state)
+    if receipt.is_file():
+        recorded = load_owned_json_object(receipt)
+        if recorded.get("inputDigest") == fingerprint and recorded.get("stateDigest") == hashlib.sha256(review.state.read_bytes()).hexdigest():
+            return recorded
+    if any(row.get("round") == number for row in state.get("roundHistory", [])):
+        return {"status": "needs-lead", "round": number,
+                "reason": "round already closed; automatic completion will not replace its recorded inputs"}
+    prepared = load_owned_json_object(review.items)
+    if prepared.get("dispatchKind") == "reverify":
+        return {"status": "needs-lead", "round": number,
+                "reason": "self-fix re-verification needs the lead's cause groups and completion metadata"}
+    completed = finish_verification_round(review, results, number)
+    output = {**completed, "status": "completed", "round": number,
+              "inputDigest": fingerprint, "stateDigest": hashlib.sha256(review.state.read_bytes()).hexdigest(),
+              "receiptPath": str(receipt)}
+    write_json_atomic(receipt, output)
+    return output
+
+
+def complete_ready_plan_round(plan: DispatchPlan) -> dict[str, Any] | None:
+    from okstra_ctl.dispatch_core import TERMINAL_DISPATCH_STATUSES
+
+    if plan.manifest.get("taskType") != "implementation-planning":
+        return None
+    number = 0
+    try:
+        with dir_flock(plan.team_state_path.parent, ".plan-round-completion.lock"):
+            team = load_owned_json_object(plan.team_state_path)
+            batch = _round_dispatches(plan, team)
+            if batch is None:
+                return None
+            number, rows = batch
+            review = validate_current_review(plan.manifest_path)
+            prepared = load_owned_json_object(review.items)
+            workers = {analyser_key(worker) for worker in prepared.get("reviewInputs", {}).get("workers", [])}
+            actual = {_verifier_key(row) for row in rows}
+            if prepared.get("dispatchKind") == "critic-tie":
+                if not critic_is_rostered(plan.manifest):
+                    return {"status": "needs-lead", "round": number,
+                            "reason": "the run has no rostered critic to settle this tie"}
+                if actual & workers and not actual - (workers | {"critic"}):
+                    return {"status": "needs-lead", "round": number,
+                            "reason": "critic shares an analyser round; preserve its queue through manual append"}
+                workers = {"critic"}
+            if actual - workers:
+                raise PlanItemContractError("plan-verification dispatch includes an unassigned verifier")
+            if not workers or actual != workers:
+                return {"status": "pending", "round": number, "reason": "waiting for the complete prepared verifier roster"}
+            if any(row.get("status") not in TERMINAL_DISPATCH_STATUSES for row in rows):
+                return {"status": "pending", "round": number, "reason": "waiting for every verifier to settle"}
+            if any(row.get("status") != "completed" for row in rows):
+                raise PlanItemContractError("one or more plan verifiers failed; preserve their results for lead recovery")
+            return _completion_receipt(plan, number, _accepted_results(plan, team, rows))
+    except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired) as exc:
+        output = {"status": "failed", "round": number, "reason": str(exc)}
+        logged = record_runtime_failure(plan.manifest_path, command="plan-round automatic completion",
+                                        exit_code=2, detail=str(exc))
+        if not logged["ok"]:
+            output["errorLogFailure"] = logged["reason"]
+        return output

package/runtime/python/okstra_ctl/render.py

@@ -1761,6 +1761,8 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
             Path(ctx.get("PROJECT_ROOT", "")), task_manifest, {}
         ),
         "leadModel": ctx.get("LEAD_MODEL", ""),
+        # `okstra-provider-exec.py` 가 워커를 띄울 때마다 읽는다.
+        "reasoningEffort": ctx.get("REASONING_EFFORT", ""),
         # Every other path in this manifest is project-relative; this is the
         # anchor they resolve against. Convergence reads it to place run
         # artifacts, so a manifest without it cannot seed a round.