okstra 0.219.0 → 0.220.0

package/runtime/templates/worker-prompt-preamble.md

@@ -2,7 +2,7 @@
 
 This file is the audience-specific contract for initial `analysis` workers. Read it end-to-end from the path selected by the dispatch prompt. Before doing work, also read the shared file named by `**Worker Error Contract Path:**`; that file is the only source for error-sidecar rules.
 
-Your identity is the stored role execution (`executionLabel`). Canonical roles are `leader`, `analyser`, `critic`, `designer`, `planner`, `implementer`, `verifier`, `report-writer`, and `translator`. `lead` and `executor` are compatibility aliases only.
+Your identity is the stored role execution (`executionLabel`). Canonical roles are `leader`, `analyser`, `critic`, `designer`, `planner`, `implementer`, `verifier`, and `report-writer`. `lead` and `executor` are compatibility aliases only.
 
 ## Required reading
 

package/runtime/validators/validate-run.py

@@ -40,6 +40,7 @@ from okstra_ctl.phases.implementation.validation import (
     _validate_verifier_reran_independently,
     _validate_verifier_discrepancy_is_not_passed,
     _validate_verifier_fail_blocks_verdict,
+    _validate_correction_rounds,
     _validate_lead_fixes,
     _validate_verifier_command_log_is_read_only as validate_verifier_command_log_is_read_only,
     _validate_verifier_discrepancy_names_checklist_phase as validate_verifier_discrepancy_names_checklist_phase,
@@ -230,7 +231,6 @@ from okstra_ctl.workflow import (  # noqa: E402
 )
 from okstra_ctl.final_report_paths import (  # noqa: E402
     final_report_data_path as _data_path_for,
-    translation_sidecar_path,
 )
 from okstra_token_usage.report import _match_worker_index  # noqa: E402
 from okstra_ctl.phases.requirements_discovery.validation import (
@@ -3188,6 +3188,7 @@ def validate_final_report_data(
         _validate_stage_carry_sidecar_exists(data, report_path, failures)
         _validate_lead_fixes(data, failures)
         _validate_lead_fix_carry_head(data, report_path, failures)
+        _validate_correction_rounds(data, manifest, failures)
     _validate_lead_authored_report(data, report_path, failures)
     if task_type == "error-analysis":
         _validate_error_analysis_consistency(data, failures)
@@ -3328,7 +3329,7 @@ _CITATION_LIST_KEYS = ("evidenceRefs", "supportingEvidence", "falsifyingEvidence
 
 def _prose_pointers(node: object, key: str = "", pointer: str = "") -> list[tuple[str, str]]:
     """(JSON pointer, value) for every string under a reader-facing prose key."""
-    from okstra_ctl.report_translation import PROSE_KEYS
+    from okstra_ctl.report_prose_keys import PROSE_KEYS
 
     out: list[tuple[str, str]] = []
     if isinstance(node, dict):
@@ -4685,29 +4686,6 @@ def _validate_improvement_discovery(
             failures.append(f"improvement-discovery: {err}")
 
 
-def _validate_translation_sidecar(
-    data: Mapping[str, Any], report_path: Path, failures: list[str]
-) -> None:
-    """영어가 아닌 사람 HTML 은 번역 사이드카가 있어야 한다.
-
-    사이드카가 없으면 렌더러가 크롬만 번역하고 본문은 영어로 남긴다.
-    `render-views` 가 그 조합을 거부하고, 여기가 같은 규칙의 두 번째 게이트다.
-    """
-    if not data:
-        return
-    lang = str((data.get("meta") or {}).get("reportLanguage") or "en")
-    if lang == "en":
-        return
-    sidecar = translation_sidecar_path(report_path, lang)
-    if not sidecar.is_file():
-        failures.append(
-            f"final-report has reportLanguage {lang!r} but no translation "
-            f"sidecar at {sidecar.name}. The human HTML rendered from the "
-            "English source instead; re-run `report-finalize --only translate "
-            "--only render-views` to dispatch the translator and overlay it."
-        )
-
-
 def _validate_session_conformance(
     team_state: dict,
     team_state_path: Path,
@@ -6003,9 +5981,6 @@ def main() -> int:
         ),
     )
     validation_data = report_data if isinstance(report_data, Mapping) else {}
-    _validate_translation_sidecar(
-        validation_data, _data_path_for(report_path), failures
-    )
     validate_report(
         report_path,
         failures,

package/runtime/agents/operations/report-translation.json

@@ -1,6 +0,0 @@
-{
-  "schemaVersion": "1.0",
-  "id": "report-translation",
-  "dutyId": "translator",
-  "count": 1
-}

package/runtime/agents/roles/translator.json

@@ -1,19 +0,0 @@
-{
-  "schemaVersion": "1.0",
-  "id": "translator",
-  "legacyAliases": [],
-  "identity": "Renders the report's reader-facing text in another language without editing the underlying decision.",
-  "responsibilities": [
-    "Carry the source's precision, uncertainty, and operational force into the target language.",
-    "Preserve identifiers, paths, commands, and status tokens exactly as the source writes them."
-  ],
-  "requiredCapabilities": [
-    "extended-artifact-authoring",
-    "source-readonly",
-    "worker-artifact-io"
-  ],
-  "prohibitions": [
-    "Do not edit the source, translate an unassigned file, or add analysis of your own.",
-    "Do not strengthen or weaken a normative statement in translation."
-  ]
-}

package/runtime/bin/okstra-report-translate.py

@@ -1,404 +0,0 @@
-#!/usr/bin/env python3
-"""CLI entrypoint for the Phase 7 translation sidecar.
-
-Usage:
-  okstra-report-translate.py extract <path-to-final-report.data.json>
-  okstra-report-translate.py check <path-to-sidecar.i18n.<lang>.json>
-
-``extract`` writes the translator's work list — every pointer the report holds
-a translatable string at, paired with the English text. The translator fills
-in the values rather than authoring pointers, so a sidecar cannot cite a path
-the document does not have.
-
-``check`` is the translator's own gate before it returns: it resolves every
-pointer in the sidecar against the report and reports what is still English.
-Without it a bad sidecar surfaces at render time, after the worker is gone.
-
-This script is the canonical single-reference-point. The Node CLI
-(``bin/okstra report-translate``) is a thin wrapper that spawns it.
-"""
-from __future__ import annotations
-
-import argparse
-import hashlib
-import json
-import re
-import os
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parent))
-from okstra_bootstrap import prefer_colocated_modules  # noqa: E402
-
-prefer_colocated_modules(__file__, "okstra_ctl/report_translation.py")
-
-from okstra_ctl.report_translation import (  # noqa: E402
-    extract,
-    group_translation_pointers,
-    overlay,
-)
-from okstra_ctl.final_report_paths import (  # noqa: E402
-    translation_sidecar_path,
-    translation_source_path,
-)
-from okstra_ctl.json_boundary import (  # noqa: E402
-    JsonBoundaryError,
-    load_owned_object,
-    load_owned_object_snapshot,
-    write_owned_object_atomic,
-)
-from okstra_ctl.fixed_text import block, line  # noqa: E402
-from okstra_ctl.convergence import (  # noqa: E402
-    ConvergenceContractError,
-    RunArtifactAuthority,
-    canonical_run_report_artifact,
-    validated_run_authority,
-)
-
-
-def _load(path: Path) -> dict:
-    try:
-        return load_owned_object(path, artifact="report translation artifact")
-    except JsonBoundaryError as exc:
-        raise SystemExit(f"error: {exc}") from exc
-
-
-def _translation_authority(
-    manifest_path: Path,
-) -> tuple[RunArtifactAuthority, Path]:
-    try:
-        authority = validated_run_authority(manifest_path)
-        report = canonical_run_report_artifact(authority)
-    except (ConvergenceContractError, JsonBoundaryError) as exc:
-        raise SystemExit(f"error: {exc}") from exc
-    return authority, report
-
-
-def _report_snapshot(path: Path):
-    try:
-        return load_owned_object_snapshot(
-            path, artifact="report translation source"
-        )
-    except JsonBoundaryError as exc:
-        raise SystemExit(f"error: {exc}") from exc
-
-
-def _source_payload(
-    authority: RunArtifactAuthority, data_path: Path, raw_bytes: bytes, data: dict
-) -> dict:
-    strings = extract(data)
-    return {
-        "taskKey": authority.task_key,
-        "runManifestPath": authority.manifest_ref,
-        "sourceData": data_path.name,
-        "sourceDataPath": data_path.relative_to(authority.project_root).as_posix(),
-        "sourceDataSha256": hashlib.sha256(raw_bytes).hexdigest(),
-        "lang": str((data.get("meta") or {}).get("reportLanguage") or ""),
-        "strings": strings,
-        "translationGroups": group_translation_pointers(data, strings),
-    }
-
-
-def _validate_source_payload(
-    source: dict, expected: dict, supplied_digest: str
-) -> None:
-    for key in (
-        "taskKey", "runManifestPath", "sourceData", "sourceDataPath",
-        "sourceDataSha256", "lang", "strings",
-    ):
-        if source.get(key) != expected.get(key):
-            raise SystemExit(
-                "error: report changed after translation source publication"
-            )
-    if supplied_digest != expected["sourceDataSha256"]:
-        raise SystemExit(
-            "error: report changed after translation source publication"
-        )
-    if "translationGroups" in source and (
-        source["translationGroups"] != expected["translationGroups"]
-    ):
-        raise SystemExit("error: translation groups do not match report source")
-
-
-def cmd_extract(args: argparse.Namespace) -> int:
-    data_path = Path(args.data).resolve()
-    data = _load(data_path)
-    strings = extract(data)
-    out_path = translation_source_path(data_path)
-    lang = str((data.get("meta") or {}).get("reportLanguage") or "")
-    write_owned_object_atomic(
-        out_path,
-        {"lang": lang, "sourceData": data_path.name, "strings": strings},
-        artifact="translation source",
-    )
-    print(
-        json.dumps(
-            {
-                "ok": True,
-                "sourcePath": str(out_path),
-                "sidecarPath": str(translation_sidecar_path(data_path, lang)) if lang else "",
-                "lang": lang,
-                "stringCount": len(strings),
-                "charCount": sum(len(v) for v in strings.values()),
-            },
-            ensure_ascii=False,
-        )
-    )
-    return 0
-
-
-def cmd_source(args: argparse.Namespace) -> int:
-    authority, data_path = _translation_authority(Path(args.run_manifest))
-    snapshot = _report_snapshot(data_path)
-    data = snapshot.value
-    payload = _source_payload(authority, data_path, snapshot.raw_bytes, data)
-    out_path = translation_source_path(data_path)
-    if out_path.is_symlink():
-        raise SystemExit("error: translation source path is a symlink")
-    write_owned_object_atomic(
-        out_path, payload, artifact="translation source"
-    )
-    strings = payload["strings"]
-    print("# Translation work list")
-    print(line("Task key", authority.task_key), end="")
-    print(line("Report", payload["sourceDataPath"]), end="")
-    print(line("Run manifest", authority.manifest_ref), end="")
-    print(line("Source digest", payload["sourceDataSha256"]), end="")
-    groups = payload["translationGroups"]
-    print(line("Field count", len(strings)), end="")
-    print(line("String count", len(groups)), end="")
-    print(line("Source characters", sum(len(value) for value in strings.values())), end="")
-    print(line("Translation characters", sum(len(strings[row[0]]) for row in groups)), end="")
-    for index, pointers in enumerate(groups, 1):
-        print(f"\n## T-{index:03d}\n{block(strings[pointers[0]])}")
-    return 0
-
-
-def _translation_block(rows: list[str]) -> str:
-    # Markdown 의 `\`` 는 백틱 리터럴이고, 이전 `source` 출력이 본문 백틱을 그렇게
-    # 내보냈다. 렌더러는 Markdown 이스케이프를 모르므로 여기서 백틱으로 되돌린다.
-    return "\n".join(rows).strip().replace("\\`", "`")
-
-
-_T_HEADING_RE = re.compile(r"^#{1,6}\s+T-\d{3}\b")
-
-
-def _translation_blocks(path: Path) -> list[str]:
-    text = path.read_text(encoding="utf-8")
-    blocks: list[str] = []
-    current: list[str] | None = None
-    for number, row in enumerate(text.splitlines(), start=1):
-        # 헤딩 수준이 다른 `### T-NNN` 은 블록 경계로 안 보여 본문에 묻히고, 그러면
-        # 블록 수 불일치라는 엉뚱한 메시지가 났다(실측 2026-09-08: id 164개 전부
-        # 일치, 틀린 것은 `#` 개수뿐). 경계처럼 생긴 줄은 여기서 이름을 대고 거절한다.
-        if _T_HEADING_RE.match(row) and not row.startswith("## T-"):
-            raise SystemExit(
-                f"error: translation heading must be level 2 — line {number} is "
-                f"{row.split()[0]!r}, expected '## T-NNN' ({path.name})"
-            )
-        if row.startswith("## T-"):
-            if current is not None:
-                blocks.append(_translation_block(current))
-            expected = f"## T-{len(blocks) + 1:03d}"
-            if row != expected:
-                raise SystemExit(
-                    f"error: expected translation heading {expected} at line {number}, "
-                    f"found {row!r} ({path.name})"
-                )
-            current = []
-        elif current is not None:
-            current.append(row)
-    if current is not None:
-        blocks.append(_translation_block(current))
-    return blocks
-
-
-def cmd_write(args: argparse.Namespace) -> int:
-    authority, data_path = _translation_authority(Path(args.run_manifest))
-    snapshot = _report_snapshot(data_path)
-    data = snapshot.value
-    expected = _source_payload(
-        authority, data_path, snapshot.raw_bytes, data
-    )
-    source_path = translation_source_path(data_path)
-    if source_path.is_symlink():
-        raise SystemExit("error: translation source path is a symlink")
-    source = _load(source_path)
-    _validate_source_payload(source, expected, args.source_digest)
-    sources = expected["strings"]
-    # 발행된 구형 작업 목록은 필드당 한 블록이므로 진행 중 번역의 번호를 보존한다.
-    groups = source.get("translationGroups", [[pointer] for pointer in sources])
-    translated = _translation_blocks(Path(args.translations))
-    if len(translated) != len(groups):
-        raise SystemExit(
-            f"error: translation blocks must match every T-NNN item — "
-            f"{len(translated)} blocks in {Path(args.translations).name}, "
-            f"{len(groups)} items in the translation source"
-        )
-    empty = [f"T-{index + 1:03d}" for index, value in enumerate(translated) if not value]
-    if empty:
-        raise SystemExit(
-            "error: translation blocks must match every T-NNN item — empty: "
-            + ", ".join(empty[:10])
-        )
-    lang = expected["lang"]
-    sidecar = translation_sidecar_path(data_path, lang)
-    if sidecar.is_symlink():
-        raise SystemExit("error: translation sidecar path is a symlink")
-    strings = {
-        pointer: value
-        for pointers, value in zip(groups, translated)
-        for pointer in pointers
-    }
-    _, report = overlay(data, strings)
-    if report.unresolved or report.applied != len(strings):
-        raise SystemExit("error: translations do not validate against report source")
-    write_owned_object_atomic(
-        sidecar,
-        {
-            "taskKey": authority.task_key,
-            "runManifestPath": authority.manifest_ref,
-            "lang": lang,
-            "sourceData": data_path.name,
-            "sourceDataPath": expected["sourceDataPath"],
-            "sourceDataSha256": expected["sourceDataSha256"],
-            "strings": strings,
-        },
-        artifact="report translation sidecar",
-    )
-    print("Translation sidecar\n" + line("Status", "ready"), end="")
-    return 0
-
-
-def cmd_check_data(args: argparse.Namespace) -> int:
-    authority, data_path = _translation_authority(Path(args.run_manifest))
-    snapshot = _report_snapshot(data_path)
-    expected = _source_payload(
-        authority, data_path, snapshot.raw_bytes, snapshot.value
-    )
-    sidecar_path = translation_sidecar_path(data_path, expected["lang"])
-    if sidecar_path.is_symlink():
-        raise SystemExit("error: translation sidecar path is a symlink")
-    sidecar = _load(sidecar_path)
-    _validate_authority_sidecar(sidecar, expected)
-    payload, code = _check_sidecar(sidecar_path)
-    print("Translation check\n" + line("Status", "ready" if payload["ok"] else "error")
-          + line("Applied strings", payload["applied"])
-          + line("Unresolved strings", len(payload["unresolved"])), end="")
-    return code
-
-
-def _validate_authority_sidecar(sidecar: dict, expected: dict) -> None:
-    for key in (
-        "taskKey", "runManifestPath", "lang", "sourceData", "sourceDataPath",
-        "sourceDataSha256",
-    ):
-        if sidecar.get(key) != expected.get(key):
-            raise SystemExit(
-                "error: translation sidecar does not match run authority"
-            )
-
-
-def cmd_check(args: argparse.Namespace) -> int:
-    sidecar_file = Path(args.sidecar).resolve()
-    payload, code = _check_sidecar(sidecar_file)
-    print(json.dumps(payload, ensure_ascii=False))
-    return code
-
-
-def _check_sidecar(sidecar_file: Path) -> tuple[dict, int]:
-    sidecar = _load(sidecar_file)
-    strings = sidecar.get("strings")
-    if not isinstance(strings, dict):
-        raise SystemExit(f"error: {sidecar_file} has no 'strings' object")
-    source_name = str(sidecar.get("sourceData") or "")
-    if not source_name:
-        raise SystemExit(f"error: {sidecar_file} does not name its sourceData")
-    data_path = sidecar_file.parent / source_name
-    if not data_path.is_file():
-        raise SystemExit(f"error: sourceData not found beside the sidecar: {data_path}")
-
-    _, report = overlay(_load(data_path), strings)
-    offered = report.applied + len(report.untranslated)
-    payload = {
-        "ok": not report.unresolved,
-        "applied": report.applied,
-        "offered": offered,
-        "untranslated": list(report.untranslated),
-        "unresolved": list(report.unresolved),
-    }
-    if report.unresolved:
-        # A pointer that resolves nowhere means the sidecar was written against
-        # a different report. Rendering it would silently drop those strings.
-        sys.stderr.write(
-            f"error: {len(report.unresolved)} pointer(s) do not resolve in "
-            f"{data_path.name}\n"
-        )
-        return payload, 1
-    return payload, 0
-
-
-_CLI_EPILOG = r"""A thin spawn shim over `scripts/okstra-report-translate.py` (installed at
-`$HOME/.okstra/bin/okstra-report-translate.py`).
-
-The final-report data.json is authored in English and stays the SSOT. When the
-resolved report language is not English, Phase 7 dispatches a translator that
-writes a sidecar beside the report; `render-views` overlays it so only the
-human HTML is localized.
-
-Usage:
-  okstra report-translate extract <path-to-final-report.data.json>
-  okstra report-translate source --run-manifest <path>
-  okstra report-translate write --run-manifest <path> --source-digest <sha256> --translations <markdown>
-  okstra report-translate check-data --run-manifest <path>
-      Write <stem>.translation-source.json — every pointer the report holds a
-      translatable string at, paired with its English text. The translator
-      fills in the values, so a sidecar cannot cite a path the report lacks.
-
-  okstra report-translate check <path-to-final-report.i18n.<lang>.json>
-      Resolve every pointer in a filled sidecar against the report it names
-      and report what is still English. Exits non-zero on a pointer that
-      resolves nowhere — the translator's own gate before it returns.
-"""
-
-
-def _parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        epilog=_CLI_EPILOG,
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        prog="okstra report-translate",
-        description="Build and verify the final-report translation sidecar.",
-    )
-    sub = parser.add_subparsers(dest="op", required=True)
-
-    extract_cmd = sub.add_parser("extract", help="write the translator's work list")
-    extract_cmd.add_argument("data", help="path to final-report-<type>-<seq>.data.json")
-    extract_cmd.set_defaults(func=cmd_extract)
-
-    source_view = sub.add_parser("source", help="render a fixed translation work list")
-    source_view.add_argument("--run-manifest", required=True)
-    source_view.set_defaults(func=cmd_source)
-
-    write_cmd = sub.add_parser("write", help="publish translations from T-NNN blocks")
-    write_cmd.add_argument("--run-manifest", required=True)
-    write_cmd.add_argument("--source-digest", required=True)
-    write_cmd.add_argument("--translations", required=True)
-    write_cmd.set_defaults(func=cmd_write)
-
-    check_data = sub.add_parser("check-data", help="verify the derived sidecar")
-    check_data.add_argument("--run-manifest", required=True)
-    check_data.set_defaults(func=cmd_check_data)
-
-    check_cmd = sub.add_parser("check", help="verify a filled sidecar against its report")
-    check_cmd.add_argument("sidecar", help="path to final-report-<type>-<seq>.i18n.<lang>.json")
-    check_cmd.set_defaults(func=cmd_check)
-    return parser
-
-
-def main(argv: list[str] | None = None) -> int:
-    args = _parser().parse_args(argv)
-    return int(args.func(args))
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/runtime/prompts/duties/translator.json

@@ -1,32 +0,0 @@
-{
-  "schemaVersion": "1.0",
-  "id": "translator",
-  "roleId": "translator",
-  "responsibilities": [
-    "Translate only the designated sidecar into the requested language as a faithful technical translator, never as an editor of the underlying decision."
-  ],
-  "requiredConduct": [
-    "Read the complete designated source, preserve identifiers, code, paths, commands, data shapes, headings, links, status tokens, normative strength, and uncertainty; use consistent project terminology; and verify that no source section or material qualification was omitted."
-  ],
-  "decisionPrinciples": [
-    "Translate meaning rather than word order, producing natural target-language prose that carries the same precision, tone, uncertainty, and operational force as the source. Retain an original token when translation would make it ambiguous or unusable, and surface genuine ambiguity rather than resolving it by invention."
-  ],
-  "authorityAndBoundaries": [
-    "Write only the assigned translation sidecar. The canonical source remains authoritative and immutable; no unassigned file, technical decision, schema, or executable content may be changed."
-  ],
-  "evidenceStandards": [
-    "The translated structure must map completely to the source structure. Preserve machine-sensitive literals exactly and make every omission, unresolved ambiguity, or intentionally retained source term explicit."
-  ],
-  "collaborationContract": [
-    "Return source ambiguity to the lead or designated owner without editing the source. Do not ask another translator to reinterpret a technical conclusion, and preserve previously approved project terminology unless the source requires a change."
-  ],
-  "completionCriteria": [
-    "Every source section has a meaning-equivalent target section, technical literals and links remain usable, terminology is consistent, natural-language quality has been reviewed, and no new analysis or conclusion has entered the sidecar."
-  ],
-  "prohibitions": [
-    "Do not edit the source of truth, translate unassigned files, add analysis, omit inconvenient qualifications, weaken or strengthen normative language, change a technical conclusion, or localize code and identifiers that must remain exact."
-  ],
-  "blockedStateReporting": [
-    "Name the ambiguous or untranslatable source passage, explain the competing interpretations and affected output, preserve the passage unchanged where safe, and wait for the responsible owner to resolve it."
-  ]
-}