okstra 0.191.1 → 0.192.0

package/runtime/python/okstra_ctl/convergence_reverify_prompt.py

@@ -0,0 +1,231 @@
+"""Reverify 지시문을 수렴 상태와 라운드 계획에서 결정적으로 렌더한다.
+
+Phase 5.5 의 재검증 워커는 리드가 손으로 쓴 지시문을 받아 왔다. 그 손에서 두
+가지가 반복해서 어긋났다(실측 2026-09-09, 다른 세션의 첫 reverify 보고).
+
+- 응답 형식 — 리드가 `- Verdict:` 불릿을 적었고 워커는 시킨 대로 썼다. 파서는
+  이제 그 모양도 읽지만(`verdict_blocks._field_match`), 형식 블록을 리드가 매
+  라운드 다시 쓰는 구조 자체가 결함이다.
+- 근거 축약 — 리드가 `**Cited evidence**` 줄에 원 워커가 인용한 근거의 일부만
+  옮겨 적었다. 검증자는 계약대로 그 줄만 열었고, `burden-not-met` 5건은 주장을
+  검증한 것이 아니라 리드의 전사(轉寫)를 검증한 것이었다.
+
+이 모듈은 그 지시문을 코드로 만든다. finding 마다 그룹의 요약·원 워커·인용
+근거 줄에 더해, **원 워커의 결과 파일과 그 안의 항목 id, 그리고 원 워커의 감사
+사이드카**(실행한 읽기 전용 명령과 출력이 기록된 파일)를 싣고, 그 둘을 열어도
+된다고 명시한다. 검증자는 리드의 요약이 아니라 원 워커가 실제로 인용한 것을
+판단한다. 응답 형식은 `verdict_blocks` 가 읽는 정본 모양 그대로다.
+
+산출물은 프롬프트 materializer 의 `--instruction` 이 받는 본문이다. `## Instructions`
+로 시작하므로 `complete_reverify_instruction` 이 모델·task type·금지 목록을 그
+앞에 붙이고, 출력 계약(`templates/reverify-output-contract.md`)을 뒤에 덧붙인다.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from .convergence_critic_prompt import analyser_results
+from .worker_artifact_paths import WorkerArtifactPathError, audit_sidecar_rel
+
+
+class ReverifyPromptError(ValueError):
+    """지시문을 결정적으로 만들 수 없다."""
+
+
+@dataclass(frozen=True)
+class ReverifyFinding:
+    """검증 큐의 finding 하나와, 그 원 워커의 실물 인용 위치."""
+
+    finding_id: str
+    summary: str
+    origin_worker: str
+    origin_item_id: str
+    origin_evidence: str
+    origin_result_path: str
+    origin_audit_path: str
+
+
+_ADVERSARIAL_MANDATE = """Your job is to BREAK each finding below, not to confirm it. For EACH finding,
+open the cited evidence directly and actively search for evidence that the claim
+is wrong, overstated, or unproven. Then respond with exactly one verdict:
+
+- **REFUTED**: You broke the claim. State the basis:
+  - counter-evidence — you found contradicting evidence (give file:line or log line), OR
+  - burden-not-met — you re-inspected the cited evidence and could neither confirm
+    nor refute it (the claim has not proven itself).
+- **SURVIVES**: You actively tried to refute it and failed — the claim withstood the attack.
+- **SURVIVES-WITH-CAVEAT**: It holds, but a scope limit / extra condition / missing
+  precondition exists (state it).
+- **UNVERIFIABLE**: Capability, credential, network, or service state prevents you
+  from opening or reproducing the cited evidence. Do not use REFUTED as a substitute.
+
+The burden of proof is on the claim. If after inspecting the cited evidence you remain
+uncertain, your verdict is REFUTED with basis = burden-not-met.
+
+Inspect ONLY the evidence each finding cites and its immediate surroundings. Do NOT
+re-read the task brief, instruction-set, or report template."""
+
+_COLLABORATIVE_MANDATE = """Review the following findings discovered by other workers.
+For EACH finding, respond with exactly one verdict:
+
+- **AGREE**: The finding is valid based on the evidence presented
+- **DISAGREE**: The finding is incorrect or unsupported (explain briefly why)
+- **SUPPLEMENT**: The finding is valid AND you have additional supporting evidence or context
+- **UNVERIFIABLE**: Capability, credential, network, or service state prevents you
+  from checking this finding. Explain the unavailable capability; do not substitute DISAGREE.
+
+Do NOT re-analyze the original source materials. Judge based on the evidence provided."""
+
+# 근거 접근 규칙. `**Cited evidence**` 는 리드의 요약이고, 완전한 인용은 원 워커의
+# 결과 항목이다. 검증자가 요약만 열고 "이 근거로는 입증되지 않는다" 고 답하던
+# 자리를 막는다.
+_EVIDENCE_ACCESS = """The `**Cited evidence**` line is the lead's summary of what the origin worker cited.
+The complete citation is the origin worker's own item: before judging, open the
+`**Origin item**` file at the named `### <item-id>` section and read every path, line,
+command, and quote it cites. The `**Origin audit sidecar**` records the read-only
+commands that worker ran and their output; it counts as cited evidence and you may
+open it. Judge the claim against what the origin worker actually cited, never against
+the summary line alone."""
+
+_ADVERSARIAL_RESPONSE = """### <finding-id>
+**Verdict**: REFUTED | SURVIVES | SURVIVES-WITH-CAVEAT | UNVERIFIABLE
+**Basis** (only if REFUTED): counter-evidence | burden-not-met
+**Explanation**: <2-3 sentences; for counter-evidence include the file:line you found>"""
+
+_COLLABORATIVE_RESPONSE = """### <finding-id>
+**Verdict**: AGREE | DISAGREE | SUPPLEMENT | UNVERIFIABLE
+**Explanation**: <2-3 sentences>"""
+
+
+def _nonempty_string(value: Any) -> str:
+    return value if isinstance(value, str) and value.strip() else ""
+
+
+def plan_row_for_worker(plan: Mapping[str, Any], worker_id: str) -> Mapping[str, Any]:
+    """계획의 `dispatches[]` 에서 이 워커의 행 하나. 검증기와 같은 규칙으로 맞춘다.
+
+    `validators/validate-run.py` `_plan_dispatch_finding_ids` 처럼 `worker` 가
+    그대로 같거나 `<worker>-worker` 가 같으면 그 행이다.
+    """
+    dispatches = plan.get("dispatches")
+    if not isinstance(dispatches, list):
+        raise ReverifyPromptError("round plan has no dispatches array")
+    matched = [
+        row for row in dispatches
+        if isinstance(row, Mapping)
+        and (row.get("worker") == worker_id or f"{row.get('worker')}-worker" == worker_id)
+    ]
+    if len(matched) != 1:
+        planned = ", ".join(
+            _nonempty_string(row.get("worker")) or "?" for row in dispatches
+            if isinstance(row, Mapping)
+        )
+        raise ReverifyPromptError(
+            f"round plan dispatches nothing to `{worker_id}`; planned workers: "
+            f"{planned or 'none'}"
+        )
+    finding_ids = matched[0].get("findingIds")
+    if not isinstance(finding_ids, list) or not finding_ids:
+        raise ReverifyPromptError(f"round plan row for `{worker_id}` has no findingIds")
+    return matched[0]
+
+
+def reverify_findings(
+    groups: Mapping[str, Any],
+    plan: Mapping[str, Any],
+    worker_id: str,
+    *,
+    project_root: Path,
+    run_dir: Path,
+) -> list[ReverifyFinding]:
+    """계획 행의 finding 을 계획 순서대로, 원 워커의 실물 인용 위치와 함께."""
+    row = plan_row_for_worker(plan, worker_id)
+    by_id = {
+        _nonempty_string(group.get("findingId")): group
+        for group in groups.get("groups") or []
+        if isinstance(group, Mapping) and _nonempty_string(group.get("findingId"))
+    }
+    result_paths = {
+        result.worker_id: result.result_path
+        for result in analyser_results(groups, project_root=project_root, run_dir=run_dir)
+    }
+    findings: list[ReverifyFinding] = []
+    for finding_id in row["findingIds"]:
+        group = by_id.get(str(finding_id))
+        if group is None:
+            raise ReverifyPromptError(
+                f"round plan names `{finding_id}`, which the grouping does not carry"
+            )
+        origin = _nonempty_string(group.get("originWorker"))
+        discovered = group.get("discoveredBy")
+        origin_item = (
+            _nonempty_string((discovered.get(origin) or {}).get("itemId"))
+            if isinstance(discovered, Mapping) and isinstance(discovered.get(origin), Mapping)
+            else ""
+        )
+        result_path = result_paths.get(origin, "")
+        if not origin or not origin_item or not result_path:
+            raise ReverifyPromptError(
+                f"finding `{finding_id}` has no resolvable origin item "
+                f"(origin worker `{origin or '?'}`, item `{origin_item or '?'}`)"
+            )
+        try:
+            audit_path = audit_sidecar_rel(result_path)
+        except WorkerArtifactPathError as exc:
+            raise ReverifyPromptError(str(exc)) from exc
+        findings.append(ReverifyFinding(
+            finding_id=str(finding_id),
+            summary=_nonempty_string(group.get("summary")),
+            origin_worker=origin,
+            origin_item_id=origin_item,
+            origin_evidence=_nonempty_string(group.get("originEvidence")),
+            origin_result_path=result_path,
+            origin_audit_path=audit_path,
+        ))
+    return findings
+
+
+def reverify_prompt_body(
+    *,
+    task_key: str,
+    round_number: int,
+    adversarial: bool,
+    findings: Sequence[ReverifyFinding],
+) -> str:
+    """reverify 지시문 파일 본문. 같은 입력이면 같은 바이트를 낸다."""
+    if not _nonempty_string(task_key):
+        raise ReverifyPromptError("convergence groups carry no taskKey")
+    if not findings:
+        raise ReverifyPromptError("no findings to verify")
+    mode = "ADVERSARIAL re-verification" if adversarial else "re-verification"
+    mandate = _ADVERSARIAL_MANDATE if adversarial else _COLLABORATIVE_MANDATE
+    response = _ADVERSARIAL_RESPONSE if adversarial else _COLLABORATIVE_RESPONSE
+    rows = [
+        "## Instructions\n\n",
+        f"Perform {mode} for {task_key} (round {round_number}).\n\n",
+        mandate, "\n\n",
+        _EVIDENCE_ACCESS, "\n\n",
+        "## Findings to verify\n",
+    ]
+    for finding in findings:
+        rows.append(f"\n### {finding.finding_id}: {finding.summary or '(no summary)'}\n")
+        rows.append(f"**Origin**: {finding.origin_worker}\n")
+        rows.append(f"**Cited evidence**: {finding.origin_evidence or '(none recorded)'}\n")
+        rows.append(
+            f"**Origin item**: `{finding.origin_result_path}` — section "
+            f"`### {finding.origin_item_id}`\n"
+        )
+        rows.append(f"**Origin audit sidecar**: `{finding.origin_audit_path}`\n")
+    rows.append("\n## Response format\n\n")
+    rows.append(
+        "One block per finding, headed by the finding id at exactly three hashes. "
+        "Field labels are bold with the colon outside (`**Verdict**: …`); the "
+        "collector also reads `**Verdict:** …` and `- Verdict: …` as the same field.\n\n"
+    )
+    rows.append(response.replace("<finding-id>", findings[0].finding_id))
+    rows.append("\n")
+    if len(findings) > 1:
+        rows.append(f"\n### {findings[1].finding_id}\n**Verdict**: ...\n")
+    return "".join(rows)

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -31,6 +31,8 @@ from .dispatch_state import (
     load_json_object as _load_json_object,
     link_agent_dispatch_result as _link_agent_dispatch_result,
     missing_completion_paths as _missing_completion_paths,
+    unusable_result_defect,
+    _dispatch_worker_key,
     _plan_verify_result_aliases,
     mutate_team_state as _mutate_team_state,
     require_string as _require_string,
@@ -276,6 +278,9 @@ class WorkerOutcome:
     timeout: bool
     terminal_stage: str
     degraded_from: str
+    # 파일은 있는데 읽을 수 없는 산출물의 사유 — `missing_completion_paths` 에
+    # 그 경로가 함께 들어가고, 실패 사유는 이 문장을 인용한다.
+    artifact_defects: tuple[str, ...] = ()
 
 
 @dataclass(frozen=True)
@@ -1027,29 +1032,8 @@ def _translator_job_from_reservation(
         raise DispatchError(
             "translator dispatch requires a canonical translator role execution"
         )
-    contract = manifest.get("agentContract")
-    if not isinstance(contract, Mapping):
-        raise DispatchError("translator dispatch requires an agent contract")
-    reservation_root = _resolve_required_path(
-        project_root, contract, "invocationReservationRootPath"
-    )
-    dispatched_ids = {
-        str(row.get("dispatchId") or "")
-        for collection in (
-            team_state.get("workerDispatches") or [],
-            team_state.get("agentDispatches") or [],
-        )
-        for row in collection
-        if isinstance(row, Mapping)
-    }
+    candidates, seen = translator_reservations(project_root, manifest, team_state)
     run_manifest_rel = _string_value(manifest.get("runManifestPath"))
-    candidates, seen = _translator_reservation_candidates(
-        project_root,
-        reservation_root,
-        execution=execution,
-        dispatched_ids=dispatched_ids,
-        run_manifest_rel=run_manifest_rel,
-    )
     if len(candidates) != 1:
         run_label = run_manifest_rel or "run manifest path unknown"
         raise DispatchError(
@@ -1115,6 +1099,47 @@ def _translator_job_from_reservation(
     )
 
 
+def translator_reservations(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+) -> tuple[list[Mapping[str, Any]], list[str]]:
+    """이 run 이 지금 디스패치할 수 있는 translator 예약과, 본 예약 전부의 요약.
+
+    두 소비자가 같은 답을 읽는다: `_translator_job_from_reservation` 은 그 하나를
+    골라 띄우고, `report-finalize` 의 `translate` 단계
+    (`okstra_ctl.report_translation_dispatch`) 는 0건이면 예약을 만든다. 후보를
+    세는 규칙이 두 곳이면 한쪽만 고쳐져 "만들었는데 못 고른다" 가 나온다.
+    """
+    execution = _canonical_translator_execution(manifest)
+    if execution is None:
+        raise DispatchError(
+            "translator dispatch requires a canonical translator role execution"
+        )
+    contract = manifest.get("agentContract")
+    if not isinstance(contract, Mapping):
+        raise DispatchError("translator dispatch requires an agent contract")
+    reservation_root = _resolve_required_path(
+        project_root, contract, "invocationReservationRootPath"
+    )
+    dispatched_ids = {
+        str(row.get("dispatchId") or "")
+        for collection in (
+            team_state.get("workerDispatches") or [],
+            team_state.get("agentDispatches") or [],
+        )
+        for row in collection
+        if isinstance(row, Mapping)
+    }
+    return _translator_reservation_candidates(
+        project_root,
+        reservation_root,
+        execution=execution,
+        dispatched_ids=dispatched_ids,
+        run_manifest_rel=_string_value(manifest.get("runManifestPath")),
+    )
+
+
 def _translator_reservation_candidates(
     project_root: Path,
     reservation_root: Path,
@@ -1953,9 +1978,15 @@ def _outcome_from_completed(handle: WorkerHandle) -> WorkerOutcome:
         timeout=False,
         terminal_stage="exited",
         degraded_from=handle.degraded_from,
+        artifact_defects=_artifact_defects(handle.job),
     )
 
 
+def _artifact_defects(job: WorkerJob) -> tuple[str, ...]:
+    defect = unusable_result_defect(job.worker_id, job.result_path)
+    return (defect,) if defect else ()
+
+
 def _correct_teardown_marked_dispatches(plan: DispatchPlan) -> None:
     """Let the wrapper's own exit settle a record teardown wrote off.
 
@@ -3123,6 +3154,7 @@ def _outcome_from_status(record: Mapping[str, Any], status) -> WorkerOutcome:
         timeout=status.timeout,
         terminal_stage=status.stage,
         degraded_from=_string_value(record.get("degradedFrom")),
+        artifact_defects=_record_artifact_defects(record),
     )
 
 
@@ -3190,8 +3222,11 @@ def _record_missing_completion_paths(record: Mapping[str, Any]) -> tuple[Path, .
     result_path = Path(_string_value(record.get("resultPath")))
     worker_result = Path(_string_value(record.get("workerResultPath")))
     missing: list[Path] = []
+    worker_id = _dispatch_worker_key(record)
     for path in _record_completion_paths(record):
         if path.is_file():
+            if path == result_path and unusable_result_defect(worker_id, path):
+                missing.append(path)
             continue
         if path in {result_path, worker_result} and any(alias.is_file() for alias in aliases):
             continue
@@ -3199,6 +3234,13 @@ def _record_missing_completion_paths(record: Mapping[str, Any]) -> tuple[Path, .
     return tuple(missing)
 
 
+def _record_artifact_defects(record: Mapping[str, Any]) -> tuple[str, ...]:
+    defect = unusable_result_defect(
+        _dispatch_worker_key(record), Path(_string_value(record.get("resultPath")))
+    )
+    return (defect,) if defect else ()
+
+
 def _should_retry(outcome: WorkerOutcome, attempt: int) -> bool:
     """결과가 없으면 재시도한다 — 기준은 종료 코드가 아니라 산출물이다.
 
@@ -3245,6 +3287,8 @@ def _failure_reason(outcome: WorkerOutcome) -> str:
         return "CLI ended cleanly without emitting a result event"
     if outcome.returncode != 0:
         return f"wrapper exited with code {outcome.returncode}"
+    if outcome.artifact_defects:
+        return "required worker artifact is unusable: " + "; ".join(outcome.artifact_defects)
     if outcome.missing_completion_paths:
         missing = ", ".join(str(path) for path in outcome.missing_completion_paths)
         return f"required worker artifact was not produced: {missing}"

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -53,6 +53,7 @@ from .execution_manifest import (
 from .execution_mutation_audit import ExecutionMutationAudit, MutationSnapshot
 from .final_report_paths import final_report_data_path
 from .report_inputs import report_narrative_path, uses_report_contract_v3
+from .report_narrative import narrative_structure_defect
 from .worker_prompt_body import REPORT_WRITER_WORKER_ID
 from .worker_prompt_contract import (
     PromptRecord,
@@ -1636,10 +1637,33 @@ def dispatch_mode(jobs: Sequence[WorkerJob]) -> str:
     return BACKEND_MIXED
 
 
+def unusable_result_defect(worker_id: str, result_path: Path) -> str | None:
+    """산출물이 있어도 소비자가 읽을 수 없으면 없는 것이다 — 지금은 서사 한 종류.
+
+    report-writer 의 서사가 줄 문법을 어기면(frontmatter·헤딩으로 된 보통
+    보고서) 조립이 Phase 7 에서 거절하고, 그때는 배치의 재시도가 이미 지나
+    리드가 손으로 재저작을 띄워야 한다 — 실측(2026-09-09, jobs implementation
+    stage-2)에서 리드는 그것을 하지 않고 run 을 닫았다. 수집 시점에 "없는
+    산출물" 로 세면 `_should_retry` 가 같은 배치 안에서 다시 띄운다.
+    """
+    if worker_id != REPORT_WRITER_WORKER_ID or not result_path.is_file():
+        return None
+    try:
+        text = result_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return f"narrative is unreadable: {exc}"
+    defect = narrative_structure_defect(text)
+    if defect is None:
+        return None
+    return f"narrative does not parse: {defect}"
+
+
 def missing_completion_paths(job: WorkerJob) -> tuple[Path, ...]:
     missing: list[Path] = []
     for path in job.completion_paths:
         if path.is_file():
+            if path == job.result_path and unusable_result_defect(job.worker_id, path):
+                missing.append(path)
             continue
         # reports seq 와 workerResults seq 가 갈라지면 워커는 다른 쪽
         # 파일명으로 쓴다. 둘 중 하나가 있으면 산출물은 있는 것이다.

package/runtime/python/okstra_ctl/next_phase.py

@@ -71,8 +71,9 @@ HANDLED_TASK_TYPES = frozenset(
 )
 
 # implementation-option-selection 의 routing enum 중 phase 가 아닌 값.
+# `pending-direction-selection` 과 `blocked` 는 `_from_option_selection` 이
+# 명시 분기로 다룬다.
 _OPTION_SELECTION_NON_PHASE = {
-    "pending-direction-selection": STATUS_PENDING,
     "blocked": STATUS_BLOCKED,
 }
 
@@ -231,13 +232,22 @@ def _from_option_selection(report_data: Mapping[str, Any]) -> dict[str, str]:
         # release-handoff 는 `routingRecommendation`.
         return make(status=STATUS_BLOCKED, rationale=_selection_guidance(selection))
     if routing == "pending-direction-selection":
-        # 이 상태는 **성공**이다 — 비교가 끝났고 사용자가 방향을 고르면 된다.
-        # 그런데 근거가 비면 closeout 표에 `pending` 행이 없어 "Otherwise →
-        # /okstra-inspect status" 로 떨어지고, 사용자는 끝난 phase 를 들여다보라는
-        # 안내를 받는다. 실측(dev-10341): 1회차가 IO-001·IO-002 를 내고 여기서
-        # 멈췄는데 안내가 없어 같은 phase 가 세 번 더 돌았고, 그동안 워커가
-        # 무너지며 결과가 0건으로 나빠졌다.
-        return make(status=STATUS_PENDING, rationale=_direction_selection_reason(selection))
+        # 이 상태는 **성공**이다 — 비교가 끝났고, 방향은 계획 단계의 위저드가
+        # 고르게 한다(`selected_direction_pick`). 그러니 다음 phase 는 지금 바로
+        # 시작할 수 있는 `implementation-planning` 이고 status 는 `ready` 다.
+        # 종전에는 phase 없는 `pending` 이었다: task 선택 화면이 `next: --
+        # (pending)` 을 찍어 목적지를 지웠고, task-type 화면은 추천 없이 방금
+        # 끝난 phase 의 재실행을 1번에 올렸다(실측 2026-09-09) — 근거 문장은
+        # "다시 돌리지 마세요" 라고 말하는데 화면은 그 반대를 권한 셈이다.
+        # 근거는 후보 id 를 이름으로 싣는다. 실측(dev-10341): 1회차가
+        # IO-001·IO-002 를 내고 안내 없이 멈춰 같은 phase 가 세 번 더 돌았다.
+        # 후보가 0건이면 고를 것이 없으므로 종전대로 phase 없는 pending 이다.
+        rationale = _direction_selection_reason(selection)
+        if not rationale:
+            return make(status=STATUS_PENDING)
+        return make(
+            phase="implementation-planning", status=STATUS_READY, rationale=rationale
+        )
     if routing in _OPTION_SELECTION_NON_PHASE:
         return make(status=_OPTION_SELECTION_NON_PHASE[routing])
     if not routing:

package/runtime/python/okstra_ctl/plan_items.py

@@ -763,8 +763,9 @@ REVERIFY_PREAMBLE = (
 # 정본 서술은 plan-body-verification.md §"Response format" 이지만 전달 채널은
 # 이 출력이다 — 큐는 모든 검증자 프롬프트에 verbatim 으로 실리는 유일한
 # 조각이라, 여기 실린 블록은 리드가 프롬프트를 어떻게 손 조립하든 도달한다.
-# 두 실측 실패 모양(`## <id>` 2해시 헤딩, `**Verdict:** AGREE` 굵게 안 콜론)을
-# 본문이 직접 금지한다.
+# 실측 실패 모양 중 `## <id>` 2해시 헤딩은 본문이 직접 금지한다. 라벨 변형
+# (`**Verdict:** AGREE`, `- Verdict: AGREE`)은 파서가 같은 필드로 읽으므로
+# (`verdict_blocks._field_match`) 금지하지 않고 그렇게 적는다.
 PLAN_VERIFY_RESPONSE_FORMAT = (
     "\n## Response format\n"
     "\n"
@@ -772,8 +773,9 @@ PLAN_VERIFY_RESPONSE_FORMAT = (
     "item's own id at exactly three hashes (`### P-...`). The collector parses "
     "`^### ` and nothing else — a block at any other depth is not an unparsed "
     "block; it is a verdict that was never recorded, and the round is scored "
-    "on the items that remain. Field labels keep the colon outside the bold: "
-    "`**Verdict**: AGREE`, never `**Verdict:** AGREE`.\n"
+    "on the items that remain. Field labels are bold with the colon outside: "
+    "`**Verdict**: AGREE`; the collector also reads `**Verdict:** AGREE` and "
+    "`- Verdict: AGREE` as the same field.\n"
     "\n"
     "### <item-id>\n"
     "**Verdict**: AGREE | DISAGREE(<a|b|c|d|e|f>) | SUPPLEMENT | UNVERIFIABLE\n"

package/runtime/python/okstra_ctl/report_finalize.py

@@ -25,10 +25,15 @@ 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 —
-after verifying the data.json is English, which is why `check-source` is also
-available as a standalone command.
+The translation sidecar is the `translate` step, between `check-source` and
+`render-views`: `render-views` overlays it, and `check-source` has to pass first
+because the extractor refuses a work list from a non-English source. It used to
+be a manual lead sequence outside this command (materialize the translator
+prompt, dispatch it, resume finalize at `render-views`), written only in a doc
+the lead lazy-reads; a lead that ran the whole sequence at once skipped it and
+the run kept an English view under a `ko` report (2026-09-09, fontsninja-v3-site
+dev-10628-3). `okstra_ctl.report_translation_dispatch` owns the step; an English
+report or an existing sidecar makes it a no-op.
 
 Every lead adapter drives Phase 7 through this module: the Codex adapter calls
 it in-process (``codex_dispatch``), and a Claude-led run reaches the same code
@@ -62,6 +67,7 @@ from .final_report_paths import (
 from .paths import task_dir, task_manifest_file
 from .report_view_artifacts import html_view_path
 from .release_gate import release_handoff_allowed
+from .report_translation_dispatch import TranslateOutcome, translate_report
 from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
 from .stage_integrate import IntegrateError
 from .stage_targets import (
@@ -83,6 +89,7 @@ from okstra_project.phase_pointer import (
 
 STEP_PROJECT_ACTIVITY = "project-activity"
 STEP_CHECK_SOURCE = "check-source"
+STEP_TRANSLATE = "translate"
 STEP_TOKEN_USAGE = "token-usage"
 STEP_RENDER_VIEWS = "render-views"
 STEP_SPAWN_FOLLOWUPS = "spawn-followups"
@@ -96,6 +103,7 @@ STEP_ORDER = (
     # a Korean SSOT into English chrome, spawning follow-ups from it, and
     # validating it all succeed on a record the next phase cannot read.
     STEP_CHECK_SOURCE,
+    STEP_TRANSLATE,
     STEP_TOKEN_USAGE,
     STEP_RENDER_VIEWS,
     STEP_SPAWN_FOLLOWUPS,
@@ -112,6 +120,8 @@ V3_STEP_ORDER = (
     STEP_TOKEN_USAGE,
     STEP_PROJECT_ACTIVITY,
     STEP_CHECK_SOURCE,
+    # After the English gate, before the render that overlays its sidecar.
+    STEP_TRANSLATE,
     STEP_RENDER_VIEWS,
     STEP_SPAWN_FOLLOWUPS,
     STEP_VALIDATE_RUN,
@@ -337,6 +347,10 @@ def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
                 str(ctx.data_path),
             ],
         ),
+        (
+            STEP_TRANSLATE,
+            ["<in-process>", "translate", str(ctx.data_path)],
+        ),
         (
             STEP_TOKEN_USAGE,
             [
@@ -782,6 +796,8 @@ def _run_finalize_step(
     """한 Phase 7 단계를 실행하고 그 단계의 종료 코드만 돌려준다."""
     if name == STEP_PROJECT_ACTIVITY:
         return _run_project_activity(ctx, command)
+    if name == STEP_TRANSLATE:
+        return _run_translate(ctx, command)
     if name == STEP_TEARDOWN_STAGES:
         return _teardown_stage_worktrees(ctx, command)
     if name == STEP_RECORD_GROUP_MEMORY:
@@ -801,6 +817,31 @@ def _run_finalize_step(
     )
 
 
+def _run_translate(
+    ctx: FinalizeContext,
+    command: Sequence[str],
+) -> subprocess.CompletedProcess[str]:
+    """비영어 리포트의 번역 사이드카를 만든다. 영어 리포트는 건너뛴다.
+
+    실패는 다른 단계처럼 기록만 하고 시퀀스는 계속 돈다 — `render-views` 는
+    사이드카 없이 영어 열람본을 내고, `validate-run` 은 권고를 남기며, 결과의
+    `--only translate --only render-views …` 재개 힌트가 그 둘을 다시 돌린다.
+    """
+    try:
+        outcome = translate_report(
+            project_root=ctx.project_root,
+            workspace_root=ctx.workspace_root,
+            manifest_path=ctx.manifest_path,
+            manifest=_load_manifest(ctx.manifest_path),
+            data_path=ctx.data_path,
+        )
+    except (FinalizeError, OSError, JsonBoundaryError) as exc:
+        outcome = TranslateOutcome(1, "", f"translate failed: {exc}")
+    return subprocess.CompletedProcess(
+        command, outcome.returncode, outcome.stdout, outcome.stderr
+    )
+
+
 def _run_project_activity(
     ctx: FinalizeContext,
     command: Sequence[str],
@@ -932,15 +973,21 @@ _CLI_EPILOG = r"""Usage:
   okstra report-finalize --project-root <dir> --run-manifest <path> \
     --report <final-report-<task-type>-<seq>.md> [--team-state <path>]
 
-Runs the six Phase 7 steps in their contractual order against one final-report:
+Runs the Phase 7 steps in their contractual order against one final-report:
 
   1. project-activity  project the run's activity events into the data.json
   2. check-source      verify the data.json is the English SSOT
-  3. token-usage       substitute real token/cost numbers into the data.json
-  4. render-views      write the schema-v2 task-specific *.html sibling; v1
-                       keeps the legacy conditional interactive view
-  5. spawn-followups   turn section 4 rows into task stubs
-  6. validate-run      validate the finished run artifacts
+  3. translate         for a non-English reportLanguage, materialize and
+                       dispatch the translator worker and require its
+                       *.i18n.<lang>.json sidecar; a no-op for English or
+                       when the sidecar already exists
+  4. token-usage       substitute real token/cost numbers into the data.json
+  5. render-views      write the schema-v2 task-specific *.html sibling with
+                       the translation overlaid; v1 keeps the
+                       legacy conditional interactive view
+  6. spawn-followups   turn section 4 rows into task stubs
+  7. validate-run      validate the finished run artifacts
+  8. record-group-memory / 9. teardown-stages  after a clean validation
 
 Every step is idempotent, so re-running after a fixed failure is safe. The
 sequence stops at the first non-zero exit and reports which step failed, except

package/runtime/python/okstra_ctl/report_narrative.py

@@ -29,6 +29,39 @@ class NarrativeContractError(ValueError):
     """서사 입력이 보고서 작성자 소유권이나 Markdown 문법을 위반했다."""
 
 
+# 작성자에게 도달해야 하는 줄 문법 — 합성 패킷의 Authoring Contract 가 이것을
+# 그대로 싣는다. 문법이 preamble 템플릿에만 있던 동안 작성자는 read-scope
+# 규칙대로 패킷만 읽고 frontmatter + 헤딩으로 된 보통 보고서를 냈다(실측
+# 2026-09-09, jobs implementation stage-2: `# OKSTRA Report Narrative` 0회,
+# 조립 거부, 최종 리포트 미발행).
+NARRATIVE_GRAMMAR_INSTRUCTIONS: tuple[str, ...] = (
+    f"Narrative line grammar: the file starts with the line `{TITLE}` and then "
+    "contains only three line shapes — `- **Humanised Field Name**` (one field; "
+    "nest a child by indenting two more spaces), `- Item <N>` (one array entry, "
+    "numbered 1..N without gaps), and `> value` (one scalar; repeat the line for a "
+    "multi-line value; `> _none_` for null, an empty object, or an empty array). "
+    "Blank lines are ignored.",
+    "Every other line is rejected — YAML frontmatter (`---` blocks), Markdown "
+    "headings (`#`, `##`, `###`), pipe tables at column 0, code fences, bare "
+    "paragraphs, JSON. Put such text inside a `> ` value instead. Report assembly "
+    "refuses the file otherwise and the run publishes no report.",
+)
+
+
+def narrative_structure_defect(markdown: str) -> str | None:
+    """줄 문법 위반 메시지, 없으면 None — 수집 시점의 산출물 검사용.
+
+    값 결함(enum 밖 값 등)은 보지 않는다; 그것은 교정 원장이 고친다. 구조가
+    깨진 파일은 원장이 해소될 자료가 없어 재저작 대상이고, 그것을 산출물이
+    있는 것으로 세면 결함이 Phase 7 조립까지 숨어 있다 재저작 없이 run 이 닫힌다.
+    """
+    try:
+        _parse_tree(markdown)
+    except NarrativeContractError as exc:
+        return str(exc)
+    return None
+
+
 class _Node:
     def __init__(self, kind: str, label: str, level: int) -> None:
         self.kind = kind