okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/plan_items_cli.py

@@ -7,8 +7,10 @@ does not depend on a parser the lead re-writes each time.
 from __future__ import annotations
 
 import argparse
+import copy
 import importlib.util
 import json
+import re
 from collections.abc import Mapping, Sequence
 from datetime import datetime, timezone
 from pathlib import Path
@@ -21,6 +23,7 @@ from .convergence import (
     validated_run_authority,
 )
 from .convergence_store import write_json_atomic
+from .incremental_carry import sync_prepared_dispatch_queue
 from .json_boundary import JsonBoundaryError, load_owned_object
 from .report_finalize import task_manifest_path
 from .plan_derivations import extract_tokens, find_derivations
@@ -30,13 +33,17 @@ from .plan_items import (
     advisory_plan_body_gating,
     content_hash,
     correction_prompt_text,
+    critic_is_rostered,
     critic_tie_prompt_text,
     dispatch_item_ids,
     extract_plan_items,
     next_dispatch,
     planning_stage_ledger,
     reverify_item_ids,
+    reverify_prompt_text,
     tie_vote_item_ids,
+    voting_analyser_keys,
+    with_response_format,
 )
 from .paths import RunRef
 from .stage_ledger import build_stage_ledger
@@ -151,7 +158,9 @@ def _parser() -> argparse.ArgumentParser:
     prepare.add_argument(
         "--state", type=Path,
         help="previous plan-body state; when it carries verifiedContentHash "
-             "rows the dispatch queue shrinks to the self-fix reverify set",
+             "rows the dispatch queue shrinks to the self-fix reverify set, and "
+             "each queued item's recorded votes and selfFixNote are carried "
+             "into the prompt as its `**Prior round dissent**` block",
     )
     prepare.add_argument(
         "--tie-vote", action="store_true",
@@ -164,7 +173,8 @@ def _parser() -> argparse.ArgumentParser:
     validate_prepared.add_argument("--run-manifest", type=Path, required=True)
     validate_prepared.add_argument(
         "--state", type=Path,
-        help="same previous state prepare used to shrink the dispatch queue",
+        help="same previous state prepare used to shrink the dispatch queue "
+             "and to build the prior-dissent carry; both are re-derived here",
     )
     validate_prepared.add_argument(
         "--tie-vote", action="store_true",
@@ -177,7 +187,14 @@ def _parser() -> argparse.ArgumentParser:
     collect.add_argument("--result", action="append", default=[], required=True,
                          metavar="<worker-id>=<path>",
                          help="one worker's plan-verify result file (repeatable)")
-    collect.add_argument("--items", type=Path, required=True)
+    collect.add_argument(
+        "--items", type=Path, required=True,
+        metavar="<plan-items artifact>",
+        help="the plan-items artifact this round dispatched (not a list of "
+             "ids). Its `dispatchQueue` is the id set the results must answer, "
+             "so a tie round takes the `--tie-vote` artifact, not the full "
+             "round's one",
+    )
     collect.add_argument("--output", type=Path, required=True)
     derivations = commands.add_parser(
         "derivations",
@@ -199,6 +216,15 @@ def _parser() -> argparse.ArgumentParser:
         help="record the stage ledger so the gate can scope itself to the "
              "stage about to start; without it the gate does not narrow",
     )
+    seed.add_argument(
+        "--prior-state", type=Path,
+        help="the previous run's plan-body-verification-<task-type>-<seq>.json. "
+             "A newly seeded item whose contentHash still equals that run's "
+             "verifiedContentHash inherits its verdicts and is tagged "
+             "carriedForwardFromSeq, so round 1 does not re-judge text nobody "
+             "changed. Requires --state, refuses a state file belonging to "
+             "another task, and never carries on a matching id alone",
+    )
     apply_verdicts = commands.add_parser(
         "apply-verdicts",
         help="overwrite planBodyVerification.planItems[].verdicts in owned state",
@@ -239,8 +265,18 @@ def _parser() -> argparse.ArgumentParser:
     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"))
+    complete.add_argument(
+        "--self-fix-group", action="append", default=[],
+        metavar="<cause-file>=<item-id>[,<item-id>...]",
+        help="this round's cause groups; requires --self-fix-stop-reason",
+    )
+    complete.add_argument(
+        "--self-fix-stop-reason",
+        choices=("all-resolved", "no-progress", "max-rounds-reached"),
+        help="why the self-fix loop stops. Required with --self-fix-group, and "
+             "valid on its own to record a stop the round did not rewrite for; "
+             "on its own it leaves selfFixRoundsApplied and selfFixGroups alone",
+    )
     _add_dispatch_commands(commands)
     return parser
 
@@ -354,6 +390,8 @@ def _prepare(args: argparse.Namespace) -> dict[str, Any]:
         envelope["tieSplits"] = _tie_splits_from_state(
             getattr(args, "state", None), envelope["dispatchQueue"],
         )
+    else:
+        envelope.update(_reverify_carry(args, envelope["dispatchQueue"]))
     gating = not advisory_plan_body_gating(_planning(source), envelope["items"])
     _sync_task_manifest_gating(args.run_manifest, gating)
     write_json_atomic(output, envelope)
@@ -506,6 +544,70 @@ def _render_payload(item_id: str, payload: object) -> list[str]:
     return rows
 
 
+# 검증 시점의 서사에는 조립 소유 필드가 없다는 계약을 검증자에게 직접 알린다.
+# run 003 실측: critic 이 P-Prep 항목에 `designSurfaceCoverage` 처분을 요구하며
+# DISAGREE(b) — writer 가 그 필드를 쓰면 계약 위반이라 self-fix 로도 풀 수 없는
+# 차단이었다.
+_PREP_OWNERSHIP_NOTE = (
+    "\nOwnership boundary: `designPreparation` / `designSurfaceCoverage` rows "
+    "are produced by report assembly after this verification, so the narrative "
+    "under review carries neither — their absence is the contract, not a "
+    "defect. Judge the trigger evidence above; do not DISAGREE because the "
+    "writer did not produce those fields.\n"
+)
+
+
+def _step_coordinate(payload: object, field: str) -> int | None:
+    if not isinstance(payload, Mapping):
+        return None
+    value = payload.get(field)
+    if isinstance(value, int) and not isinstance(value, bool) and value >= 1:
+        return value
+    return None
+
+
+def _render_prior_steps(item: Mapping[str, Any], all_items: object) -> str:
+    """같은 stage 의 선행 step 요약. run 003 실측: step 1.1 이 만드는 스크립트를
+    1.2 검증자가 '없다'고 판정했다 — 검증 단위는 step 인데 payload 가 자기 행뿐이라
+    계획이 앞 step 에서 만드는 것을 볼 수 없었다. dispatchQueue 가 좁혀져도 선행
+    맥락은 봉투의 전체 items 에서 온다."""
+    stage = _step_coordinate(item.get("payload"), "stage")
+    step = _step_coordinate(item.get("payload"), "step")
+    if stage is None or step is None or step < 2:
+        return ""
+    priors: list[tuple[int, str]] = []
+    for other in all_items if isinstance(all_items, list) else []:
+        if not isinstance(other, Mapping):
+            continue
+        other_step = _step_coordinate(other.get("payload"), "step")
+        if (
+            other_step is None
+            or other_step >= step
+            or _step_coordinate(other.get("payload"), "stage") != stage
+        ):
+            continue
+        payload = other.get("payload")
+        action = str(payload.get("action") or other.get("subject") or "").strip()
+        files = payload.get("files")
+        if isinstance(files, str) and files.strip():
+            files = [files]
+        suffix = (
+            " — files: " + ", ".join(f"`{scalar(entry)}`" for entry in files)
+            if isinstance(files, list) and files
+            else ""
+        )
+        priors.append((other_step, f"- step {other_step}: {action}{suffix}\n"))
+    if not priors:
+        return ""
+    priors.sort()
+    return (
+        "\nPrior steps in this stage (already applied when this step runs):\n"
+        + "".join(text for _, text in priors)
+        + "Judge this step against the state after them — a script, file, or "
+        "path a prior step creates is not missing.\n"
+    )
+
+
 def _render_analyser_split(verdicts: object) -> str:
     """동수 항목에 이미 찍힌 분석자 표를 critic 프롬프트에 붙인다."""
     if not isinstance(verdicts, list):
@@ -544,11 +646,147 @@ def _tie_splits_from_state(
     return splits
 
 
+_PRIOR_DISSENT_PROMPT_ANCHOR = "**Prior round dissent**"
+_NO_SELF_FIX_NOTE = (
+    "no correction — this item's text shifted under a neighbouring rewrite"
+)
+
+
+def _prior_vote(row: Mapping[str, Any]) -> dict[str, Any]:
+    """직전 라운드의 한 표를 프롬프트가 렌더할 만큼만 옮긴다.
+
+    `basis` 는 워커가 적은 근거다. `explanation` 이 계약상 필수 줄이고 `note` 는
+    반증 후보라, 설명이 비어 있을 때만 후자로 내려간다. 둘 다 없으면 근거 없는
+    표이므로 빈 문자열을 남긴다 — 없는 근거를 지어내지 않는다.
+    """
+    vote: dict[str, Any] = {
+        "worker": str(row.get("worker") or ""),
+        "verdict": str(row.get("verdict") or ""),
+    }
+    kind = str(row.get("breakageKind") or "").strip()
+    if kind:
+        vote["breakageKind"] = kind
+    fixability = str(row.get("fixability") or "").strip()
+    if fixability:
+        vote["fixability"] = fixability
+    basis = (
+        str(row.get("explanation") or "").strip()
+        or str(row.get("note") or "").strip()
+    )
+    if basis:
+        vote["basis"] = basis
+    return vote
+
+
+def _prior_rounds_from_state(
+    state_path: Path | None, queue: Sequence[str],
+) -> dict[str, dict[str, Any]]:
+    """큐에 오른 항목별로 직전 라운드의 표와 자가수정 노트를 모은다.
+
+    `planBodyVerification.planItems[].verdicts[]` 는 라운드마다 덮어써지므로 지금
+    거기 남아 있는 것이 직전 라운드의 판정이다. 자가수정 노트는 감사용
+    `planItems[]` 행의 `selfFixNote` 에 본문 그대로 들어 있다.
+
+    라운드 번호가 없는 표는 어느 라운드의 것인지 알 수 없어 싣지 않는다 —
+    `apply-verdicts --round` 가 필수라 계약을 지킨 행에는 항상 번호가 있다.
+    큐 순서를 그대로 따라 담아 같은 입력이 같은 바이트를 내도록 한다.
+    """
+    if state_path is None or not state_path.is_file():
+        return {}
+    state = _load_json_object(state_path)
+    audit = state.get("planItems")
+    notes = {
+        str(row["id"]): row["selfFixNote"].strip()
+        for row in (audit if isinstance(audit, list) else [])
+        if isinstance(row, Mapping)
+        and isinstance(row.get("id"), str)
+        and isinstance(row.get("selfFixNote"), str)
+        and row["selfFixNote"].strip()
+    }
+    voted = {
+        str(row["id"]): row
+        for row in _state_plan_body_items(state, state_path)
+        if isinstance(row, Mapping) and isinstance(row.get("id"), str)
+    }
+    prior: dict[str, dict[str, Any]] = {}
+    for item_id in queue:
+        row = voted.get(item_id)
+        if row is None:
+            continue
+        verdicts = [
+            vote for vote in (row.get("verdicts") or [])
+            if isinstance(vote, Mapping) and isinstance(vote.get("round"), int)
+        ]
+        if not verdicts:
+            continue
+        last = max(int(vote["round"]) for vote in verdicts)
+        entry: dict[str, Any] = {
+            "round": last,
+            "votes": [
+                _prior_vote(vote) for vote in verdicts if int(vote["round"]) == last
+            ],
+        }
+        if item_id in notes:
+            entry["selfFixNote"] = notes[item_id]
+        prior[item_id] = entry
+    return prior
+
+
+def _reverify_carry(
+    args: argparse.Namespace, queue: Sequence[str],
+) -> dict[str, Any]:
+    """라운드 2+ 봉투에 실을 직전 라운드 맥락. 실을 것이 없으면 빈 dict.
+
+    라운드 1 은 `--state` 없이 준비되고, `--state` 가 있어도 판정이 하나도
+    기록돼 있지 않으면 옮길 반대 의견이 없다. 두 경우 모두 봉투는 라운드 1 의
+    모양 그대로다.
+    """
+    prior = _prior_rounds_from_state(getattr(args, "state", None), queue)
+    if not prior:
+        return {}
+    return {"dispatchKind": "reverify", "priorRounds": prior}
+
+
+def _render_prior_round(entry: object) -> str:
+    """직전 라운드의 반대 의견을 이 항목의 블록으로 렌더한다.
+
+    앵커는 `**Prior round dissent**` 이고, 워커가 답에 적는 줄의 앵커
+    (`**Prior dissent**`, `verdict_blocks.py` 가 읽는다) 와 다른 문자열이다.
+    두 표기는 서로 다른 산출물의 서로 다른 앵커다.
+    """
+    if not isinstance(entry, Mapping):
+        return ""
+    votes = entry.get("votes")
+    if not isinstance(votes, list) or not votes:
+        return ""
+    rows = [
+        f"{_PRIOR_DISSENT_PROMPT_ANCHOR} (round {scalar(entry.get('round'))}):\n"
+    ]
+    for vote in votes:
+        if not isinstance(vote, Mapping):
+            continue
+        kind = str(vote.get("breakageKind") or "")
+        token = str(vote.get("verdict") or "")
+        if kind:
+            token = f"{token}({kind})"
+        rows.append(
+            f"- `{scalar(vote.get('worker'))}`: `{scalar(token)}` — "
+            f"`{scalar(vote.get('basis'))}`\n"
+        )
+        if vote.get("fixability"):
+            rows.append("  " + line("Fixability", vote.get("fixability")))
+    rows.append(
+        line("What the planner changed", entry.get("selfFixNote") or _NO_SELF_FIX_NOTE)
+    )
+    return "".join(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 []
+    all_items = envelope.get("items") if isinstance(envelope.get("items"), list) else []
+    items = all_items
     queue = envelope.get("dispatchQueue")
     if isinstance(queue, list):
         allowed = {item_id for item_id in queue if isinstance(item_id, str)}
@@ -556,6 +794,10 @@ def _prompt(args: argparse.Namespace) -> str:
             item for item in items
             if isinstance(item, Mapping) and item.get("id") in allowed
         ]
+    prior_rounds = (
+        envelope.get("priorRounds")
+        if isinstance(envelope.get("priorRounds"), Mapping) else {}
+    )
     rows = ["# Plan verification queue\n", line("Item count", len(items))]
     for index, item in enumerate(items, 1):
         if not isinstance(item, Mapping):
@@ -563,7 +805,13 @@ def _prompt(args: argparse.Namespace) -> str:
         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.append(_render_prior_round(prior_rounds.get(item_id)))
         rows.extend(_render_payload(item_id, item.get("payload")))
+        rows.append(_render_prior_steps(item, all_items))
+        if item_id.startswith("P-Prep-"):
+            rows.append(_PREP_OWNERSHIP_NOTE)
         split = _render_analyser_split(
             (envelope.get("tieSplits") or {}).get(item_id) if isinstance(
                 envelope.get("tieSplits"), Mapping
@@ -571,9 +819,11 @@ def _prompt(args: argparse.Namespace) -> str:
         )
         if split:
             rows.append(split)
-    body = "".join(rows)
+    body = with_response_format("".join(rows))
     if envelope.get("dispatchKind") == "critic-tie":
         return critic_tie_prompt_text(body)
+    if envelope.get("dispatchKind") == "reverify":
+        return reverify_prompt_text(body)
     return body
 
 
@@ -594,6 +844,17 @@ def _validate_prepared(args: argparse.Namespace) -> dict[str, Any]:
     )
     if actual.get("dispatchQueue") != expected_queue:
         raise PlanItemContractError("prepared dispatch queue does not match")
+    if not getattr(args, "tie_vote", False):
+        # 라운드 2+ 의 반대 의견 반입은 여기서만 검사된다. 봉투에서 빠지면
+        # 프롬프트에도 빠지고, 반대한 워커는 자기 판정을 그대로 다시 적는다.
+        expected_carry = _reverify_carry(args, expected_queue)
+        if actual.get("priorRounds") != expected_carry.get("priorRounds"):
+            raise PlanItemContractError(
+                "prepared plan items do not carry the previous round's dissent "
+                "— re-run `okstra plan-items prepare` with the same --state so "
+                "each re-dispatched item carries its `**Prior round dissent**` "
+                "block"
+            )
     return {"ok": True, "operation": "validate-prepared", "path": str(path)}
 
 
@@ -834,6 +1095,104 @@ def _stage_ledger_snapshot(run_manifest: Path | None) -> dict[str, str] | None:
     return snapshot or None
 
 
+# `plan-body-verification-<task-type-segment>-<seq>.json`. seq 는 파일 이름에만
+# 있다 — 상태 본문은 자기 run 의 순번을 담지 않는다.
+_PRIOR_STATE_NAME_RE = re.compile(
+    r"^plan-body-verification-.+-(?P<seq>\d{3,})\.json$"
+)
+
+
+class _PriorRunCarry:
+    """직전 run 에서 실제로 이월된 것. 이월을 요청하지 않았으면 만들지 않는다."""
+
+    def __init__(self, prev_seq: str, count: int) -> None:
+        self.prev_seq = prev_seq
+        self.count = count
+
+
+def _state_task_root(path: Path, *, option: str) -> Path:
+    """``<task_root>/runs/<task-type>/state/<file>`` 의 task_root.
+
+    plan-body 상태 파일은 자기 안에 task 신원을 담지 않는다(`_new_v3_state` 는
+    `schemaVersion` 과 `owner` 만 쓴다). 남은 신원은 경로뿐이므로, 이월 양쪽이
+    같은 task 의 기록인지는 여기서만 판정할 수 있다. 정규 run 경로가 아니면
+    판정할 근거가 없다는 뜻이고, 그때는 이월을 거절한다 — 판정 못 하는 신원을
+    통과시키면 남의 task 판정이 이 run 의 게이트를 결정한다.
+    """
+    try:
+        return RunRef.from_run_dir(path.parent.parent).task_root
+    except ValueError as exc:
+        raise PlanItemContractError(
+            f"{option} must be a plan-body state under "
+            f"<task-root>/runs/<task-type>/state/: {path}"
+        ) from exc
+
+
+def _carry_prior_run_verdicts(
+    args: argparse.Namespace,
+    added: list[dict[str, Any]],
+    hashes: Mapping[str, str],
+) -> _PriorRunCarry | None:
+    """직전 run 이 같은 본문에 내린 판정을 새로 시드된 행에 옮긴다.
+
+    실패한 계획 run 을 다시 돌면 판정이 하나도 넘어오지 않았다. 이월은 답변된
+    clarification 이 있는 경로에만 있고(`incremental_scope.decide_scope` 는
+    답변된 `C-NNN` 이 없으면 `full` 을 되돌려 `incremental_carry` 를 도달 불가로
+    만든다), 그래서 아무도 고치지 않은 문장이 매 재실행마다 다시 채점됐다.
+
+    행 모양은 `incremental_carry._stamp_carried` 와 같다 — `verdicts` 를 그대로
+    옮기고, `carriedForwardFromSeq` 에 직전 seq 를 찍고, `verifiedContentHash` 를
+    이번 추출 해시로 맞춘다. 그 해시가 시드의 `dispatchQueue` 계산에 그대로
+    들어가므로(`_queue_for` → `reverify_item_ids`), 이월된 행은 라운드 1 큐에서
+    빠진다. 큐를 따로 줄이지 않는 이유가 이것이다: incremental 경로가
+    `incremental_carry._recompute_dispatch_queue` 에서 쓰는 것과 같은 장치다.
+
+    id 만 같은 행은 절대 이월하지 않는다. `P-*` id 는 위치에서 나오므로 계획이
+    한 줄만 밀려도 같은 번호가 다른 문장을 가리킨다. 해시가 같아야 그 문장이
+    같은 문장이다.
+    """
+    prior = getattr(args, "prior_state", None)
+    if prior is None:
+        return None
+    if args.state is None:
+        raise PlanItemContractError("--prior-state requires --state")
+    matched = _PRIOR_STATE_NAME_RE.match(prior.name)
+    if matched is None:
+        raise PlanItemContractError(
+            "--prior-state must name a plan-body-verification-<task-type>-<seq>"
+            f".json file; the seq is what a carried row is tagged with: {prior}"
+        )
+    if _state_task_root(prior, option="--prior-state") != _state_task_root(
+        args.state, option="--state"
+    ):
+        raise PlanItemContractError(
+            f"--prior-state belongs to another task than --state: {prior}"
+        )
+    prev_seq = matched.group("seq")
+    prior_rows = {
+        str(row["id"]): row
+        for row in _state_plan_body_items(_load_json_object(prior), prior)
+        if isinstance(row, Mapping) and isinstance(row.get("id"), str)
+    }
+    count = 0
+    for row in added:
+        item_id = row.get("id")
+        previous = prior_rows.get(item_id)
+        if previous is None:
+            continue
+        verdicts = previous.get("verdicts")
+        if not isinstance(verdicts, list) or not verdicts:
+            continue
+        current_hash = hashes.get(item_id)
+        if not current_hash or previous.get("verifiedContentHash") != current_hash:
+            continue
+        row["verdicts"] = copy.deepcopy(verdicts)
+        row["carriedForwardFromSeq"] = prev_seq
+        row["verifiedContentHash"] = current_hash
+        count += 1
+    return _PriorRunCarry(prev_seq, count)
+
+
 def _seed(args: argparse.Namespace) -> dict[str, Any]:
     """Create the `planBodyVerification.planItems[]` rows a round lands in.
 
@@ -847,6 +1206,10 @@ def _seed(args: argparse.Namespace) -> dict[str, Any]:
     Idempotent by id. An existing row keeps everything it carries — verdicts
     already applied, `carriedForwardFromSeq`, `selfFixNote` — because a re-seed
     between rounds must not erase the round before it.
+
+    `--prior-state` extends that to the previous *run*: a newly seeded item
+    whose text the previous run already judged inherits its verdicts instead of
+    entering round 1 again (`_carry_prior_run_verdicts`).
     """
     source = _plan_source(args)
     extracted = _envelope(source)["items"]
@@ -887,6 +1250,7 @@ def _seed(args: argparse.Namespace) -> dict[str, Any]:
         for item in extracted
         if item["id"] not in known
     ]
+    carried = _carry_prior_run_verdicts(args, added, hashes)
     recorded.extend(added)
     for row in recorded:
         item_id = row.get("id") if isinstance(row, Mapping) else None
@@ -932,13 +1296,22 @@ def _seed(args: argparse.Namespace) -> dict[str, Any]:
         _planning(source), extracted,
     )
     write_json_atomic(target, data)
-    return {
+    result = {
         "ok": True,
         "operation": "seed",
         "path": str(target),
         "seeded": len(added),
         "existing": len(known),
     }
+    if carried is not None:
+        result["carried"] = carried.count
+        result["carriedForwardFromSeq"] = carried.prev_seq
+        if carried.count:
+            # 시드는 prepare **뒤에** 돈다(리드 계약 step 1). 이월이 상태의
+            # 큐만 줄이면 `plan-items prompt` 가 읽는 형제 파일은 여전히 전량
+            # 이라, 워커는 직전 run 이 이미 판정한 행을 다시 받는다.
+            sync_prepared_dispatch_queue(target, data)
+    return result
 
 
 def _judged_row(row: Mapping[str, Any], project_root: Path | None) -> dict[str, Any]:
@@ -1061,7 +1434,14 @@ def _append_item_verdicts(
 
 
 def _gate_module() -> Any:
-    path = Path(__file__).parents[2] / "validators" / "validate-run.py"
+    # 부모 개수를 세면 체크아웃에서만 맞는다 — 설치본은 패키지가
+    # `~/.okstra/lib/python/` 이라 validators 가 `~/.okstra/lib/` 아래다.
+    from .paths import RUN_VALIDATOR_RELATIVE, find_asset_root
+
+    root = find_asset_root(RUN_VALIDATOR_RELATIVE)
+    if root is None:
+        raise PlanItemContractError("cannot locate plan-body gate authority")
+    path = root.joinpath(*RUN_VALIDATOR_RELATIVE)
     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")
@@ -1088,12 +1468,7 @@ def _round_snapshot(item: Mapping[str, Any], round_number: int) -> dict[str, Any
 
 
 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)
+    module = _gate_module()
     summary = module.plan_body_gate_summary({
         "implementationPlanning": {"planBodyVerification": dict(verification)}
     })
@@ -1105,8 +1480,13 @@ def _plan_gate_summary(verification: Mapping[str, Any]) -> dict[str, Any]:
 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")
+    if args.self_fix_group and not args.self_fix_stop_reason:
+        raise PlanItemContractError(
+            "--self-fix-group requires --self-fix-stop-reason — a self-fix "
+            "round has to say why the loop stops, and a defaulted "
+            "`all-resolved` is the one value that later forbids promoting the "
+            "items it left unresolved"
+        )
     for raw in args.self_fix_note:
         item_id, separator, filename = raw.partition("=")
         if not separator or not item_id or not filename:
@@ -1137,7 +1517,12 @@ def _record_self_fixes(args: argparse.Namespace, audit: list[object], verificati
     if groups:
         verification["selfFixGroups"] = groups
         verification["selfFixRoundsApplied"] = args.round_number
-        verification["selfFixStopReason"] = args.self_fix_stop_reason or "all-resolved"
+    if args.self_fix_stop_reason:
+        # 원인 그룹 없이 중단 사유만 기록하는 라운드는 `selfFixRoundsApplied` 를
+        # 건드리지 않는다. `validate-run.py` `_validate_self_fix_grouping` 이
+        # `max(selfFixGroups[].round) == selfFixRoundsApplied` 를 요구하므로,
+        # 그룹 없이 올린 숫자는 통과할 수 있는 값이 없는 상태를 만든다.
+        verification["selfFixStopReason"] = args.self_fix_stop_reason
 
 
 def _round_inputs(args: argparse.Namespace) -> tuple[dict[str, Any], list[dict[str, Any]], list[object], list[object]]:
@@ -1177,14 +1562,22 @@ def _record_audit_round(audit: list[object], snapshots: Mapping[str, dict[str, A
             item["rounds"].append(snapshots[str(item["id"])])
 
 
-def _participant_counts(args: argparse.Namespace, snapshots: Mapping[str, dict[str, Any]]) -> tuple[set[str], int, int]:
+def _participant_counts(
+    manifest: Mapping[str, Any],
+    snapshots: Mapping[str, dict[str, Any]],
+    items: Sequence[Mapping[str, Any]],
+) -> tuple[set[str], int, int]:
+    """이번 라운드의 투표자, run 전체의 분석자 수, 로스터 크기.
+
+    `workers` 는 uniformVerifiers 를 뽑기 위한 이번 라운드 큐의 투표자다.
+    `voting` 은 게이트 산술의 분모이므로 라운드 큐가 아니라 run 전체를 세고,
+    검증기와 같은 함수(`voting_analyser_keys`)를 쓴다 — 종전에는 이쪽만 라운드
+    큐를 세서, critic 이 동수만 가른 라운드에서 기록값 0 과 검증기 재계산값이
+    갈렸다.
+    """
     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")
+    voting = voting_analyser_keys(items)
+    assignments = 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)
@@ -1192,6 +1585,34 @@ def _participant_counts(args: argparse.Namespace, snapshots: Mapping[str, dict[s
     return workers, len(voting), rostered
 
 
+def _reject_round_gap(history: list[Any], round_number: int) -> None:
+    """앞 라운드의 결과가 기록되기 전에 다음 라운드를 닫지 못하게 한다.
+
+    `roundCount` 는 이 인자의 최대값이라 건너뛴 라운드까지 세지만, 이력에는
+    행이 남지 않는다. 그 불일치는 phase 끝에서 활동 건수 검증이 잡아내는데
+    (`recorded=3` vs `rounds=4`), 그때는 라운드를 다시 닫을 방법이 없어 실행
+    전체가 막힌다. 빠진 라운드의 판정도 그대로 사라진다 — 다음 라운드는 그것을
+    settle 하러 존재하므로 근거 없는 표결이 된다.
+
+    실측(2026-08-27, `fontsninja-v3-site` `dev-10341`): 이력이 1·2·4 이고
+    `roundCount` 가 4 였다.
+    """
+    recorded = {
+        row.get("round")
+        for row in history
+        if isinstance(row, Mapping) and isinstance(row.get("round"), int)
+    }
+    missing = [
+        number for number in range(1, round_number) if number not in recorded
+    ]
+    if missing:
+        raise PlanItemContractError(
+            f"round {round_number} cannot be completed while round(s) "
+            f"{', '.join(str(number) for number in missing)} have no history "
+            "entry — complete them in order so each round's verdict is recorded"
+        )
+
+
 def _complete_round(args: argparse.Namespace) -> dict[str, Any]:
     if args.round_number < 1:
         raise PlanItemContractError("--round must be 1 or greater")
@@ -1202,20 +1623,31 @@ def _complete_round(args: argparse.Namespace) -> dict[str, Any]:
             raise PlanItemContractError(
                 "advisory plan-body gating allows one verification round"
             )
-        if args.self_fix_group or args.self_fix_note:
+        if args.self_fix_group or args.self_fix_note or args.self_fix_stop_reason:
             raise PlanItemContractError(
                 "advisory plan-body gating forbids the self-fix loop"
             )
+    _reject_round_gap(history, args.round_number)
     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
-    ]
+    manifest = _load_json_object(args.run_manifest)
+    workers, voting, rostered = _participant_counts(manifest, snapshots, current)
+    # critic-tie 는 큐 일부에만 표를 남긴다. 합집합 워커를 모든 행에
+    # 강제하면 표 없는 행에서 KeyError 가 난다. 모든 행에 같은 판정이
+    # 있을 때만 uniform 이다.
+    uniform = []
+    for worker in workers:
+        values = [
+            row["votes"][worker]
+            for row in snapshots.values()
+            if worker in row["votes"]
+        ]
+        if len(values) != len(snapshots) or len(set(values)) != 1:
+            continue
+        uniform.append(
+            {"worker": worker, "verdict": values[0], "itemCount": len(values)}
+        )
     verification.update({"roundCount": max(int(verification.get("roundCount", 0)), args.round_number),
                          "gateResult": gate, "gateBlockedBy": summary["blockedBy"],
                          # 무엇이 막았는지는 `gateBlockedBy` 가, 무엇이 막지 않았고
@@ -1235,7 +1667,9 @@ def _complete_round(args: argparse.Namespace) -> dict[str, Any]:
         "operation": "complete-round",
         "path": str(args.state),
         "gateResult": gate,
-        "nextDispatch": next_dispatch(current, payloads).as_dict(),
+        "nextDispatch": next_dispatch(
+            current, payloads, critic_rostered=critic_is_rostered(manifest),
+        ).as_dict(),
     }
 
 
@@ -1258,10 +1692,26 @@ def _prepared_payloads(run_manifest: Path | None) -> dict[str, dict[str, Any]]:
     }
 
 
+def _rostered_critic(run_manifest: Path | None) -> bool:
+    """매니페스트 없이 부르면 종전대로 critic 이 있다고 본다.
+
+    없다고 단정하면 critic 을 둔 run 이 가를 수 있는 동수까지 사용자에게
+    넘긴다 — 그쪽이 더 나쁜 오답이다. 리드 계약은 `next-dispatch` 를
+    `--run-manifest` 와 함께 부르도록 못박고 있다
+    (`prompts/lead/plan-body-verification.md` §"Round protocol" step 6).
+    """
+    if run_manifest is None:
+        return True
+    return critic_is_rostered(_load_json_object(run_manifest))
+
+
 def _state_next_dispatch(args: argparse.Namespace) -> NextDispatch:
     _data, current, _audit, _history = _round_inputs(args)
-    payloads = _prepared_payloads(getattr(args, "run_manifest", None))
-    return next_dispatch(current, payloads)
+    run_manifest = getattr(args, "run_manifest", None)
+    payloads = _prepared_payloads(run_manifest)
+    return next_dispatch(
+        current, payloads, critic_rostered=_rostered_critic(run_manifest),
+    )
 
 
 def _next_dispatch(args: argparse.Namespace) -> dict[str, Any]: