okstra 0.186.4 → 0.186.6

package/runtime/validators/validate-run.py

@@ -80,7 +80,9 @@ from okstra_ctl.report_translation import (  # noqa: E402
 )
 from okstra_ctl.stage_citations import enumerated_stage_numbers  # noqa: E402
 from okstra_ctl.plan_items import (  # noqa: E402
+    CRITIC_WORKER_ID,
     advisory_plan_body_gating,
+    is_critic_worker,
     stage_scope_bucket as _item_stage_scope_bucket,
 )
 from okstra_ctl.incremental_scope import (  # noqa: E402
@@ -92,6 +94,7 @@ from okstra_ctl.clarification_items import (  # noqa: E402
     APPROVAL_BLOCKS,
     PROCEEDING_DISPOSITIONS,
     clarification_disposition,
+    incorporated_clarification_ids,
     progress_blocking_ids,
     row_blocks_progress,
 )
@@ -512,7 +515,7 @@ def _validate_agent_dispatch_contract(
 
     links = [
         row for row in (team_state.get("agentResultLinks") or [])
-        if isinstance(row, Mapping)
+        if isinstance(row, Mapping) and not row.get("supersededBy")
     ]
     paths: dict[str, str] = {}
     dispatch_link_counts: dict[str, int] = {}
@@ -3492,8 +3495,8 @@ def validate_final_report_data(
     errors = schema_validate(data, schema)
     for err in errors:
         failures.append(f"final-report data.json: {err}")
-    if errors:
-        return data
+    # 스키마 실패가 계약 스캔을 가리지 않는다. 빈 decisionRefs 가
+    # minItems 에서 막히면 종료상태 표 누락이 안 보였다.
 
     manifest = run_manifest or {}
     if data.get("executionIdentityVersion") == 2 or data.get("executionRoles"):
@@ -3595,8 +3598,11 @@ def validate_final_report_data(
             data, _project_root_from_report(report_path)
         ):
             print(f"validate-run: warning: {warning}", file=sys.stderr)
+        carried = _carried_decision_map(
+            manifest, project_root=project_root, report_path=report_path
+        )
         _validate_supersession_ledger(data, failures)
-        _validate_clarification_evidence_note(data, failures)
+        _validate_clarification_evidence_note(data, failures, carried=carried)
         _validate_approval_clarification_backtrace(data, failures)
         _validate_rerun_guidance(data, failures)
         _validate_approval_guidance(data, failures)
@@ -3606,7 +3612,11 @@ def validate_final_report_data(
             failures,
         )
         if not selected_direction_contract:
-            _validate_requirement_deviations(data, failures)
+            _validate_requirement_deviations(
+                data,
+                failures,
+                carried=carried,
+            )
             _validate_requirement_coverage_covered_by(data, failures)
         warnings = _validate_design_prep_contract(
             data,
@@ -3915,6 +3925,34 @@ def _single_vote_block_survives(item: dict, kinds: set[str]) -> bool:
     )
 
 
+def _critic_non_error_verdicts(item: dict) -> list[dict]:
+    return [
+        row
+        for row in (item.get("verdicts") or [])
+        if isinstance(row, dict)
+        and is_critic_worker(str(row.get("worker") or ""))
+        and str(row.get("verdict") or "").strip().upper()
+        not in ("", "VERIFICATION-ERROR")
+    ]
+
+
+def _tie_gate_class(item: dict, agree: list, disagree: list) -> str | None:
+    """분석자 동수면 critic 이 가르고, 없으면 재검증. 동수가 아니면 None."""
+    if not (len(disagree) == len(agree) and disagree):
+        return None
+    critic = _critic_non_error_verdicts(item)
+    if not critic:
+        return "needs-reverify"
+    if any(
+        str(row.get("verdict") or "").strip().upper() == "DISAGREE"
+        and str(row.get("breakageKind") or "").strip().lower()
+        not in _ADVISORY_ONLY_KINDS
+        for row in critic
+    ):
+        return "majority-disagree"
+    return "has-dissent"
+
+
 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
@@ -3923,7 +3961,8 @@ def _classify_plan_item_gate(item: dict) -> str:
     (``dissent-isolated`` / ``partial-consensus`` on ``b``/``c``/``e``) is
     ``majority-disagree`` so the user gate sees it. ``has-dissent`` remains
     advisory-only, rollback items, and a single-vote kind that lost its
-    reproduction.
+    reproduction. An analyser 1-1 is ``needs-reverify`` until ``critic-worker``
+    settles it.
     """
     tokens = [
         (
@@ -3932,6 +3971,7 @@ def _classify_plan_item_gate(item: dict) -> str:
         )
         for v in (item.get("verdicts") or [])
         if isinstance(v, dict)
+        and not is_critic_worker(str(v.get("worker") or ""))
     ]
     non_error = [(vd, bk) for (vd, bk) in tokens if vd and vd != "VERIFICATION-ERROR"]
     if not non_error:
@@ -3981,19 +4021,9 @@ 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"
+    settled = _tie_gate_class(item, agree, blocking_disagree)
+    if settled is not None and len(non_error) >= 2:
+        return settled
     if (
         len(non_error) >= 2
         and blocking_disagree
@@ -4009,12 +4039,6 @@ def _classify_plan_item_gate(item: dict) -> str:
     return "has-dissent"
 
 
-# 동수를 한 번 재검증한 뒤에도 갈리면 그때는 사용자가 판단한다. 초기 검증이
-# 라운드 1이고 자가수정 뒤의 표적 재검증이 라운드 2이므로, 라운드 2 이상의
-# 판정이 붙은 동수는 이미 한 번 돌아온 것이다.
-_TIE_SETTLED_ROUND = 2
-
-
 def _max_verdict_round(item: dict) -> int:
     """이 항목의 판정이 붙은 가장 늦은 라운드. 스탬프가 없으면 1.
 
@@ -4031,18 +4055,25 @@ def _max_verdict_round(item: dict) -> int:
     return max(rounds, default=1)
 
 
+def _is_even_analyser_split(item: dict) -> bool:
+    tokens = [
+        str(row.get("verdict") or "").strip().upper()
+        for row in (item.get("verdicts") or [])
+        if isinstance(row, dict)
+        and not is_critic_worker(str(row.get("worker") or ""))
+        and str(row.get("verdict") or "").strip().upper()
+        not in ("", "VERIFICATION-ERROR")
+    ]
+    if len(tokens) < 2:
+        return False
+    disagree = sum(1 for token in tokens if token == "DISAGREE")
+    agree = sum(1 for token in tokens if token in {"AGREE", "SUPPLEMENT"})
+    return disagree == agree and disagree > 0
+
+
 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
-    )
+    """분석자는 갈렸고 critic 표가 아직 없는 동수 항목."""
+    return _is_even_analyser_split(item) and not _critic_non_error_verdicts(item)
 
 
 def _disagree_breakage_kinds(item: dict) -> set[str]:
@@ -5346,6 +5377,7 @@ def _validate_approval_context(
     activities = _approval_activities_by_id(data)
     activity_timestamps = _canonical_activity_timestamps(run_manifest, report_path)
     report_approved = (data.get("frontmatter") or {}).get("approved") is True
+    incorporated = incorporated_clarification_ids(data)
     for row in data.get("clarificationItems") or []:
         if not isinstance(row, dict) or row.get("blocks") != "approval":
             continue
@@ -5427,7 +5459,9 @@ def _validate_approval_context(
             failures,
         )
         if report_approved and row_blocks_progress(
-            str(row.get("status") or ""), clarification_disposition(row)
+            str(row.get("status") or ""),
+            clarification_disposition(row),
+            incorporated=row_id in incorporated,
         ):
             failures.append(
                 f"final-report data.json: approval is true while clarification `{row_id}` "
@@ -5491,6 +5525,7 @@ def _validate_v3_approval_context(data: dict, failures: list[str]) -> None:
     activities = _approval_activities_by_id(data)
     _validate_v3_plan_backlinks(data, activities, failures)
     approved = (data.get("frontmatter") or {}).get("approved") is True
+    incorporated = incorporated_clarification_ids(data)
     for row in data.get("clarificationItems") or []:
         if not isinstance(row, dict) or row.get("blocks") != "approval":
             continue
@@ -5504,8 +5539,11 @@ def _validate_v3_approval_context(data: dict, failures: list[str]) -> None:
             row, context, failures, schema_version="3.0"
         )
         _validate_v3_resolution_links(row, activities, failures)
+        row_id = str(row.get("id") or "")
         if approved and row_blocks_progress(
-            str(row.get("status") or ""), clarification_disposition(row)
+            str(row.get("status") or ""),
+            clarification_disposition(row),
+            incorporated=row_id in incorporated,
         ):
             failures.append(
                 f"final-report data.json: approval is true while clarification "
@@ -5521,12 +5559,8 @@ def _validate_activity_contract_plan_limits(
     if not _is_activity_contract_v1_planning(run_manifest):
         return
     pbv = (data.get("implementationPlanning") or {}).get("planBodyVerification") or {}
-    rounds_applied = pbv.get("selfFixRoundsApplied", 0)
-    if isinstance(rounds_applied, int) and rounds_applied > 1:
-        failures.append(
-            "final-report data.json: activity contract v1 selfFixRoundsApplied "
-            "must be at most one automatic self-fix round"
-        )
+    # 리포트 칸은 이어진 런의 누적이다. 자동 자가수정 1회 상한은 이번 창의
+    # 상태 파일이 세고, 세션 적합성이 그 횟수와 `self-fix-applied` 를 맞춘다.
     if pbv.get("selfFixStopReason") == "cause-group-recurrence":
         failures.append(
             "final-report data.json: activity contract v1 cannot newly emit "
@@ -5778,6 +5812,14 @@ def _validate_self_fix_rewrite_scope(data: dict, failures: list[str]) -> None:
                 )
 
 
+def _analyser_key(worker: str) -> str:
+    """`codex` 와 `codex-worker` 는 같은 분석기다."""
+    name = worker.strip()
+    if name.endswith("-worker"):
+        return name[: -len("-worker")]
+    return name
+
+
 def _validate_participating_analysers(data: dict, failures: list[str]) -> None:
     """The gate's own arithmetic base, checked against the votes it ran on.
 
@@ -5809,12 +5851,13 @@ def _validate_participating_analysers(data: dict, failures: list[str]) -> None:
         return
 
     observed = {
-        str(v.get("worker"))
+        _analyser_key(str(v.get("worker")))
         for item in (pbv.get("planItems") or [])
         if isinstance(item, dict)
         for v in (item.get("verdicts") or [])
         if isinstance(v, dict) and str(v.get("verdict") or "") != "verification-error"
     }
+    observed.discard("")
     if observed and voting != len(observed):
         failures.append(
             "final-report data.json: planBodyVerification.participatingAnalysers "
@@ -5917,7 +5960,9 @@ _EVIDENCE_NONE_RE = re.compile(r"^none\s*[—-]\s*\S")
 _EVIDENCE_PATH_LINE_RE = re.compile(r"\S+\.\w+:\d+")
 
 
-def _validate_clarification_evidence_note(data: dict, failures: list[str]) -> None:
+def _validate_clarification_evidence_note(
+    data: dict, failures: list[str], *, carried: dict | None = None,
+) -> None:
     """Every clarification row must show its codebase-first work.
 
     The profile requires any ambiguity answerable by `Read` / `Grep` to be
@@ -5930,10 +5975,13 @@ def _validate_clarification_evidence_note(data: dict, failures: list[str]) -> No
     """
     if (data.get("header") or {}).get("taskType") != "implementation-planning":
         return
+    carried_ids = set((carried or {}).keys())
     for row in data.get("clarificationItems") or []:
         if not isinstance(row, dict):
             continue
         row_id = str(row.get("id") or "<unknown>")
+        if row_id in carried_ids:
+            continue
         statement = str(row.get("statement") or "")
         match = _EVIDENCE_NOTE_RE.search(statement)
         if not match:
@@ -6266,7 +6314,11 @@ def _next_step_texts(steps: object) -> list[str]:
 
 def _has_unresolved_approval_blocker(data: dict) -> bool:
     return bool(
-        progress_blocking_ids(data.get("clarificationItems"), APPROVAL_BLOCKS)
+        progress_blocking_ids(
+            data.get("clarificationItems"),
+            APPROVAL_BLOCKS,
+            report_data=data,
+        )
     )
 
 
@@ -7299,21 +7351,12 @@ def _validate_unresolved_tie_was_reverified(
     data: dict,
     failures: list[str],
 ) -> None:
-    """A split panel is sent back once before the gate is declared.
+    """A split panel goes to critic-worker 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.
+    is classified `needs-reverify` until `critic-worker` settles it. Passing
+    without that vote records a dissent nobody acted on.
     """
     ip = data.get("implementationPlanning")
     if not isinstance(ip, dict):
@@ -7332,14 +7375,13 @@ def _validate_unresolved_tie_was_reverified(
     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."
+        "final-report data.json: plan item(s) "
+        f"{unsettled} carry an even split on a blocking breakage kind and "
+        f"have no `{CRITIC_WORKER_ID}` vote. A tie is not consensus. Dispatch "
+        f"`{CRITIC_WORKER_ID}` on those items only (`okstra plan-items "
+        "prepare --tie-vote`) and record the vote with `okstra plan-items "
+        "apply-verdicts --append --round 2`. Critic AGREE settles the split; "
+        "critic DISAGREE blocks."
     )
 
 
@@ -7347,7 +7389,7 @@ def _validate_tie_received_extra_vote(
     data: dict,
     failures: list[str],
 ) -> None:
-    """동수는 같은 둘을 다시 돌리는 것이 아니라 세 번째 표로 가른다."""
+    """동수는 같은 둘을 다시 돌리는 것이 아니라 critic 이 가른다."""
     ip = data.get("implementationPlanning")
     if not isinstance(ip, dict):
         return
@@ -7363,17 +7405,17 @@ def _validate_tie_received_extra_vote(
         and str(item.get("id") or "").strip() not in accepted
         and _stage_scope_bucket(item, pbv) == "in-scope"
         and _is_even_blocking_split(item)
-        and _distinct_verdict_workers(item) < 3
+        and not _critic_non_error_verdicts(item)
     })
     if not missing:
         return
     failures.append(
         f"final-report data.json: plan item(s) {missing} carry an even split "
-        "on a blocking breakage kind and have no third vote. Re-running the "
-        "original two does not settle a 1-1 split. Dispatch one extra analyser "
-        "whose prompt is those items only (`okstra plan-items prepare "
-        "--tie-vote`) and record the vote with `okstra plan-items "
-        "apply-verdicts --append --round 2`."
+        "on a blocking breakage kind and have no critic vote. Re-running the "
+        "original two does not settle a 1-1 split. Dispatch "
+        f"`{CRITIC_WORKER_ID}` whose prompt is those items only "
+        "(`okstra plan-items prepare --tie-vote`) and record the vote with "
+        "`okstra plan-items apply-verdicts --append --round 2`."
     )
 
 
@@ -7390,14 +7432,6 @@ def _is_even_blocking_split(item: dict) -> bool:
     return _is_unsettled_tie(forced)
 
 
-def _distinct_verdict_workers(item: dict) -> int:
-    return len({
-        str(row.get("worker") or "")
-        for row in (item.get("verdicts") or [])
-        if isinstance(row, dict) and str(row.get("worker") or "").strip()
-    })
-
-
 def _validate_advisory_plan_body_gating(data: dict, failures: list[str]) -> None:
     """gating=false 는 검출 표면 0 + 스테이지 1 일 때만 받는다."""
     ip = data.get("implementationPlanning")
@@ -8628,14 +8662,83 @@ _DEVIATION_DECISION_REF_RE = re.compile(r"^(C-\d{3,}|D-\d{4,})$")
 _DEVIATION_BLOCKED_DISPOSITION_RE = re.compile(r"^blocked (C-\d{3,})$")
 
 
+def _carried_decision_map(
+    run_manifest: Mapping[str, Any] | None,
+    *,
+    project_root: Path | None,
+    report_path: Path,
+) -> dict[str, dict]:
+    """이전 런에서 carry 한 결정. active `clarificationItems` 에 다시 올리지 않는다."""
+    raw = (run_manifest or {}).get("approvalDecisionsPath")
+    if not isinstance(raw, str) or not raw.strip():
+        return {}
+    path = Path(raw.strip())
+    if not path.is_absolute():
+        root = project_root or _project_root_from_report(report_path)
+        path = root / path
+    if not path.is_file():
+        return {}
+    try:
+        ledger = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    if not isinstance(ledger, dict):
+        return {}
+    carried: dict[str, dict] = {}
+    for row in ledger.get("carriedDecisions") or []:
+        if not isinstance(row, dict):
+            continue
+        decision = row.get("decision")
+        if not isinstance(decision, dict):
+            continue
+        cid = decision.get("id")
+        if isinstance(cid, str) and cid:
+            carried[cid] = decision
+    return carried
+
+
+def _deviation_target(
+    ref: str,
+    clarifications: dict,
+    decisions: dict,
+    carried: dict,
+) -> dict | None:
+    if ref.startswith("C-"):
+        row = clarifications.get(ref) or carried.get(ref)
+        return row if isinstance(row, dict) else None
+    row = decisions.get(ref)
+    return row if isinstance(row, dict) else None
+
+
+def _deviation_is_user_confirmed(
+    ref: str, clarifications: dict, carried: dict,
+) -> bool:
+    row = clarifications.get(ref)
+    if (
+        isinstance(row, dict)
+        and row.get("status") in {"answered", "resolved"}
+        and str(row.get("userInput") or "").strip()
+    ):
+        return True
+    carried_row = carried.get(ref)
+    if not isinstance(carried_row, dict):
+        return False
+    resolution = carried_row.get("resolutionInput")
+    if isinstance(resolution, dict) and str(resolution.get("userText") or "").strip():
+        return True
+    return bool(str(carried_row.get("userConfirmation") or "").strip())
+
+
 def _resolved_deviation_refs(
     row_id: str,
     refs: object,
     clarifications: dict,
     decisions: dict,
     failures: list[str],
+    carried: dict | None = None,
 ) -> list[str]:
     valid_refs: list[str] = []
+    carried_rows = carried or {}
     for ref in refs if isinstance(refs, list) else []:
         if not isinstance(ref, str) or not _DEVIATION_DECISION_REF_RE.fullmatch(ref):
             failures.append(
@@ -8643,12 +8746,7 @@ def _resolved_deviation_refs(
                 f"unsupported decisionRef `{ref}`; expected C-NNN or D-NNNN."
             )
             continue
-        target = (
-            clarifications.get(ref)
-            if ref.startswith("C-")
-            else decisions.get(ref)
-        )
-        if target is None:
+        if _deviation_target(ref, clarifications, decisions, carried_rows) is None:
             failures.append(
                 f"final-report data.json: requirementCoverage `{row_id}` "
                 f"decisionRef `{ref}` does not exist in this report."
@@ -8664,12 +8762,13 @@ def _validate_deviation_disposition(
     refs: list[str],
     clarifications: dict,
     failures: list[str],
+    carried: dict | None = None,
 ) -> None:
+    carried_rows = carried or {}
     if disposition == "accepted":
         confirmed = any(
             ref.startswith("C-")
-            and clarifications[ref].get("status") in {"answered", "resolved"}
-            and bool(str(clarifications[ref].get("userInput") or "").strip())
+            and _deviation_is_user_confirmed(ref, clarifications, carried_rows)
             for ref in refs
         )
         if not confirmed:
@@ -8688,7 +8787,9 @@ def _validate_deviation_disposition(
     if blocked is None:
         return
     clarification_id = blocked.group(1)
-    clarification = clarifications.get(clarification_id)
+    clarification = clarifications.get(clarification_id) or carried_rows.get(
+        clarification_id
+    )
     if clarification is None:
         failures.append(
             f"final-report data.json: requirementCoverage `{row_id}` "
@@ -8706,7 +8807,9 @@ def _validate_deviation_disposition(
         )
 
 
-def _validate_requirement_deviations(data: dict, failures: list[str]) -> None:
+def _validate_requirement_deviations(
+    data: dict, failures: list[str], *, carried: dict | None = None,
+) -> None:
     """Require documented deviations to reference real decisions and approval."""
     planning = data.get("implementationPlanning")
     if not isinstance(planning, dict):
@@ -8721,15 +8824,26 @@ def _validate_requirement_deviations(data: dict, failures: list[str]) -> None:
         for row in (planning.get("decisionDrafts") or [])
         if isinstance(row, dict) and row.get("number")
     }
+    carried_rows = carried or {}
     for row in planning.get("requirementCoverage") or []:
         if not isinstance(row, dict) or row.get("status") != "documented-deviation":
             continue
         row_id = row.get("id") or "<row>"
         refs = _resolved_deviation_refs(
-            row_id, row.get("decisionRefs"), clarifications, decisions, failures
+            row_id,
+            row.get("decisionRefs"),
+            clarifications,
+            decisions,
+            failures,
+            carried_rows,
         )
         _validate_deviation_disposition(
-            row_id, row.get("approvalDisposition"), refs, clarifications, failures
+            row_id,
+            row.get("approvalDisposition"),
+            refs,
+            clarifications,
+            failures,
+            carried_rows,
         )
 
 
@@ -9518,15 +9632,37 @@ def _validate_convergence_rounds_match_manifest(
             )
 
 
-def _validate_convergence_states(run_dir, failures) -> None:
-    """Replay shared engine invariants for every public final state artifact."""
+def _validate_convergence_states(
+    run_dir, failures, run_manifest: dict | None = None, project_root: Path | None = None,
+) -> None:
+    """이번 런이 가리키는 수렴 상태만 본다. 디렉터리의 옛 seq 파일은 건너뛴다.
+
+    매니페스트가 경로를 채워도 파일이 없으면 검사하지 않는다. render-only 와
+    workflow 픽스처는 수렴을 돌리지 않아 파일이 없고, 없는 파일을 실패로 치면
+    예전 glob 이 빈 결과를 내던 계약이 깨진다. 목적은 현재 런이 아닌 seq 를
+    보지 않는 것이다.
+    """
     from pathlib import Path as _Path
 
-    state_dir = _Path(run_dir) / "state"
-    if not state_dir.is_dir():
-        return
-    for state_path in sorted(state_dir.glob("convergence-*.json")):
-        if state_path.name.startswith(_CONVERGENCE_INTERMEDIATE_PREFIXES):
+    declared = (run_manifest or {}).get("convergenceStatePath")
+    if isinstance(declared, str) and declared.strip():
+        path = _Path(declared.strip())
+        if not path.is_absolute():
+            if project_root is None:
+                return
+            path = project_root / path
+        paths = [path] if path.is_file() else []
+    else:
+        state_dir = _Path(run_dir) / "state"
+        if not state_dir.is_dir():
+            return
+        paths = [
+            state_path
+            for state_path in sorted(state_dir.glob("convergence-*.json"))
+            if not state_path.name.startswith(_CONVERGENCE_INTERMEDIATE_PREFIXES)
+        ]
+    for state_path in paths:
+        if not state_path.is_file():
             continue
         try:
             state = json.loads(state_path.read_text(encoding="utf-8"))
@@ -10355,7 +10491,9 @@ def main() -> int:
             run_dir = report_path.parent.parent
             _validate_requirements_discovery_fanout(run_dir, failures, brief_path)
     # Phase-agnostic: convergence runs in every finding-producing phase.
-    _validate_convergence_states(report_path.parent.parent, failures)
+    _validate_convergence_states(
+        report_path.parent.parent, failures, run_manifest, project_root
+    )
     _validate_convergence_rounds_match_manifest(
         report_path.parent.parent, run_manifest, failures
     )