okstra 0.191.2 → 0.192.0

package/runtime/python/okstra_ctl/report_translation_dispatch.py

@@ -0,0 +1,300 @@
+"""Phase 7 `translate` 단계 — 번역 사이드카를 okstra 가 직접 만든다.
+
+비영어 리포트의 번역 워커는 종전에 리드의 수동 절차였다: `agent-prompt
+materialize --audience translator` 로 예약을 만들고, `worker-dispatch --workers
+translator` 로 띄우고, `report-finalize` 를 두 번에 나눠 도는 순서가 리드가
+lazy-read 하는 문서(`prompts/lead/report-writer.md`)에만 있었다. 실측(2026-09-09,
+fontsninja-v3-site dev-10628-3 implementation-option-selection, grok 리드): 리드가
+`report-finalize` 를 한 번에 돌려 번역 예약이 0건이었고, 디스패처는 0건을 거절할
+뿐 만들지 못한다(`dispatch_core._translator_job_from_reservation`). 검증은 권고
+한 줄을 남겼고 HTML 은 영어로 남았다.
+
+이 모듈은 그 절차를 `report-finalize` 의 한 단계로 내린다. 예약이 없으면 지시문과
+프롬프트를 발행하고(`agent-prompt materialize` 와 같은 코드), CLI 래퍼 디스패처로
+워커를 띄운 뒤 사이드카가 생겼는지 본다. 디스패치 기록과 결과 링크는
+`dispatch_core` 가 배치 안에서 이미 하므로 여기서 다시 하지 않는다.
+"""
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+from . import worker_dispatch
+from .agent.prompt_cli.cli import main as agent_prompt_main
+from .dispatch_core import translator_reservations
+from .dispatch_state import (
+    DispatchError,
+    load_json_object,
+    resolve_project_path,
+    resolve_required_path,
+)
+from .final_report_paths import translation_sidecar_path
+from .json_boundary import JsonBoundaryError
+
+TRANSLATOR_WORKER_ID = "translator"
+
+# 지시문의 언어 이름. 워커는 `**Report Language:**` 헤더로 코드를 받지만, 지시문은
+# 사람이 읽는 문장이라 이름으로 적는다. 표에 없는 코드는 코드 그대로 쓴다.
+_LANGUAGE_NAMES = {"ko": "Korean"}
+
+# 리드가 종전에 손으로 쓰던 지시문(실측 2026-09-08, fontsninja-nlpvibe dev-10786
+# requirements-discovery-002)과 같은 절차다. 명령은 `agents/workers/translator-worker.md`
+# 의 Procedure 와 같은 세 개이고, 결과·감사 경로는 프롬프트 앵커가 이름한다.
+_INSTRUCTIONS = """## Instructions
+
+Translate the finalized report into {language} faithfully. This is translation only: no analysis, no source edits.
+
+1. Run `okstra report-translate source --run-manifest {manifest}` and read the complete work list, in chunks if it is long. Copy the `Source digest` it prints.
+2. Write one translated block per `## T-NNN` item to the exact Result Path, using the same `## T-NNN` headings. Preserve every identifier, path, command, enum token, link, and qualification character for character.
+3. Publish with `okstra report-translate write --run-manifest {manifest} --source-digest <digest from step 1> --translations <Result Path>`, then run `okstra report-translate check-data --run-manifest {manifest}`. Fix the translation until that check passes; do not return on a failing check.
+4. Write a completion pointer to the Worker Result Path naming the translations file, the published sidecar, the digest, and the check result. Write the audit sidecar with reading, completeness, and terminology checks.
+
+Do not edit the canonical report, the narrative, the HTML, or any source file. All `.okstra` paths resolve from Project Root.
+"""
+
+
+@dataclass(frozen=True)
+class TranslateOutcome:
+    """`translate` 단계의 결과. `report_finalize` 가 CompletedProcess 로 옮긴다."""
+
+    returncode: int
+    stdout: str = ""
+    stderr: str = ""
+
+
+class TranslateError(Exception):
+    """번역 워커를 예약하거나 띄우지 못했다. 메시지가 그 자리를 이름한다."""
+
+
+def report_language(manifest: Mapping[str, Any], data_path: Path) -> str:
+    """이 run 의 사람 리포트 언어. 매니페스트가 정본이고, 없으면 리포트의 meta.
+
+    매니페스트 `reportLanguage` 는 prepare 가 `report_language.resolve_report_language`
+    로 정한 값이고, 조립이 `meta.reportLanguage` 로 복사한다. 그 필드가 없는 옛
+    run 은 리포트에서 읽는다. 둘 다 없으면 영어다.
+    """
+    value = str(manifest.get("reportLanguage") or "").strip()
+    if value:
+        return value
+    if data_path.is_file():
+        try:
+            data = load_json_object(data_path, "final-report data")
+        except (DispatchError, JsonBoundaryError):
+            return "en"
+        meta = data.get("meta")
+        if isinstance(meta, Mapping):
+            value = str(meta.get("reportLanguage") or "").strip()
+    return value or "en"
+
+
+def translate_report(
+    *,
+    project_root: Path,
+    workspace_root: Path,
+    manifest_path: Path,
+    manifest: Mapping[str, Any],
+    data_path: Path,
+) -> TranslateOutcome:
+    """비영어 리포트의 번역 사이드카를 있게 만든다. 영어 리포트는 할 일이 없다.
+
+    사이드카가 이미 있으면(앞선 호출, 또는 리드가 손으로 띄운 워커) 그대로 둔다.
+    없으면 예약을 보장하고 워커를 띄운 뒤, 사이드카의 존재로만 성공을 판정한다 —
+    워커의 종료 코드는 산출물의 존재를 대신하지 못한다.
+    """
+    lang = report_language(manifest, data_path)
+    if lang == "en":
+        return TranslateOutcome(0, f"skipped: reportLanguage is {lang!r}")
+    sidecar = translation_sidecar_path(data_path, lang)
+    if sidecar.is_file():
+        return TranslateOutcome(0, f"translation sidecar already present: {sidecar.name}")
+    try:
+        metadata_path = ensure_translator_reservation(
+            project_root, manifest_path, manifest, lang
+        )
+        dispatch = dispatch_translator(project_root, workspace_root, manifest_path)
+    except TranslateError as exc:
+        return TranslateOutcome(1, "", str(exc))
+    if sidecar.is_file():
+        return TranslateOutcome(
+            0,
+            f"translated into {lang!r}: {sidecar.name} (reservation "
+            f"{metadata_path.name})",
+            dispatch.stderr,
+        )
+    return TranslateOutcome(
+        1,
+        dispatch.stdout,
+        f"translator dispatch exited {dispatch.returncode} and left no "
+        f"translation sidecar at {sidecar}"
+        + (f": {dispatch.stderr.strip()}" if dispatch.stderr.strip() else ""),
+    )
+
+
+def ensure_translator_reservation(
+    project_root: Path,
+    manifest_path: Path,
+    manifest: Mapping[str, Any],
+    lang: str,
+) -> Path:
+    """이 run 의 아직 안 띄운 translator 예약 하나를 돌려준다. 없으면 만든다.
+
+    Returns the invocation metadata path of that reservation.
+
+    예약이 둘이면 디스패처가 고를 수 없고 회수 명령도 없으므로 그대로 거절한다 —
+    그 상태는 리드가 다른 id 로 두 번 발행했을 때만 생긴다. 예약 id 는
+    `<task-type>-<seq>-translator` 이고, 같은 run 의 앞선 시도가 실패해 그 id 가
+    이미 쓰였으면 `-r2`, `-r3` 로 잇는다.
+    """
+    team_state = load_json_object(
+        resolve_required_path(project_root, manifest, "teamStatePath"), "team-state"
+    )
+    try:
+        candidates, seen = translator_reservations(project_root, manifest, team_state)
+    except DispatchError as exc:
+        raise TranslateError(f"translator reservation lookup failed: {exc}") from exc
+    if len(candidates) == 1:
+        return resolve_project_path(
+            project_root, str(candidates[0].get("metadataPath") or "")
+        )
+    if len(candidates) > 1:
+        raise TranslateError(
+            "translator dispatch requires exactly one canonical invocation "
+            f"reservation for this run; found {len(candidates)}. Translator "
+            "reservations seen: " + "; ".join(seen)
+        )
+    return _materialize_translator(project_root, manifest_path, manifest, lang, seen)
+
+
+def dispatch_translator(
+    project_root: Path, workspace_root: Path, manifest_path: Path,
+) -> TranslateOutcome:
+    """`okstra worker-dispatch --workers translator` 와 같은 코드를 프로세스 안에서 돈다.
+
+    디스패처는 결과 JSON 을 stdout 에 찍는다. Phase 7 의 stdout 은 finalize 결과
+    JSON 하나여야 하므로 여기서 받아 단계 결과로 넘긴다.
+    """
+    out, err = io.StringIO(), io.StringIO()
+    with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+        try:
+            code = worker_dispatch.main([
+                "--project-root", str(project_root),
+                "--run-manifest", str(manifest_path),
+                "--workspace-root", str(workspace_root),
+                "--workers", TRANSLATOR_WORKER_ID,
+            ])
+        except (DispatchError, OSError) as exc:
+            raise TranslateError(f"translator dispatch failed: {exc}") from exc
+    return TranslateOutcome(code, out.getvalue(), err.getvalue())
+
+
+def _materialize_translator(
+    project_root: Path,
+    manifest_path: Path,
+    manifest: Mapping[str, Any],
+    lang: str,
+    seen: list[str],
+) -> Path:
+    task_type = str(manifest.get("taskType") or "").strip()
+    if not task_type:
+        raise TranslateError("run manifest has no taskType")
+    run_dir = resolve_required_path(project_root, manifest, "runDirectoryPath")
+    base_id = f"{task_type}-{_seq(manifest, 'manifests')}-translator"
+    used = {entry.split(" ", 1)[0] for entry in seen}
+    invocation_id = base_id
+    attempt = 1
+    while invocation_id in used:
+        attempt += 1
+        invocation_id = f"{base_id}-r{attempt}"
+    prompt_seq = _seq(manifest, "prompts")
+    result_seq = _seq(manifest, "workerResults")
+    suffix = "" if attempt == 1 else f"-r{attempt}"
+    instruction = (
+        _instruction_root(project_root, manifest, run_dir)
+        / f"translator-instructions-{task_type}-{_seq(manifest, 'state')}{suffix}.md"
+    )
+    prompt = run_dir / "prompts" / f"translator-worker-prompt-{task_type}-{prompt_seq}{suffix}.md"
+    translations = (
+        run_dir / "worker-results"
+        / f"translator-translations-{task_type}-{result_seq}{suffix}.md"
+    )
+    worker_result = (
+        run_dir / "worker-results" / f"translator-worker-{task_type}-{result_seq}{suffix}.md"
+    )
+    if not instruction.is_file():
+        # 리드가 먼저 써 둔 지시문은 그대로 쓴다. 없을 때만 okstra 의 것을 쓴다.
+        instruction.parent.mkdir(parents=True, exist_ok=True)
+        instruction.write_text(
+            _INSTRUCTIONS.format(
+                language=_LANGUAGE_NAMES.get(lang, lang),
+                manifest=manifest_path.relative_to(project_root).as_posix()
+                if manifest_path.is_relative_to(project_root)
+                else str(manifest_path),
+            ),
+            encoding="utf-8",
+        )
+    out, err = io.StringIO(), io.StringIO()
+    with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+        code = agent_prompt_main([
+            "materialize",
+            "--project-root", str(project_root),
+            "--run-manifest", str(manifest_path),
+            "--invocation-id", invocation_id,
+            "--worker-id", TRANSLATOR_WORKER_ID,
+            "--audience", TRANSLATOR_WORKER_ID,
+            "--dispatch-kind", TRANSLATOR_WORKER_ID,
+            "--assignment-ref", TRANSLATOR_WORKER_ID,
+            "--instruction", str(instruction),
+            "--prompt", str(prompt),
+            "--result", str(translations),
+            "--audit-source", str(worker_result),
+            "--json",
+        ])
+    if code != 0:
+        raise TranslateError(
+            "translator prompt materialization failed: "
+            + (err.getvalue().strip() or out.getvalue().strip() or f"exit {code}")
+        )
+    try:
+        payload = json.loads(out.getvalue())
+    except json.JSONDecodeError as exc:
+        raise TranslateError(
+            f"translator materialization printed no JSON: {out.getvalue()[:200]!r}"
+        ) from exc
+    metadata = str(payload.get("metadataPath") or "")
+    if not metadata:
+        raise TranslateError("translator materialization named no metadataPath")
+    return resolve_project_path(project_root, metadata)
+
+
+def _instruction_root(
+    project_root: Path, manifest: Mapping[str, Any], run_dir: Path,
+) -> Path:
+    """지시문을 둘 디렉터리. materialize 는 `authorizedPaths.instructionRoots` 밖의
+    지시문을 거절하므로 그 목록에서 고른다 — 리드가 쓰던 `state/` 가 있으면 그것,
+    없으면 첫 항목, 목록이 없으면 run 의 `state/`."""
+    contract = manifest.get("agentContract")
+    authorized = contract.get("authorizedPaths") if isinstance(contract, Mapping) else None
+    roots = authorized.get("instructionRoots") if isinstance(authorized, Mapping) else None
+    candidates = [
+        resolve_project_path(project_root, str(root))
+        for root in (roots if isinstance(roots, list) else [])
+        if str(root).strip()
+    ]
+    for root in candidates:
+        if root.name == "state":
+            return root
+    return candidates[0] if candidates else run_dir / "state"
+
+
+def _seq(manifest: Mapping[str, Any], category: str) -> str:
+    seqs = manifest.get("runSequencesByCategory")
+    if not isinstance(seqs, Mapping):
+        raise TranslateError("run manifest has no runSequencesByCategory object")
+    value = str(seqs.get(category) or seqs.get("manifests") or "").strip()
+    if not value:
+        raise TranslateError(f"run manifest has no {category} sequence")
+    return value

package/runtime/python/okstra_ctl/verdict_blocks.py

@@ -5,6 +5,14 @@ The response shape is fixed by contract (`prompts/lead/plan-body-verification.md
 per-round ad-hoc regex makes the round's fidelity depend on whoever wrote it,
 and its failure mode is silence: dev-10400 lost 19 of 37 assigned items to a
 no-match that nothing reported. Every shape this module cannot read is an error.
+
+A label that means the same thing is read, not refused. The contract writes
+`**Verdict**: AGREE`; a worker following a lead-authored instruction wrote
+`- Verdict: REFUTED` and the whole reverify round was rejected for it
+(2026-09-09). The bullet form, the colon inside the bold (`**Verdict:**`), a
+bullet before the bold, and a differently-cased key all name the same field —
+refusing them costs a dispatch cycle and yields no information. A bare
+`Verdict:` without bullet or bold is still prose: `Note:` opens sentences.
 """
 from __future__ import annotations
 
@@ -60,11 +68,19 @@ DISAGREE_BASES = frozenset({"counter-evidence", "burden-not-met"})
 _ITEM_RE = re.compile(r"^###[ \t]+(?P<id>[^\s:]+)[ \t]*:?.*$", re.MULTILINE)
 # The contract writes some labels with a parenthetical qualifier —
 # `**Fixability** (only when DISAGREE):` — so the colon may trail a `(...)`.
+# The label shapes read as one field (see the module docstring):
+#   `**Key**: v`  `**Key:** v`  `- Key: v`  `- **Key**: v`  `- **Key:** v`
+# `_field_match` enforces that an opening `**` is closed exactly once and that
+# a label without bold carries a bullet.
+_FIELD_KEYS = ("Verdict", "Fixability", "Note", "Explanation", "Prior dissent",
+               "Basis", "Your evidence")
+_CANONICAL_KEYS = {key.lower(): key for key in _FIELD_KEYS}
 _FIELD_RE = re.compile(
-    r"^\*\*(?P<key>Verdict|Fixability|Note|Explanation|Prior dissent|Basis"
-    r"|Your evidence)\*\*"
-    r"(?:[ \t]*\([^)]*\))?[ \t]*:[ \t]*(?P<value>.*)$",
-    re.MULTILINE,
+    r"^(?P<bullet>[-*+][ \t]+)?(?P<open>\*\*)?"
+    r"(?P<key>" + "|".join(re.escape(key) for key in _FIELD_KEYS) + r")"
+    r"(?P<close>\*\*)?(?:[ \t]*\([^)]*\))?[ \t]*:(?P<close_after>\*\*)?"
+    r"[ \t]*(?P<value>.*)$",
+    re.IGNORECASE,
 )
 _VERDICT_RE = re.compile(r"^(?P<token>[A-Z-]+)(?:\((?P<kind>[a-f])\))?$")
 _PROSE_FIELDS = frozenset({"Explanation", "Note", "Prior dissent", "Your evidence"})
@@ -75,6 +91,20 @@ class VerdictBlockError(ValueError):
     """Raised when a worker response does not match the contract shape."""
 
 
+def _field_match(line: str) -> tuple[str, str] | None:
+    """`(canonical key, value)` when *line* is a field label, else ``None``."""
+    match = _FIELD_RE.match(line)
+    if match is None:
+        return None
+    opened = bool(match.group("open"))
+    closes = sum(1 for name in ("close", "close_after") if match.group(name))
+    if opened and closes != 1:
+        return None
+    if not opened and (closes or not match.group("bullet")):
+        return None
+    return _CANONICAL_KEYS[match.group("key").lower()], match.group("value")
+
+
 @dataclass(frozen=True)
 class FindingVote:
     """One worker's vote on one convergence finding, in schema vocabulary."""
@@ -112,12 +142,12 @@ def _scan_blocks(text: str) -> dict[str, dict[str, str]]:
             continue
         if not item_id:
             continue
-        match = _FIELD_RE.match(line)
+        match = _field_match(line)
         if match:
-            field = match.group("key")
+            field, value = match
             if field in blocks[item_id]:
                 raise VerdictBlockError(f"item `{item_id}` has duplicate field `{field}`")
-            blocks[item_id][field] = match.group("value")
+            blocks[item_id][field] = value
         elif field in _PROSE_FIELDS:
             blocks[item_id][field] += "\n" + line
     return {

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

@@ -180,8 +180,13 @@ def _passed_screens(state: WizardState) -> int:
 
 
 def _sim_answer(prompt: Prompt) -> str:
-    """분모 추정 시뮬레이션의 기본답: pick 은 첫 옵션(추천), text 는 빈 값."""
+    """분모 추정 시뮬레이션의 기본답: pick 은 추천(체크박스는 추천 집합, 없으면
+    첫 옵션), text 는 빈 값."""
     if prompt.kind == "pick" and prompt.options:
+        if prompt.multi:
+            flagged = [option.value for option in prompt.options if option.recommended]
+            if flagged:
+                return ",".join(flagged)
         return prompt.options[0].value
     return ""
 
@@ -191,7 +196,10 @@ def _sim_advance(state: WizardState, prompt: Prompt) -> None:
     _submit_group() 은 호출하지 않고 step.submit 만 직접 호출해 재귀를 막는다."""
     try:
         if _is_role_selection_step(prompt.step):
-            _submit_role_prompt(state, prompt, _sim_answer(prompt))
+            # 화면은 호스트 한도에 맞춰 쪽으로 잘린 사본일 수 있다 — 기본답은
+            # 잘리지 않은 원본(추천 집합)에서 낸다.
+            original = next_role_prompt(state) or prompt
+            _submit_role_prompt(state, original, _sim_answer(original))
             if prompt.step not in state.answered:
                 state.answered.append(prompt.step)
             if prompt.step not in state.role_selection_order:
@@ -369,6 +377,12 @@ def submit(state: WizardState, value: str) -> dict[str, Any]:
     if prompt.kind == "pick_group":
         return _submit_group(state, prompt, value)
     if _is_role_selection_step(prompt.step):
+        # 화면은 호스트 한도에 맞춰 쪽으로 잘린 사본일 수 있다(`present_picker`).
+        # 답은 잘리지 않은 원본의 선택지로 검증한다 — 체크박스의 CSV 는 여러
+        # 쪽에 걸쳐 고른 값이다.
+        original = next_role_prompt(state)
+        if original is not None and original.step == prompt.step:
+            prompt = original
         echo = _submit_role_prompt(state, prompt, value or "")
         if prompt.step not in state.answered:
             state.answered.append(prompt.step)

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

@@ -648,11 +648,20 @@ STEPS: list[Step] = [
     # 이어가기에 필수인 직전 final-report 가 존재하면 use_defaults 와 무관하게
     # 입력 기회를 노출한다. (과거: use_defaults 게이트 뒤에 숨어 "Use defaults"
     # 를 고르면 직전 리포트가 통째로 누락됐다.)
+    # implementation-planning 의 `--clarification-response` 는 같은 phase 의
+    # 계획서만 받는다(`run._validate_planning_entry_inputs`). 그 계획서가 없는
+    # 첫 계획 run 에서 이 화면은 `없음 / 직접 입력` 뿐이고, 직접 입력으로 넣을
+    # 수 있는 파일도 없다 — 질문이 아니라 막다른 길이다(실측 2026-09-09, grok:
+    # 사용자는 직전 후보비교 run 의 user-responses/ 답변을 넘길 자리를 여기서
+    # 찾았다). 그 답변은 방향 선택 단계(`selected_direction_pick`)가 리포트와
+    # 함께 전달하므로, 계획 run 은 이어받을 계획서가 있을 때만 여기를 묻는다.
     Step(S_CLARIFICATION_PICK,
          applies=lambda s: (S_CLARIFICATION_PICK not in s.answered
                             and s.use_defaults is not None
-                            and (s.use_defaults is False
-                                 or bool(_suggest_latest_final_report(s)))),
+                            and (bool(_suggest_latest_final_report(s))
+                                 if s.task_type == "implementation-planning"
+                                 else (s.use_defaults is False
+                                       or bool(_suggest_latest_final_report(s))))),
          build=_build_clarification_pick, submit=_submit_clarification_pick,
          owns=("clarification_response_path", "clarification_pending_text")),
     Step(S_CLARIFICATION,