okstra 0.197.1 → 0.198.0

package/runtime/python/okstra_ctl/convergence_store.py

@@ -42,6 +42,38 @@ _CRITIC_BATCH_SCHEMA = {
 }
 
 
+# acceptance 모드는 coverage 의 gap 어휘를 쓰지 않는다 — 후보 하나에 대한 판정이
+# `confirmed`/`downgraded` 둘뿐이고, 회계는 이 배치를 읽는 쪽이 센다.
+_ACCEPTANCE_BATCH_SCHEMA = {
+    "type": "object",
+    "required": [
+        "schemaVersion", "taskKey", "mode", "provider",
+        "modelExecutionValue", "candidates",
+    ],
+    "additionalProperties": False,
+    "properties": {
+        "schemaVersion": {"const": "1.0"},
+        "taskKey": {"type": "string", "pattern": "\\S"},
+        "mode": {"const": "acceptance-devils-advocate"},
+        "provider": {"type": "string", "pattern": "\\S"},
+        "modelExecutionValue": {"type": "string", "pattern": "\\S"},
+        "candidates": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["candidateId", "verdict"],
+                "additionalProperties": False,
+                "properties": {
+                    "candidateId": {"type": "string", "pattern": "\\S"},
+                    "verdict": {"enum": ["confirmed", "downgraded"]},
+                    "statement": {"type": "string"},
+                },
+            },
+        },
+    },
+}
+
+
 def load_owned_json_object(path: Path) -> dict[str, Any]:
     try:
         return load_owned_object(path, artifact="convergence artifact")
@@ -71,6 +103,10 @@ def load_convergence_critic_batch(path: Path) -> dict[str, Any]:
     return _load_convergence_result(path, schema=_CRITIC_BATCH_SCHEMA)
 
 
+def load_acceptance_critic_batch(path: Path) -> dict[str, Any]:
+    return _load_convergence_result(path, schema=_ACCEPTANCE_BATCH_SCHEMA)
+
+
 def load_json_object(path: Path) -> dict[str, Any]:
     """Compatibility alias for convergence artifacts owned by okstra."""
     return load_owned_json_object(path)

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -1988,7 +1988,9 @@ def _outcome_from_completed(handle: WorkerHandle) -> WorkerOutcome:
 
 
 def _artifact_defects(job: WorkerJob) -> tuple[str, ...]:
-    defect = unusable_result_defect(job.worker_id, job.result_path)
+    defect = unusable_result_defect(
+        job.worker_id, job.result_path, job.dispatch_kind,
+    )
     return (defect,) if defect else ()
 
 
@@ -3228,9 +3230,12 @@ def _record_missing_completion_paths(record: Mapping[str, Any]) -> tuple[Path, .
     worker_result = Path(_string_value(record.get("workerResultPath")))
     missing: list[Path] = []
     worker_id = _dispatch_worker_key(record)
+    dispatch_kind = _string_value(record.get("dispatchKind"))
     for path in _record_completion_paths(record):
         if path.is_file():
-            if path == result_path and unusable_result_defect(worker_id, path):
+            if path == result_path and unusable_result_defect(
+                worker_id, path, dispatch_kind,
+            ):
                 missing.append(path)
             continue
         if path in {result_path, worker_result} and any(alias.is_file() for alias in aliases):
@@ -3241,7 +3246,9 @@ def _record_missing_completion_paths(record: Mapping[str, Any]) -> tuple[Path, .
 
 def _record_artifact_defects(record: Mapping[str, Any]) -> tuple[str, ...]:
     defect = unusable_result_defect(
-        _dispatch_worker_key(record), Path(_string_value(record.get("resultPath")))
+        _dispatch_worker_key(record),
+        Path(_string_value(record.get("resultPath"))),
+        _string_value(record.get("dispatchKind")),
     )
     return (defect,) if defect else ()
 

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -54,6 +54,7 @@ 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 .verdict_blocks import finding_vote_defect
 from .worker_prompt_body import REPORT_WRITER_WORKER_ID
 from .worker_prompt_contract import (
     PromptRecord,
@@ -1642,16 +1643,39 @@ def dispatch_mode(jobs: Sequence[WorkerJob]) -> str:
     return BACKEND_MIXED
 
 
-def unusable_result_defect(worker_id: str, result_path: Path) -> str | None:
-    """산출물이 있어도 소비자가 읽을 수 없으면 없는 것이다 — 지금은 서사 한 종류.
+def unusable_result_defect(
+    worker_id: str, result_path: Path, dispatch_kind: str = "",
+) -> str | None:
+    """산출물이 있어도 소비자가 읽을 수 없으면 없는 것이다 — 서사와 재검증 표.
 
     report-writer 의 서사가 줄 문법을 어기면(frontmatter·헤딩으로 된 보통
     보고서) 조립이 Phase 7 에서 거절하고, 그때는 배치의 재시도가 이미 지나
     리드가 손으로 재저작을 띄워야 한다 — 실측(2026-09-09, jobs implementation
     stage-2)에서 리드는 그것을 하지 않고 run 을 닫았다. 수집 시점에 "없는
     산출물" 로 세면 `_should_retry` 가 같은 배치 안에서 다시 띄운다.
+
+    재검증(`reverify-r<N>`) 결과도 같은 자리에 있다. `okstra convergence
+    collect-results` 는 표로 읽히지 않는 결과를 거절하는데, 원장은 그 attempt 를
+    `ok` 로 닫아 두므로 그 워커를 빼고 수집하면 `apply-round` 가 "missing vote
+    for completed worker" 로 막는다. 즉 리드에게 남는 수가 없다 — 실측
+    (2026-09-10, fontsninja-v3-site dev-10631 implementation-option-selection):
+    antigravity 가 35건 중 34건의 `**Explanation**` 을 빼먹었고 run 이 그 자리에
+    멈췄다. 여기서 결함으로 세면 재시도가 배치 안에서 돌고, 그마저 실패하면
+    attempt 가 실패로 닫혀 `collect-results` 가 그 워커를 `error` 로 적는다 —
+    엔진은 그 표를 `verification-error` 로 기록하고 라운드는 진행한다.
     """
-    if worker_id != REPORT_WRITER_WORKER_ID or not result_path.is_file():
+    if not result_path.is_file():
+        return None
+    if dispatch_kind.startswith("reverify-r"):
+        try:
+            text = result_path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError) as exc:
+            return f"reverify result is unreadable: {exc}"
+        defect = finding_vote_defect(text)
+        if defect is None:
+            return None
+        return f"reverify result does not parse: {defect}"
+    if worker_id != REPORT_WRITER_WORKER_ID:
         return None
     try:
         text = result_path.read_text(encoding="utf-8")
@@ -1667,7 +1691,9 @@ 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):
+            if path == job.result_path and unusable_result_defect(
+                job.worker_id, path, job.dispatch_kind,
+            ):
                 missing.append(path)
             continue
         # reports seq 와 workerResults seq 가 갈라지면 워커는 다른 쪽

package/runtime/python/okstra_ctl/implementation_options.py

@@ -6,9 +6,14 @@ import hashlib
 import json
 import re
 from collections import Counter
+from dataclasses import dataclass
 from collections.abc import Mapping, Sequence
 from typing import Any
 
+from .clarification_items.dispositions import (
+    USER_INPUT_BLOCKS,
+    progress_blocking_ids,
+)
 from .exact_coverage import ExactCoverageError, calculate_exact_coverage
 
 
@@ -361,6 +366,124 @@ def _validate_option_count_and_routing(
         errors.append("recommendedOptionId must name the first ranked option")
 
 
+@dataclass(frozen=True)
+class VoteGap:
+    """전원 투표만 모자란 후보 하나와, 표를 받아야 할 분석자."""
+
+    option_id: str
+    missing: tuple[str, ...]
+    feasible_votes: int
+
+
+def vote_gaps(
+    selection: Mapping[str, object],
+    participating_analysers: Sequence[str],
+) -> list[VoteGap]:
+    """표만 채우면 살아날 후보 — 유효성 규칙을 거꾸로 읽는다.
+
+    1라운드의 설계자들은 병렬로 돌아 서로의 후보를 보지 못한다. 그래서 자기가
+    낸 후보에만 표를 남기고, 병합된 집합에는 분석자마다 다른 구멍이 생긴다.
+    `_validate_option_feasibility` 의 전원 투표 조항은 그 상태를 조립 시점에
+    거절할 뿐 메우지 못한다 — 실측(2026-09-10, dev-10629-4): 설계자 3명 로스터에서
+    IO-001·IO-002·IO-003 이 각각 `feasible` 2표를 받고도 빠진 분석자가 하나씩
+    달라 전부 탈락했고, 그 run 은 후보 0건으로 차단됐다.
+
+    여기서 세는 것은 **표만 모자란** 후보다. `safetyBlockers` 나
+    `unresolvedFeasibilityFacts` 가 있거나 베낀 표가 있으면 표를 더 받아도
+    유효해지지 않으므로 제외한다. 남은 표를 다 받아도 `feasible` 이
+    `MIN_FEASIBLE_VOTES` 에 못 미치는 후보도 제외한다 — 부쳐 봐야 결과가
+    같다.
+    """
+    roster = list(dict.fromkeys(str(name) for name in participating_analysers))
+    gaps: list[VoteGap] = []
+    for candidate in (
+        row
+        for key in ("rankedOptions", "candidateAudit")
+        for row in (selection.get(key) or ())
+        if isinstance(row, Mapping)
+    ):
+        if candidate.get("safetyBlockers") or candidate.get(
+            "unresolvedFeasibilityFacts"
+        ):
+            continue
+        votes = candidate.get("feasibilityVotes") or ()
+        if _copied_votes(votes):
+            continue
+        voted = [str(vote.get("worker")) for vote in votes if isinstance(vote, Mapping)]
+        if len(voted) != len(set(voted)):
+            continue
+        missing = tuple(name for name in roster if name not in set(voted))
+        if not missing or set(voted) - set(roster):
+            continue
+        feasible = sum(
+            isinstance(vote, Mapping) and vote.get("verdict") == "feasible"
+            for vote in votes
+        )
+        if feasible + len(missing) < MIN_FEASIBLE_VOTES:
+            continue
+        gaps.append(
+            VoteGap(
+                option_id=str(candidate.get("id") or "?"),
+                missing=missing,
+                feasible_votes=feasible,
+            )
+        )
+    return gaps
+
+
+def validate_blocked_answer_channel(
+    report_data: Mapping[str, object],
+) -> list[str]:
+    """차단된 run 이 사용자가 답할 자리를 남겼는지.
+
+    `routing: blocked` 는 목적지가 없는 유일한 종료 상태다. 그 차단이
+    `unresolvedFeasibilityFacts` 때문이면 — 값이 미정이다, 계약이 없다,
+    리포터 확인이 필요하다 — 푸는 사람은 사용자인데, 답변 채널은
+    `clarificationItems[]` 하나뿐이다. 조립은 그 배열을 승인 결정 원장에서만
+    읽고(`report_assembly._clarifications`), `okstra user-response` 는 발행된
+    리포트의 그 배열만 읽는다(`user_response._record_clarification_rows`).
+    그래서 미해결 사실이 산문으로만 남으면 run 은 "사용자를 기다림" 상태로
+    발행되고 사용자에게는 답할 항목이 0건으로 보인다(2026-09-10 실측,
+    dev-10630: 후보 5개 전부 미해결 사실을 달고 원장은 빈 배열).
+
+    앞으로 가는 길은 원장에 행을 여는 것이다 —
+    `okstra approval-decision open --ledger <approvalDecisionsPath>` 를 행마다
+    한 번. 미해결 사실이 없는 차단(워커가 결과를 못 냈다 같은 실행 차단)은
+    사용자가 답할 것이 없으므로 이 검사에 걸리지 않는다.
+
+    `clarificationItems[]` 는 리드 소유라 작성자 서사에는 없다. 그래서 이
+    검사는 조립이 끝난 리포트 레코드 전체를 받고
+    `validate_implementation_option_selection`(작성자 소유 의미론) 과 따로
+    선다 — 교정 루프의 semantic validator 에 묶으면 원장에 행이 있어도 매번
+    발화한다.
+    """
+    selection = report_data.get("implementationOptionSelection")
+    if not isinstance(selection, Mapping):
+        return []
+    if selection.get("routing") != NO_VALID_OPTIONS_ROUTING:
+        return []
+    unresolved = [
+        str(candidate.get("id"))
+        for key in ("rankedOptions", "candidateAudit")
+        for candidate in (selection.get(key) or ())
+        if isinstance(candidate, Mapping)
+        and candidate.get("unresolvedFeasibilityFacts")
+    ]
+    if not unresolved:
+        return []
+    if progress_blocking_ids(
+        report_data.get("clarificationItems"), USER_INPUT_BLOCKS
+    ):
+        return []
+    return [
+        "blocked routing leaves the user no answer channel: "
+        f"{', '.join(unresolved)} carry unresolvedFeasibilityFacts and no open "
+        "clarification row asks them — open one decision row per answerable "
+        "fact with `okstra approval-decision open --ledger "
+        "<approvalDecisionsPath>`, then reassemble"
+    ]
+
+
 def _validate_candidate_audit(
     data: Mapping[str, object],
     options: Sequence[Mapping[str, object]],

package/runtime/python/okstra_ctl/option_votes.py

@@ -0,0 +1,194 @@
+"""전원 투표만 모자란 구현 후보와, 그 표를 받아야 할 분석자를 낸다.
+
+`implementation-option-selection` 의 1라운드는 설계자들이 병렬로 돌아 서로의
+후보를 보지 못한다. 그래서 자기가 낸 후보에만 실현 가능성 표를 남기고, 병합된
+집합에는 분석자마다 다른 구멍이 생긴다. 유효성 규칙은 전원 투표를 요구하므로
+(`implementation_options._validate_option_feasibility`) 그런 후보는 순위표에
+오르지 못하고, 남는 후보가 하나도 없으면 run 이 `routing: blocked` 로 끝난다 —
+실측(2026-09-10, dev-10629-4): 설계자 3명 로스터에서 IO-001·IO-002·IO-003 이
+각각 `feasible` 2표를 받고도 빠진 분석자가 하나씩 달라 전부 탈락했다.
+
+거절은 그 상태를 알려 줄 뿐 메우지 못한다. 이 명령이 앞으로 가는 길이다:
+표만 모자란 후보를 세고, 어느 분석자에게 어떤 후보를 부쳐야 하는지 말한다.
+재검증(reverify) 라운드는 주장을 반박하는 라운드이지 후보에 표를 남기는
+라운드가 아니므로, 그 구멍을 메우는 디스패치는 리드가 이 목록을 보고 연다.
+
+읽는 자리는 두 가지다. 조립 전이면 작성자 서사(`--narrative`), 이미 발행된
+run 이면 리포트 레코드(`--report`). 로스터는 task-manifest 의
+`recommendedWorkers` 에서 `report-writer` 를 뺀 것이고, 그것이 검증기가
+`participating analysers` 로 쓰는 값과 같은 정의다(`validators/validate-run.py`).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from okstra_ctl.final_report_schema import load_schema_version
+from okstra_ctl.implementation_options import VoteGap, vote_gaps
+from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
+from okstra_ctl.report_contract import CURRENT_REPORT_SCHEMA_VERSION
+from okstra_ctl.report_narrative import parse_narrative_structure
+
+
+class OptionVotesError(ValueError):
+    """투표 구멍을 셀 입력이 없거나 읽히지 않는다."""
+
+
+def _record_from_report(path: Path) -> dict[str, Any]:
+    try:
+        return load_owned_object(path, artifact="final-report data.json")
+    except (JsonBoundaryError, OSError) as exc:
+        raise OptionVotesError(f"report record is unreadable: {exc}") from exc
+
+
+def _record_from_narrative(path: Path) -> dict[str, Any]:
+    """작성자 서사를 레코드 모양으로 읽는다.
+
+    값 결함은 무시한다 — 교정 원장이 고칠 자리이고, 표 구멍을 세는 데에는
+    후보 id 와 `feasibilityVotes` 만 있으면 된다. 여기서 서사 전체를 거절하면
+    아직 교정 중인 run 은 이 명령을 쓸 수 없다.
+    """
+    try:
+        markdown = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise OptionVotesError(f"narrative is unreadable: {exc}") from exc
+    schema = load_schema_version(CURRENT_REPORT_SCHEMA_VERSION)
+    record, _defects = parse_narrative_structure(markdown, schema)
+    return record
+
+
+def participating_analysers(manifest_path: Path) -> tuple[str, ...]:
+    try:
+        manifest = load_owned_object(manifest_path, artifact="task-manifest")
+    except (JsonBoundaryError, OSError) as exc:
+        raise OptionVotesError(f"task manifest is unreadable: {exc}") from exc
+    roster = manifest.get("recommendedWorkers")
+    if not isinstance(roster, list):
+        raise OptionVotesError("task manifest has no recommendedWorkers roster")
+    return tuple(
+        str(worker) for worker in roster if str(worker) != "report-writer"
+    )
+
+
+def _selection(record: Mapping[str, Any]) -> Mapping[str, Any]:
+    selection = record.get("implementationOptionSelection")
+    if not isinstance(selection, Mapping):
+        raise OptionVotesError(
+            "the source has no implementationOptionSelection block — "
+            "this command reads an implementation-option-selection run"
+        )
+    return selection
+
+
+def _dispatch_lines(gaps: list[VoteGap]) -> list[str]:
+    """분석자별로 부칠 후보 목록. 디스패치 단위가 분석자이기 때문이다."""
+    by_analyser: dict[str, list[str]] = {}
+    for gap in gaps:
+        for analyser in gap.missing:
+            by_analyser.setdefault(analyser, []).append(gap.option_id)
+    return [
+        f"  {analyser}: {', '.join(options)}"
+        for analyser, options in sorted(by_analyser.items())
+    ]
+
+
+def _render(gaps: list[VoteGap]) -> str:
+    if not gaps:
+        return (
+            "No candidate is short of votes alone. A blocked run here is "
+            "blocked by something a vote cannot settle — safety blockers, "
+            "unresolved feasibility facts, or too few feasible verdicts."
+        )
+    lines = [
+        f"{len(gaps)} candidate(s) need only the missing feasibility votes:",
+        "",
+    ]
+    lines += [
+        f"  {gap.option_id}: {gap.feasible_votes} feasible so far, "
+        f"missing {', '.join(gap.missing)}"
+        for gap in gaps
+    ]
+    lines += ["", "Dispatch one vote-completion assignment per analyser:"]
+    lines += _dispatch_lines(gaps)
+    lines += [
+        "",
+        "Each assignment asks that analyser for its own feasibility verdict, "
+        "rationale, and counterevidence on the named candidate — nothing else. "
+        "It generates no candidate, so the run stays in `candidate-comparison` "
+        "mode; `preselected-validation` is a whole-run mode that would collapse "
+        "the comparison to one direction.",
+    ]
+    return "\n".join(lines)
+
+
+def _gaps(args: argparse.Namespace) -> int:
+    if bool(args.report) == bool(args.narrative):
+        raise OptionVotesError("pass exactly one of --report or --narrative")
+    record = (
+        _record_from_report(args.report)
+        if args.report
+        else _record_from_narrative(args.narrative)
+    )
+    gaps = vote_gaps(
+        _selection(record), participating_analysers(args.task_manifest)
+    )
+    if args.json:
+        print(json.dumps(
+            {
+                "gaps": [
+                    {
+                        "optionId": gap.option_id,
+                        "missing": list(gap.missing),
+                        "feasibleVotes": gap.feasible_votes,
+                    }
+                    for gap in gaps
+                ]
+            },
+            ensure_ascii=False,
+            indent=2,
+        ))
+    else:
+        print(_render(gaps))
+    return 0
+
+
+_CLI_DESCRIPTION = (
+    "Report the implementation candidates that only lack feasibility votes, "
+    "and which analyser owes each one."
+)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION, prog="okstra option-votes"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    gaps_parser = subparsers.add_parser("gaps")
+    gaps_parser.add_argument(
+        "--task-manifest", type=Path, required=True,
+        help="the task's task-manifest.json — its roster names the analysers")
+    gaps_parser.add_argument(
+        "--report", type=Path,
+        help="a published final-report `.data.json`")
+    gaps_parser.add_argument(
+        "--narrative", type=Path,
+        help="the report writer's narrative markdown, before assembly")
+    gaps_parser.add_argument("--json", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        return _gaps(args)
+    except OptionVotesError as exc:
+        print(f"okstra option-votes: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/report_assembly.py

@@ -24,6 +24,7 @@ from .report_synthesis_packet import (
 )
 from .conformance import strip_stage_declaration_label
 from .design_prep import DesignPrepError, materialize_design_prep_requests
+from .implementation_options import validate_blocked_answer_channel
 from .implementation_direction import (
     load_selected_direction_snapshot,
     validate_selected_direction_plan,
@@ -453,6 +454,15 @@ def _compose(
     data["tokenUsage"] = usage
     data["crossVerification"] = convergence_data["crossVerification"]
     data["clarificationItems"] = _clarifications(ledger, activities, inputs["approval-decisions"].path)
+    # 차단된 option-selection 은 발행 전에 답변 채널을 갖춰야 한다. 발행 뒤에는
+    # 이 원장을 다시 읽는 경로가 없어 사용자에게 질문이 0건으로 보인다.
+    for reason in validate_blocked_answer_channel(data):
+        _fail(
+            "lead",
+            inputs["approval-decisions"].path,
+            "activeClarifications",
+            reason,
+        )
     carry_in = _clarification_carry_in(project_root, manifest, manifest_path)
     if carry_in is not None:
         data["clarificationCarryIn"] = carry_in

package/runtime/python/okstra_ctl/verdict_blocks.py

@@ -169,6 +169,33 @@ def parse_finding_votes(text: str, *, adversarial: bool) -> dict[str, FindingVot
     )
 
 
+def finding_vote_defect(text: str) -> str | None:
+    """재검증 결과가 표로 읽히지 않는 이유. 읽히면 ``None``.
+
+    수집(`okstra convergence collect-results`)은 이 파일이 표로 읽혀야 진행한다.
+    읽히지 않는 파일은 산출물이 있어도 표가 없는 것이므로, 디스패치가 그 자리에서
+    "없는 산출물" 로 세어 같은 배치 안에서 재시도한다
+    (`okstra_ctl.dispatch_state.unusable_result_defect`). 그러지 않으면 원장은
+    `ok`, 수집기는 거절이 되어 리드가 손으로 재띄우거나 run 을 닫는 수밖에 없다
+    (2026-09-10 실측, fontsninja-v3-site dev-10631 implementation-option-selection).
+
+    라운드가 adversarial 인지 collaborative 인지는 결과 파일에 적혀 있지 않다. 한쪽
+    어휘로만 읽으면 반대쪽 라운드의 정상 결과를 결함으로 신고하므로, 어느 한쪽으로
+    읽히면 결함이 아니다. 둘 다 실패했을 때만 adversarial 쪽 메시지를 낸다 — 실측된
+    결함(설명 누락)은 두 어휘에서 같은 문장을 낸다.
+    """
+    adversarial_error: str | None = None
+    for adversarial in (True, False):
+        try:
+            parse_finding_votes(text, adversarial=adversarial)
+        except VerdictBlockError as exc:
+            if adversarial:
+                adversarial_error = str(exc)
+            continue
+        return None
+    return adversarial_error
+
+
 def _collect_blocks(blocks: dict[str, dict[str, str]], parse) -> dict:
     """모든 블록을 읽고 결함을 한 번에 보고한다.
 

package/runtime/python/okstra_ctl/wizard/engine.py

@@ -28,6 +28,7 @@ from .ids import (
     S_DESIGN_PREP_OVERRIDES,
     S_DONE,
     S_TASK_PICK,
+    S_REPORT_LANGUAGE,
     TASK_PICK_NEW_TOKEN,
     _STEP_TO_GROUP,
 )
@@ -222,6 +223,9 @@ def _sim_answer(prompt: Prompt) -> str:
 def _sim_advance(state: WizardState, prompt: Prompt) -> None:
     """기본답으로 한 화면 전진한다. progress 를 재계산하는 submit()/
     _submit_group() 은 호출하지 않고 step.submit 만 직접 호출해 재귀를 막는다."""
+    if prompt.step == S_REPORT_LANGUAGE:
+        state.answered.append(prompt.step)
+        return
     if is_split_picker(prompt):
         # 조각 질문의 step 은 등록된 step 이 아니다 — 잘리지 않은 원본으로 낸다.
         prompt = _next_prompt_screen(state)

package/runtime/python/okstra_ctl/wizard/ids.py

@@ -136,6 +136,7 @@ _BRIEF_HEAD_LINES = 60
 
 # ---- Step IDs ------------------------------------------------------------
 
+S_REPORT_LANGUAGE = "report_language"
 S_TASK_PICK = "task_pick"
 
 

package/runtime/python/okstra_ctl/wizard/registry.py

@@ -50,6 +50,7 @@ from .ids import (
     S_RELATED_TASKS,
     S_RELATED_TASKS_PICK,
     S_REPORT_WRITER_MODEL,
+    S_REPORT_LANGUAGE,
     S_REUSE_PREVIOUS,
     S_REVERIFY_SCOPE_PICK,
     S_REVERIFY_SCOPE_STAGES,
@@ -167,6 +168,9 @@ from .steps_plan import (
     _submit_stage_pick,
 )
 from .steps_options import (
+    _report_language_required,
+    _build_report_language,
+    _submit_report_language,
     _build_clarification,
     _build_clarification_pick,
     _build_directive,
@@ -278,6 +282,10 @@ def _submit_edit_target(state: WizardState, value: str) -> Optional[str]:
 # --- step registry ---
 
 STEPS: list[Step] = [
+    Step(S_REPORT_LANGUAGE,
+         applies=_report_language_required,
+         build=_build_report_language, submit=_submit_report_language,
+         owns=()),
     Step(S_TASK_PICK,
          applies=lambda s: s.is_new_task is None,
          build=_build_task_pick, submit=_submit_task_pick,

package/runtime/python/okstra_ctl/wizard/steps_options.py

@@ -6,7 +6,8 @@ from pathlib import Path
 from typing import Callable, Optional
 
 from okstra_ctl.clarification_items import user_response_sidecars
-from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
+from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
+from okstra_ctl.report_language import is_language_tag
 from okstra_ctl.pr_template import PrTemplateError, resolve_pr_template_path
 from okstra_project.dirs import project_json_path
 from okstra_project.state import StateError, list_project_tasks
@@ -23,6 +24,7 @@ from .ids import (
     S_PR_TEMPLATE_SCOPE,
     S_RELATED_TASKS,
     S_RELATED_TASKS_PICK,
+    S_REPORT_LANGUAGE,
     _LATEST_REPORT_TOKEN,
     _PROJECT_DEFAULT_TOKEN,
     _REUSE_LAST_TOKEN,
@@ -33,6 +35,40 @@ from .prompts import _opt, _p, _pick_snippet
 from .sources import _latest_run_inputs, _require_file, _suggest_latest_final_report
 
 
+def _report_language_required(state: WizardState) -> bool:
+    path = project_json_path(Path(state.project_root))
+    if not path.is_file():
+        return False
+    try:
+        data = load_owned_object(path, artifact="project config")
+    except JsonBoundaryError as exc:
+        raise WizardError(str(exc)) from exc
+    return data.get("reportLanguage") in (None, "")
+
+
+def _build_report_language(state: WizardState) -> Prompt:
+    text = _p(state.workspace_root, "report_language")
+    return Prompt(
+        step=S_REPORT_LANGUAGE, kind="text",
+        label=text["label"], echo_template=text["echo_template"],
+    )
+
+
+def _submit_report_language(state: WizardState, value: str) -> Optional[str]:
+    language = value.strip()
+    if not is_language_tag(language):
+        raise WizardError("보고서 언어 태그를 입력하세요: en, ko, fr, pt-BR")
+    path = project_json_path(Path(state.project_root))
+    try:
+        data = load_owned_object(path, artifact="project config")
+        if data.get("reportLanguage") in (None, ""):
+            data["reportLanguage"] = language
+            write_owned_object_atomic(path, data, artifact="project config")
+    except (OSError, JsonBoundaryError) as exc:
+        raise WizardError(str(exc)) from exc
+    return f"report-language: {data['reportLanguage']}"
+
+
 def _clarification_sidecar_note(state: WizardState, suggestion: str) -> str:
     """추천 final-report 와 함께 carry-in 될 ``user-responses/`` 사이드카 현황 문구.