okstra 0.180.0 → 0.183.2

package/runtime/python/okstra_ctl/plan_items_cli.py

@@ -7,15 +7,26 @@ does not depend on a parser the lead re-writes each time.
 from __future__ import annotations
 
 import argparse
+import importlib.util
 import json
 from collections.abc import Mapping
+from datetime import datetime, timezone
 from pathlib import Path
 import sys
 from typing import Any
 
+from .convergence import (
+    ConvergenceContractError,
+    canonical_run_state_artifact,
+    validated_run_authority,
+)
 from .convergence_store import write_json_atomic
+from .json_boundary import JsonBoundaryError, load_owned_object
 from .plan_derivations import extract_tokens, find_derivations
 from .plan_items import PlanItemContractError, extract_plan_items
+from .paths import RunRef
+from .stage_ledger import build_stage_ledger
+from .claim_reproduction import NOT_RUNNABLE, reproduce
 from .final_report_schema import load_schema_version
 from .report_narrative import parse_narrative
 from .user_response import parse_user_response_entries
@@ -25,16 +36,14 @@ from .verdict_blocks import (
     VerdictBlockError,
     parse_verdict_blocks,
 )
+from .fixed_text import line, scalar
 
 
 def _load_json_object(path: Path) -> dict[str, Any]:
     try:
-        value = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
-        raise PlanItemContractError(f"cannot read JSON object {path}: {exc}") from exc
-    if not isinstance(value, dict):
-        raise PlanItemContractError(f"JSON input must be an object: {path}")
-    return value
+        return load_owned_object(path, artifact="plan-items artifact")
+    except JsonBoundaryError as exc:
+        raise PlanItemContractError(str(exc)) from exc
 
 
 def _planning(data: Mapping[str, Any]) -> Mapping[str, Any]:
@@ -64,6 +73,14 @@ def _parser() -> argparse.ArgumentParser:
     validate = commands.add_parser("validate")
     _add_plan_source(validate)
     validate.add_argument("--items", type=Path, required=True)
+    prepare = commands.add_parser("prepare")
+    _add_plan_source(prepare)
+    prepare.add_argument("--run-manifest", type=Path, required=True)
+    prompt = commands.add_parser("prompt")
+    prompt.add_argument("--run-manifest", type=Path, required=True)
+    validate_prepared = commands.add_parser("validate-prepared")
+    _add_plan_source(validate_prepared)
+    validate_prepared.add_argument("--run-manifest", type=Path, required=True)
     collect = commands.add_parser(
         "collect-verdicts",
         help="read this round's worker responses into a verdicts envelope",
@@ -88,6 +105,11 @@ def _parser() -> argparse.ArgumentParser:
     )
     _add_plan_source(seed)
     seed.add_argument("--state", type=Path)
+    seed.add_argument(
+        "--run-manifest", type=Path,
+        help="record the stage ledger so the gate can scope itself to the "
+             "stage about to start; without it the gate does not narrow",
+    )
     apply_verdicts = commands.add_parser(
         "apply-verdicts",
         help="overwrite planBodyVerification.planItems[].verdicts in owned state",
@@ -95,12 +117,37 @@ def _parser() -> argparse.ArgumentParser:
     target = apply_verdicts.add_mutually_exclusive_group(required=True)
     target.add_argument("--data", type=Path)
     target.add_argument("--state", type=Path)
-    apply_verdicts.add_argument("--verdicts", type=Path, required=True)
+    incoming = apply_verdicts.add_mutually_exclusive_group(required=True)
+    incoming.add_argument(
+        "--verdicts", type=Path,
+        help="historical automation envelope; model-facing calls use --result",
+    )
+    incoming.add_argument(
+        "--result", action="append", default=[],
+        metavar="<worker-id>=<path>",
+        help="one worker's plan-verify Markdown result (repeatable)",
+    )
+    apply_verdicts.add_argument(
+        "--run-manifest", type=Path,
+        help="resolve the project a `fact` claim's probe runs against; without "
+             "it every such claim records `not-runnable` and takes the quorum "
+             "route instead of blocking on one vote",
+    )
     apply_verdicts.add_argument(
         "--round", type=int, required=True, dest="round_number",
         help="the verification round these verdicts were cast in; stamped on "
              "every row so a later self-fix can be told from a current judgement",
     )
+    complete = commands.add_parser(
+        "complete-round",
+        help="derive and atomically record one verified plan-body round",
+    )
+    complete.add_argument("--state", type=Path, required=True)
+    complete.add_argument("--run-manifest", type=Path, required=True)
+    complete.add_argument("--round", type=int, required=True, dest="round_number")
+    complete.add_argument("--self-fix-note", action="append", default=[], metavar="<item-id>=<markdown-file>")
+    complete.add_argument("--self-fix-group", action="append", default=[], metavar="<cause-file>=<item-id>[,<item-id>...]")
+    complete.add_argument("--self-fix-stop-reason", choices=("all-resolved", "no-progress", "max-rounds-reached"))
     return parser
 
 
@@ -139,6 +186,203 @@ def _validate(args: argparse.Namespace) -> dict[str, Any]:
     return {"ok": True, "operation": "validate", "path": str(args.items)}
 
 
+def _prepared_items_path(
+    run_manifest: Path, *, require_regular: bool = False
+) -> Path:
+    try:
+        authority = validated_run_authority(run_manifest)
+        state = canonical_run_state_artifact(
+            authority,
+            manifest_field="planBodyVerificationPath",
+            prefix="plan-body-verification",
+            label="plan body verification path",
+        )
+    except ConvergenceContractError as exc:
+        raise PlanItemContractError(str(exc)) from exc
+    path = state.with_name(
+        "plan-items-" + state.name.removeprefix("plan-body-verification-")
+    )
+    if path.absolute() != path.resolve(strict=False):
+        raise PlanItemContractError("plan items path does not match run authority")
+    if require_regular and not path.is_file():
+        raise PlanItemContractError("plan items path is not a regular file")
+    if path.exists() and not path.is_file():
+        raise PlanItemContractError("plan items path is not a regular file")
+    return path
+
+
+def _prepare(args: argparse.Namespace) -> dict[str, Any]:
+    output = _prepared_items_path(args.run_manifest)
+    envelope = _envelope(_plan_source(args))
+    write_json_atomic(output, envelope)
+    return {"ok": True, "operation": "prepare", "path": str(output)}
+
+
+_PAYLOAD_FIELDS = {
+    "Dir": ("goal", "coreMechanism", "architectureBoundaries", "expectedChangeAreas",
+            "fileStructure", "interfaces", "blastRadius", "testSeams", "assumptions",
+            "planningInvariants", "userConstraints"),
+    "Opt": ("name", "ticketId", "fileStructure", "interfaces", "blastRadius"),
+    "Step": ("stage", "step", "ticketId", "action", "files", "plannedPaths",
+             "command", "outcome", "expectedDetail"),
+    "Dep": ("id", "ticketId", "kind", "item", "impact", "mitigation"),
+    "Val": ("id", "phase", "ticketId", "check", "commandOrObservation", "expectedOutcome",
+            "stageRefs"),
+    "Rb": ("id", "ticketId", "step", "action", "triggerSignal", "verificationMethod"),
+    # 두 계약의 합집합이다. `ImplementationRequirementCoverageRow` 는 id/source/
+    # requirement/coveredBy/status 와 사용자 처분 기록(approvalDisposition,
+    # decisionRefs)을, `SelectedDirectionRequirementCoverage` 는 originalRequirementId
+    # 와 네 개의 *Refs 를 싣는다. 어느 한쪽만 남기면 다른 계약의 계획이 렌더에서
+    # 거부되므로 줄이지 말 것.
+    "Req": ("id", "source", "requirement", "coveredBy", "originalRequirementId",
+            "stageRefs", "stepRefs", "validationRefs", "fileRefs", "ticketId", "status",
+            "approvalDisposition", "decisionRefs"),
+    "Prep": ("stage", "kind", "evidence"),
+}
+_VAR_ANALYSIS_FIELDS = (
+    "hasMultipleImplementations", "noVariationRationale", "points",
+)
+_VAR_POINT_FIELDS = (
+    "behavior", "implementations", "evidence", "extractionDecision",
+)
+_OBJECT_LIST_FIELDS = {
+    "fileStructure": ("id", "ticketId", "action", "path", "summary", "details"),
+    "testSeams": ("boundary", "injectedAs", "replacedInTest"),
+    "planningInvariants": ("id", "statement", "requirementIds", "evidence"),
+    "evidence": ("step", "field", "match"),
+}
+
+
+def _label(key: str) -> str:
+    return " ".join(part.capitalize() for part in key.replace("Id", " ID").split())
+
+
+def _render_object_list(key: str, value: object) -> list[str]:
+    if not isinstance(value, list):
+        raise PlanItemContractError(f"plan item {key} must be an array")
+    rows = [f"- {_label(key)}:\n"]
+    allowed = _OBJECT_LIST_FIELDS[key]
+    for index, entry in enumerate(value, 1):
+        if not isinstance(entry, Mapping) or set(entry) - set(allowed):
+            raise PlanItemContractError(f"plan item {key}[{index}] has unknown fields")
+        rows.append(f"  - Entry {index}:\n")
+        for field in allowed:
+            if field in entry:
+                field_path = f"{key}[{index - 1}].{field}"
+                field_value = entry[field]
+                if isinstance(field_value, list):
+                    rows.append(f"    - `{field_path}`:\n")
+                    rows.extend(
+                        f"      - `{scalar(item)}`\n" for item in field_value
+                    )
+                elif isinstance(field_value, Mapping):
+                    raise PlanItemContractError(
+                        f"plan item {field_path} must be scalar"
+                    )
+                else:
+                    rows.append(
+                        f"    - `{field_path}`: `{scalar(field_value)}`\n"
+                    )
+    return rows
+
+
+def _render_variation_points(value: object) -> list[str]:
+    if not isinstance(value, list):
+        raise PlanItemContractError("plan item points must be an array")
+    rows = ["- Points:\n"]
+    allowed = {"behavior", "implementations", "evidence", "extractionDecision"}
+    decision_fields = ("extract", "interfaceKind", "coveredBy", "rationale")
+    for index, point in enumerate(value, 1):
+        if not isinstance(point, Mapping) or set(point) - allowed:
+            raise PlanItemContractError(f"plan item points[{index}] has unknown fields")
+        rows.append(f"  - Point {index}:\n")
+        for field in ("behavior", "implementations", "evidence"):
+            rows.extend(_render_scalar_or_list(field, point.get(field), "    "))
+        decision = point.get("extractionDecision")
+        if not isinstance(decision, Mapping) or set(decision) - set(decision_fields):
+            raise PlanItemContractError("variation extractionDecision has unknown fields")
+        rows.append("    - Extraction decision:\n")
+        for field in decision_fields:
+            rows.append("      " + line(_label(field), decision.get(field)))
+    return rows
+
+
+def _render_variation_point_payload(payload: Mapping[str, Any]) -> list[str]:
+    rows: list[str] = []
+    for field in ("behavior", "implementations", "evidence"):
+        rows.extend(_render_scalar_or_list(field, payload.get(field)))
+    decision = payload.get("extractionDecision")
+    decision_fields = ("extract", "interfaceKind", "coveredBy", "rationale")
+    if not isinstance(decision, Mapping) or set(decision) - set(decision_fields):
+        raise PlanItemContractError("variation extractionDecision has unknown fields")
+    rows.append("- Extraction decision:\n")
+    for field in decision_fields:
+        rows.append("  " + line(_label(field), decision.get(field)))
+    return rows
+
+
+def _render_scalar_or_list(key: str, value: object, indent: str = "") -> list[str]:
+    if isinstance(value, list):
+        if any(isinstance(entry, (Mapping, list)) for entry in value):
+            raise PlanItemContractError(f"plan item {key} must contain scalars")
+        rows = [f"{indent}- {_label(key)}:\n"]
+        rows.extend(f"{indent}  - `{scalar(entry)}`\n" for entry in value)
+        return rows
+    if isinstance(value, Mapping):
+        raise PlanItemContractError(f"plan item {key} must be scalar")
+    return [indent + line(_label(key), value)]
+
+
+def _render_payload(item_id: str, payload: object) -> list[str]:
+    if not isinstance(payload, Mapping):
+        raise PlanItemContractError(f"plan item {item_id} payload must be an object")
+    kind = item_id.split("-", 2)[1] if item_id.startswith("P-") else ""
+    allowed = (
+        _VAR_ANALYSIS_FIELDS if item_id == "P-Var-0"
+        else _VAR_POINT_FIELDS if kind == "Var"
+        else _PAYLOAD_FIELDS.get(kind)
+    )
+    if allowed is None or set(payload) - set(allowed):
+        raise PlanItemContractError(f"plan item {item_id} has unknown payload fields")
+    if kind == "Var" and item_id != "P-Var-0":
+        return _render_variation_point_payload(payload)
+    rows: list[str] = []
+    for key in allowed:
+        if key not in payload:
+            continue
+        if key in _OBJECT_LIST_FIELDS:
+            rows.extend(_render_object_list(key, payload[key]))
+        elif key == "points":
+            rows.extend(_render_variation_points(payload[key]))
+        else:
+            rows.extend(_render_scalar_or_list(key, payload[key]))
+    return rows
+
+
+def _prompt(args: argparse.Namespace) -> str:
+    envelope = _load_json_object(
+        _prepared_items_path(args.run_manifest, require_regular=True)
+    )
+    items = envelope.get("items") if isinstance(envelope.get("items"), list) else []
+    rows = ["# Plan verification queue\n", line("Item count", len(items))]
+    for index, item in enumerate(items, 1):
+        if not isinstance(item, Mapping):
+            continue
+        item_id = str(item.get("id") or "")
+        rows.extend((f"\n## Plan item {index}\n", line("Item ID", item_id),
+                     line("Subject", item.get("subject"))))
+        rows.extend(_render_payload(item_id, item.get("payload")))
+    return "".join(rows)
+
+
+def _validate_prepared(args: argparse.Namespace) -> dict[str, Any]:
+    expected = _envelope(_plan_source(args))
+    path = _prepared_items_path(args.run_manifest, require_regular=True)
+    if _load_json_object(path) != expected:
+        raise PlanItemContractError("prepared plan items do not match deterministic extraction")
+    return {"ok": True, "operation": "validate-prepared", "path": str(path)}
+
+
 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():
@@ -195,8 +439,15 @@ def _worker_blocks(
     parser; each is a round scored on a table that does not match the queue.
     """
     collected: list[tuple[str, dict[str, VerdictBlock]]] = []
+    seen_workers: set[str] = set()
     for raw in raw_results:
         worker, path = _split_result_arg(raw)
+        if worker in seen_workers:
+            raise PlanItemContractError(
+                f"duplicate worker result for `{worker}` — one worker may cast "
+                "only one verdict per plan-item round"
+            )
+        seen_workers.add(worker)
         try:
             blocks = parse_verdict_blocks(path.read_text(encoding="utf-8"))
         except (OSError, UnicodeError) as exc:
@@ -334,6 +585,37 @@ def _derivations(args: argparse.Namespace) -> dict[str, Any]:
     }
 
 
+def _stage_ledger_snapshot(run_manifest: Path | None) -> dict[str, str] | None:
+    """`{스테이지 번호: 상태}`. 원장을 못 읽으면 ``None``.
+
+    게이트가 범위를 좁히려면 어느 스테이지가 지금 시작 가능한지 알아야 한다. 그
+    사실은 Stage 원장에 있고, 상태 어휘(`done` / `active` / `ready` / `blocked`)는
+    `stage_targets.StageLifecycle.status` 의 것을 그대로 쓴다 — 원장이 자기 어휘를
+    따로 가지면 같은 stage 가 소비처마다 다르게 읽힌다.
+
+    ``None`` 은 판정 근거가 없다는 뜻이고, 소비처는 좁히지 않는다. 첫 계획 run 이라
+    원장이 아직 없는 경우와 `--run-manifest` 를 안 넘긴 경우가 여기 해당한다.
+    """
+    if run_manifest is None:
+        return None
+    try:
+        authority = validated_run_authority(run_manifest)
+        task_root = RunRef.from_run_dir(authority.run_dir).task_root
+        ledger = build_stage_ledger(task_root)
+    except (ConvergenceContractError, ValueError, OSError):
+        return None
+    if not isinstance(ledger, Mapping) or not isinstance(ledger.get("stages"), list):
+        return None
+    snapshot = {
+        str(row["stage"]): str(row["status"])
+        for row in ledger["stages"]
+        if isinstance(row, Mapping)
+        and isinstance(row.get("stage"), int)
+        and isinstance(row.get("status"), str)
+    }
+    return snapshot or None
+
+
 def _seed(args: argparse.Namespace) -> dict[str, Any]:
     """Create the `planBodyVerification.planItems[]` rows a round lands in.
 
@@ -374,7 +656,12 @@ def _seed(args: argparse.Namespace) -> dict[str, Any]:
             key: item[key]
             for key in ("id", "subject", "sourceSection")
             if key in item
-        } | {"verdicts": []}
+        } | (
+            {"stageScope": item["stageScope"]}
+            if item.get("stageScope") else {}
+        ) | (
+            {"block": item["block"]} if item.get("block") else {}
+        ) | {"verdicts": []}
         for item in extracted
         if item["id"] not in known
     ]
@@ -398,6 +685,13 @@ def _seed(args: argparse.Namespace) -> dict[str, Any]:
             for item in extracted
             if item["id"] not in audited
         )
+    ledger = _stage_ledger_snapshot(getattr(args, "run_manifest", None))
+    if ledger is not None:
+        verification = (
+            data["planBodyVerification"] if args.state is not None
+            else _planning(data)["planBodyVerification"]
+        )
+        verification["stageLedger"] = ledger
     write_json_atomic(target, data)
     return {
         "ok": True,
@@ -408,23 +702,48 @@ def _seed(args: argparse.Namespace) -> dict[str, Any]:
     }
 
 
+def _judged_row(row: Mapping[str, Any], project_root: Path | None) -> dict[str, Any]:
+    """한 verdict 행에 재현 결과를 채워 돌려준다.
+
+    `reproductionResult` 는 들어온 값을 쓰지 않고 **항상 여기서 덮어쓴다.** 그
+    필드가 1표 차단의 자격을 결정하므로, 워커가 보낸 값을 그대로 실으면 검증자가
+    자기 주장의 판정을 스스로 적는 것이 된다. 계약이 "okstra 가 쓴다" 고 적은 것이
+    이 뜻이고, 그 문장은 이 덮어쓰기가 있어야 참이다.
+
+    프로젝트를 못 찾으면 `not-runnable` 이다 — 못 돌렸다는 사실이 기록되고, 그
+    주장은 정족수로 내려간다. 조용히 통과시키지도, 근거 없이 차단하지도 않는다.
+    """
+    judged = dict(row)
+    if str(judged.get("claimKind") or "") != "fact":
+        judged.pop("reproductionResult", None)
+        return judged
+    judged["reproductionResult"] = (
+        reproduce(judged.get("reproduction"), project_root=project_root)
+        if project_root is not None
+        else NOT_RUNNABLE
+    )
+    return judged
+
+
+def _probe_project_root(run_manifest: Path | None) -> Path | None:
+    if run_manifest is None:
+        return None
+    try:
+        return validated_run_authority(run_manifest).project_root
+    except ConvergenceContractError:
+        return None
+
+
 def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
     target = args.state or args.data
     data = _load_json_object(target)
-    incoming = _load_json_object(args.verdicts).get("planItems")
-    if not isinstance(incoming, list):
-        raise PlanItemContractError("verdicts envelope has no `planItems` array")
-    rows = {
-        item["id"]: item.get("verdicts", [])
-        for item in incoming
-        if isinstance(item, Mapping) and isinstance(item.get("id"), str)
-    }
     recorded = (
         _state_plan_body_items(data, target)
         if args.state is not None
         else _plan_body_items(data, target)
     )
     known = {item.get("id") for item in recorded if isinstance(item, Mapping)}
+    rows = _incoming_verdict_rows(args, known)
     missing = sorted(item_id for item_id in rows if item_id not in known)
     if missing:
         raise PlanItemContractError(
@@ -434,6 +753,7 @@ def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
         )
     if args.round_number < 1:
         raise PlanItemContractError("--round must be 1 or greater")
+    project_root = _probe_project_root(getattr(args, "run_manifest", None))
     for item in recorded:
         if isinstance(item, Mapping) and item.get("id") in rows:
             # Overwrite, never merge: the contract records one round at a time,
@@ -446,19 +766,189 @@ def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
             # row's vintage. Stamping it here is what lets the validator tell a
             # current judgement from one two rewrites old.
             item["verdicts"] = [
-                {**row, "round": args.round_number} for row in rows[item["id"]]
+                {**_judged_row(row, project_root), "round": args.round_number}
+                for row in rows[item["id"]]
             ]
     write_json_atomic(target, data)
     return {"ok": True, "operation": "apply-verdicts", "path": str(target)}
 
 
+def _round_snapshot(item: Mapping[str, Any], round_number: int) -> dict[str, Any]:
+    votes = {
+        str(row["worker"]): str(row["verdict"])
+        for row in item.get("verdicts", [])
+        if isinstance(row, Mapping) and row.get("round") == round_number
+        and isinstance(row.get("worker"), str) and isinstance(row.get("verdict"), str)
+    }
+    disagrees = sum(value.startswith("DISAGREE") for value in votes.values())
+    if votes and disagrees == 0:
+        classification = "full-consensus"
+    elif disagrees * 2 > len(votes):
+        classification = "majority-disagree"
+    else:
+        classification = "partial-consensus"
+    return {"round": round_number, "votes": votes, "classification": classification}
+
+
+def _plan_gate_summary(verification: Mapping[str, Any]) -> dict[str, Any]:
+    path = Path(__file__).parents[2] / "validators" / "validate-run.py"
+    spec = importlib.util.spec_from_file_location("okstra_plan_gate", path)
+    if spec is None or spec.loader is None:
+        raise PlanItemContractError("cannot load plan-body gate authority")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    summary = module.plan_body_gate_summary({
+        "implementationPlanning": {"planBodyVerification": dict(verification)}
+    })
+    if not isinstance(summary, Mapping):
+        raise PlanItemContractError("plan-body gate authority returned no gate")
+    return dict(summary)
+
+
+def _record_self_fixes(args: argparse.Namespace, audit: list[object], verification: dict[str, Any]) -> None:
+    notes: dict[str, str] = {}
+    known = {item.get("id") for item in audit if isinstance(item, Mapping)}
+    if args.self_fix_stop_reason and not args.self_fix_group:
+        raise PlanItemContractError("--self-fix-stop-reason requires --self-fix-group")
+    for raw in args.self_fix_note:
+        item_id, separator, filename = raw.partition("=")
+        if not separator or not item_id or not filename:
+            raise PlanItemContractError("--self-fix-note must be <item-id>=<markdown-file>")
+        if item_id not in known:
+            raise PlanItemContractError(f"unknown self-fix item `{item_id}`")
+        try:
+            notes[item_id] = Path(filename).read_text(encoding="utf-8").strip()
+        except (OSError, UnicodeError) as exc:
+            raise PlanItemContractError(f"cannot read self-fix note {filename}: {exc}") from exc
+    for item in audit:
+        if isinstance(item, dict) and item.get("id") in notes:
+            item["selfFixNote"] = notes[item["id"]]
+    groups = []
+    for raw in args.self_fix_group:
+        filename, separator, item_ids = raw.partition("=")
+        if not separator or not filename or not item_ids:
+            raise PlanItemContractError("--self-fix-group must be <cause-file>=<item-id>[,<item-id>...]")
+        try:
+            cause = Path(filename).read_text(encoding="utf-8").strip()
+        except (OSError, UnicodeError) as exc:
+            raise PlanItemContractError(f"cannot read self-fix cause {filename}: {exc}") from exc
+        ids = [item for item in item_ids.split(",") if item]
+        unknown = sorted(set(ids) - known)
+        if unknown:
+            raise PlanItemContractError("unknown self-fix item(s): " + ", ".join(unknown))
+        groups.append({"round": args.round_number, "causeSummary": cause, "itemIds": ids})
+    if groups:
+        verification["selfFixGroups"] = groups
+        verification["selfFixRoundsApplied"] = args.round_number
+        verification["selfFixStopReason"] = args.self_fix_stop_reason or "all-resolved"
+
+
+def _round_inputs(args: argparse.Namespace) -> tuple[dict[str, Any], list[dict[str, Any]], list[object], list[object]]:
+    data = _load_json_object(args.state)
+    audit, history = data.get("planItems"), data.get("roundHistory")
+    if not isinstance(audit, list) or not isinstance(history, list):
+        raise PlanItemContractError("state planItems and roundHistory must be arrays")
+    return data, _state_plan_body_items(data, args.state), audit, history
+
+
+def _round_snapshots(current: list[dict[str, Any]], verification: Mapping[str, Any], round_number: int) -> tuple[dict[str, dict[str, Any]], dict[str, Any]]:
+    snapshots = {str(item.get("id")): _round_snapshot(item, round_number) for item in current}
+    if not snapshots or any(not row["votes"] for row in snapshots.values()):
+        raise PlanItemContractError("every current plan item needs a verdict before completion")
+    summary = _plan_gate_summary(verification)
+    classes = {row["id"]: row["stateClassification"] for row in summary["items"]}
+    for item_id, snapshot in snapshots.items():
+        snapshot["classification"] = classes.get(item_id, snapshot["classification"])
+    return snapshots, summary
+
+
+def _record_audit_round(audit: list[object], snapshots: Mapping[str, dict[str, Any]], round_number: int) -> None:
+    for item in audit:
+        if isinstance(item, dict) and str(item.get("id")) in snapshots:
+            rounds = item.get("rounds")
+            if not isinstance(rounds, list):
+                raise PlanItemContractError("state plan item rounds must be an array")
+            item["rounds"] = [row for row in rounds if row.get("round") != round_number]
+            item["rounds"].append(snapshots[str(item["id"])])
+
+
+def _participant_counts(args: argparse.Namespace, snapshots: Mapping[str, dict[str, Any]]) -> tuple[set[str], int, int]:
+    workers = {worker for row in snapshots.values() for worker in row["votes"]}
+    voting = {
+        worker for row in snapshots.values()
+        for worker, verdict in row["votes"].items()
+        if verdict != "verification-error"
+    }
+    assignments = _load_json_object(args.run_manifest).get("workerAssignments")
+    if not isinstance(assignments, list):
+        raise PlanItemContractError("run manifest workerAssignments must be an array")
+    rostered = sum(1 for row in assignments if isinstance(row, Mapping)
+                   and isinstance(row.get("workerId"), str) and row["workerId"] != "report-writer")
+    return workers, len(voting), rostered
+
+
+def _complete_round(args: argparse.Namespace) -> dict[str, Any]:
+    if args.round_number < 1:
+        raise PlanItemContractError("--round must be 1 or greater")
+    data, current, audit, history = _round_inputs(args)
+    verification = data["planBodyVerification"]
+    snapshots, summary = _round_snapshots(current, verification, args.round_number)
+    _record_audit_round(audit, snapshots, args.round_number)
+    gate = str(summary["recomputed"])
+    workers, voting, rostered = _participant_counts(args, snapshots)
+    uniform = [
+        {"worker": worker, "verdict": values[0], "itemCount": len(values)}
+        for worker in workers
+        for values in [[row["votes"][worker] for row in snapshots.values()]]
+        if len(set(values)) == 1
+    ]
+    verification.update({"roundCount": max(int(verification.get("roundCount", 0)), args.round_number),
+                         "gateResult": gate, "gateBlockedBy": summary["blockedBy"],
+                         # 무엇이 막았는지는 `gateBlockedBy` 가, 무엇이 막지 않았고
+                         # 왜인지는 이 쪽이 적는다. 둘 다 같은 계산에서 나온다.
+                         "setAside": summary["setAside"],
+                         "participatingAnalysers": {"rostered": rostered, "voting": voting},
+                         "uniformVerifiers": uniform})
+    _record_self_fixes(args, audit, verification)
+    if args.self_fix_group:
+        data["selfFixRoundsApplied"] = args.round_number
+    history[:] = [row for row in history if row.get("round") != args.round_number]
+    history.append({"round": args.round_number, "completedAt": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), "gateResult": gate, "gateBlockedBy": verification["gateBlockedBy"]})
+    write_json_atomic(args.state, data)
+    return {"ok": True, "operation": "complete-round", "path": str(args.state), "gateResult": gate}
+
+
+def _incoming_verdict_rows(
+    args: argparse.Namespace, known: set[object],
+) -> dict[str, list[dict[str, Any]]]:
+    if args.verdicts is not None:
+        incoming = _load_json_object(args.verdicts).get("planItems")
+        if not isinstance(incoming, list):
+            raise PlanItemContractError("verdicts envelope has no `planItems` array")
+        return {
+            item["id"]: item.get("verdicts", [])
+            for item in incoming
+            if isinstance(item, Mapping) and isinstance(item.get("id"), str)
+        }
+    assigned = {item_id for item_id in known if isinstance(item_id, str)}
+    collected = _worker_blocks(args.result, assigned)
+    return {
+        item_id: [_verdict_row(worker, blocks[item_id]) for worker, blocks in collected]
+        for item_id in assigned
+    }
+
+
 _HANDLERS = {
     "extract": _extract,
     "validate": _validate,
+    "prepare": _prepare,
+    "prompt": _prompt,
+    "validate-prepared": _validate_prepared,
     "collect-verdicts": _collect_verdicts,
     "derivations": _derivations,
     "seed": _seed,
     "apply-verdicts": _apply_verdicts,
+    "complete-round": _complete_round,
 }
 
 
@@ -469,7 +959,12 @@ def main(argv: list[str] | None = None) -> int:
     except (PlanItemContractError, VerdictBlockError, OSError, ValueError) as exc:
         print(f"plan-items: {exc}", file=sys.stderr)
         return 2
-    print(json.dumps(result, ensure_ascii=False, indent=2))
+    if isinstance(result, str):
+        print(result, end="")
+    elif args.command in {"prepare", "validate-prepared"}:
+        print("Plan items\n" + line("Status", "ready") + line("Operation", result["operation"]), end="")
+    else:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
     return 0