okstra 0.179.2 → 0.183.2

package/runtime/validators/validate-run.py

@@ -2890,7 +2890,7 @@ def validate_report(
     report_data: Mapping[str, Any] | None = None,
     team_state: Mapping[str, Any] | None = None,
 ) -> None:
-    if (report_data or {}).get("schemaVersion") == "2.0":
+    if (report_data or {}).get("schemaVersion") in {"2.0", "3.0"}:
         _validate_v2_report(report_data or {}, failures, team_state=team_state)
         return
 
@@ -2997,6 +2997,9 @@ def validate_report(
 
 
 _REPORT_BASENAME_SEQ_RE = re.compile(r"-(?P<seq>\d{3})(?:\.data)?\.(?:md|json)$")
+_REPORT_BASENAME_TASK_TYPE_RE = re.compile(
+    r"^final-report-(?P<task_type>[a-z][a-z-]*?)-\d{3}(?:\.data)?\.(?:md|json)$"
+)
 
 
 def _report_run_seq(report_path: Path) -> str | None:
@@ -3007,6 +3010,25 @@ def _report_run_seq(report_path: Path) -> str | None:
     return match.group("seq") if match else None
 
 
+def _report_task_type(report_path: Path) -> str:
+    """This run's task type, read off `final-report-<task-type>-<seq>`.
+
+    The report's own `header.taskType` is the first source, but it is not
+    always reachable. `report_narrative._allowed_top_level()` has no `header` —
+    it is not a writer-owned block — so a gate scored from a narrative, which is
+    the only input a report-contract-3.0 run has before assembly, carries no
+    task type at all. Globbing with an empty one matched nothing and reported
+    every verdict as unbacked under a `runs//worker-results/` path.
+
+    The filename carries it in every caller: the full-run path passes the report
+    itself, and `_report_path_for_state` builds the same canonical name from the
+    state file. Returns `""` when the name does not carry one, so a caller can
+    tell "not resolvable" from a real task type.
+    """
+    match = _REPORT_BASENAME_TASK_TYPE_RE.match(report_path.name)
+    return match.group("task_type") if match else ""
+
+
 def validate_worker_results_audit(
     report_path: Path,
     task_type: str,
@@ -3090,29 +3112,21 @@ PLAN_VERIFY_GATE_VALUES = (
 # the approved-frontmatter gate (the `.match` would otherwise return None).
 _FRONTMATTER_BLOCK_RE = re.compile(r"\A\ufeff?\s*---\n(.*?)\n---\n", re.DOTALL)
 def _validate_verdict_card_fields(data: dict, failures: list[str]) -> None:
-    """`verdictCard.direction` must byte-match its authoritative home in §7.
-
-    The markdown check above compares only the Verdict Token, so a Card whose
-    Direction contradicted §7 shipped silently. `nextStep` is deliberately NOT
-    compared: every shipped fixture authors the Card's cell as the actionable
-    command (`/okstra-run task-type=release-handoff`) while §7 states the same
-    action as prose ("Proceed to release-handoff."), so a byte-match rule there
-    would reject the reference reports.
-    """
+    """Verdict Card의 정본 표시 값이 §7의 값과 같은지 모두 검사한다."""
     card = data.get("verdictCard")
     final = data.get("finalVerdict")
     if not isinstance(card, dict) or not isinstance(final, dict):
         return
-    card_value = str(card.get("direction") or "").strip()
-    final_value = str(final.get("direction") or "").strip()
-    if not card_value or not final_value or card_value == final_value:
-        return
-    failures.append(
-        f"final-report data.json: verdictCard.direction `{card_value}` does not "
-        f"match finalVerdict.direction `{final_value}` — the Card is a "
-        "non-authoritative index and MUST byte-match §7 "
-        "(_common-contract.md Verdict Card)."
-    )
+    for field in ("finalConclusion", "direction", "nextStep"):
+        card_value = str(card.get(field) or "").strip()
+        final_value = str(final.get(field) or "").strip()
+        if not card_value or not final_value or card_value == final_value:
+            continue
+        failures.append(
+            f"final-report data.json: verdictCard.{field} value `{card_value}` "
+            f"does not match finalVerdict.{field} value `{final_value}` — the "
+            "Card is a non-authoritative index and must preserve the §7 value."
+        )
 
 
 def _route_target_matches(value: Any, target: str, *, command: bool) -> bool:
@@ -3585,8 +3599,12 @@ def validate_final_report_data(
 # namespaced audit ref (claude:F-005), or a §section reference (§5.4) — any one
 # satisfies "this claim is anchored". A bare brief/worker ID (RC-*/RF-*/F-*) is
 # handled separately by `_validate_no_opaque_id_references`.
-_EVIDENCE_TOKEN = re.compile(
-    r"[\w./-]+\.\w+:\d+|\b[A-Z]{1,3}(?:-[a-z]+)?-\d+\b|§\s*\d")
+_PATH_LINE_EVIDENCE_TOKEN = re.compile(r"[\w./-]+\.\w+:\d+")
+_SECTION_EVIDENCE_TOKEN = re.compile(r"§\s*\d")
+_IN_REPORT_ID_TOKEN = re.compile(r"\b[A-Z]{1,3}(?:-[a-z]+)?-\d+\b")
+_NAMESPACED_EVIDENCE_TOKEN = re.compile(
+    r"(?<![\w-])[a-z][a-z0-9-]*:[A-Z]{1,3}(?:-[a-z]+)?-\d+(?![\w-])"
+)
 # Explicit "I don't know" escapes — anti-fabrication's other valid answer.
 _INSUFFICIENCY_MARKERS = (
     "근거 불충분", "근거가 불충분", "증거 불충분", "증거가 불충분",
@@ -3596,6 +3614,44 @@ _INSUFFICIENCY_MARKERS = (
 _RATIONALE_FIELDS = ("motivation", "problem", "approach", "justification")
 
 
+def _report_reference_ids(data: Mapping[str, Any]) -> set[str]:
+    references: set[str] = set()
+
+    def visit(value: Any, key: str = "") -> None:
+        if isinstance(value, Mapping):
+            for child_key, child_value in value.items():
+                visit(child_value, str(child_key))
+            return
+        if isinstance(value, list):
+            for child in value:
+                visit(child, key)
+            return
+        if not isinstance(value, str):
+            return
+        if (key == "id" or key.endswith("Id")) and _IN_REPORT_ID_TOKEN.fullmatch(value):
+            references.add(value)
+        if key == "sourceItems":
+            references.update(_NAMESPACED_EVIDENCE_TOKEN.findall(value))
+
+    visit(data)
+    return references
+
+
+def _rationale_reference_status(
+    text: str,
+    known_references: set[str],
+) -> tuple[bool, tuple[str, ...]]:
+    if _PATH_LINE_EVIDENCE_TOKEN.search(text) or _SECTION_EVIDENCE_TOKEN.search(text):
+        return True, ()
+    namespaced = tuple(_NAMESPACED_EVIDENCE_TOKEN.findall(text))
+    without_namespaced = _NAMESPACED_EVIDENCE_TOKEN.sub("", text)
+    report_ids = tuple(_IN_REPORT_ID_TOKEN.findall(without_namespaced))
+    candidates = (*namespaced, *report_ids)
+    if any(candidate in known_references for candidate in candidates):
+        return True, ()
+    return False, tuple(dict.fromkeys(candidates))
+
+
 def _validate_rationale_evidence(data: dict, failures: list[str]) -> None:
     """Every `## 작업 배경과 근거` field must anchor its claim: carry at least
     one evidence reference (path:line, report ID, §section) OR an explicit
@@ -3605,14 +3661,25 @@ def _validate_rationale_evidence(data: dict, failures: list[str]) -> None:
     rationale = data.get("rationale")
     if not isinstance(rationale, dict):
         return  # absence/shape is the schema's job; don't double-report.
+    known_references = _report_reference_ids(data)
     for field in _RATIONALE_FIELDS:
         text = rationale.get(field)
         if not isinstance(text, str):
             continue
-        if _EVIDENCE_TOKEN.search(text):
+        grounded, unknown_references = _rationale_reference_status(
+            text,
+            known_references,
+        )
+        if grounded:
             continue
         if any(m in text.lower() for m in _INSUFFICIENCY_MARKERS):
             continue
+        if unknown_references:
+            failures.append(
+                f"final-report data.json: rationale.{field} cites unknown "
+                "in-report reference(s): " + ", ".join(unknown_references) + "."
+            )
+            continue
         failures.append(
             f"final-report data.json: rationale.{field} cites no evidence "
             f"(expected a path:line, an in-report ID like C-001, or a §"
@@ -3787,6 +3854,42 @@ def _is_variation_point_item(item: dict) -> bool:
     return str(item.get("id") or "").upper().startswith("P-VAR")
 
 
+def _single_vote_dissents(item: dict, kinds: set[str]) -> list[dict]:
+    """이 항목에서 1표 차단을 주장하는 DISAGREE 행들."""
+    return [
+        row for row in (item.get("verdicts") or [])
+        if isinstance(row, dict)
+        and str(row.get("verdict") or "").strip().upper() == "DISAGREE"
+        and str(row.get("breakageKind") or "").strip().lower() in kinds
+    ]
+
+
+def _single_vote_block_survives(item: dict, kinds: set[str]) -> bool:
+    """1표 차단이 성립하는지.
+
+    1표 차단에는 근거가 있다 — 명시된 두 인용이 서로 모순이라는 것은 한 명이
+    실측으로 확정할 수 있는 사실이고, 사실을 다수결로 기각하면 안 된다. 문제는
+    1표라는 것이 아니라 **1표에 재현 요구가 없었다**는 것이다. "이 경로는 존재하지
+    않는다" 라고 쓰기만 하면 그대로 차단이 됐다.
+
+    이제 주장이 스스로 `fact` 를 선언하고 okstra 가 그것을 재현했을 때만 1표로
+    막는다. 선언했는데 재현되지 않았거나 `judgement` 였다면 정족수로 내려간다.
+
+    아무 행도 `claimKind` 를 선언하지 않았으면 종전대로 막는다. 그 필드를 실을 수
+    없던 시절의 판정을 뒤에서 뒤집지 않기 위해서다 — 도입은 완화 방향으로만
+    작동하고, 선언한 주장만 재현을 요구받는다.
+    """
+    dissents = _single_vote_dissents(item, kinds)
+    declared = [row for row in dissents if row.get("claimKind")]
+    if not declared:
+        return bool(dissents)
+    return any(
+        str(row.get("claimKind") or "") == "fact"
+        and str(row.get("reproductionResult") or "") == "reproduced"
+        for row in declared
+    )
+
+
 def _classify_plan_item_gate(item: dict) -> str:
     """Recompute one plan item's gate class from its per-worker verdicts,
     per `prompts/lead/plan-body-verification.md` "Round protocol". Returns one of
@@ -3831,8 +3934,11 @@ def _classify_plan_item_gate(item: dict) -> str:
     # `a` for any item except `P-Var-*` (majority-gated, see
     # `_is_variation_point_item`); `f` only for P-Req items (requirement coverage).
     is_req = str(item.get("id") or "").upper().startswith("P-REQ")
-    if not _is_variation_point_item(item) and (
-        blocking_kinds & _SINGLE_VOTE_BLOCKING_KINDS or (is_req and "f" in blocking_kinds)
+    single_vote_kinds = set(_SINGLE_VOTE_BLOCKING_KINDS) | ({"f"} if is_req else set())
+    if (
+        not _is_variation_point_item(item)
+        and blocking_kinds & single_vote_kinds
+        and _single_vote_block_survives(item, single_vote_kinds)
     ):
         # "One confirmed DISAGREE" presupposes the item was actually
         # cross-verified. When the peer returned a non-result nothing confirmed
@@ -3848,9 +3954,58 @@ def _classify_plan_item_gate(item: dict) -> str:
     # made the gate stricter than a healthy roster would.
     if len(non_error) >= 2 and len(blocking_disagree) > len(agree):
         return "majority-disagree"
+    # A tie is not consensus, and until now it read as one. The majority test is
+    # strict, so an even panel splitting 1-AGREE / 1-DISAGREE on a blocking kind
+    # fell through to `has-dissent` and the gate passed — the dissent recorded
+    # and never acted on. An even panel is not only the two-analyser roster: one
+    # UNVERIFIABLE or one lost dispatch turns any roster even for that item.
+    # Send the split back for a round; if it survives a round that judged the
+    # rewritten text, nothing further is going to settle it and the user decides.
+    # `_validate_unresolved_tie_was_reverified` is what makes the first branch
+    # more than a label — `needs-reverify` folds into `passed-with-dissent`.
+    if len(non_error) >= 2 and len(blocking_disagree) == len(agree):
+        if _max_verdict_round(item) >= _TIE_SETTLED_ROUND:
+            return "majority-disagree"
+        return "needs-reverify"
     return "has-dissent"
 
 
+# 동수를 한 번 재검증한 뒤에도 갈리면 그때는 사용자가 판단한다. 초기 검증이
+# 라운드 1이고 자가수정 뒤의 표적 재검증이 라운드 2이므로, 라운드 2 이상의
+# 판정이 붙은 동수는 이미 한 번 돌아온 것이다.
+_TIE_SETTLED_ROUND = 2
+
+
+def _max_verdict_round(item: dict) -> int:
+    """이 항목의 판정이 붙은 가장 늦은 라운드. 스탬프가 없으면 1.
+
+    `apply-verdicts --round <N>` 이 각 행을 찍는다. 스탬프가 없는 행은 자가수정이
+    한 번도 없었던 run 에서만 나오고, 그때는 라운드가 하나뿐이다.
+    """
+    rounds = [
+        verdict["round"]
+        for verdict in (item.get("verdicts") or [])
+        if isinstance(verdict, dict)
+        and isinstance(verdict.get("round"), int)
+        and not isinstance(verdict.get("round"), bool)
+    ]
+    return max(rounds, default=1)
+
+
+def _is_unsettled_tie(item: dict) -> bool:
+    """아직 재검증되지 않은 동수 항목."""
+    return (
+        _classify_plan_item_gate(item) == "needs-reverify"
+        and _max_verdict_round(item) < _TIE_SETTLED_ROUND
+        and len([
+            verdict for verdict in (item.get("verdicts") or [])
+            if isinstance(verdict, dict)
+            and str(verdict.get("verdict") or "").strip().upper()
+            not in ("", "VERIFICATION-ERROR")
+        ]) >= 2
+    )
+
+
 def _disagree_breakage_kinds(item: dict) -> set[str]:
     return {
         str(v.get("breakageKind") or "").strip().lower()
@@ -3980,6 +4135,103 @@ def _is_dissent_downgraded(
     )
 
 
+_STARTABLE_STAGE_STATUSES = frozenset({"ready", "active"})
+
+
+def _stage_scope_bucket(item: dict, pbv: dict) -> str:
+    """Whether this item has standing to block the stage about to start.
+
+    The plan covers every stage; implementation runs one at a time. Judging all
+    of them at once means a defect in a stage nobody has reached, or in one
+    already frozen, stops the next stage from starting — and a frozen stage's
+    item cannot be fixed at all, because the Stage Ledger forbids editing its
+    commands. Measured on one run, 9 of 13 blockers were that shape, 6 of them
+    frozen.
+
+    Returns `in-scope` (may block), `observed` (only frozen stages), or
+    `deferred` (only stages not yet startable). Anything unresolvable is
+    `in-scope`: an absent ledger is no basis to narrow, and an item with no
+    `stageScope` belongs to the plan as a whole — `P-Opt-*` and `P-Var-*` live
+    there permanently, and scoping them out would stop an unrequested-work
+    verdict from blocking a start.
+    """
+    ledger = pbv.get("stageLedger")
+    if not isinstance(ledger, dict) or not ledger:
+        return "in-scope"
+    scope = item.get("stageScope")
+    stages = [
+        value for value in scope
+        if isinstance(value, int) and not isinstance(value, bool)
+    ] if isinstance(scope, list) else []
+    if not stages:
+        return "in-scope"
+    statuses = {str(ledger.get(str(stage)) or "") for stage in stages}
+    if statuses & _STARTABLE_STAGE_STATUSES:
+        return "in-scope"
+    return "observed" if "done" in statuses else "deferred"
+
+
+def _set_aside_reason(item: dict, pbv: dict, accepted_item_ids: set[str]) -> str | None:
+    """Why this item stopped blocking, or ``None`` if it never did.
+
+    A gate that passes while defects were set aside has to say which ones and on
+    what grounds. Without that the two halves of the acceptance condition — the
+    next stage can start, and the known risks are written down — collapse into
+    the first, and a defect deferred for a good reason is indistinguishable in
+    the record from one nobody found.
+    """
+    raw = (
+        "has-dissent"
+        if _is_dissent_downgraded(item, pbv, accepted_item_ids)
+        else _classify_plan_item_gate(item)
+    )
+    if raw != "majority-disagree":
+        return None
+    bucket = _stage_scope_bucket(item, pbv)
+    if bucket != "in-scope":
+        return bucket
+    return "record" if str(item.get("block") or "") == "record" else None
+
+
+def _set_aside_register(pbv: dict, accepted_item_ids: set[str]) -> list[dict]:
+    """Every set-aside item, in id order, as the gate records them."""
+    register = [
+        {"id": str(item.get("id") or ""), "reason": reason}
+        for item in (pbv.get("planItems") or [])
+        if isinstance(item, dict)
+        for reason in [_set_aside_reason(item, pbv, accepted_item_ids)]
+        if reason is not None
+    ]
+    return sorted(register, key=lambda row: row["id"])
+
+
+def _plan_item_gate_class(
+    item: dict, pbv: dict, accepted_item_ids: set[str],
+) -> str:
+    """The gate class for one item, after stage scope is applied.
+
+    An out-of-scope blocker is not dropped — it lands on `has-dissent`, so the
+    gate still reads `passed-with-dissent` rather than `passed` and the record
+    says something is outstanding. Silently scoring it `passed` would hide the
+    defect instead of deferring it.
+    """
+    classification = (
+        "has-dissent"
+        if _is_dissent_downgraded(item, pbv, accepted_item_ids)
+        else _classify_plan_item_gate(item)
+    )
+    if classification != "majority-disagree":
+        return classification
+    if _stage_scope_bucket(item, pbv) != "in-scope":
+        return "has-dissent"
+    if str(item.get("block") or "") == "record":
+        # 자기 기록의 부정확은 기록되고 다음 run 의 입력이 되지, 구현 착수를 막지
+        # 않는다. 요구사항이 실제로 안 만들어지는 경우는 이 경로가 아니라
+        # `_independent_coverage_blockers` 의 `coverage-gap` 이 계속 막는다.
+        return "has-dissent"
+    return classification
+
+
 def _recompute_plan_body_gate(
     pbv: dict,
     accepted_item_ids: set[str] | None = None,
@@ -3989,9 +4241,7 @@ def _recompute_plan_body_gate(
     no plan items to judge (disabled / empty round)."""
     accepted = accepted_item_ids or set()
     classes = [
-        "has-dissent"
-        if _is_dissent_downgraded(it, pbv, accepted)
-        else _classify_plan_item_gate(it)
+        _plan_item_gate_class(it, pbv, accepted)
         for it in (pbv.get("planItems") or [])
         if isinstance(it, dict)
     ]
@@ -4013,6 +4263,60 @@ def _recompute_plan_body_gate(
     return "passed"
 
 
+def _validate_set_aside_register(
+    data: dict, failures: list[str], accepted_item_ids: set[str] | None = None,
+) -> None:
+    """A gate that set defects aside must say which ones and why.
+
+    The gate stops blocking on a defect that belongs to a frozen or unreached
+    stage, or to the plan's own record. That is the point — but a reader of the
+    report cannot tell such a defect from one that was never raised unless the
+    run writes the register down. `gateBlockedBy` names what blocked; this names
+    what did not, and why.
+
+    Declared against recomputed, the same shape as `_validate_gate_blocked_by`:
+    a hand-written register drifts from the verdicts it claims to summarise, and
+    the drift is invisible precisely because nothing else reads it.
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    pbv = ip.get("planBodyVerification")
+    if not isinstance(pbv, dict):
+        return
+    round_count = pbv.get("roundCount")
+    if not isinstance(round_count, int) or round_count < 1:
+        return
+    accepted = (
+        _resolved_noncritical_dissent_ids(data)
+        if accepted_item_ids is None
+        else accepted_item_ids
+    )
+    expected = _set_aside_register(pbv, accepted)
+    declared_raw = pbv.get("setAside")
+    declared = sorted(
+        (
+            {"id": str(row.get("id") or ""), "reason": str(row.get("reason") or "")}
+            for row in declared_raw
+            if isinstance(row, dict)
+        ),
+        key=lambda row: row["id"],
+    ) if isinstance(declared_raw, list) else None
+    if declared == expected:
+        return
+    if declared is None and not expected:
+        return
+    failures.append(
+        "final-report data.json: planBodyVerification.setAside is "
+        f"{declared!r} but the recorded verdicts set aside {expected!r}. The "
+        "gate stopped blocking on those items — a frozen or unreached stage, or "
+        "the plan's own record — and a run that passes without listing them "
+        "leaves a deferred defect indistinguishable from one nobody raised. "
+        "Re-record the round with `okstra plan-items complete-round`, which "
+        "writes this register from the same computation."
+    )
+
+
 def _validate_plan_body_gate_recompute(
     data: dict,
     failures: list[str],
@@ -4072,6 +4376,29 @@ def _blocks_approval(row: dict) -> bool:
     return status == "documented-deviation" and disposition.startswith("blocked C-")
 
 
+def _plan_item_clarification_ids(item: object) -> set[str]:
+    """이 plan item 이 가리키는 `C-NNN` 들.
+
+    계약 v3 에서 리포트 정본의 이 링크는 복수형 `clarificationRefs[]` 다 —
+    `report_assembly` 가 활동 원장의 `clarificationRefs[]` + `planItemIds[]` 에서
+    유도해 쓰고, v3.0 스키마의 `planItems[]` 는 `additionalProperties: false` 아래
+    그 이름만 허용한다. 단수형 `clarificationId` 는 lead 가 쓰는 plan-body 상태
+    파일과 v2 리포트에 남아 있으므로 읽을 때는 둘 다 받는다
+    (`incremental_scope` 가 이미 그렇게 한다).
+    """
+    if not isinstance(item, dict):
+        return set()
+    ids = {
+        str(ref).strip()
+        for ref in (item.get("clarificationRefs") or [])
+        if str(ref).strip()
+    }
+    single = item.get("clarificationId")
+    if isinstance(single, str) and single.strip():
+        ids.add(single.strip())
+    return ids
+
+
 def _plan_body_promoted_clarification_ids(pbv: dict) -> set[str]:
     """`C-NNN` ids this run's own plan-body round created by promoting a
     majority-disagree item (step 8). Used to break the Requirement Coverage
@@ -4079,11 +4406,9 @@ def _plan_body_promoted_clarification_ids(pbv: dict) -> set[str]:
     the gate already counted, rather than contributing an independent one.
     """
     return {
-        item["clarificationId"].strip()
+        clarification_id
         for item in (pbv.get("planItems") or [])
-        if isinstance(item, dict)
-        and isinstance(item.get("clarificationId"), str)
-        and item["clarificationId"].strip()
+        for clarification_id in _plan_item_clarification_ids(item)
     }
 
 
@@ -4536,6 +4861,8 @@ def _validate_approval_dispositions(
     row: dict,
     context: dict,
     failures: list[str],
+    *,
+    schema_version: str = "2.0",
 ) -> None:
     row_id = str(row.get("id") or "<unknown>")
     classification = str(context.get("classification") or "")
@@ -4546,7 +4873,11 @@ def _validate_approval_dispositions(
         for index, option in enumerate(row.get("options") or [])
         if isinstance(option, dict)
     )
-    resolution = context.get("resolution")
+    resolution = (
+        row.get("resolution")
+        if schema_version == "3.0"
+        else context.get("resolution")
+    )
     if isinstance(resolution, dict):
         candidates.append(("resolution.disposition", resolution.get("disposition")))
     for field, disposition in candidates:
@@ -4562,11 +4893,17 @@ def _validate_resolved_approval(
     row: dict,
     context: dict,
     failures: list[str],
+    *,
+    schema_version: str = "2.0",
 ) -> None:
     if row.get("status") != "resolved":
         return
     row_id = str(row.get("id") or "<unknown>")
-    resolution = context.get("resolution")
+    resolution = (
+        row.get("resolution")
+        if schema_version == "3.0"
+        else context.get("resolution")
+    )
     if not isinstance(resolution, dict):
         failures.append(
             f"final-report data.json: resolved approval clarification `{row_id}` "
@@ -4882,6 +5219,9 @@ def _validate_approval_context(
 ) -> None:
     if not _is_activity_contract_v1_planning(run_manifest):
         return
+    if data.get("schemaVersion") == "3.0":
+        _validate_v3_approval_context(data, failures)
+        return
     ip = data.get("implementationPlanning") or {}
     pbv = ip.get("planBodyVerification") or {}
     plan_items_by_id = {
@@ -4991,6 +5331,81 @@ def _validate_approval_context(
             )
 
 
+def _v3_expected_plan_backlinks(
+    activities: Mapping[str, dict],
+) -> dict[str, set[str]]:
+    expected: dict[str, set[str]] = {}
+    for activity in activities.values():
+        refs = {str(value) for value in activity.get("clarificationRefs") or []}
+        for item_id in activity.get("planItemIds") or []:
+            expected.setdefault(str(item_id), set()).update(refs)
+    return expected
+
+
+def _validate_v3_plan_backlinks(
+    data: dict, activities: Mapping[str, dict], failures: list[str],
+) -> None:
+    expected = _v3_expected_plan_backlinks(activities)
+    planning = data.get("implementationPlanning") or {}
+    verification = planning.get("planBodyVerification") or {}
+    for item in verification.get("planItems") or []:
+        if not isinstance(item, dict):
+            continue
+        item_id = str(item.get("id") or "")
+        actual = {str(value) for value in item.get("clarificationRefs") or []}
+        if actual != expected.get(item_id, set()):
+            failures.append(
+                f"final-report data.json: plan item `{item_id}` clarificationRefs "
+                "do not match activity-ledger backlinks."
+            )
+
+
+def _validate_v3_resolution_links(
+    row: dict, activities: Mapping[str, dict], failures: list[str],
+) -> None:
+    resolution = row.get("resolution")
+    if not isinstance(resolution, dict):
+        return
+    row_id = str(row.get("id") or "<unknown>")
+    for activity_id in resolution.get("checkRefs") or []:
+        activity = activities.get(activity_id)
+        if activity is None:
+            failures.append(
+                f"final-report data.json: clarification `{row_id}` references "
+                f"unknown activity `{activity_id}`."
+            )
+        elif row_id not in (activity.get("clarificationRefs") or []):
+            failures.append(
+                f"final-report data.json: activity `{activity_id}` does not "
+                f"link back to clarification `{row_id}`."
+            )
+
+
+def _validate_v3_approval_context(data: dict, failures: list[str]) -> None:
+    """검증 가능한 원장 참조만으로 v3 승인 역추적을 다시 계산한다."""
+    activities = _approval_activities_by_id(data)
+    _validate_v3_plan_backlinks(data, activities, failures)
+    approved = (data.get("frontmatter") or {}).get("approved") is True
+    for row in data.get("clarificationItems") or []:
+        if not isinstance(row, dict) or row.get("blocks") != "approval":
+            continue
+        context = row.get("approvalContext")
+        if not isinstance(context, dict):
+            continue
+        _validate_approval_dispositions(
+            row, context, failures, schema_version="3.0"
+        )
+        _validate_resolved_approval(
+            row, context, failures, schema_version="3.0"
+        )
+        _validate_v3_resolution_links(row, activities, failures)
+        if approved and row.get("status") in {"open", "answered"}:
+            failures.append(
+                f"final-report data.json: approval is true while clarification "
+                f"`{row.get('id')}` remains `{row.get('status')}`."
+            )
+
+
 def _validate_activity_contract_plan_limits(
     data: dict,
     run_manifest: dict,
@@ -5435,7 +5850,7 @@ def _validate_clarification_evidence_note(data: dict, failures: list[str]) -> No
         )
 
 
-_CLARIFICATION_OPTION_SCHEMA_VERSION = "2.0"
+_CLARIFICATION_OPTION_SCHEMA_VERSIONS = frozenset({"2.0", "3.0"})
 # The four profiles that read `_clarification-recommendation.md`. Unlike the
 # evidence-note gate above — which is called from inside the
 # `implementation-planning` branch — this one is called phase-agnostically, so
@@ -5508,7 +5923,7 @@ def _validate_clarification_options(data: dict, failures: list[str]) -> None:
     demanding one would fail every v1 `decision` row for a structure the format
     has no place to hold.
     """
-    if data.get("schemaVersion") != _CLARIFICATION_OPTION_SCHEMA_VERSION:
+    if data.get("schemaVersion") not in _CLARIFICATION_OPTION_SCHEMA_VERSIONS:
         return
     task_type = (data.get("header") or {}).get("taskType")
     if task_type not in _CLARIFICATION_OPTION_TASK_TYPES:
@@ -5517,7 +5932,10 @@ def _validate_clarification_options(data: dict, failures: list[str]) -> None:
         if not isinstance(row, dict) or row.get("kind") != "decision":
             continue
         row_id = str(row.get("id") or "<unknown>")
-        _validate_option_set(row.get("options"), row_id, failures)
+        _validate_option_set(
+            row.get("options"), row_id, failures,
+            schema_version=str(data.get("schemaVersion") or ""),
+        )
         if _LEGACY_EXPECTED_FORM_RE.search(str(row.get("expectedForm") or "")):
             failures.append(
                 f"final-report data.json: clarification `{row_id}` still encodes "
@@ -5529,7 +5947,7 @@ def _validate_clarification_options(data: dict, failures: list[str]) -> None:
 
 
 def _validate_option_set(
-    options: object, row_id: str, failures: list[str]
+    options: object, row_id: str, failures: list[str], *, schema_version: str = "2.0"
 ) -> None:
     """Check one `decision` row's `options[]` for pickability and reach."""
     if not isinstance(options, list) or len(options) < 2:
@@ -5550,7 +5968,9 @@ def _validate_option_set(
     for index, option in enumerate(entries):
         tokens = option.get("scopeImpact")
         reach = (
-            [token for token in tokens if token in _REACH_TOKENS]
+            [str(option.get("reach"))]
+            if schema_version == "3.0" and option.get("reach") in _REACH_TOKENS
+            else [token for token in tokens if token in _REACH_TOKENS]
             if isinstance(tokens, list)
             else []
         )
@@ -5649,8 +6069,7 @@ def _has_clarification_backtrace(
     resolver cannot disagree about what counts as a link.
     """
     if isinstance(plan_items, list) and any(
-        isinstance(item, dict) and item.get("clarificationId") == row_id
-        for item in plan_items
+        row_id in _plan_item_clarification_ids(item) for item in plan_items
     ):
         return True
     return isinstance(coverage, list) and any(
@@ -6134,6 +6553,7 @@ def _validate_plan_body_state_file(
     data: dict,
     report_path: Path,
     failures: list[str],
+    state_path: Path | None = None,
 ) -> None:
     """The per-round state file must exist once a round has run.
 
@@ -6157,20 +6577,34 @@ def _validate_plan_body_state_file(
     round_count = pbv.get("roundCount")
     if not isinstance(round_count, int) or round_count < 1:
         return
-    seq = _report_run_seq(report_path)
-    if seq is None:
-        return
     state_dir = report_path.parent.parent / "state"
-    expected = state_dir / f"plan-body-verification-implementation-planning-{seq}.json"
-    if not expected.is_file():
-        failures.append(
-            f"plan-body verification ran ({round_count} round(s)) but "
-            f"`state/{expected.name}` was not written. It is the only record "
-            "of superseded rounds — data.json keeps just the final verdicts, "
-            "so without it a self-fixed run leaves no trace of what the "
-            'earlier rounds found (plan-body-verification.md §"schema").'
-        )
-        return
+    if state_path is not None:
+        # 호출자가 경로를 넘겼으면 그걸 본다. 리드는 launch 프롬프트의
+        # `Run Paths` 에서 정본 경로를 받으므로, 여기서 이름을 다시 만들면
+        # 그 정본과 어긋날 수 있다 — 실제로 그랬다.
+        written = [state_path] if state_path.is_file() else []
+    else:
+        # 이름을 유도할 근거가 없다. run 은 seq 계열을 둘 갖고(`state` /
+        # `reports`) 리포트 정본은 자기 run 의 state seq 를 담지 않으므로,
+        # 리포트 seq 로 만든 이름은 추측이다. 이 검사가 묻는 것은 "덮어써진
+        # 라운드의 기록이 남았는가" 이지 파일 이름이 아니므로, 이 run 의 상태
+        # 디렉터리에 사이드카가 있는지만 본다. 이름의 정본은 `paths.py` 다.
+        written = sorted(
+            state_dir.glob("plan-body-verification-implementation-planning-*.json")
+        )
+    if not written:
+        failures.append(
+            f"plan-body verification ran ({round_count} round(s)) but no "
+            f"`state/plan-body-verification-*.json` was written. It is the only "
+            "record of superseded rounds — data.json keeps just the final "
+            "verdicts, so without it a self-fixed run leaves no trace of what "
+            'the earlier rounds found (plan-body-verification.md §"schema"). '
+            "The path is rendered into the launch prompt's `Run Paths` block; "
+            "write it there rather than deriving a name."
+        )
+        return
+    # 여럿이면 가장 최신(seq 가 큰) 것이 이 run 의 것이다.
+    expected = written[-1]
     try:
         state = json.loads(expected.read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError) as exc:
@@ -6697,6 +7131,53 @@ def _validate_round_recorded_verdicts(data: dict, failures: list[str]) -> None:
     )
 
 
+def _validate_unresolved_tie_was_reverified(
+    data: dict,
+    failures: list[str],
+) -> None:
+    """A split panel is sent back once before the gate is declared.
+
+    The gate needs a strict majority to block, so a panel splitting evenly on a
+    blocking kind reaches neither consensus nor `majority-disagree`. That state
+    is classified `needs-reverify`, and `needs-reverify` folds into
+    `passed-with-dissent` — which is correct for the shape it was built for (a
+    peer that returned nothing) and wrong for this one: nothing failed here, two
+    verifiers read the same plan and disagreed, and passing on that records a
+    dissent nobody acted on.
+
+    So the round is not optional. Re-dispatch those items and record the votes
+    with `--round 2`; a split that survives becomes `majority-disagree` and the
+    user decides. This is satisfiable with the machinery the contract already
+    defines — it is the same targeted re-verification step 7 runs after a
+    self-fix, with the tied items added to that queue.
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    pbv = ip.get("planBodyVerification")
+    if not isinstance(pbv, dict):
+        return
+    unsettled = sorted({
+        str(item.get("id") or "").strip()
+        for item in pbv.get("planItems") or []
+        if isinstance(item, dict)
+        and not item.get("carriedForwardFromSeq")
+        and _is_unsettled_tie(item)
+    })
+    if not unsettled:
+        return
+    failures.append(
+        f"final-report data.json: plan item(s) {unsettled} carry an even split "
+        "on a blocking breakage kind and were never re-verified. A tie is not "
+        "consensus: the gate's majority test is strict, so this split neither "
+        "blocks nor resolves, and declaring the gate on it passes a dissent "
+        "nobody settled. Re-dispatch those items in a plan-body round and "
+        "record the votes with `okstra plan-items apply-verdicts --data "
+        "<data.json> --verdicts <verdicts.json> --round 2`. A split that "
+        "survives that round becomes `majority-disagree` and goes to the user."
+    )
+
+
 def _validate_verdict_rounds_outlive_self_fix(
     data: dict,
     failures: list[str],
@@ -6941,7 +7422,15 @@ def _validate_plan_body_verdict_provenance(
     if not voters:
         return
 
-    task_type = str((data.get("header") or {}).get("taskType") or "")
+    task_type = (
+        str((data.get("header") or {}).get("taskType") or "")
+        or _report_task_type(report_path)
+    )
+    if not task_type:
+        # Neither source names it, so the glob below would be built from an
+        # empty segment and match nothing — reporting every verdict as unbacked
+        # on the strength of a path this check could not construct.
+        return
     dispatched = _plan_verify_result_workers(report_path, task_type)
     if dispatched is None:
         return
@@ -7609,15 +8098,20 @@ def _validate_plan_body_clarification_matching(
         if _is_dissent_downgraded(item, pbv, accepted):
             continue
         item_id = item.get("id") or "<unknown>"
-        cid = item.get("clarificationId")
-        if not cid:
+        cids = _plan_item_clarification_ids(item)
+        if not cids:
             failures.append(
                 f"final-report data.json: plan item `{item_id}` is majority-disagree "
-                "but carries no `clarificationId`. A blocking disagreement MUST "
+                "but carries no `clarificationRefs`. A blocking disagreement MUST "
                 "surface as a `## 1. Clarification Items` row (blocks=approval) so "
-                "the user sees the blocker (implementation-planning.md self-review step 7)."
+                "the user sees the blocker (implementation-planning.md self-review "
+                "step 12). Report assembly derives this link from the activity "
+                "ledger's `clarificationRefs[]` + `planItemIds[]`, so record the "
+                "decision through `okstra approval-decision` rather than editing "
+                "the report."
             )
-        elif cid not in approval_ids:
+            continue
+        for cid in sorted(cids - approval_ids):
             reason = (
                 "references a non-existent §1 row"
                 if cid not in all_ids
@@ -7625,8 +8119,9 @@ def _validate_plan_body_clarification_matching(
             )
             failures.append(
                 f"final-report data.json: plan item `{item_id}` (majority-disagree) "
-                f"has clarificationId `{cid}` which {reason}. Every majority-disagree "
-                "item MUST map 1:1 to a `blocks: approval` Clarification row."
+                f"has clarificationRefs entry `{cid}` which {reason}. Every "
+                "majority-disagree item MUST reach a `blocks: approval` "
+                "Clarification row."
             )
 
 
@@ -7793,7 +8288,9 @@ def validate_plan_body_section(
     _validate_aborted_gate_has_clarification(data, failures)
     _validate_round_recorded_verdicts(data, failures)
     _validate_verdicts_match_current_subjects(data, failures)
+    _validate_set_aside_register(data, failures, accepted_item_ids)
     _validate_verdict_rounds_outlive_self_fix(data, failures)
+    _validate_unresolved_tie_was_reverified(data, failures)
     _validate_plan_item_extraction_completeness(data, failures)
     _validate_plan_item_subject_substance(data, failures)
     _validate_plan_body_clarification_matching(data, failures, accepted_item_ids)
@@ -7808,16 +8305,16 @@ def _gate_summary_item(
     accepted_item_ids: set[str],
 ) -> dict:
     """One `gate.items[]` row: the gate class plus its state-file counterpart."""
-    classification = (
-        "has-dissent"
-        if _is_dissent_downgraded(item, pbv, accepted_item_ids)
-        else _classify_plan_item_gate(item)
-    )
+    classification = _plan_item_gate_class(item, pbv, accepted_item_ids)
     return {
         "id": item.get("id"),
         "classification": classification,
         "stateClassification": _state_classification(item, classification),
         "correctnessCritical": _is_correctness_critical(item),
+        # 왜 안 막는지가 기록에 남아야 한다. 이 값이 없으면 범위 밖 강등과
+        # 실제 합의가 산출물에서 같은 모양으로 읽힌다.
+        "stageScope": _stage_scope_bucket(item, pbv),
+        "block": str(item.get("block") or "execution"),
     }
 
 
@@ -7858,6 +8355,7 @@ def plan_body_gate_summary(data: dict) -> dict | None:
             _gate_blocking_causes(pbv, coverage_blockers, accepted_item_ids)
         ),
         "coverageBlockers": coverage_blockers,
+        "setAside": _set_aside_register(pbv, accepted_item_ids),
         "blockingItems": [
             item["id"] for item in items if item["classification"] == "majority-disagree"
         ],
@@ -9233,7 +9731,9 @@ SECTION_PLAN_BODY = "plan-body"
 _FULL_ONLY_REQUIRED_FLAGS = ("team_state", "run_manifest", "task_manifest")
 
 
-def run_plan_body_section(report_path: Path) -> int:
+def run_plan_body_section(
+    report_path: Path, state_path: Path | None = None
+) -> int:
     """`--section plan-body` — the §5.5.9 checks a self-fix round can run on
     its own, plus the recomputed gate the lead records for that round.
 
@@ -9260,7 +9760,45 @@ def run_plan_body_section(report_path: Path) -> int:
         return 2
     failures = _data_schema_failures(data)
     warnings = validate_plan_body_section(data, report_path, failures)
-    _validate_plan_body_state_file(data, report_path, failures)
+    _validate_plan_body_state_file(data, report_path, failures, state_path)
+    payload = {
+        "ok": not failures,
+        "section": SECTION_PLAN_BODY,
+        "gate": plan_body_gate_summary(data),
+        "failures": failures,
+        "warnings": warnings,
+    }
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0 if not failures else 2
+
+
+def run_plan_body_inputs(narrative_path: Path, state_path: Path) -> int:
+    """게시 전 서사와 수렴 소유 상태에서 같은 계획 게이트를 채점한다."""
+    from okstra_ctl.report_narrative import parse_narrative
+    from okstra_ctl.final_report_schema import load_schema_version
+
+    try:
+        narrative = parse_narrative(
+            narrative_path.read_text(encoding="utf-8"),
+            load_schema_version("3.0"),
+        )
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, ValueError) as exc:
+        print(f"validate-run: plan-body inputs are invalid ({exc})", file=sys.stderr)
+        return 2
+    state_owner = state.get("owner") if isinstance(state, dict) else None
+    verification = state.get("planBodyVerification") if isinstance(state, dict) else None
+    planning = narrative.get("implementationPlanning")
+    if state_owner != "convergence" or not isinstance(verification, dict):
+        print("validate-run: plan-body state must be convergence-owned", file=sys.stderr)
+        return 2
+    if not isinstance(planning, dict):
+        print("validate-run: narrative has no implementationPlanning", file=sys.stderr)
+        return 2
+    data = {**narrative, "schemaVersion": "3.0"}
+    data["implementationPlanning"] = {**planning, "planBodyVerification": verification}
+    failures: list[str] = []
+    warnings = validate_plan_body_section(data, _report_path_for_state(state_path), failures)
     payload = {
         "ok": not failures,
         "section": SECTION_PLAN_BODY,
@@ -9272,6 +9810,14 @@ def run_plan_body_section(report_path: Path) -> int:
     return 0 if not failures else 2
 
 
+def _report_path_for_state(state_path: Path) -> Path:
+    match = re.search(r"-(\d{3})\.json$", state_path.name)
+    seq = match.group(1) if match else "001"
+    return state_path.parent.parent / "reports" / (
+        f"final-report-implementation-planning-{seq}.data.json"
+    )
+
+
 def _data_schema_failures(data: dict) -> list[str]:
     """Schema errors in the round's data.json, as failures.
 
@@ -9315,9 +9861,11 @@ def main() -> int:
     )
     parser.add_argument(
         "--report",
-        required=True,
+        required=False,
         help="Project-relative or absolute path to the report record (.data.json). Schema-v1 reports still use the Markdown file.",
     )
+    parser.add_argument("--narrative", required=False)
+    parser.add_argument("--state", required=False)
     parser.add_argument(
         "--run-manifest",
         required=False,
@@ -9343,7 +9891,18 @@ def main() -> int:
     args = parser.parse_args()
 
     if args.section == SECTION_PLAN_BODY:
-        return run_plan_body_section(Path(args.report).resolve())
+        if args.narrative and args.state and not args.report:
+            return run_plan_body_inputs(
+                Path(args.narrative).resolve(), Path(args.state).resolve()
+            )
+        if args.report and not args.narrative and not args.state:
+            return run_plan_body_section(
+                Path(args.report).resolve(),
+                Path(args.state).resolve() if args.state else None,
+            )
+        parser.error(
+            "--section plan-body requires either --report or both --narrative and --state"
+        )
 
     missing = [
         f"--{flag.replace('_', '-')}"
@@ -9550,7 +10109,12 @@ def main() -> int:
             validation_data, project_root, failures
         )
     if task_type == "implementation-planning":
-        _validate_plan_body_state_file(validation_data, report_path, failures)
+        _validate_plan_body_state_file(
+            validation_data,
+            report_path,
+            failures,
+            Path(args.state).resolve() if args.state else None,
+        )
     if task_type == "final-verification":
         _validate_verification_target_match(
             validation_data,