okstra 0.102.1 → 0.102.3

package/docs/superpowers/specs/2026-05-15-implementation-plan-verification-design.md

@@ -1,254 +0,0 @@
-# Implementation Plan Body Verification — Design
-
-- Date: 2026-05-15
-- Scope: okstra phase `implementation-planning` only
-- Status: Designed (pending implementation)
-- Implementation plan: `docs/superpowers/plans/2026-05-15-implementation-plan-verification.md` (to be written)
-
-## 1. 목적
-
-`implementation-planning` phase는 현재 다음 흐름을 따른다.
-
-```
-Phase 4 (워커 독립 분석)
-  → Phase 5.5 (워커 finding 상호 검증 — convergence)
-  → Phase 6 (report-writer가 통합 plan draft 작성)
-  → User Approval gate
-  → implementation phase
-```
-
-Phase 5.5의 convergence는 **워커의 finding (section 1~5)** 만 cross-verify한다. 그 뒤 report-writer가 합성한 **통합 plan body (section 4.5: Option Candidates / Trade-off / Recommended Option / Stepwise Execution Order / Dependency / Validation Checklist / Rollback)** 에 대해서는 워커의 재검증이 없다. lead의 self-review pass만 거치고 User Approval로 직행한다.
-
-본 변경은 Phase 6 직후, User Approval 직전에 **합성 결과물 자체를 워커가 peer-review하는 라운드**를 끼워 넣는다. 통합 plan의 내적 일관성 / 실행 가능성 / 누락된 step / 깨진 file path 등을 워커들이 잡아내고, majority disagreement는 `## 5. Clarification Items`에 `Blocks=approval` row로 변환해 사용자에게 던진다.
-
-## 2. 결정된 분기 (대화에서 확정)
-
-| ID | 결정 |
-|----|-----|
-| Q1 | **gating**. majority DISAGREE는 User Approval 체크박스를 막고 clarification 변환 경로로 보낸다. `contested` 와 `partial-consensus` 는 보고서에 기록만 하고 통과. |
-| Q2 | **lifecycle 내부 step**. 외부 6-phase 계약 유지. `/okstra-status` 에는 implementation-planning 내부의 `plan-verification` sub-state로만 노출. |
-| Q3 | **maxRounds = 1**. plan body 검증은 사실 검증이 아닌 일관성·완전성 검증이며 추가 라운드 이득이 작음. manifest로 override 가능. |
-| Q4 | **자동 revise 안 함**. majority DISAGREE 항목은 lead가 직접 `## 5. Clarification Items` 표의 `Blocks=approval` row로 변환. report-writer 재호출 없음. |
-
-## 3. Plan Item 분리 규칙
-
-report-writer가 draft한 final-report의 `## 4.5 Implementation Plan Deliverables` 본문을 lead가 파싱해 다음 형식의 plan-item으로 쪼갠다.
-
-| Prefix | 출처 섹션 | 1 row의 정의 |
-|--------|----------|--------------|
-| `P-Opt-<N>` | `4.5 Option Candidates` | Option 1개 전체 (File Structure / 인터페이스 / blast radius 묶음) |
-| `P-Step-<N>` | `Stepwise Execution Order` | step 1개 (file path + command + 성공 신호) |
-| `P-Dep-<N>` | `Dependency` | dependency row 1개 |
-| `P-Val-<N>` | `Validation Checklist` | checklist item 1개 |
-| `P-Rb-<N>` | `Rollback` | rollback path 1개 (보통 1행) |
-
-`Trade-off matrix`, `Recommended Option`은 별도 plan-item으로 만들지 않는다 (각 Option 자체가 P-Opt-* 로 평가되므로 중복).
-
-Ticket ID 표기는 기존 규칙 그대로 (`[TICKETID: ...]`) plan-item 라인에 강제.
-
-## 4. 평결 스키마 (재사용)
-
-기존 convergence의 `AGREE` / `DISAGREE` / `SUPPLEMENT` 스키마와 워커 실패 처리 규칙을 그대로 재사용. plan-body 모드에서의 각 평결 의미는 다음과 같다.
-
-| 평결 | plan-body 모드 의미 |
-|------|--------------------|
-| `AGREE` | 항목이 실행 가능하고 다른 항목과 내적으로 일관됨 |
-| `DISAGREE` | 항목이 깨짐 — 다음 중 하나 이상: (a) 참조된 file path / symbol 이 다른 step·option과 불일치, (b) command가 실행 불가하거나 ambiguity, (c) validation step이 관측 불가, (d) rollback이 commit 순서·dependency 위반, (e) 명시된 trade-off와 모순 |
-| `SUPPLEMENT` | 항목 자체는 OK이나 누락된 dependency / edge case / 사전조건 보강이 필요함 |
-
-워커 non-result(`timeout`/`error`/no result file) 처리는 finding convergence와 동일 — DISAGREE로 집계하지 않고 `contract-violation` 이벤트만 기록.
-
-## 5. 최종 분류 → Gate 매핑
-
-`effectiveMaxRounds = 1` 이므로 단일 라운드 결과로 결정.
-
-| 항목 분류 | Gate 동작 |
-|----------|----------|
-| `full-consensus AGREE` | 통과. 보고서에 기록. |
-| `partial-consensus` (majority AGREE, 일부 DISAGREE) | 통과(`passed-with-dissent`). 반대 의견은 보고서 4.5.9 섹션에 기록. |
-| `majority DISAGREE` | **gate 차단**. clarification row 변환. User Approval 체크박스 라인 자체를 렌더하지 않음. |
-| `worker-unique DISAGREE` (1명만 반대) | 통과. 보고서 기록만. |
-| `contested` (round 1 종료 시 큐 잔류 — maxRounds=1에서는 partial-consensus 와 동일 취급) | partial-consensus 로 fold-in. |
-| 모든 워커 non-result | 라운드 전체 실패. `aborted-non-result` 기록 + User Approval 체크박스 라인 렌더하지 않음 + clarification에 "plan-body verification could not run" row 추가. |
-
-## 6. 변경 파일
-
-### 6.1 `prompts/profiles/implementation-planning.md`
-- `Required deliverable shape` 끝에 새 bullet: "the final report MUST include a `## 4.5.9 Plan Body Verification` section populated by the post-synthesis worker verification round (see `okstra-convergence` "Plan-body verification mode")."
-- `Approval gate` 항목 보강: User Approval 체크박스 라인은 **plan-body verification gate가 `passed` 또는 `passed-with-dissent`일 때만 렌더된다**. `blocked-by-disagreement` / `aborted-non-result` 면 라인 자체를 생략하고 clarification 표로 사용자에게 던진다.
-- `Self-review pass` 끝에 6번 항목 신설: "If plan-body verification produced `DISAGREE` majority on any P-* item, convert each into a row of `## 5. Clarification Items` with `Blocks=approval`. Do NOT create a parallel `Open Questions` block."
-
-### 6.2 `skills/okstra-convergence/SKILL.md`
-- 신규 섹션 추가: "Plan-body verification mode (implementation-planning only)"
-- 본문 내용:
-  - **선행 흐름**: Phase 5.5 finding convergence → Phase 6 report-writer → plan-body verification round → User Approval
-  - finding 큐와 plan-item 큐는 **서로 독립**. 같은 워커, 같은 평결 스키마, 같은 wrapper 인프라를 재사용하되 state file은 별도(`plan-body-verification.json`).
-  - **MUTUAL EXCLUSION (BLOCKING)**: finding convergence 의 reverify prompt에 P-* item을 끼워 넣거나, plan-body 라운드의 reverify prompt에 F-* finding을 끼워 넣지 말 것.
-  - plan-body 라운드 전용 reverify prompt 본문 템플릿 (§7 참고).
-  - prompt anchor 5종은 finding convergence와 동일하게 유지.
-
-### 6.3 `templates/reports/final-report.template.md`
-- 신규 sub-section `### 4.5.9 Plan Body Verification` 추가. 위치: 기존 `### 4.5.8 User Approval Request` 직후, `## 4.6 Release Handoff Deliverables` 직전 (implementation-planning 4.5 블록의 마지막 sub-section).
-- 필드:
-
-  ```
-  ## 4.5.9 Plan Body Verification
-
-  - Round count: <N>
-  - Gate result: <passed | passed-with-dissent | blocked-by-disagreement | aborted-non-result>
-  - Verdict table:
-
-  | Plan item | Ticket ID | Section | <worker1> | <worker2> | ... | Classification |
-  |-----------|-----------|---------|-----------|-----------|-----|----------------|
-  | P-Opt-1   | ...       | 4.5.1   | AGREE     | AGREE     | ... | full-consensus |
-  | P-Step-3  | ...       | 4.5.4   | DISAGREE  | DISAGREE  | ... | majority-disagree → C-7 |
-
-  - Dissent log: (partial-consensus / worker-unique 인 항목의 반대 의견 본문)
-  ```
-
-### 6.4 `validators/validate-run.py`
-- `implementation-planning` phase 일 때 final-report에서 다음 substring을 필수로 검사:
-  - `Plan Body Verification`
-- Approval gate 라인 검사 로직 보강: gate 결과가 `passed` / `passed-with-dissent` 이면 `- [ ] Approved` / `- [x] Approved` 라인이 반드시 존재해야 하고, `blocked-by-disagreement` / `aborted-non-result` 이면 해당 라인이 **존재하지 않아야** 한다.
-
-### 6.5 `scripts/okstra_ctl/render.py` (task-manifest payload)
-현재 codebase 에는 task-manifest 를 위한 Python dataclass 가 없다 (`models.py` 는 model alias 전용). manifest payload 는 `render_task_manifest()` 안에서 dict literal 로 직접 구성된다. 기존 `convergence` 블록은 아직 manifest 에 출력되지 않으며, skill 문서에만 "있으면 읽고 없으면 default" 로 기술돼 있다. 따라서:
-
-- `render_task_manifest()` payload 에 신규 `convergence` 블록을 명시적으로 출력한다:
-
-  ```json
-  "convergence": {
-    "enabled": true,
-    "maxRounds": <phase-aware default>,
-    "verificationMode": "lightweight",
-    "planBodyVerification": {
-      "enabled": true,
-      "maxRounds": 1,
-      "gating": true
-    }
-  }
-  ```
-
-  - `maxRounds`: `requirements-discovery` 면 1, 그 외 phase 면 2 (기존 skill 문서의 default 그대로).
-  - `planBodyVerification.enabled`: task-type 이 `implementation-planning` 일 때만 의미를 가진다. 다른 phase 에서는 무시되어도 안전한 dead-letter 필드 (스키마 일관성을 위해 항상 출력).
-- ctx 입력 키 (CLI / wizard / interactive 입력 → ctx env 로 합류):
-  - `OKSTRA_PLAN_VERIFICATION` ∈ `{"true","false",""}` — 빈 값이면 default(true). 명령행 `--no-plan-verification` 가 `"false"` 로 set.
-  - 추후 `OKSTRA_PLAN_VERIFICATION_MAX_ROUNDS` 같은 추가 knob 가능하지만 본 spec 범위에서는 1 고정.
-- 기존 manifest 와의 호환: render 마다 payload 가 매 회 다시 쓰이므로 (`render_task_manifest` 의 `existing` 머지 대상은 `workflow` 일부와 `createdAt`/`latestRunPath` 같은 lifecycle 키뿐) `convergence` 블록은 매 render 마다 새로 작성된다. legacy task-key 의 resume 시 ctx 가 default(true) 면 자동으로 enabled 가 set 된다 (§8 마이그레이션 항목 그대로).
-
-### 6.6 `agents/SKILL.md` (lead orchestration skill — markdown only, no Python)
-
-**아키텍처 정정**: okstra 의 orchestration 패턴은 conversational-only 다. Python 코드(`scripts/okstra_ctl/`)는 task bundle 준비 / 템플릿 렌더링 / validation 만 담당하고, Phase 4 (워커 dispatch), Phase 5.5 (convergence), Phase 6 (report-writer dispatch) 등 **모든 phase 실행은 lead 가 SKILL.md 명세를 따라 inline 으로 Agent() 호출**로 수행한다. `render.py:1133` 의 rendered prompt 문구 ("convergence loop. The Claude lead performs every step inline") 와 run.py 에 convergence 관련 dispatch 함수가 존재하지 않는 점이 이 패턴을 확인해 준다.
-
-따라서 plan-body verification 도 별도 Python 함수 추가 없이, lead skill 의 Phase 6 섹션 확장만으로 wiring 한다.
-
-- `agents/SKILL.md` 의 "Phase 6: Final report assembly" 섹션 끝에 새 sub-step 추가:
-  - report-writer draft 검토 후 → `task_type == "implementation-planning"` 이고 manifest 의 `convergence.planBodyVerification.enabled == true` 면 → `okstra-convergence` "Plan-body verification mode" sub-skill invoke (이 명세는 §6.2 Phase D 에서 추가됨).
-  - 라운드 결과(`gateResult`) 에 따라 §6.3 양식의 `### 4.5.9 Plan Body Verification` 섹션을 final-report 에 직접 채우고, `majority-disagree` 항목은 `## 5. Clarification Items` 의 `Blocks=approval` row 로 변환. (이 변환 로직은 §6.1 Phase C 의 self-review step 6 가 lead 에게 BLOCKING 으로 명령.)
-  - 변환 완료 후, Gate result 에 따라 top-of-report Approval marker 의 렌더 / 비렌더 결정 (이 룰은 §6.1 Phase C 의 Approval gate bullet 이 BLOCKING 으로 명령, §6.4 Phase B 의 validator 가 실행 후 검사).
-- `agents/SKILL.md` 상단 "Lifecycle / Skill index" 표(line 28 근처)에 plan-body verification 이 Phase 6 의 sub-step 임을 한 줄 명시 — 별도 phase 식별자는 부여하지 **않는다** (spec §2 Q2 = lifecycle 내부 step).
-
-**Single-reference-point invariant**: Python dispatch 함수가 존재하지 않으므로 분기 가능성 자체가 없다. 모든 entry point (CLI / skill / interactive) 가 동일한 `task-manifest.json` 의 `convergence.planBodyVerification` 블록을 읽고, 동일한 `okstra-convergence` SKILL.md "Plan-body verification mode" 명세를 따라 lead 가 수행한다. 메모리상의 `prepare_task_bundle` 수렴 invariant 는 manifest 생성 시점에서만 의미를 가지며, 이는 §6.5 Phase B 에서 이미 완료됨.
-
-### 6.7 CLI 진입점 (single reference point 준수)
-세 진입점 모두 동일한 manifest write 경로(`prepare_task_bundle`)로 수렴해야 한다.
-
-- `scripts/okstra.sh` — `--no-plan-verification` 플래그 추가 (boolean off)
-- `scripts/lib/okstra-ctl/` Bash 라우팅 — flag → CLI args 통과만 (business logic 없음)
-- `bin/okstra` (Node CLI) — `setup` / `config set` 경로에서 `plan-verification` 키 지원
-- `okstra config set plan-verification <on|off> [--scope project|global]` 명령 추가 (기존 `pr-template-path` 패턴 답습)
-
-flag 우선순위: 명령행 `--no-plan-verification` > 프로젝트 config (`project.json` `planVerification`) > 글로벌 config (`~/.okstra/config.json` `planVerification`) > 기본값 ON.
-
-### 6.8 인터랙티브 skill 진입점
-`skills/okstra-run/SKILL.md` 의 Step 6 (worker / option 선택) 에 다음 질문 추가:
-
-> "implementation-planning 의 plan-body 검증 라운드를 활성화할까요? (default: yes — 합성된 plan을 워커가 peer-review)"
-
-`AskUserQuestion` 의 옵션은 yes / no 단일 선택. 사용자 선택은 manifest의 `plan_body_verification.enabled` 로 기록.
-
-## 7. plan-body 모드 reverify prompt 템플릿 (lightweight 만 지원)
-
-`full-reanalysis` 모드는 plan-body에 대해서는 의미가 약함(원본은 워커 자신의 분석 + lead 합성 결과이므로 "원본 재검토"의 정의가 모호). 따라서 plan-body 모드는 lightweight만 지원하고 manifest의 `verificationMode` 와는 독립적으로 동작한다.
-
-```
-You are <worker-role> performing plan-body verification for <task-key> (round 1).
-
-## Instructions
-
-Review the following items extracted from the consolidated implementation plan
-authored after your initial analysis. For EACH item, respond with exactly one verdict:
-
-- **AGREE**: The item is executable as written and internally consistent with
-  other items in the plan.
-- **DISAGREE**: The item is broken. Cite which kind of breakage:
-  (a) referenced file path / symbol mismatches another step or option,
-  (b) command is not executable or is ambiguous,
-  (c) validation signal is not observable,
-  (d) rollback violates commit / dependency order,
-  (e) item contradicts the trade-off matrix.
-- **SUPPLEMENT**: The item is sound but a dependency / edge case / precondition
-  is missing.
-
-Do NOT re-analyze the original requirements. Judge solely from plan internal
-consistency and stated commands / paths.
-
-## Plan items to verify
-
-### P-Step-3 [TICKETID: <id>]: <one-line summary>
-**From section**: 4.5.4 Stepwise Execution Order
-**Original text**:
-> <verbatim quote of the step>
-
-**Check**:
- - Are referenced file paths consistent with the option's File Structure list?
- - Is the named command executable as written?
- - Does the success criterion produce an observable signal?
-
-### P-Opt-2 [TICKETID: <id>]: <one-line summary>
-...
-
-## Response format
-
-### P-Step-3
-**Verdict**: AGREE | DISAGREE(<a|b|c|d|e>) | SUPPLEMENT
-**Explanation**: <2-3 sentences>
-
-### P-Opt-2
-...
-```
-
-## 8. 마이그레이션 / 호환성
-
-- **신규 task-key**: manifest에 plan_body_verification 기본값 ON으로 기록. 정상 동작.
-- **legacy task-key** (이미 implementation-planning을 한 번 돌렸으나 implementation으로 넘어가지 않은 task-key): manifest에 `plan_body_verification` 키 없음.
-  - resume 시 lead가 기본값 ON으로 채워 1라운드 dispatch를 추가 실행한다.
-  - **사용자 영향**: 기존 IP 산출물이 있어도 resume 시 한 라운드가 추가됨. 원치 않는 경우 resume 명령에 `--no-plan-verification`을 명시하거나 project config로 영구 off.
-  - 이 동작은 `CHANGES.md` 의 `사용자 영향:` 라인에 명시한다.
-
-## 9. 검증 가능성 / 테스트 포인트
-
-1. **manifest 기본값 / override**: `plan_body_verification` 키 누락 시 기본값 주입, `--no-plan-verification` 명령행 옵션 우선순위 (unit).
-2. **plan-item 파서**: §3 분리 규칙대로 P-Opt / P-Step / P-Dep / P-Val / P-Rb 가 추출되는지, Ticket ID 태그 보존 (unit).
-3. **verdict aggregation**: §5 매핑 4가지 케이스 모두 (unit).
-4. **majority DISAGREE → clarification row 변환** round-trip: P-* item → `## 5. Clarification Items` row(`Blocks=approval`) → `--resume-clarification` 흐름에서 사용자 응답이 다음 run에 carry-in (unit + e2e).
-5. **Approval 체크박스 라인 조건부 렌더**: gate 결과 4가지에 따라 라인 존재/부재 (unit + validator).
-6. **e2e 시나리오**: 의도적으로 깨진 plan(예: step의 file path가 option의 File Structure와 불일치)을 inject한 task를 돌려, DISAGREE 발생 → clarification 자동 추가 → resume 후 통과까지의 full happy path (e2e).
-7. **워커 non-result**: 모든 워커가 timeout / error 일 때 `aborted-non-result` 분류 + Approval 라인 부재 + clarification에 "could not run" row (unit).
-
-## 10. 위험 / 미해결 항목
-
-1. **report-writer 재호출 안 함** (Q4=b) 으로 인해, majority DISAGREE → clarification 변환 누락이 발생하면 사용자에게 dead-end(Approval 라인은 사라졌는데 무엇을 고쳐야 하는지 안 보이는 상태) 가 노출된다. 변환 round-trip 단위 테스트를 BLOCKING으로 잠근다.
-
-2. **convergence 스킬 안에 mode 두 개 공존** (finding / plan-body). 본문 첫 줄에 MUTUAL EXCLUSION 박스를 두고 future Claude 가 두 큐를 섞지 않도록 명시.
-
-3. **maxRounds=1의 `contested` 정의**: 기존 finding convergence의 `contested`는 maxRounds 도달 시점의 잔류 큐에 부여되는 라벨. plan-body 모드에서 maxRounds=1 인 경우 round 1 종료 직후의 partial-consensus와 사실상 구별 불가. §5 표에서 `contested → partial-consensus 로 fold-in` 으로 명시했지만, 사용자가 manifest 에서 maxRounds=2,3 으로 override 한 경우엔 finding 모드와 동일한 정의가 살아남는다는 점을 스킬 본문에 명시 필요.
-
-4. **plan-item 파서의 robustness**: report-writer 가 markdown 구조를 약간 다르게 작성할 가능성(예: option 헤더 들여쓰기 깊이). 파서는 `## 4.5`, `### 4.5.x` 헤더 + `Stepwise Execution Order` substring 같은 anchored 검색을 사용하고, 추출 실패 시 `aborted-non-result` 와 동등하게 처리한다.
-
-5. **CLI flag 단일 진입점**: 메모리상의 invariant(`prepare_task_bundle` 단일 수렴) 를 유지해야 함. flag → manifest 의 변환은 Python 측 한 곳에서만 수행되도록 분기 막기.
-
-## 11. 후속 작업 (out of scope)
-
-- error-analysis 결과물 (cause analysis 통합본) 에도 유사한 검증 라운드를 추가할지 여부 — 본 spec 범위 밖. plan-body 검증이 안정화된 후 별도 spec으로 검토.
-- requirements-discovery 의 routing decision 자체에 대한 검증 라운드 — 동일하게 후속 검토 대상.

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

@@ -1,383 +0,0 @@
-# Final Report Language Configuration — Design Spec
-
-- Date: 2026-05-20
-- Status: Approved (pending writing-plans)
-- Owner: Claude lead (this session)
-- Related: `templates/reports/final-report.template.md`, `scripts/okstra-render-final-report.py`, `skills/okstra-setup/SKILL.md`, `skills/okstra-report-writer/SKILL.md`, `agents/SKILL.md`
-
-## 1. Problem
-
-The okstra final report is currently hardcoded to Korean in three places:
-
-1. `skills/okstra-report-writer/SKILL.md` Writing Guidelines — `Write the final report body in Korean.`
-2. `templates/reports/final-report.template.md` — ~30–40 lines of Korean fixed text (section intros, empty-state lines, column headers, token-summary "읽는 법" block, release-handoff 4.6.x labels, etc.).
-3. `agents/SKILL.md` line 322 — lead's post-persistence reply hardcoded to Korean.
-
-There is no way to opt into English (or any other language) without manually patching skill / template files. The user request: add a setup step that selects the final-report language, defaulting to English.
-
-## 2. Goals & non-goals
-
-### Goals
-
-- One project-level setting (`reportLanguage`) decides the language of (a) the prose authored by the report-writer worker and (b) the fixed labels rendered from the template.
-- Default for **new** setups is English. Default for **existing** projects whose `project.json` predates this change is `auto` (no surprise switch to English for Korean-speaking users).
-- `auto` resolves to `en` or `ko` based on the task brief's main prose language.
-- Validator-checked English identifiers (`Option Candidates`, `Verdict Token`, `accepted` / `conditional-accept` / `blocked`, etc.) remain English in both languages.
-
-### Non-goals (this spec)
-
-- Worker analysis prose, lead user-facing messages outside the final-report flow, `okstra-status` / `okstra-schedule` skill responses, and `prompts/profiles/*.md` Korean preferences are **out of scope**.
-- Languages other than `en` and `ko`. (Adding a third language later requires only a new `i18n/<lang>.yaml` file plus extending the enum.)
-- Worker-results audit files under `runs/.../worker-results/*.md` stay in their current language (Korean prose by default).
-
-## 3. Data model
-
-### 3.1 `project.json` — new optional field
-
-```json
-{
-  "projectId": "...",
-  "projectRoot": "...",
-  "reportLanguage": "auto" | "en" | "ko"
-}
-```
-
-- Listed as a user-managed field in `scripts/okstra_project/resolver.py` so runtime `upsert_project_json` preserves it across `okstra setup` / `okstra run` invocations (same treatment as `worktreeSyncDirs`, `qaCommands`, `prTemplatePath`).
-- Absent field ⇒ runtime treats as `"auto"`.
-
-### 3.2 `~/.okstra/config.json` — optional global fallback
-
-```json
-{ "reportLanguage": "auto" | "en" | "ko" }
-```
-
-Same enum, used only when `project.json` doesn't have the field.
-
-### 3.3 `final-report-v1.0.schema.json` — audit field
-
-Add required `meta.reportLanguage` ∈ `{"en", "ko"}` (no `"auto"` — the lead resolves before dispatching).
-
-Rationale: the renderer needs an SSOT inside the data.json so re-rendering after the fact (e.g. someone re-runs `okstra-render-final-report.py` without a `--report-language` flag) produces the same artifact.
-
-### 3.4 Resolution priority (lead)
-
-```
-CLI flag `--report-language`
-  > project.json.reportLanguage
-  > ~/.okstra/config.json.reportLanguage
-  > "auto"
-```
-
-If the resolved value is `"auto"`, the lead inspects the task brief and picks `en` or `ko` based on its main prose language. Default to `en` when the brief is mostly code/identifiers and the language is ambiguous. The lead writes the resolved literal `en`/`ko` into the report-writer dispatch prompt's `**Report Language:**` line and into `data.json.meta.reportLanguage`.
-
-## 4. Setup flow
-
-### 4.1 `skills/okstra-setup/SKILL.md` — add Step 4.9
-
-Insert between current Step 4.8 (PR body template) and Step 5 (`okstra doctor`).
-
-```
-## Step 4.9 (optional): choose final report language
-
-Skip-friendly. Default behaviour when this step is skipped is `auto`
-(report-writer infers from the task brief, falling back to English).
-
-AskUserQuestion (fixed options):
-- Question: "Final report를 어느 언어로 작성할까요?"
-- Options:
-  1. English (recommended) → reportLanguage: "en"
-  2. 한국어               → reportLanguage: "ko"
-  3. Auto (task brief 언어로 추론, 불분명하면 영어) → reportLanguage: "auto"
-
-After selection:
-  okstra config set report-language <en|ko|auto> --scope project
-```
-
-Project scope only at this step. Global scope is mentioned in README but not prompted during setup (advanced).
-
-### 4.2 New CLI subcommands
-
-Same handler pattern as the existing `okstra config set pr-template-path`:
-
-```bash
-okstra config set report-language <en|ko|auto> --scope <project|global>
-okstra config get report-language --scope <project|global>
-```
-
-Validation:
-- Value must be one of `en`, `ko`, `auto`. Any other value exits `1` with a clear error.
-- `--scope` is required and must be `project` or `global`.
-- Atomic write (`config-write` path used by `pr-template-path`).
-- Output: JSON to stdout naming which file was updated, same shape as the existing `pr-template-path` command.
-
-Confirm during implementation that `okstra config get` already exists for `pr-template-path`; if not, extend it to support both keys.
-
-## 5. Template i18n
-
-### 5.1 Dictionary location
-
-```
-templates/reports/i18n/en.yaml
-templates/reports/i18n/ko.yaml
-```
-
-YAML chosen because the Korean help text (e.g. the "읽는 법" block) is multi-line and benefits from `|` literal blocks; JSON would require escaped `\n` everywhere. If PyYAML is not already a runtime dependency of okstra Python (to be confirmed during implementation), fall back to JSON with `\n` escapes.
-
-### 5.2 Key naming
-
-Dot-namespaced groups. Jinja accesses via `t.section.subkey`.
-
-```yaml
-verdictCard:
-  intro: >-
-    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`.
-
-tokenSummary:
-  heading: "Token Usage Summary"
-  columns:
-    item: "Item"
-    raw: "Raw tokens"
-    billable: "Billable tokens (input-equiv.)"
-    cost: "Cost (USD)"
-  rows:
-    lead: "Lead"
-    workerTotal: "Worker subtotal"
-    grandTotal: "**Grand total**"
-    cliExtra: "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 …
-
-emptyState:
-  consensusItems: "- No consensus items."
-  contestedItems: "- No items missing consensus."
-  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."
-  noFollowUp: "- No follow-up tasks. The next phase for this run is in §6 (Recommended Next Steps)."
-  noClarification: "- No additional information requested. The Section 2 verdict stands as-is."
-
-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"
-
-# ... and similar groups for release-handoff 4.6.x, evidence column
-# headers, etc.
-```
-
-The `ko.yaml` mirror keeps Korean strings; **both files must have identical key sets** (enforced by a unit test — see §8).
-
-### 5.3 Validator-checked English substrings
-
-These remain English in both `en.yaml` and `ko.yaml` (i.e. `sectionAside.optionCandidates` in `ko.yaml` is still the English string `Option Candidates`):
-
-- Phase-specific heading anchors: `Option Candidates`, `Trade-off`, `Recommended Option`, `Stepwise Execution Order`, `Dependency`, `Validation Checklist`, `Rollback`, `User Approval Request`, `Plan Body Verification`, `Gate result:`
-- Verdict tokens: `accepted`, `conditional-accept`, `blocked`, `not-applicable`
-- Direction tokens: `continue-investigation`, `begin-implementation`, `approve`, `reject`, `hold`
-
-Korean parenthetical aside is i18n'd. For Korean reports this renders as `### Recommended Option (권장 옵션)`; for English reports it renders as `### Recommended Option (Recommended Option)` — which looks silly. **Decision:** when Korean and English would produce the same string, the template omits the parenthetical entirely. Template form:
-
-```jinja
-### Recommended Option{% if t.sectionAside.recommendedOption != "Recommended Option" %} ({{ t.sectionAside.recommendedOption }}){% endif %}
-```
-
-### 5.4 Missing-key policy
-
-Jinja `Environment(undefined=StrictUndefined)` — referencing a missing key raises `UndefinedError` at render time. No silent fallback to the key name. This makes "I forgot to translate X" fail loudly during e2e instead of shipping `{{ t.foo.bar }}` literal in production reports.
-
-### 5.5 Template conversion scope
-
-Run `grep -P '[\x{AC00}-\x{D7A3}]'` (Korean Unicode range) against `templates/reports/final-report.template.md` until 0 matches remain. Estimated 50–70 i18n keys across the categories:
-
-1. Section intro prose (lines 35, 49, 54, 84, 131, 243, 275, 525)
-2. Empty-state lines (lines 122, 136, 162, 176, 188, 248, 299, 424, 449, 495, 527, 530, 570)
-3. Column headers (line 56 "한 줄 요약 / 출처", line 86 "처리 토큰 / 환산 토큰 / 비용", line 267 "확인 방법")
-4. Heading Korean aside (lines 245, 257, 273, the 4.5.x series)
-5. The token-summary "읽는 법" blockquote
-6. release-handoff 4.6.x Korean labels (lines 325, 329, 448, 473, etc.)
-
-Identifier strings (`Verdict Token`, JSON code blocks, model names, file paths) stay verbatim.
-
-## 6. Renderer changes
-
-### 6.1 `scripts/okstra-render-final-report.py`
-
-```python
-import argparse, json, yaml
-from pathlib import Path
-import jinja2
-
-def main():
-    ap = argparse.ArgumentParser()
-    ap.add_argument("data_json", type=Path)
-    ap.add_argument("--report-language", choices=["en", "ko"], default=None)
-    args = ap.parse_args()
-
-    data = json.loads(args.data_json.read_text())
-    lang = (
-        args.report_language
-        or data.get("meta", {}).get("reportLanguage")
-        or "en"
-    )
-    if lang not in {"en", "ko"}:
-        raise SystemExit(f"reportLanguage must be 'en' or 'ko', got {lang!r}")
-
-    i18n_path = Path(__file__).parent.parent / "templates" / "reports" / "i18n" / f"{lang}.yaml"
-    i18n = yaml.safe_load(i18n_path.read_text())
-
-    env = jinja2.Environment(
-        loader=jinja2.FileSystemLoader(...),
-        undefined=jinja2.StrictUndefined,
-        autoescape=False,
-        keep_trailing_newline=True,
-    )
-    tmpl = env.get_template("final-report.template.md")
-    out_path = args.data_json.with_suffix("").with_suffix(".md")
-    out_path.write_text(tmpl.render(**data, t=i18n))
-```
-
-(Sketch — actual file structure follows the existing renderer's conventions; the changes are: `--report-language` flag, `meta.reportLanguage` read, YAML loader, `t=i18n` context key, `StrictUndefined`.)
-
-### 6.2 `scripts/okstra-render-report-views.py`
-
-Reads the rendered markdown — no logic change needed. The HTML view inherits whatever language the markdown was rendered in.
-
-## 7. Worker / lead contract changes
-
-### 7.1 `agents/SKILL.md` (Claude lead)
-
-Add to the Phase 6 preparation checklist:
-
-```
-- 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`/`ko` value as
-  `**Report Language:**` in the report-writer dispatch prompt and ensure
-  the worker writes the same value into `data.json.meta.reportLanguage`.
-```
-
-Replace line 322:
-
-```diff
-- After persistence, reply briefly in Korean with: completion status, ...
-+ After persistence, reply briefly in the resolved Report Language with:
-+  completion status, ...
-```
-
-### 7.2 `skills/okstra-report-writer/SKILL.md`
-
-Add a new entry to the Phase 6 dispatch prompt's required-header list. The list currently has 11 items; insert the new entry immediately after the convergence-classifications item (current item 9) and renumber the remaining items:
-
-```
-**Report Language:** <en|ko>   # auto must be pre-resolved by the lead;
-                               # the worker writes this verbatim into
-                               # data.json.meta.reportLanguage
-```
-
-Replace the two hardcoded "Korean" lines (Writing Guidelines + Response after Persistence):
-
-```diff
-- - Write the final report body in Korean.
-+ - Write the final report body in the language passed as **Report Language**
-+   in the dispatch prompt. The template's fixed labels (section asides,
-+   empty-states, token summary, etc.) are i18n-rendered by
-+   `okstra-render-final-report.py` from `templates/reports/i18n/<lang>.yaml`;
-+   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 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:
-```
-
-Add to the data.json contract (alongside the token-cell-null paragraph):
-
-```
-- Set `meta.reportLanguage` to the resolved `en` or `ko` value passed in
-  **Report Language**. `auto` is forbidden here — the lead has already
-  resolved it. The renderer reads this field as the SSOT when no CLI
-  `--report-language` flag is given.
-```
-
-### 7.3 `agents/workers/report-writer-worker.md`
-
-Add `templates/reports/i18n/en.yaml` and `templates/reports/i18n/ko.yaml` to the worker's reading set. One-line reminder that the `Report Language` header value goes into `data.json.meta.reportLanguage` verbatim.
-
-## 8. Tests
-
-### 8.1 Unit (`tests/`)
-
-- `test_report_language_resolver.py` — resolution priority (CLI flag > project.json > global config > `"auto"`).
-- `test_report_language_config_set.py` — `okstra config set report-language` accepts `en`/`ko`/`auto`, rejects others; writes to project.json or `~/.okstra/config.json` per scope.
-- `test_i18n_keysets_match.py` — `en.yaml` and `ko.yaml` have **identical key sets** (set diff must be empty in both directions).
-- `test_i18n_missing_key_raises.py` — referencing an undefined `t.foo.bar` from the template raises `jinja2.UndefinedError`.
-- `test_render_meta_report_language.py` — renderer reads `data.json.meta.reportLanguage` as SSOT when no `--report-language` flag is given.
-- `test_template_no_korean_glyphs.py` — `grep -P '[\x{AC00}-\x{D7A3}]'` against `templates/reports/final-report.template.md` returns zero matches. (Regression guard for "someone re-introduced Korean fixed text".)
-
-### 8.2 E2E (`tests-e2e/`)
-
-- `scenario-N-final-report-en.sh` — full okstra run with `reportLanguage: "en"`. Asserts the rendered markdown contains the English `Token Usage Summary` heading and does NOT contain Korean characters in template-owned regions.
-- `scenario-M-final-report-ko.sh` — same with `reportLanguage: "ko"`. Asserts the Korean `토큰 사용량 요약` heading is present.
-
-## 9. Migration / rollout
-
-- pre-v1 → no compat shims. Existing reports are not re-rendered.
-- Existing `project.json` files have no `reportLanguage` field → runtime treats as `"auto"`. Korean-speaking users writing Korean briefs continue to get Korean reports without any action.
-- New `okstra setup` runs see Step 4.9 with `English` as the recommended default — users explicitly opt into the new default through that prompt.
-- `CHANGES.md` entry:
-
-  ```
-  ### feat(setup): 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}.yaml`.
-  ```
-
-## 10. Files touched (final list)
-
-| File | Change |
-|---|---|
-| `templates/reports/final-report.template.md` | Korean fixed text → `{{ t.* }}` i18n references |
-| `templates/reports/i18n/en.yaml` | NEW |
-| `templates/reports/i18n/ko.yaml` | NEW |
-| `scripts/okstra-render-final-report.py` | `--report-language` flag, YAML loader, `StrictUndefined`, `t=i18n` |
-| `schemas/final-report-v1.0.schema.json` | Add required `meta.reportLanguage` ∈ `{en, ko}` |
-| `scripts/okstra_project/resolver.py` | `reportLanguage` added to preserved user fields list |
-| `src/config.mjs` (or wherever `pr-template-path` lives) | `set/get report-language` subcommands |
-| `skills/okstra-setup/SKILL.md` | Step 4.9 |
-| `skills/okstra-report-writer/SKILL.md` | Dispatch prompt header + Writing Guidelines + data.json contract |
-| `agents/SKILL.md` | Phase 6 prep checklist + line 322 |
-| `agents/workers/report-writer-worker.md` | Reading set + `meta.reportLanguage` reminder |
-| `tests/test_*.py` (6 new) | See §8.1 |
-| `tests-e2e/scenario-N-final-report-en.sh` | NEW |
-| `tests-e2e/scenario-M-final-report-ko.sh` | NEW |
-| `CHANGES.md` | New entry per §9 |
-
-## 11. Open implementation questions
-
-To be resolved during writing-plans / implementation:
-
-1. Whether PyYAML is already a runtime dependency of okstra Python (otherwise fall back to JSON dictionaries).
-2. Whether `okstra config get` exists today for `pr-template-path` — extend if yes, add if no.
-3. Exact i18n key namespacing for the release-handoff 4.6.x labels (largest single chunk of Korean text outside §4.5).
-4. Test scenario sequencing — pick free `scenario-NN` numbers in `tests-e2e/`.