okstra 0.34.0 → 0.36.0

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

@@ -0,0 +1,383 @@
+# 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/`.