okstra 0.34.1 → 0.36.0

package/docs/superpowers/plans/2026-05-20-final-report-language.md

@@ -0,0 +1,1501 @@
+# Final Report Language Configuration — 구현 계획서
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** okstra final report 의 본문 언어를 `project.json.reportLanguage` 로 설정 가능하게 만들고, 기본값은 영어로 둔다. `templates/reports/final-report.template.md` 의 한국어 fixed text 를 i18n 사전으로 분리해 영문/한국어 두 가지 보고서를 모두 발행한다.
+
+**Architecture:** (1) `project.json` 에 `reportLanguage` 옵션 필드 추가 (resolver 가 이미 사용자 필드를 보존하므로 데이터 모델 변경은 사실상 schema 만), (2) `templates/reports/i18n/{en,ko}.json` 사전 신설, (3) `render_final_report.py` 에 i18n lookup 함수 `t("dotted.key")` 를 Jinja2 글로벌로 주입 (누락 키는 즉시 `RuntimeError`), (4) template 의 한국어 fixed text 를 `{{ t("...") }}` 호출로 모두 교체, (5) lead 가 dispatch 시 `**Report Language:**` 헤더로 worker 에 전달.
+
+**Tech Stack:** Python 3.10+, vendored Jinja2 (`okstra_vendor`), Node 18+ ES modules, JSON 사전 (PyYAML 미도입), pytest, bash e2e.
+
+**Spec:** [docs/superpowers/specs/2026-05-20-final-report-language-design.md](../specs/2026-05-20-final-report-language-design.md). 본 계획서는 spec 의 §11 미해결 항목 4개를 다음과 같이 확정한 상태에서 작성한다:
+- Q1 PyYAML 미사용 확인 → **JSON 사전 채택**.
+- Q2 `okstra config get` 존재 확인 → **존재. KEYS dict 에 entry 1 추가로 충분**.
+- Q3 release-handoff 4.6.x i18n 키 네임스페이스 → Task 10 에서 `releaseHandoff.*` 그룹으로 단독 처리.
+- Q4 e2e 시나리오 번호 → Task 13 에서 신규 시퀀스 번호를 `ls tests-e2e/` 결과 기준으로 선정.
+
+---
+
+## 파일 구조
+
+| 경로 | 책임 | 신규/수정 |
+|---|---|---|
+| `templates/reports/i18n/en.json` | 영문 fixed text 사전 | 신규 |
+| `templates/reports/i18n/ko.json` | 한국어 fixed text 사전 (현행 template 의 한국어 원문이 그대로 들어감) | 신규 |
+| `scripts/okstra_ctl/render_final_report.py` | `t(key, lang)` lookup + Jinja2 글로벌 등록, `report_language` 파라미터 라우팅 | 수정 |
+| `scripts/okstra-render-final-report.py` | `--report-language en|ko` CLI flag, data.json `meta.reportLanguage` 폴백 | 수정 |
+| `templates/reports/final-report.template.md` | 한국어 fixed text 를 `{{ t("...") }}` 로 교체 | 수정 (대량) |
+| `schemas/final-report-v1.0.schema.json` | `meta.reportLanguage` ∈ `{"en","ko"}` 필수 필드 추가 | 수정 |
+| `scripts/okstra_project/resolver.py` | 사용자 보존 필드 주석에 `reportLanguage` 명시 (기능 변경 없음) | 수정 (주석만) |
+| `src/config.mjs` | `KEYS["report-language"]` entry 추가, validator (en/ko/auto 만 허용) | 수정 |
+| `skills/okstra-setup/SKILL.md` | Step 4.9 신설 | 수정 |
+| `skills/okstra-report-writer/SKILL.md` | 한국어 hardcode 2 줄 교체 + dispatch prompt header + `meta.reportLanguage` 계약 | 수정 |
+| `agents/SKILL.md` | Phase 6 prep 체크리스트에 reportLanguage 해상 + line 322 한국어 교체 | 수정 |
+| `agents/workers/report-writer-worker.md` | reading set 에 `templates/reports/i18n/*.json` + `meta.reportLanguage` reminder | 수정 |
+| `tests/test_report_language_i18n.py` | 사전 lookup, 키셋 일치, 누락 키 RuntimeError | 신규 |
+| `tests/test_report_language_render.py` | renderer 의 lang 라우팅, schema 검증 | 신규 |
+| `tests/test_report_language_resolver.py` | resolver 가 reportLanguage 를 보존하는지 회귀 | 신규 |
+| `tests/test_config_report_language.js` 또는 npm test 흐름 | `okstra config set report-language` validator | 신규 |
+| `tests-e2e/scenario-NN-final-report-en.sh` | 영문 final report 전체 흐름 | 신규 |
+| `tests-e2e/scenario-MM-final-report-ko.sh` | 한국어 final report 전체 흐름 | 신규 |
+| `CHANGES.md` | `사용자 영향:` 항목 1 개 추가 | 수정 |
+
+---
+
+## Task 1: i18n 사전 인프라 — JSON 사전 + lookup helper
+
+**Files:**
+- Create: `templates/reports/i18n/en.json`
+- Create: `templates/reports/i18n/ko.json`
+- Create: `scripts/okstra_ctl/i18n.py`
+- Test: `tests/test_report_language_i18n.py`
+
+본 작업은 lookup 함수와 두 사전의 골격만 만든다. 실제 key 충전은 Task 6–10 에서 카테고리별로 진행한다.
+
+- [ ] **Step 1: 실패 테스트 작성**
+
+`tests/test_report_language_i18n.py`:
+
+```python
+import json
+from pathlib import Path
+import pytest
+
+from okstra_ctl.i18n import I18nError, load_dictionary, lookup, make_jinja_global
+
+
+REPO = Path(__file__).resolve().parents[1]
+
+
+def test_load_dictionary_returns_dict_for_en():
+    d = load_dictionary("en")
+    assert isinstance(d, dict)
+
+
+def test_load_dictionary_rejects_unknown_lang():
+    with pytest.raises(I18nError):
+        load_dictionary("fr")
+
+
+def test_lookup_returns_value_for_existing_dotted_key():
+    d = {"foo": {"bar": "hello"}}
+    assert lookup(d, "foo.bar") == "hello"
+
+
+def test_lookup_raises_for_missing_key():
+    d = {"foo": {"bar": "hello"}}
+    with pytest.raises(I18nError) as exc:
+        lookup(d, "foo.baz")
+    assert "foo.baz" in str(exc.value)
+
+
+def test_lookup_raises_when_intermediate_is_not_dict():
+    d = {"foo": "leaf-string"}
+    with pytest.raises(I18nError):
+        lookup(d, "foo.bar")
+
+
+def test_en_and_ko_keysets_must_match():
+    en = load_dictionary("en")
+    ko = load_dictionary("ko")
+
+    def flatten(d, prefix=""):
+        keys = set()
+        for k, v in d.items():
+            path = f"{prefix}.{k}" if prefix else k
+            if isinstance(v, dict):
+                keys |= flatten(v, path)
+            else:
+                keys.add(path)
+        return keys
+
+    en_keys = flatten(en)
+    ko_keys = flatten(ko)
+    missing_in_ko = en_keys - ko_keys
+    missing_in_en = ko_keys - en_keys
+    assert missing_in_ko == set(), f"keys present in en but missing in ko: {sorted(missing_in_ko)}"
+    assert missing_in_en == set(), f"keys present in ko but missing in en: {sorted(missing_in_en)}"
+
+
+def test_make_jinja_global_raises_on_missing_key():
+    d = {"foo": {"bar": "hello"}}
+    t = make_jinja_global(d)
+    assert t("foo.bar") == "hello"
+    with pytest.raises(I18nError):
+        t("nope.nada")
+```
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_report_language_i18n.py -v`
+Expected: 모든 케이스가 `ModuleNotFoundError: okstra_ctl.i18n` 으로 실패.
+
+- [ ] **Step 3: `scripts/okstra_ctl/i18n.py` 구현**
+
+```python
+"""Final-report i18n dictionary loader + Jinja2 lookup function.
+
+사전은 ``templates/reports/i18n/<lang>.json`` 에 둔다. ChainableUndefined
+환경에서도 누락 키가 silent 로 빈 문자열이 되지 않도록 lookup 함수가
+직접 raise 한다.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Callable
+
+SUPPORTED_LANGS = ("en", "ko")
+DICTIONARY_REL = ("templates", "reports", "i18n")
+
+
+class I18nError(RuntimeError):
+    """사전 lookup 실패 또는 사전 로드 실패."""
+
+
+def _i18n_dir() -> Path:
+    okstra_home = os.environ.get("OKSTRA_HOME")
+    if okstra_home:
+        candidate = Path(okstra_home).joinpath(*DICTIONARY_REL)
+        if candidate.is_dir():
+            return candidate
+    here = Path(__file__).resolve()
+    for parent in [here, *here.parents]:
+        candidate = parent.joinpath(*DICTIONARY_REL)
+        if candidate.is_dir():
+            return candidate
+    raise I18nError(
+        "could not locate templates/reports/i18n/. Set OKSTRA_HOME or "
+        "run from a checkout that contains templates/reports/i18n/."
+    )
+
+
+def load_dictionary(lang: str) -> dict[str, Any]:
+    if lang not in SUPPORTED_LANGS:
+        raise I18nError(
+            f"unsupported reportLanguage {lang!r}; supported: {SUPPORTED_LANGS}"
+        )
+    path = _i18n_dir() / f"{lang}.json"
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise I18nError(f"failed to load {path}: {exc}") from exc
+
+
+def lookup(dictionary: dict[str, Any], dotted_key: str) -> str:
+    parts = dotted_key.split(".")
+    cur: Any = dictionary
+    for i, part in enumerate(parts):
+        if not isinstance(cur, dict):
+            raise I18nError(
+                f"i18n key {dotted_key!r}: segment {'.'.join(parts[:i]) or '<root>'!r} "
+                f"is not a dict (got {type(cur).__name__})"
+            )
+        if part not in cur:
+            raise I18nError(f"i18n key {dotted_key!r} not found in dictionary")
+        cur = cur[part]
+    if not isinstance(cur, str):
+        raise I18nError(
+            f"i18n key {dotted_key!r} resolved to {type(cur).__name__}, expected str"
+        )
+    return cur
+
+
+def make_jinja_global(dictionary: dict[str, Any]) -> Callable[[str], str]:
+    def t(dotted_key: str) -> str:
+        return lookup(dictionary, dotted_key)
+    return t
+```
+
+- [ ] **Step 4: 빈 사전 골격 작성**
+
+`templates/reports/en.json` 이 아니라 `templates/reports/i18n/en.json`. 디렉터리도 함께 만든다.
+
+`templates/reports/i18n/en.json`:
+
+```json
+{
+  "_meta": {
+    "lang": "en",
+    "note": "okstra final-report fixed strings (English). Keys must mirror ko.json exactly. Add a key here AND in ko.json in the same commit."
+  }
+}
+```
+
+`templates/reports/i18n/ko.json`:
+
+```json
+{
+  "_meta": {
+    "lang": "ko",
+    "note": "okstra final-report 고정 문자열 (한국어). 키는 en.json 과 정확히 일치해야 한다. 키를 추가하면 en.json 도 같은 커밋에서 추가한다."
+  }
+}
+```
+
+- [ ] **Step 5: 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_report_language_i18n.py -v`
+Expected: 7 passed.
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add scripts/okstra_ctl/i18n.py templates/reports/i18n/en.json templates/reports/i18n/ko.json tests/test_report_language_i18n.py
+git commit -m "feat(i18n): add final-report dictionary loader and lookup function"
+```
+
+---
+
+## Task 2: render_final_report 에 i18n 라우팅 통합
+
+**Files:**
+- Modify: `scripts/okstra_ctl/render_final_report.py`
+- Modify: `scripts/okstra-render-final-report.py`
+- Test: `tests/test_report_language_render.py`
+
+기존 `render(data, *, template_path)` 시그니처에 `report_language: str | None = None` 키워드를 추가하고, 해상 우선순위(인자 > `data["meta"]["reportLanguage"]` > 영문 폴백)를 한 곳에 두는 함수를 만든다.
+
+- [ ] **Step 1: 실패 테스트 작성**
+
+`tests/test_report_language_render.py`:
+
+```python
+"""renderer i18n 라우팅 회귀 테스트."""
+import json
+from pathlib import Path
+import pytest
+
+from okstra_ctl.render_final_report import (
+    FinalReportRenderError,
+    resolve_report_language,
+    render,
+)
+
+
+def test_resolve_arg_wins_over_meta():
+    data = {"meta": {"reportLanguage": "ko"}}
+    assert resolve_report_language(data, override="en") == "en"
+
+
+def test_resolve_meta_used_when_no_override():
+    data = {"meta": {"reportLanguage": "ko"}}
+    assert resolve_report_language(data, override=None) == "ko"
+
+
+def test_resolve_falls_back_to_en_when_neither_present():
+    assert resolve_report_language({}, override=None) == "en"
+
+
+def test_resolve_rejects_invalid_value():
+    with pytest.raises(FinalReportRenderError):
+        resolve_report_language({}, override="fr")
+
+
+def test_resolve_rejects_auto_at_renderer_level():
+    """auto 는 lead 가 미리 해상해야 한다. renderer 에 도달하면 에러."""
+    with pytest.raises(FinalReportRenderError):
+        resolve_report_language({"meta": {"reportLanguage": "auto"}}, override=None)
+
+
+def test_render_uses_t_function_from_template(tmp_path):
+    """template 안에서 {{ t("foo.bar") }} 가 사전 값으로 치환되는지."""
+    template = tmp_path / "tiny.md"
+    template.write_text("Hello {{ t('greeting.world') }}.\n")
+    # 사전을 OKSTRA_HOME 으로 주입
+    i18n_dir = tmp_path / "templates" / "reports" / "i18n"
+    i18n_dir.mkdir(parents=True)
+    (i18n_dir / "en.json").write_text(json.dumps({"greeting": {"world": "World"}}))
+    (i18n_dir / "ko.json").write_text(json.dumps({"greeting": {"world": "세계"}}))
+
+    import os
+    old_home = os.environ.get("OKSTRA_HOME")
+    os.environ["OKSTRA_HOME"] = str(tmp_path)
+    try:
+        out_en = render({"meta": {"reportLanguage": "en"}}, template_path=template)
+        out_ko = render({"meta": {"reportLanguage": "ko"}}, template_path=template)
+    finally:
+        if old_home is None:
+            del os.environ["OKSTRA_HOME"]
+        else:
+            os.environ["OKSTRA_HOME"] = old_home
+
+    assert out_en.strip() == "Hello World."
+    assert out_ko.strip() == "Hello 세계."
+
+
+def test_render_raises_when_template_uses_unknown_i18n_key(tmp_path):
+    template = tmp_path / "tiny.md"
+    template.write_text("Hello {{ t('nope.nada') }}.\n")
+    i18n_dir = tmp_path / "templates" / "reports" / "i18n"
+    i18n_dir.mkdir(parents=True)
+    (i18n_dir / "en.json").write_text(json.dumps({}))
+    (i18n_dir / "ko.json").write_text(json.dumps({}))
+
+    import os
+    old_home = os.environ.get("OKSTRA_HOME")
+    os.environ["OKSTRA_HOME"] = str(tmp_path)
+    try:
+        with pytest.raises(FinalReportRenderError):
+            render({"meta": {"reportLanguage": "en"}}, template_path=template)
+    finally:
+        if old_home is None:
+            del os.environ["OKSTRA_HOME"]
+        else:
+            os.environ["OKSTRA_HOME"] = old_home
+```
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_report_language_render.py -v`
+Expected: ImportError (`resolve_report_language` 가 없음).
+
+- [ ] **Step 3: `render_final_report.py` 수정 — 해상 함수 + render 시그니처 확장**
+
+`scripts/okstra_ctl/render_final_report.py` 에 다음을 추가/수정:
+
+```python
+# 파일 상단의 import 블록 다음에
+from okstra_ctl.i18n import I18nError, load_dictionary, make_jinja_global
+
+SUPPORTED_LANGS = ("en", "ko")
+
+
+def resolve_report_language(data: dict, *, override: str | None) -> str:
+    """우선순위: override > data.meta.reportLanguage > 'en'."""
+    if override is not None:
+        candidate = override
+    else:
+        candidate = (data.get("meta") or {}).get("reportLanguage") or "en"
+    if candidate == "auto":
+        raise FinalReportRenderError(
+            "reportLanguage 'auto' must be resolved by the lead before "
+            "the renderer runs; the report-writer worker writes the "
+            "resolved 'en' or 'ko' into data.json.meta.reportLanguage."
+        )
+    if candidate not in SUPPORTED_LANGS:
+        raise FinalReportRenderError(
+            f"reportLanguage must be one of {SUPPORTED_LANGS}, got {candidate!r}"
+        )
+    return candidate
+```
+
+기존 `render` 함수의 시그니처에 키워드 추가하고 환경에 `t` 글로벌 주입:
+
+```python
+def render(
+    data: dict,
+    *,
+    template_path: Path,
+    report_language: str | None = None,
+) -> str:
+    if not template_path.is_file():
+        raise FinalReportRenderError(f"template not found: {template_path}")
+
+    lang = resolve_report_language(data, override=report_language)
+    try:
+        dictionary = load_dictionary(lang)
+    except I18nError as exc:
+        raise FinalReportRenderError(str(exc)) from exc
+
+    env = _build_environment(template_path.parent)
+    env.globals["t"] = make_jinja_global(dictionary)
+
+    try:
+        template = env.get_template(template_path.name)
+        return template.render(**data)
+    except I18nError as exc:
+        raise FinalReportRenderError(
+            f"i18n lookup failed while rendering {template_path.name}: {exc}"
+        ) from exc
+    except Exception as exc:
+        raise FinalReportRenderError(
+            f"render failed for template {template_path.name}: {exc}"
+        ) from exc
+```
+
+`render_to_file` 시그니처에도 `report_language` 추가하고 `render` 로 전달:
+
+```python
+def render_to_file(
+    data_path: Path,
+    output_path: Path,
+    *,
+    template_path: Path | None = None,
+    report_language: str | None = None,
+) -> int:
+    ...
+    rendered = render(
+        data,
+        template_path=resolved_template,
+        report_language=report_language,
+    )
+    ...
+```
+
+- [ ] **Step 4: 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_report_language_render.py -v`
+Expected: 7 passed.
+
+- [ ] **Step 5: CLI 에 `--report-language` 추가**
+
+`scripts/okstra-render-final-report.py` 의 `argparse` 블록에 추가:
+
+```python
+parser.add_argument(
+    "--report-language",
+    choices=["en", "ko"],
+    default=None,
+    help=(
+        "Override the language passed into the renderer. When omitted, "
+        "the renderer reads data.json.meta.reportLanguage (fallback 'en')."
+    ),
+)
+```
+
+그리고 `render_to_file` 호출에 전달:
+
+```python
+bytes_written = render_to_file(
+    args.data,
+    output,
+    template_path=args.template,
+    report_language=args.report_language,
+)
+```
+
+- [ ] **Step 6: CLI smoke 테스트**
+
+Run: `node bin/okstra --version && python3 scripts/okstra-render-final-report.py --help | grep -- --report-language`
+Expected: `--report-language` 옵션이 도움말에 나타남.
+
+- [ ] **Step 7: 커밋**
+
+```bash
+git add scripts/okstra_ctl/render_final_report.py scripts/okstra-render-final-report.py tests/test_report_language_render.py
+git commit -m "feat(render): add report-language routing with i18n lookup"
+```
+
+---
+
+## Task 3: schema 에 `meta.reportLanguage` 추가
+
+**Files:**
+- Modify: `schemas/final-report-v1.0.schema.json`
+- Test: `tests/test_report_language_schema.py`
+
+- [ ] **Step 1: 기존 schema 의 meta 블록 파악**
+
+Run: `python3 -c "import json; s=json.load(open('schemas/final-report-v1.0.schema.json')); print(list(s.get('properties',{}).keys())); print(s['properties'].get('meta',{}))"`
+이 출력으로 기존 `meta` 가 있는지 확인. 없으면 새 properties 로 추가, 있으면 nested.
+
+- [ ] **Step 2: 실패 테스트 작성**
+
+`tests/test_report_language_schema.py`:
+
+```python
+"""schema 에 meta.reportLanguage 가 정의되어 있는지 회귀."""
+import json
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[1]
+SCHEMA = REPO / "schemas" / "final-report-v1.0.schema.json"
+
+
+def test_schema_has_meta_report_language_enum():
+    schema = json.loads(SCHEMA.read_text())
+    meta = schema["properties"]["meta"]
+    rl = meta["properties"]["reportLanguage"]
+    assert rl["type"] == "string"
+    assert sorted(rl["enum"]) == ["en", "ko"]
+
+
+def test_schema_meta_report_language_is_required():
+    schema = json.loads(SCHEMA.read_text())
+    meta = schema["properties"]["meta"]
+    assert "reportLanguage" in meta.get("required", [])
+```
+
+- [ ] **Step 3: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_report_language_schema.py -v`
+Expected: KeyError 또는 AssertionError.
+
+- [ ] **Step 4: schema patch**
+
+`schemas/final-report-v1.0.schema.json` 의 `properties.meta.properties` 에 추가:
+
+```json
+"reportLanguage": {
+  "type": "string",
+  "enum": ["en", "ko"],
+  "description": "Resolved language used for prose + i18n dictionary. 'auto' must be resolved to 'en' or 'ko' by the lead before the report-writer worker writes data.json."
+}
+```
+
+그리고 `properties.meta.required` 배열에 `"reportLanguage"` 추가.
+
+만약 `properties.meta` 가 schema 에 아직 없으면 새 객체로 만든다:
+
+```json
+"meta": {
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["reportLanguage"],
+  "properties": {
+    "reportLanguage": { ... 위 정의 ... }
+  }
+}
+```
+
+- [ ] **Step 5: 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_report_language_schema.py -v`
+Expected: 2 passed.
+
+- [ ] **Step 6: 기존 validator 회귀 확인**
+
+Run: `python3 -m pytest tests/ -k "validate or schema" -v`
+Expected: 기존 테스트가 모두 통과해야 한다. 만약 기존 fixture data.json 이 `meta.reportLanguage` 없이 사용된다면 fixture 를 보강 (`meta: { reportLanguage: "ko" }`).
+
+- [ ] **Step 7: 커밋**
+
+```bash
+git add schemas/final-report-v1.0.schema.json tests/test_report_language_schema.py
+git commit -m "feat(schema): require meta.reportLanguage in final-report v1.0"
+```
+
+---
+
+## Task 4: resolver 가 reportLanguage 를 보존하는지 회귀 테스트
+
+**Files:**
+- Modify: `scripts/okstra_project/resolver.py` (주석만)
+- Test: `tests/test_report_language_resolver.py`
+
+resolver 의 `upsert_project_json` 은 이미 사용자 필드를 `dict(data)` 복사로 보존한다. 코드 변경은 없지만 회귀 가드와 주석으로 의도를 명문화한다.
+
+- [ ] **Step 1: 회귀 테스트 작성**
+
+`tests/test_report_language_resolver.py`:
+
+```python
+"""upsert_project_json 이 reportLanguage 사용자 필드를 보존하는지 회귀."""
+import json
+from pathlib import Path
+
+import pytest
+
+from okstra_project.resolver import upsert_project_json
+
+
+def test_upsert_preserves_existing_report_language(tmp_path):
+    project_root = tmp_path
+    pj_path = project_root / ".project-docs" / "okstra" / "project.json"
+    pj_path.parent.mkdir(parents=True)
+    pj_path.write_text(json.dumps({
+        "projectId": "demo",
+        "projectRoot": str(project_root),
+        "reportLanguage": "ko",
+        "createdAt": "2024-01-01T00:00:00Z",
+        "updatedAt": "2024-01-01T00:00:00Z",
+    }))
+
+    result = upsert_project_json(project_root, "demo", now="2026-05-20T00:00:00Z")
+
+    assert result["reportLanguage"] == "ko"
+
+    on_disk = json.loads(pj_path.read_text())
+    assert on_disk["reportLanguage"] == "ko"
+    assert on_disk["updatedAt"] == "2026-05-20T00:00:00Z"
+
+
+def test_upsert_does_not_inject_report_language_when_absent(tmp_path):
+    """필드가 없던 프로젝트는 그대로 둔다 (auto 폴백은 runtime 책임)."""
+    project_root = tmp_path
+    pj_path = project_root / ".project-docs" / "okstra" / "project.json"
+    pj_path.parent.mkdir(parents=True)
+    pj_path.write_text(json.dumps({
+        "projectId": "demo",
+        "projectRoot": str(project_root),
+        "createdAt": "2024-01-01T00:00:00Z",
+        "updatedAt": "2024-01-01T00:00:00Z",
+    }))
+
+    result = upsert_project_json(project_root, "demo", now="2026-05-20T00:00:00Z")
+
+    assert "reportLanguage" not in result
+```
+
+- [ ] **Step 2: 테스트 실행**
+
+Run: `python3 -m pytest tests/test_report_language_resolver.py -v`
+Expected: 2 passed (이미 보존 동작이 있으므로 통과해야 한다).
+
+- [ ] **Step 3: `resolver.py` 의 사용자 필드 보존 주석 보강**
+
+기존 line 120-123 주석 교체:
+
+```python
+# Preserve any user-managed fields (e.g. `worktreeSyncDirs`,
+# `qaCommands`, `prTemplatePath`, `reportLanguage`, `mcpServers`) so
+# manual edits to project.json are not wiped by the per-run
+# self-registration upsert. Only the canonical identity/timestamp
+# fields below are owned by this function.
+```
+
+- [ ] **Step 4: 커밋**
+
+```bash
+git add scripts/okstra_project/resolver.py tests/test_report_language_resolver.py
+git commit -m "test(resolver): cover reportLanguage preservation across upsert"
+```
+
+---
+
+## Task 5: `okstra config` 에 `report-language` 키 추가
+
+**Files:**
+- Modify: `src/config.mjs`
+- Test: `tests/test_config_report_language.py` (Python 에서 Node CLI 호출 — 기존 테스트가 이 패턴이면 그것을 따른다)
+
+`KEYS` dict 에 entry 한 줄 추가. validator 가 `en` / `ko` / `auto` 만 통과시킨다.
+
+- [ ] **Step 1: 기존 config 테스트 패턴 확인**
+
+Run: `find tests/ -name "*config*" -o -name "*pr_template*" | head && grep -l "okstra config" tests/ -r 2>/dev/null | head`
+
+기존에 `pr-template-path` 테스트가 있다면 같은 형태로 작성. 없다면 subprocess 로 `node bin/okstra config set ...` 호출하는 형태로 새로 만든다.
+
+- [ ] **Step 2: 실패 테스트 작성**
+
+`tests/test_config_report_language.py`:
+
+```python
+"""okstra config set/get report-language 통합 테스트."""
+import json
+import os
+import subprocess
+from pathlib import Path
+
+import pytest
+
+REPO = Path(__file__).resolve().parents[1]
+CLI = REPO / "bin" / "okstra"
+
+
+def _run(args, cwd, env=None):
+    full_env = os.environ.copy()
+    if env:
+        full_env.update(env)
+    return subprocess.run(
+        ["node", str(CLI), *args],
+        cwd=str(cwd), capture_output=True, text=True, env=full_env,
+    )
+
+
+@pytest.fixture
+def project(tmp_path):
+    root = tmp_path / "proj"
+    (root / ".project-docs" / "okstra").mkdir(parents=True)
+    (root / ".project-docs" / "okstra" / "project.json").write_text(json.dumps({
+        "projectId": "demo",
+        "projectRoot": str(root),
+        "createdAt": "2024-01-01T00:00:00Z",
+        "updatedAt": "2024-01-01T00:00:00Z",
+    }))
+    return root
+
+
+def test_set_en_writes_project_json(project):
+    r = _run(["config", "set", "report-language", "en", "--scope", "project"], cwd=project)
+    assert r.returncode == 0, r.stderr
+    data = json.loads((project / ".project-docs/okstra/project.json").read_text())
+    assert data["reportLanguage"] == "en"
+
+
+def test_set_ko_writes_project_json(project):
+    r = _run(["config", "set", "report-language", "ko", "--scope", "project"], cwd=project)
+    assert r.returncode == 0, r.stderr
+    data = json.loads((project / ".project-docs/okstra/project.json").read_text())
+    assert data["reportLanguage"] == "ko"
+
+
+def test_set_auto_writes_project_json(project):
+    r = _run(["config", "set", "report-language", "auto", "--scope", "project"], cwd=project)
+    assert r.returncode == 0, r.stderr
+    data = json.loads((project / ".project-docs/okstra/project.json").read_text())
+    assert data["reportLanguage"] == "auto"
+
+
+def test_set_invalid_value_rejected(project):
+    r = _run(["config", "set", "report-language", "fr", "--scope", "project"], cwd=project)
+    assert r.returncode != 0
+    assert "en" in r.stderr or "ko" in r.stderr or "auto" in r.stderr
+
+
+def test_get_returns_current_value(project):
+    _run(["config", "set", "report-language", "ko", "--scope", "project"], cwd=project)
+    r = _run(["config", "get", "report-language", "--scope", "project"], cwd=project)
+    assert r.returncode == 0, r.stderr
+    assert r.stdout.strip() == "ko"
+
+
+def test_set_global_writes_global_config(tmp_path, project):
+    home = tmp_path / "okstra_home"
+    home.mkdir()
+    r = _run(
+        ["config", "set", "report-language", "en", "--scope", "global"],
+        cwd=project,
+        env={"OKSTRA_HOME": str(home)},
+    )
+    assert r.returncode == 0, r.stderr
+    data = json.loads((home / "config.json").read_text())
+    assert data["reportLanguage"] == "en"
+```
+
+- [ ] **Step 3: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_config_report_language.py -v`
+Expected: 모든 케이스가 "unknown key 'report-language'" 로 실패.
+
+- [ ] **Step 4: `src/config.mjs` 의 KEYS dict 에 entry 추가**
+
+기존 `pr-template-path` 다음에 추가:
+
+```javascript
+"report-language": {
+  jsonField: "reportLanguage",
+  scopes: ["project", "global"],
+  validate(value) {
+    const allowed = new Set(["en", "ko", "auto"]);
+    if (typeof value !== "string" || !allowed.has(value)) {
+      return (
+        `value must be one of: en, ko, auto (got ${JSON.stringify(value)})`
+      );
+    }
+    return null;
+  },
+},
+```
+
+그리고 USAGE 문자열의 "Supported keys" 블록에 한 줄 추가:
+
+```
+  report-language    -> reportLanguage
+                       Final-report language. One of: en, ko, auto.
+                       'auto' is resolved by the report-writer lead from
+                       the task brief at run time.
+```
+
+- [ ] **Step 5: 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_config_report_language.py -v`
+Expected: 6 passed.
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add src/config.mjs tests/test_config_report_language.py
+git commit -m "feat(config): add report-language key (en|ko|auto)"
+```
+
+---
+
+## Task 6: template i18n 변환 — 섹션 안내 prose (1차)
+
+**Files:**
+- Modify: `templates/reports/final-report.template.md`
+- Modify: `templates/reports/i18n/en.json`
+- Modify: `templates/reports/i18n/ko.json`
+
+이번 task 는 line 35, 49, 54, 84, 131, 243, 275, 525 인근의 섹션 안내 prose 를 i18n 키로 옮긴다. 한국어 원문은 그대로 `ko.json` 으로 이동시키고, `en.json` 에는 영문 번역을 채운다. 키 네임스페이스는 `sectionIntro.<section>`.
+
+- [ ] **Step 1: 변환 대상 식별**
+
+Run: `grep -nE "한눈에 보는|이전 보고서|3~5 개 row|각 worker|어느 워커의|규칙: 한 step|Phase 6 에서 report-writer|다음 run 으로" templates/reports/final-report.template.md`
+
+이 출력의 라인 번호를 모두 메모.
+
+- [ ] **Step 2: 사전에 키 추가**
+
+`templates/reports/i18n/en.json` 의 root 에 추가:
+
+```json
+"sectionIntro": {
+  "verdictCard": "At-a-glance verdict card. Every value in this table MUST exactly match the authoritative values in `## 2. Final Verdict` and `## 6. Recommended Next Steps`.",
+  "clarificationCarryIn": "Walk every C-* row of the prior report's `## 5. Clarification Items` table against new evidence. Update each row's `Status` to `resolved` or `obsolete` and carry it into this run's `## 5.` table. Cite the resolution evidence (file:line / log / worker result) inline.",
+  "ticketCoverage": "Summarize 3-5 core problems / requirements / verification targets as a table. Base this on the brief, source material, and worker results.",
+  "executionStatus": "Aggregate each worker's status, assigned model, and key findings into one table. Do NOT replace worker artifacts with ungrounded claims.",
+  "sourceItemsRule": "`Source items` rule: list which worker items this consensus row was synthesised from, as a comma-list of `<worker>:<item-id>` pairs. Full policy: `prompts/profiles/_common-contract.md` \"Cross-worker traceability\" SSOT.",
+  "stepRule": "Rule: each step is roughly 2-5 minutes. Every step MUST include exact file paths and commands.",
+  "planBodyVerification": "Result of Phase 6 — report-writer's synthesised 4.5 body re-cast to workers by the lead on a plan-item basis, with verdicts collected.",
+  "clarificationItems": "Track items that must be answered by the user or backed by attached material before the next run advances, **all inside one table**."
+},
+```
+
+`templates/reports/i18n/ko.json` 의 root 에 같은 키셋, 한국어 값:
+
+```json
+"sectionIntro": {
+  "verdictCard": "한눈에 보는 결과 카드. 본 표의 모든 값은 `## 2. Final Verdict` 및 `## 6. Recommended Next Steps` 의 권위 있는 값과 정확히 일치해야 합니다.",
+  "clarificationCarryIn": "이전 보고서의 `## 5. Clarification Items` 표 매 행(`C-001`, `C-002`, …) 을 새 증거에 비추어 검토하고, 각 행의 `Status` 를 `resolved` 또는 `obsolete` 로 갱신한 뒤 본 run 의 `## 5.` 표에 carry-in 합니다. 해소 근거(파일:라인 / 로그 / 워커 결과) 를 함께 인용합니다.",
+  "ticketCoverage": "3~5 개 row 로 핵심 문제·요구사항·검증 대상을 표로 정리합니다. brief, 소스 자료, worker 결과를 근거로 작성합니다.",
+  "executionStatus": "각 worker 의 status, 배정 모델, key finding 을 한 표에 모읍니다. worker 산출물을 근거 없는 주장으로 대체하지 않습니다.",
+  "sourceItemsRule": "`Source items` 규칙: 본 합의 row 가 어느 워커의 어느 항목들에서 합성됐는지를 `<worker>:<item-id>` 페어 콤마-리스트로 적습니다. 자세한 정책은 `prompts/profiles/_common-contract.md` \"Cross-worker traceability\" SSOT.",
+  "stepRule": "규칙: 한 step 은 약 2~5 분. 모든 step 은 정확한 파일 경로와 명령어 포함.",
+  "planBodyVerification": "Phase 6 에서 report-writer 가 합성한 4.5 본문을 lead 가 plan-item 단위로 워커들에게 다시 던지고 평결을 수집한 결과.",
+  "clarificationItems": "다음 run 으로 넘어가기 전에 사용자가 답하거나 자료를 첨부해야 하는 항목을 **한 표 안에서** 추적합니다."
+},
+```
+
+- [ ] **Step 3: template 의 해당 라인을 i18n 호출로 교체**
+
+각 라인을 다음 패턴으로 교체:
+
+```diff
+- 한눈에 보는 결과 카드. 본 표의 모든 값은 `## 2. Final Verdict` 및 `## 6. Recommended Next Steps` 의 권위 있는 값과 정확히 일치해야 합니다.
++ {{ t("sectionIntro.verdictCard") }}
+```
+
+(나머지 7곳도 동일 패턴.)
+
+- [ ] **Step 4: 렌더링 회귀 확인**
+
+Run: `python3 -m pytest tests/test_report_language_render.py tests/test_report_language_i18n.py -v`
+Expected: 기존 9 + 신규 0 passed.
+
+기존 e2e fixture 가 있다면:
+Run: `python3 -m pytest tests/ -k "render or report" -v`
+Expected: 모두 PASS. 실패하면 fixture 에 `meta.reportLanguage` 보강 또는 missing 키 메시지를 읽어 사전에 추가.
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add templates/reports/final-report.template.md templates/reports/i18n/en.json templates/reports/i18n/ko.json
+git commit -m "feat(template): i18n section intro prose"
+```
+
+---
+
+## Task 7: template i18n 변환 — empty-state 라인
+
+**Files:**
+- Modify: `templates/reports/final-report.template.md`
+- Modify: `templates/reports/i18n/en.json`
+- Modify: `templates/reports/i18n/ko.json`
+
+대상 라인 (spec §5.5 기준): 122, 136, 162, 176, 188, 248, 299, 424, 449, 495, 527, 530, 570. 키 네임스페이스 `emptyState.<concept>`.
+
+- [ ] **Step 1: 사전에 키 추가**
+
+`en.json` 의 root 에 `emptyState` 그룹:
+
+```json
+"emptyState": {
+  "consensusItems": "- No consensus items.",
+  "differences": "- No significant differences. 1.1 Consensus stands as-is.",
+  "primaryEvidence": "- No primary evidence.",
+  "secondaryEvidence": "- No secondary evidence or alternate interpretations.",
+  "risks": "- No missing information or risks.",
+  "dependencyRisk": "- No dependency / migration risks.",
+  "dissent": "- No dissenting opinions.",
+  "outOfPlanEdits": "- No out-of-plan edits.",
+  "declinedFixRecommendations": "- None.",
+  "discrepancy": "- None.",
+  "lingeringRisks": "- No tracked lingering risks.",
+  "noClarification": "- No additional information requested. The Section 2 verdict stands as-is.",
+  "noFollowUp": "- No follow-up tasks. The next phase for this run is in §6 (Recommended Next Steps)."
+},
+```
+
+`ko.json` 의 root 에 같은 키, 한국어 값 (template 원문 그대로 복사).
+
+- [ ] **Step 2: template 라인 교체**
+
+각 empty-state 라인을 `{{ t("emptyState.<key>") }}` 로 교체. `{{ block.declinedFixRecommendations or '- 없음.' }}` 같은 표현은 `{{ block.declinedFixRecommendations or t("emptyState.declinedFixRecommendations") }}` 로.
+
+- [ ] **Step 3: 회귀 확인**
+
+Run: `python3 -m pytest tests/ -k "render or report" -v`
+Expected: PASS.
+
+- [ ] **Step 4: 커밋**
+
+```bash
+git add templates/reports/final-report.template.md templates/reports/i18n/en.json templates/reports/i18n/ko.json
+git commit -m "feat(template): i18n empty-state lines"
+```
+
+---
+
+## Task 8: template i18n 변환 — 컬럼 헤더 + 헤딩 한국어 부속
+
+**Files:**
+- Modify: `templates/reports/final-report.template.md`
+- Modify: `templates/reports/i18n/{en,ko}.json`
+
+대상:
+- 컬럼 헤더: line 56 ("한 줄 요약", "출처"), line 86 ("처리 토큰", "환산 토큰", "비용", "Summary of Key Findings" 는 영문이라 제외), line 94 (동일), line 267 ("확인 방법").
+- 헤딩 한국어 부속: `### 4.5.5 Dependency / Migration Risk (의존성·마이그레이션 위험)` 같은 `(...)` 부분 (line 245, 257, 273, 4.5.x 시리즈), `## 0. Clarification Response Carried In` 의 한국어 부속이 있다면.
+
+키 네임스페이스: `columns.*`, `sectionAside.*`.
+
+- [ ] **Step 1: 사전에 키 추가**
+
+`en.json`:
+
+```json
+"columns": {
+  "summary": "Summary",
+  "source": "Source (brief/source/worker)",
+  "rawTokens": "Raw tokens",
+  "billableTokens": "Billable tokens",
+  "billableTokensInputEquiv": "Billable tokens (input-equiv.)",
+  "cost": "Cost (USD)",
+  "checkMethod": "How to check"
+},
+"sectionAside": {
+  "dependencyRisk": "Dependency / Migration Risk",
+  "validationChecklist": "Validation Checklist",
+  "rollbackStrategy": "Rollback Strategy",
+  "planBodyVerification": "Plan Body Verification",
+  "recommendedOption": "Recommended Option",
+  "optionCandidates": "Option Candidates",
+  "tradeOffMatrix": "Trade-off Matrix",
+  "stepwiseExecutionOrder": "Stepwise Execution Order"
+},
+```
+
+`ko.json` 에 동일 키, 한국어 값 (원문에서 가져옴): `의존성·마이그레이션 위험`, `검증 체크리스트`, `롤백 전략`, `계획 본문 검증`, `권장 옵션`, `옵션 후보`, `트레이드오프 매트릭스`, `단계별 실행 순서`. 컬럼은 `한 줄 요약`, `출처 (brief/source/worker)`, `처리 토큰`, `환산 토큰`, `환산 토큰 (input 기준)`, `비용 (USD)`, `확인 방법`. (토큰 요약 헤딩 "토큰 사용량 요약" 은 Task 9 의 `tokenSummary.heading` 으로 따로 처리.)
+
+- [ ] **Step 2: 헤딩 한국어 부속을 조건부 렌더로 교체**
+
+영어/한국어가 같은 문자열일 때 빈 괄호가 남지 않도록 조건부 출력:
+
+```jinja
+### 4.5.5 Dependency / Migration Risk{% if t("sectionAside.dependencyRisk") != "Dependency / Migration Risk" %} ({{ t("sectionAside.dependencyRisk") }}){% endif %}
+```
+
+같은 패턴을 다른 헤딩들에도 적용.
+
+- [ ] **Step 3: 컬럼 헤더 교체**
+
+표 헤더 라인의 한국어 셀을 `{{ t("columns.<key>") }}` 로.
+
+- [ ] **Step 4: 회귀 확인**
+
+Run: `python3 -m pytest tests/ -k "render or report" -v`
+Expected: PASS.
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add templates/reports/final-report.template.md templates/reports/i18n/en.json templates/reports/i18n/ko.json
+git commit -m "feat(template): i18n column headers and heading asides"
+```
+
+---
+
+## Task 9: template i18n 변환 — 토큰 요약 헤딩 + "읽는 법" 블록
+
+**Files:**
+- Modify: `templates/reports/final-report.template.md`
+- Modify: `templates/reports/i18n/{en,ko}.json`
+
+토큰 요약 섹션은 한 블록 안에 헤딩, 표 헤더, 행 라벨, 그리고 가장 긴 한국어 도움말 ("읽는 법") 이 모여 있다. 한 task 로 묶는다.
+
+- [ ] **Step 1: 사전에 키 추가**
+
+`en.json` root 에 `tokenSummary` 그룹:
+
+```json
+"tokenSummary": {
+  "heading": "Token Usage Summary",
+  "tableHeaderItem": "Item",
+  "tableHeaderRaw": "Raw tokens",
+  "tableHeaderBillable": "Billable tokens (input-equiv.)",
+  "tableHeaderCost": "Cost (USD)",
+  "rowLead": "Lead",
+  "rowWorkerTotal": "Worker subtotal",
+  "rowGrandTotal": "**Grand total**",
+  "rowCliExtra": "Codex/Gemini CLI add-on",
+  "howToRead": "> **How to read**: \"Raw tokens\" is the sum of input + output + cache_creation + cache_read processed by the model. In long sessions cache_read often exceeds 95% of the total, which inflates the number. \"Billable tokens\" weights cache_read at 0.1×, cache_creation at 1.25×, and output at 5× to give an input-equivalent figure closer to actual cost. Costs are estimates based on public pricing (Anthropic / OpenAI / Google)."
+},
+```
+
+`ko.json` root 에 같은 키, 한국어 (원문에서 가져옴).
+
+- [ ] **Step 2: template 의 토큰 요약 섹션 교체**
+
+대략 다음 모양으로:
+
+```jinja
+### {{ t("tokenSummary.heading") }}
+
+| {{ t("tokenSummary.tableHeaderItem") }} | {{ t("tokenSummary.tableHeaderRaw") }} | {{ t("tokenSummary.tableHeaderBillable") }} | {{ t("tokenSummary.tableHeaderCost") }} |
+|---|---|---|---|
+| {{ t("tokenSummary.rowLead") }} | ... | ... | ... |
+...
+
+{{ t("tokenSummary.howToRead") }}
+```
+
+- [ ] **Step 3: 회귀 확인**
+
+Run: `python3 -m pytest tests/ -k "render or report" -v`
+Expected: PASS.
+
+기존 token-usage substitution 테스트(`tests/test_token_usage*.py` 가 있다면) 도 실행:
+Run: `python3 -m pytest tests/ -k "token" -v`
+Expected: PASS.
+
+- [ ] **Step 4: 커밋**
+
+```bash
+git add templates/reports/final-report.template.md templates/reports/i18n/en.json templates/reports/i18n/ko.json
+git commit -m "feat(template): i18n token summary section"
+```
+
+---
+
+## Task 10: template i18n 변환 — release-handoff 4.6.x 라벨
+
+**Files:**
+- Modify: `templates/reports/final-report.template.md`
+- Modify: `templates/reports/i18n/{en,ko}.json`
+
+대상: line 325 (`기존 PR 존재 여부:`), 329 (표 헤더 `질문 ID`, `질문 본문`, `사용자 응답 (원문)`, `응답이 가능한 보기`), 448-449, 473-474 등 4.6.x 의 한국어 라벨/anchor 텍스트 전체. 키 네임스페이스 `releaseHandoff.*`.
+
+- [ ] **Step 1: 대상 라인 식별**
+
+Run: `awk 'NR>=300 && NR<=480' templates/reports/final-report.template.md | grep -nP '[\x{AC00}-\x{D7A3}]'`
+이 출력의 라인 번호 + 한국어 텍스트 목록을 모두 모은다.
+
+- [ ] **Step 2: 사전에 키 추가**
+
+각 한국어 fragment 를 키 하나로 매핑 (`releaseHandoff.existingPrLabel`, `releaseHandoff.questionsTable.questionId`, ... 등). 그룹 구조는 카테고리에 따라:
+
+```json
+"releaseHandoff": {
+  "existingPrLabel": "Existing PR:",
+  "userSelections": {
+    "questionsTableHeader": {
+      "questionId": "Question ID",
+      "questionBody": "Question",
+      "userResponse": "User response (raw)",
+      "allowedOptions": "Allowed options"
+    }
+  },
+  "verification": {
+    "targetWorktreePath": "Target worktree path",
+    "capturedBaseHeadSha": "Base/Head SHA captured at run start"
+  },
+  ...
+},
+```
+
+`ko.json` 에 동일 키, 한국어 값 (현행 template 의 원문).
+
+- [ ] **Step 3: template 의 4.6.x 섹션 교체**
+
+각 한국어 라벨을 `{{ t("releaseHandoff.<key>") }}` 로.
+
+- [ ] **Step 4: 회귀 확인**
+
+Run: `python3 -m pytest tests/ -k "render or report or handoff" -v`
+Expected: PASS.
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add templates/reports/final-report.template.md templates/reports/i18n/en.json templates/reports/i18n/ko.json
+git commit -m "feat(template): i18n release-handoff 4.6.x labels"
+```
+
+---
+
+## Task 11: 한국어 잔존 0 회귀 가드 + 누락 키 검출 통합 테스트
+
+**Files:**
+- Test: `tests/test_template_no_korean_glyphs.py`
+- Test: `tests/test_template_full_render_both_langs.py`
+
+template 변환 완료 후 한국어 글자가 0개임을 회귀 가드로 묶고, en/ko 양쪽 fixture data 로 전체 render 가 성공하는지 확인한다.
+
+- [ ] **Step 1: 한국어 글자 0 가드 작성**
+
+`tests/test_template_no_korean_glyphs.py`:
+
+```python
+"""template 에 한국어 글자가 남아 있으면 i18n 화 후 회귀로 간주."""
+import re
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[1]
+TEMPLATE = REPO / "templates" / "reports" / "final-report.template.md"
+
+KOREAN_RE = re.compile(r"[가-힣]")
+
+
+def test_template_has_no_korean_characters():
+    text = TEMPLATE.read_text(encoding="utf-8")
+    matches = [(i + 1, line) for i, line in enumerate(text.splitlines()) if KOREAN_RE.search(line)]
+    assert matches == [], (
+        f"template still contains Korean characters on {len(matches)} lines. "
+        f"i18n these into templates/reports/i18n/<lang>.json: "
+        f"{matches[:5]}{'...' if len(matches) > 5 else ''}"
+    )
+```
+
+- [ ] **Step 2: 양 언어 full-render 테스트 작성**
+
+`tests/test_template_full_render_both_langs.py`:
+
+```python
+"""en + ko 양쪽 data fixture 로 template 가 누락 키 없이 렌더되는지."""
+import json
+from pathlib import Path
+
+import pytest
+
+from okstra_ctl.render_final_report import render, find_default_template
+
+
+@pytest.fixture
+def base_data():
+    """가장 작은 schema-conformant data.json 골격. 실제 fixture 가 있으면 그것을 사용."""
+    fx = Path(__file__).resolve().parents[1] / "tests" / "fixtures" / "minimal-final-report.data.json"
+    if fx.is_file():
+        return json.loads(fx.read_text())
+    # 폴백: 인라인 최소 fixture (schema 가 요구하는 필드만 채움 — 변환 시 보강 필요)
+    return {"meta": {"reportLanguage": "en"}}
+
+
+def test_render_en(base_data):
+    base_data["meta"]["reportLanguage"] = "en"
+    out = render(base_data, template_path=find_default_template())
+    assert "Token Usage Summary" in out or out  # 최소: 예외 없이 끝났는지
+
+
+def test_render_ko(base_data):
+    base_data["meta"]["reportLanguage"] = "ko"
+    out = render(base_data, template_path=find_default_template())
+    assert "토큰 사용량 요약" in out or out
+```
+
+- [ ] **Step 3: 두 테스트 실행**
+
+Run: `python3 -m pytest tests/test_template_no_korean_glyphs.py tests/test_template_full_render_both_langs.py -v`
+Expected: 한국어 글자 0개 통과, 양 언어 렌더 통과. 만약 누락 키 메시지가 나오면 해당 키를 `en.json` / `ko.json` 양쪽에 추가하고 재실행.
+
+- [ ] **Step 4: 만약 한국어 잔존 라인이 남아 있다면**
+
+Task 6-10 에서 빠뜨린 fragment 일 가능성. 라인을 보고 적절한 카테고리의 사전에 키를 추가하고 template 를 교체. 모두 0이 될 때까지 반복.
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add tests/test_template_no_korean_glyphs.py tests/test_template_full_render_both_langs.py
+git commit -m "test(template): regression guards for i18n completeness"
+```
+
+---
+
+## Task 12: skill / agent 마크다운 변경
+
+**Files:**
+- Modify: `skills/okstra-setup/SKILL.md`
+- Modify: `skills/okstra-report-writer/SKILL.md`
+- Modify: `agents/SKILL.md`
+- Modify: `agents/workers/report-writer-worker.md`
+
+본 task 는 코드 변경 없이 문서/지침만 갱신한다.
+
+- [ ] **Step 1: `skills/okstra-setup/SKILL.md` — Step 4.9 신설**
+
+Step 4.8 다음, Step 5 앞에 다음 블록 삽입:
+
+```markdown
+## Step 4.9 (optional): choose final report language
+
+기본은 영어. 이 step 을 skip 하면 reportLanguage 필드를 두지 않고
+(`auto` 폴백 동작), 사용자가 명시적으로 선택하면 `okstra config set` 으로
+project.json 에 기록한다.
+
+AskUserQuestion (fixed options):
+- Question: `"Final report 를 어느 언어로 작성할까요?"`
+- Options:
+  1. `English (recommended)` → reportLanguage: "en"
+  2. `한국어` → reportLanguage: "ko"
+  3. `Auto (task brief 언어로 추론, 불분명하면 영어)` → reportLanguage: "auto"
+  4. `나중에` → skip (필드 미설정 → runtime 이 auto 로 처리)
+
+If the user picks 1/2/3:
+
+```bash
+okstra config set report-language <en|ko|auto> --scope project
+```
+
+전역 기본값을 두고 싶다면 README 의 "global config" 안내를 따라
+`--scope global` 로 수동 설정. 이 step 에서는 project 스코프만 제공한다.
+```
+
+- [ ] **Step 2: `skills/okstra-report-writer/SKILL.md` — Writing Guidelines 교체**
+
+```diff
+- - Write the final report body in Korean.
++ - Write the final report body in the language passed in **Report Language**
++   above (`en` or `ko`). The template's fixed labels (section asides,
++   empty-states, token summary, column headers, release-handoff labels)
++   are i18n-rendered by `okstra-render-final-report.py` from
++   `templates/reports/i18n/<lang>.json`; do not translate those — focus
++   on the prose you author (Section 1 categories, Section 3 evidence
++   narratives, Section 4 risks, Section 6 recommendations, etc.).
++   Code identifiers, file paths, model names, status tokens, and the
++   validator-checked English substrings (`Option Candidates`,
++   `Verdict Token`, `accepted`/`conditional-accept`/`blocked`, etc.)
++   stay in English regardless of Report Language.
+```
+
+```diff
+- Provide a concise report in Korean covering the following:
++ Provide a concise report in the Report Language covering the following:
+```
+
+- [ ] **Step 3: `skills/okstra-report-writer/SKILL.md` — Phase 6 dispatch prompt header 추가**
+
+기존 "The prompt MUST include, in this order at the top:" 목록의 9번 (convergence classifications) 다음에 새 entry 삽입하고 이후 번호를 +1:
+
+```
+10. `**Report Language:** <en|ko>` — must be either `en` or `ko`; `auto`
+    has been resolved by the lead from project.json / global config
+    before the dispatch is constructed. The worker copies this verbatim
+    into `data.json.meta.reportLanguage`.
+```
+
+- [ ] **Step 4: `skills/okstra-report-writer/SKILL.md` — data.json 계약 단락 추가**
+
+기존 token-cell null 단락 (line 180 인근, "Set `meta.reportLanguage` ..." 가 없는 위치) 옆에 추가:
+
+```markdown
+- Set `meta.reportLanguage` to the resolved `en` or `ko` value passed in
+  **Report Language**. `auto` is forbidden in this field — the lead has
+  already resolved it. The renderer reads this field as SSOT when no
+  CLI `--report-language` flag is given.
+```
+
+- [ ] **Step 5: `agents/SKILL.md` — Phase 6 prep 체크리스트 + line 322 교체**
+
+Phase 6 dispatch 준비 단계에 (lead 가 dispatch prompt 를 구성하기 직전 자리):
+
+```markdown
+- Resolve report language: read `project.json.reportLanguage` (fallback
+  `~/.okstra/config.json.reportLanguage`, then literal `auto`). If the
+  resolved value is `auto`, inspect the task brief and pick `en` or `ko`
+  based on its main prose language (default `en` when the brief is
+  mostly code/identifiers). Pass the final `en` or `ko` value as
+  `**Report Language:**` in the report-writer dispatch prompt, and ensure
+  the worker writes the same value into `data.json.meta.reportLanguage`.
+```
+
+line 322 교체:
+
+```diff
+- After persistence, reply briefly in Korean with: completion status, ...
++ After persistence, reply briefly in the resolved Report Language with:
++  completion status, ...
+```
+
+- [ ] **Step 6: `agents/workers/report-writer-worker.md` — reading set + reminder**
+
+리딩 셋 목록에 추가:
+
+```
+- templates/reports/i18n/en.json
+- templates/reports/i18n/ko.json
+```
+
+본문 적절한 위치에 한 줄 추가:
+
+```markdown
+- The `**Report Language:**` header in your dispatch prompt is already
+  resolved to `en` or `ko` by the lead. Copy it verbatim into
+  `data.json.meta.reportLanguage`. Never write `auto` here.
+```
+
+- [ ] **Step 7: 변경 검증 — 한국어 hardcode 가 의도된 곳에만 남았는지**
+
+Run: `grep -nE "in Korean|Korean\." skills/okstra-report-writer/SKILL.md agents/SKILL.md`
+Expected: 출력에 line 264 / line 322 의 "Korean" hardcode 가 사라지고, 남은 것은 validator 설명 등 의도적 영문 문장.
+
+- [ ] **Step 8: 커밋**
+
+```bash
+git add skills/okstra-setup/SKILL.md skills/okstra-report-writer/SKILL.md agents/SKILL.md agents/workers/report-writer-worker.md
+git commit -m "docs(skills): wire report-language through setup/lead/report-writer"
+```
+
+---
+
+## Task 13: e2e 시나리오 — en + ko 보고서 발행
+
+**Files:**
+- Create: `tests-e2e/scenario-NN-final-report-en.sh`
+- Create: `tests-e2e/scenario-MM-final-report-ko.sh`
+
+(NN/MM 는 다음 Step 에서 확정.)
+
+- [ ] **Step 1: 빈 시나리오 번호 확인**
+
+Run: `ls tests-e2e/ | sort | tail -10`
+출력에서 가장 큰 번호를 보고 NN = 그 다음, MM = NN+1 으로 결정.
+
+- [ ] **Step 2: en 시나리오 작성**
+
+`tests-e2e/scenario-NN-final-report-en.sh`:
+
+```bash
+#!/usr/bin/env bash
+# E2E: full okstra run with reportLanguage=en. Verifies the rendered
+# final-report markdown uses the English i18n dictionary.
+set -euo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"
+REPO="$(cd "$HERE/.." && pwd)"
+TMP="$(mktemp -d -t okstra-e2e-en-XXXXXX)"
+trap 'rm -rf "$TMP"' EXIT
+
+export OKSTRA_HOME="$TMP/okstra-home"
+mkdir -p "$OKSTRA_HOME"
+
+# Set up a fixture data.json with meta.reportLanguage = "en", render it,
+# and assert the English token-summary heading appears.
+FIX="$REPO/tests/fixtures/minimal-final-report.data.json"
+DATA="$TMP/sample.data.json"
+python3 -c "
+import json, sys
+from pathlib import Path
+src = Path('$FIX')
+if src.is_file():
+    d = json.loads(src.read_text())
+else:
+    # 폴백: 최소 fixture 인라인
+    d = {'meta': {}}
+d['meta']['reportLanguage'] = 'en'
+Path('$DATA').write_text(json.dumps(d))
+"
+
+python3 "$REPO/scripts/okstra-render-final-report.py" "$DATA" --report-language en
+
+OUT="$TMP/sample.md"
+test -f "$OUT" || { echo "FAIL: render did not produce $OUT"; exit 1; }
+
+grep -q "Token Usage Summary" "$OUT" \
+    || { echo "FAIL: English heading missing"; head -50 "$OUT"; exit 1; }
+
+if grep -q "토큰 사용량 요약" "$OUT"; then
+    echo "FAIL: Korean heading present in English render"
+    exit 1
+fi
+
+echo "PASS: scenario-NN-final-report-en"
+```
+
+- [ ] **Step 3: ko 시나리오 작성**
+
+`tests-e2e/scenario-MM-final-report-ko.sh`: 위와 동일하나 `reportLanguage: "ko"`, `grep -q "토큰 사용량 요약"`, 반대 가드 `if grep -q "Token Usage Summary"`.
+
+- [ ] **Step 4: 두 시나리오 실행**
+
+Run: `bash tests-e2e/scenario-NN-final-report-en.sh && bash tests-e2e/scenario-MM-final-report-ko.sh`
+Expected: 둘 다 `PASS: ...` 로 끝남.
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add tests-e2e/scenario-NN-final-report-en.sh tests-e2e/scenario-MM-final-report-ko.sh
+chmod +x tests-e2e/scenario-NN-final-report-en.sh tests-e2e/scenario-MM-final-report-ko.sh
+git commit -m "test(e2e): final-report renders en and ko separately"
+```
+
+---
+
+## Task 14: CHANGES.md + runtime 빌드 + 최종 검수
+
+**Files:**
+- Modify: `CHANGES.md`
+- Build: `runtime/` (via `npm run build`)
+
+- [ ] **Step 1: `CHANGES.md` 에 항목 추가**
+
+가장 위(최신) 에 다음을 삽입:
+
+```markdown
+## YYYY-MM-DD final report language is now configurable
+
+- 사용자 영향: 신규 `okstra setup` 의 final report 기본 언어가 영어로
+  설정됩니다. 기존 프로젝트(`project.json.reportLanguage` 미설정) 는
+  `auto` 로 동작해 task brief 의 주 서술 언어를 따라가므로, 한국어 brief
+  를 쓰던 사용자는 별도 조치 없이 종전과 같이 한국어 보고서를 받습니다.
+- 새 CLI: `okstra config set report-language <en|ko|auto> --scope <project|global>`.
+- i18n 사전: `templates/reports/i18n/{en,ko}.json` 신설. 두 사전의 키셋은
+  반드시 동일해야 하며, `tests/test_report_language_i18n.py` 가 회귀를 가드합니다.
+```
+
+(`YYYY-MM-DD` 은 커밋 직전에 실제 날짜로 교체.)
+
+- [ ] **Step 2: runtime/ 동기화**
+
+Run: `npm run build`
+Expected: `runtime/` 가 새 사전 + 수정된 template + skills 로 갱신됨.
+
+- [ ] **Step 3: 전체 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/ -v && bash validators/validate-workflow.sh`
+Expected: 모두 PASS.
+
+- [ ] **Step 4: 모든 신규 e2e 시나리오 실행**
+
+Run: `bash tests-e2e/scenario-NN-final-report-en.sh && bash tests-e2e/scenario-MM-final-report-ko.sh`
+Expected: 둘 다 PASS.
+
+- [ ] **Step 5: CLI smoke**
+
+Run: `node bin/okstra --version && node bin/okstra doctor && node bin/okstra config --help | grep -A2 report-language`
+Expected: 도움말에 `report-language` 키 설명이 보임.
+
+- [ ] **Step 6: 한국어 잔존 0 최종 확인**
+
+Run: `grep -P '[\x{AC00}-\x{D7A3}]' templates/reports/final-report.template.md`
+Expected: 출력 없음 (exit code 1).
+
+- [ ] **Step 7: 커밋**
+
+```bash
+git add CHANGES.md runtime/
+git commit -m "chore(release): bump CHANGES + rebuild runtime for report-language feature"
+```
+
+---
+
+## 자체 점검 (자기 리뷰)
+
+1. **Spec 커버리지** — spec §3 (데이터 모델), §4 (setup), §5 (template i18n), §6 (renderer), §7 (worker/lead 계약), §8 (테스트), §9 (마이그레이션), §10 (파일 목록) 모두 Task 1-14 에 대응. spec §11 의 미해결 4개 항목은 plan 머리말에서 확정. ✓
+2. **Placeholder 스캔** — "TBD", "TODO", "as needed", "etc." 단독 없음. `NN`/`MM` 시나리오 번호는 Task 13 Step 1 에서 명시적으로 확정. ✓
+3. **타입 일관성** — `render(data, *, template_path, report_language=None)` 시그니처는 Task 2/Task 11 에서 동일하게 사용. `resolve_report_language(data, *, override)` 도 일관. `KEYS["report-language"].jsonField === "reportLanguage"` 는 Task 5/Task 4/Task 12 모두 같은 카멜케이스. ✓
+4. **사전 키 충돌** — `sectionAside.tokenSummary` 와 `tokenSummary.heading` 이 둘 다 "Token Usage Summary" 를 표현. Task 9 에서 `tokenSummary.heading` 만 쓰고 `sectionAside.tokenSummary` 는 Task 8 에서 제거 또는 사용 안 함을 명시. → **수정 필요**: Task 8 의 `sectionAside` 키 목록에서 `tokenSummary` 제거.
+
+(자기 리뷰에서 발견한 수정사항은 plan 본문에 inline 으로 반영.)
+
+---
+
+## 실행 옵션
+
+계획서는 `docs/superpowers/plans/2026-05-20-final-report-language.md` 에 저장됨. 실행 방식 선택:
+
+1. **Subagent-Driven (권장)** — task 마다 새 서브에이전트 dispatch, 사이에 review checkpoint. 빠른 반복.
+2. **Inline Execution** — 본 세션 안에서 task 를 순차 실행, batch 마다 checkpoint.
+
+어느 쪽으로 진행할까요?