okstra 0.186.3 → 0.186.5

package/docs/architecture.md

@@ -865,7 +865,7 @@ The manifest-provided `lead-events-*.jsonl` file is the canonical record for str
 
 `activityContractVersion: 1` is an interpretation version for new `implementation-planning` artifacts. A run without that field remains a historical run and does not require activity events or an `agentActivity[]` projection.
 
-The shared `okstra report-finalize` entrypoint reads canonical activity before translation source checking. Under contract v3 its in-process `project-activity` step assembles the report, filtering events by run identity and validating activity ID order before `agentActivity[]` is published. A historical v2 manifest retains the in-place projection path. For a non-English report, the lead runs `token-usage`, `project-activity`, and `check-source` before translator dispatch, then resumes at `render-views` after the translation sidecar exists. Conformance compares the resulting `agentActivity[]` IDs, order, and core fields with the canonical events for every lead host.
+The shared `okstra report-finalize` entrypoint reads canonical activity before translation source checking. Under contract v3 its in-process `project-activity` step assembles the report, filtering events by run identity and validating activity ID order before `agentActivity[]` is published. A schema-invalid composed record is still published so `validate-run` can scan it; the step itself fails. A historical v2 manifest retains the in-place projection path. A failed Phase 7 step does not skip later checks: `validate-run` still runs, and only `teardown-stages` is skipped. For a non-English report, the lead runs `token-usage`, `project-activity`, and `check-source` before translator dispatch, then resumes at `render-views` after the translation sidecar exists. Conformance compares the resulting `agentActivity[]` IDs, order, and core fields with the canonical events for every lead host.
 
 Approval blockers use `open`, `answered`, `resolved`, and `obsolete`. `open` blocks until the user judges. `answered` with `accept-risk` / `select` / `answer` does not block approval or the next phase; the DISAGREE votes stay on the plan item as evidence. A response sidecar with a proceeding disposition unblocks the same way. `request-revision` and `reject` still withhold the next phase.
 

package/docs/cli.md

@@ -862,7 +862,7 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra approval-decision <open\|resolve\|carry> --ledger <approval-decisions.json> …` | Write the lead-owned clarification and approval ledger. `open` validates classification-specific dispositions and complete option fields, `resolve` requires real `A-NNN` check references, and `carry` keeps prior resolved decisions outside the active clarification list. |
 | `okstra design-snapshot --narrative <report-narrative.md> --output <design-preparation.json>` | Detect implementation-planning design surfaces and write the detector-owned snapshot consumed by final report assembly. |
 | `okstra plan-verify --narrative <report-narrative.md> --state <plan-body-verification.json>` | Recompute the plan-body gate from the convergence-owned state before `data.json` publication. `--report <historical-data.json>` remains the v2 reader. |
-| `okstra report-finalize --project-root <dir> --run-manifest <path> --report <final-report.md>` | Run Phase 7 in the manifest's contract order. Contract v3 collects usage into team state, assembles all single-owner inputs into `data.json` once, then checks, renders, spawns follow-ups, validates, and tears down eligible stage worktrees. Contract v2 retains its historical in-place projection sequence as a read-only compatibility path. Stops at the first non-zero exit except deferred token collection, reports each step, and prints the ordered `--only` recovery tail. This is the shared path for every lead adapter. |
+| `okstra report-finalize --project-root <dir> --run-manifest <path> --report <final-report.md>` | Run Phase 7 in the manifest's contract order. Contract v3 collects usage into team state, assembles all single-owner inputs into `data.json` once, then checks, renders, spawns follow-ups, validates, and tears down eligible stage worktrees. Contract v2 retains its historical in-place projection sequence as a read-only compatibility path. A failed step still runs every later check through `validate-run`; only `teardown-stages` is skipped so a failed run does not reclaim worktrees. Reports each step and prints the ordered `--only` recovery tail from the earliest failure. This is the shared path for every lead adapter. |
 | `okstra render-views <final-report.data.json\|final-report.md>` | The Phase 7 `render-views` step, runnable on its own. Schema v2 data is rendered directly, and schema v3 data uses the same always-generated, task-specific human HTML path. The full reading copy uses `templates/reports/final-report-v2.template.md` and is rendered on demand with `okstra render-final-report`. Passing the Markdown sibling locates the same data.json. Schema v1 and quick reports keep the legacy conditional renderer. The Node wrapper calls `scripts/okstra-render-report-views.py`; `validators/validate-report-views.py` verifies source/schema/template digests, required human fields, form controls, external assets, diagram/table ID parity, and Response ID parity. |
 | `okstra design-prep <list\|show\|write>` | Review AI-prepared implementation design requests, inspect their effective confirmed response, or append a confirmed user/wizard response without editing the planning report |
 | `okstra wizard <init\|step\|render-args\|confirmation\|outcome> --state-file <path>` | Interactive input state machine for okstra-run, implemented by `okstra_ctl.wizard`. Seed a state file with `init`, then repeatedly call `step --answer <val>` to receive the next `Prompt` JSON. `--answer` is **required**; use `--no-submit` to peek at the next prompt without submitting a response. A `pick` with more choices than the host picker can display keeps `kind: "pick"` but adds `presentation: "numbered-text"`; render every option as a numbered Markdown list and submit the user's 1-based number, exact value, or exact label. Invalid, out-of-range, and ambiguous answers re-prompt without dropping choices. `render-args` returns the final `render-bundle` argument map, and `confirmation` returns the user echo block. On a completed wizard, `outcome` returns `renderArgs`, `persistActions`, and `confirmationText` together; project/global release-handoff PR-template persistence appears as `persistActions[].command == "config.set"`. For an `implementation` task type, `stage_pick` follows `approved_plan_pick` and selects the stage before `executor_pick`. The brief step appears only for entry task types—requirements-discovery, error-analysis, improvement-discovery, project-analysis, feature-analysis, and change-impact-analysis. Analysis inputs use `feature_evidence_pick` / `feature_evidence`, `project_evidence_pick` / `project_evidence`, and `analysis_target_pick` / `analysis_target`; a revision-requested report prioritizes its same-task, same-type rerun. Downstream lifecycle phases automatically carry the manifest brief, with a three-option `brief_carry` fallback when none is registered; `release-handoff` has no brief and enters multi-select `handoff_stage_pick` for eligible stage groups or the whole task |

package/docs/project-structure-overview.md

@@ -343,7 +343,7 @@ Important modules:
 | `plan_derivations.py` | the supersession sweep `_common-contract.md` requires an author to do by hand — extracts the symbols, paths, and ids an answered clarification names and reports every plan string that mentions one. Advisory: it locates candidates and never judges which are now false |
 | `scope_provenance.py` | single source of truth for the scope-provenance grammar every phase-emitted requirement must declare, shared by `validators/validate-run.py` and `validators/validate_fanout.py` so the planning report and fan-out packets cannot drift |
 | `worker_artifact_paths.py` | canonical worker artifact path derivation (e.g. `audit_sidecar_rel` inserts `-audit-` after the first `-worker-` token), so dispatch and validation agree on non-canonical-path rejection |
-| `report_finalize.py` | Phase 7 post-report sequence **SSOT** — runs `check-source` → `token-usage` → `render-views` → `spawn-followups` → `validate-run` in that load-bearing order, stops at the first non-zero exit and names the failing step — except `token-usage`, whose failure defers so the later steps still produce their artifacts. Both lead paths converge here: the Codex adapter calls it in-process (`codex_dispatch`), a Claude-led run reaches it through `okstra report-finalize`. Neither reimplements the sequence |
+| `report_finalize.py` | Phase 7 post-report sequence **SSOT** — runs `check-source` → `token-usage` → `render-views` → `spawn-followups` → `validate-run` in that load-bearing order. A non-zero exit still runs every later check through `validate-run` and names the earliest failure; `teardown-stages` is skipped when any earlier step failed. Both lead paths converge here: the Codex adapter calls it in-process (`codex_dispatch`), a Claude-led run reaches it through `okstra report-finalize`. Neither reimplements the sequence |
 | `wrapper_status.py` | worker wrapper status sidecar reader — the host-side reader of the sidecar `worker_runner.py` writes. `is_terminal` is the one question it answers for the dispatch record and the pane reclaim: does `stage` read `exited` |
 | `worker_runner.py` | runs one worker CLI and records what happened — shared by every provider entrypoint. Owns the `selectors` pump over the child's streams, the stream-arrival idle watchdog (`killpg` on breach), the run-wide progress cap on the log copy, and the status sidecar's whole life. A run that dies after launch still closes its sidecar, so `worker_liveness` never reads a dead worker as running |
 | `session_transcript.py` | worker session transcript — one line per event (time, speaker, body) with a run-wide progress-line cap (`LOG_LINE_CAP`, elision notice) so a single-file dispatch's tool echo cannot dominate the project's `.okstra/` bytes; the fixed shape lets a later lead write share the same file |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.186.3",
+  "version": "0.186.5",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.186.3",
-  "builtAt": "2026-08-24T04:42:58.072Z",
+  "package": "0.186.5",
+  "builtAt": "2026-08-24T06:52:38.243Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/report_assembly.py

@@ -131,10 +131,65 @@ def _clarifications(
         if not isinstance(row, Mapping):
             _fail("lead", path, f"activeClarifications[{index}]", "must be an object")
     activity_by_id = {row.get("activityId"): row for row in activities}
-    return [
+    rows = [
         _clarification_row(row, activity_by_id, path)
         for row in active
     ]
+    rows.extend(_carried_clarification_rows(ledger, {row.get("id") for row in rows}, path))
+    return rows
+
+
+def _carried_clarification_rows(
+    ledger: Mapping[str, Any], seen_ids: set[object], path: Path,
+) -> list[dict[str, Any]]:
+    """이월 결정은 active 질문이 아니다. 이번 런 활동 원장을 요구하지 않는다."""
+    carried = ledger.get("carriedDecisions")
+    if not isinstance(carried, list):
+        return []
+    rows: list[dict[str, Any]] = []
+    seen = set(seen_ids)
+    for index, entry in enumerate(carried):
+        if not isinstance(entry, Mapping):
+            _fail("lead", path, f"carriedDecisions[{index}]", "must be an object")
+        decision = entry.get("decision")
+        if not isinstance(decision, Mapping):
+            _fail(
+                "lead", path, f"carriedDecisions[{index}].decision",
+                "must be an object",
+            )
+        cid = decision.get("id")
+        if cid in seen:
+            continue
+        rows.append(_carried_clarification_row(decision))
+        seen.add(cid)
+    return rows
+
+
+def _carried_clarification_row(source: Mapping[str, Any]) -> dict[str, Any]:
+    row = {
+        key: source[key]
+        for key in (
+            "id", "ticketId", "kind", "statement", "expectedForm", "blocks",
+            "origin", "userConfirmation", "options",
+        )
+        if key in source
+    }
+    if "approval" in source:
+        row["approvalContext"] = source["approval"]
+    resolution = source.get("resolutionInput")
+    if not isinstance(resolution, Mapping):
+        row["status"] = "resolved"
+        return row
+    row.update(
+        status="resolved",
+        userInput=resolution.get("userText", ""),
+        resolution={
+            "disposition": resolution.get("disposition"),
+            "userText": resolution.get("userText"),
+            "checkRefs": list(resolution.get("checkRefs") or []),
+        },
+    )
+    return row
 
 
 def _project_relative(project_root: Path, path: Path) -> str:
@@ -464,7 +519,12 @@ def assemble_report(
     project_root: Path, manifest_path: Path, *,
     replace: Callable[[str, str], None] = os.replace,
 ) -> dict[str, Any]:
-    """모든 입력이 유효할 때만 계약 3.0 정본을 한 번 교체한다."""
+    """계약 3.0 정본을 조립해 게시한다.
+
+    입력이 없어 조립 자체가 안 되면 기존 파일을 건드리지 않는다. 조립은
+    됐는데 스키마만 깨진 기록은 게시한 뒤 거부한다. 게시를 건너뛰면
+    `validate-run` 이 이번 런 내용을 보지 못한다.
+    """
     manifest_row = ReportInputPath("run-manifest", "orchestrator", manifest_path)
     manifest = _read_json(manifest_row)
     if not uses_report_contract_v3(manifest):
@@ -490,9 +550,13 @@ def assemble_report(
         raise ReportAssemblyError(tuple(input_issues))
     data = _compose(project_root, manifest_path, manifest, inputs, schema)
     errors = validate(data, schema)
+    value = manifest.get("expectedReportRecordPath")
+    if not isinstance(value, str) or not value:
+        _fail("orchestrator", manifest_path, "expectedReportRecordPath", "required")
+    target = Path(value)
+    target = target if target.is_absolute() else project_root / target
+    _publish(target, data, replace)
     if errors:
-        target = Path(str(manifest.get("expectedReportRecordPath") or "data.json"))
-        target = target if target.is_absolute() else project_root / target
         raise ReportAssemblyError(
             tuple(
                 AssemblyIssue(
@@ -504,10 +568,4 @@ def assemble_report(
                 for error in errors
             )
         )
-    value = manifest.get("expectedReportRecordPath")
-    if not isinstance(value, str) or not value:
-        _fail("orchestrator", manifest_path, "expectedReportRecordPath", "required")
-    target = Path(value)
-    target = target if target.is_absolute() else project_root / target
-    _publish(target, data, replace)
     return data

package/runtime/python/okstra_ctl/report_finalize.py

@@ -7,17 +7,21 @@ read-only compatibility. The order is load-bearing: rendering before assembly
 or usage collection publishes stale derived views, and validating before
 rendering trips the report-views contract.
 
-`token-usage` is the one step whose failure does not stop the sequence, which
-deliberately accepts that first state: its input is the lead session log, so a
-refusal there would otherwise delete every artifact the later steps produce.
-The run does not pass in that state. `validators/validate-run.py` re-collects
-when the recorded usage is all zeros against an `unavailable` session source
-(`_needs_token_autofix`) and refuses the run rather than ship zeroed counts
-(`accuracy-failed`); a legacy v1 report is caught earlier still, by its
-unsubstituted `{{...}}` placeholders, which a v2 report never carries because
-its numeric cells are `null` until this step fills them. Substituting the
-tokens on a later retry then leaves the already-rendered html stale for
-`validators/validate-report-views.py`.
+A non-zero exit no longer stops the sequence before `validate-run`. A schema
+cap used to hide the contract scan: assembly refused, later steps never ran,
+and the lead only saw those failures after a second finalize. Each step still
+records its own exit; `ok` stays False when any step failed. `teardown-stages`
+is the exception — it reclaims worktrees, so a failed prefix skips it.
+
+`token-usage` reads the lead session log (state outside this run). A refusal
+there used to delete every later artifact; it no longer does, because the
+sequence continues. `validators/validate-run.py` re-collects when the recorded
+usage is all zeros against an `unavailable` session source (`_needs_token_autofix`)
+and refuses the run rather than ship zeroed counts (`accuracy-failed`). A
+legacy v1 report is caught earlier still, by its unsubstituted `{{...}}`
+placeholders, which a v2 report never carries because its numeric cells are
+`null` until this step fills them. Substituting the tokens on a later retry
+then leaves the already-rendered html stale for `validators/validate-report-views.py`.
 
 The translation sidecar is NOT one of these steps. `render-views` overlays it,
 so a non-English run dispatches the translator before this sequence starts —
@@ -447,26 +451,14 @@ def run_finalize(
     before_step: Callable[[str], None] | None = None,
     only: Sequence[str] | None = None,
 ) -> dict[str, Any]:
-    """Run the Phase 7 steps in contractual order.
-
-    A non-zero exit stops the sequence, with one exception: ``token-usage``
-    defers. Its input is the lead session log — state outside this run — so a
-    refusal there is not evidence that the artifacts after it are unwritable.
-    The deferred failure becomes the result's ``reason`` when nothing later
-    fails, and yields to any later failure, which is the step that actually
-    blocked the run.
-
-    ``before_step`` fires immediately before each step is spawned, letting an
-    adapter settle state the step will read (the Codex adapter marks the report
-    writer `completed` before `validate-run` inspects team-state).
-
-    ``only`` restricts the run to the named steps, preserving contractual
-    order. The last step (`validate-run`) is the one that usually fails, and
-    re-running the whole sequence to retry it repeats every preceding idempotent
-    step at full token and wall-clock cost.
+    """계약 순서로 Phase 7 을 돌리고, 실패해도 `validate-run` 까지 모은다.
+
+    `before_step` 은 각 단계 프로세스 직전에 호출된다. Codex 어댑터가
+    `validate-run` 앞에 작성기 상태를 `completed` 로 표시하는 자리이다.
+
+    `only` 는 고른 단계만 계약 순서로 남긴다.
     """
     steps: list[dict[str, Any]] = []
-    deferred = ""
     try:
         if ctx.report_contract_version != "3.0":
             write_execution_roles(ctx)
@@ -476,7 +468,9 @@ def run_finalize(
 
     if only:
         selected = set(only)
-        contract_order = V3_STEP_ORDER if ctx.report_contract_version == "3.0" else STEP_ORDER
+        contract_order = (
+            V3_STEP_ORDER if ctx.report_contract_version == "3.0" else STEP_ORDER
+        )
         unknown = sorted(selected - set(contract_order))
         if unknown:
             return {
@@ -486,75 +480,70 @@ def run_finalize(
             }
         commands = [(name, cmd) for name, cmd in commands if name in selected]
 
+    first_failure = ""
     for name, command in commands:
+        # 실패한 시퀀스가 worktree 를 거두면 재작업 대상이 사라진다.
+        if name == STEP_TEARDOWN_STAGES and first_failure:
+            continue
         if before_step is not None:
             before_step(name)
-        if name == STEP_PROJECT_ACTIVITY:
-            try:
-                if ctx.report_contract_version == "3.0":
-                    assembled = assemble_report(ctx.project_root, ctx.manifest_path)
-                    count = len(assembled.get("agentActivity") or [])
-                else:
-                    rows = project_agent_activity(
-                        ctx.project_root,
-                        ctx.manifest_path,
-                        ctx.data_path,
-                    )
-                    count = len(rows)
-            except (ActivityProjectionError, ReportAssemblyError) as exc:
-                result = subprocess.CompletedProcess(
-                    command,
-                    1,
-                    "",
-                    str(exc),
-                )
-            else:
-                result = subprocess.CompletedProcess(
-                    command,
-                    0,
-                    json.dumps({"count": count}),
-                    "",
-                )
-        else:
-            result = None
-        if name == STEP_TEARDOWN_STAGES:
-            result = _teardown_stage_worktrees(ctx, command)
-        if name == STEP_VALIDATE_RUN:
-            try:
-                _link_lead_result_for_validation(ctx)
-            except (DispatchError, OSError, json.JSONDecodeError) as exc:
-                return {
-                    "ok": False,
-                    "reason": f"lead result linkage failed: {exc}",
-                    "steps": steps,
-                }
-        if result is None:
-            result = subprocess.run(
-                command,
-                cwd=ctx.project_root,
-                text=True,
-                capture_output=True,
-            )
+        result = _run_finalize_step(ctx, name, command)
         steps.append(step_payload(name, command, result))
-        if result.returncode != 0:
-            failure = f"{name} failed with exit code {result.returncode}"
-            # Token collection reads the lead session log, which lives outside
-            # this run. One refusal there (`grandTotalTokens=0`) took the whole
-            # run's output with it: html never rendered, follow-ups never
-            # spawned, and `validate-run` then blocked on `report-views:
-            # missing html artifact`. So this step alone defers instead of
-            # stopping the sequence. It hides nothing — the non-zero exit stays
-            # in `steps`, `ok` stays False, and the closing `validate-run`
-            # still refuses the run.
-            if name == STEP_TOKEN_USAGE:
-                deferred = failure
-                continue
-            return {"ok": False, "reason": failure, "steps": steps}
-    if deferred:
-        return {"ok": False, "reason": deferred, "steps": steps}
+        if result.returncode != 0 and not first_failure:
+            first_failure = f"{name} failed with exit code {result.returncode}"
+    if first_failure:
+        return {"ok": False, "reason": first_failure, "steps": steps}
     return {"ok": True, "reason": "", "steps": steps}
 
 
+def _run_finalize_step(
+    ctx: FinalizeContext,
+    name: str,
+    command: Sequence[str],
+) -> subprocess.CompletedProcess[str]:
+    """한 Phase 7 단계를 실행하고 그 단계의 종료 코드만 돌려준다."""
+    if name == STEP_PROJECT_ACTIVITY:
+        return _run_project_activity(ctx, command)
+    if name == STEP_TEARDOWN_STAGES:
+        return _teardown_stage_worktrees(ctx, command)
+    if name == STEP_VALIDATE_RUN:
+        try:
+            _link_lead_result_for_validation(ctx)
+        except (DispatchError, OSError, json.JSONDecodeError) as exc:
+            return subprocess.CompletedProcess(
+                command, 1, "", f"lead result linkage failed: {exc}"
+            )
+    return subprocess.run(
+        command,
+        cwd=ctx.project_root,
+        text=True,
+        capture_output=True,
+    )
+
+
+def _run_project_activity(
+    ctx: FinalizeContext,
+    command: Sequence[str],
+) -> subprocess.CompletedProcess[str]:
+    """계약 3.0 은 조립, 그 외는 활동 투영만 한다."""
+    try:
+        if ctx.report_contract_version == "3.0":
+            assembled = assemble_report(ctx.project_root, ctx.manifest_path)
+            count = len(assembled.get("agentActivity") or [])
+        else:
+            rows = project_agent_activity(
+                ctx.project_root,
+                ctx.manifest_path,
+                ctx.data_path,
+            )
+            count = len(rows)
+    except (ActivityProjectionError, ReportAssemblyError) as exc:
+        return subprocess.CompletedProcess(command, 1, "", str(exc))
+    return subprocess.CompletedProcess(
+        command, 0, json.dumps({"count": count}), ""
+    )
+
+
 def write_execution_roles(ctx: FinalizeContext) -> None:
     """Write the exact manifest role set onto the final-report data.json."""
     if not ctx.data_path.is_file() or not ctx.manifest_path.is_file():
@@ -685,13 +674,11 @@ def _recovery_step_names(
     """The steps a retry has to re-run: every step from the earliest failure on.
 
     Naming only the failed steps would prescribe half a recovery. `token-usage`
-    defers, so `render-views` already wrote an html view from unsubstituted
-    data; substituting the tokens on a retry leaves that view stale
+    can fail while `render-views` still writes html from unsubstituted data;
+    substituting the tokens on a retry leaves that view stale
     (`validators/validate-report-views.py` checks `source-sha256` against the
-    md body). And a sequence that stopped early never reached `validate-run`,
-    which is the step that decides whether the run is shippable. Resuming from
-    the earliest failure redoes both while still skipping the prefix that
-    succeeded — the saving `--only` exists for.
+    md body). Resuming from the earliest failure redoes the tail while skipping
+    the prefix that succeeded — the saving `--only` exists for.
     """
     failed = {
         string_value(step.get("name"))

package/runtime/validators/validate-run.py

@@ -3492,8 +3492,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 +3595,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 +3609,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,
@@ -5778,6 +5785,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 +5824,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 +5933,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 +5948,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:
@@ -8628,14 +8649,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 +8733,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 +8749,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 +8774,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 +8794,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 +8811,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 +9619,35 @@ 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 파일은 건너뛴다."""
     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]
+    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():
+            if isinstance(declared, str) and declared.strip():
+                failures.append(
+                    f"convergence state {state_path.name}: missing declared artifact"
+                )
             continue
         try:
             state = json.loads(state_path.read_text(encoding="utf-8"))
@@ -10355,7 +10476,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
     )