okstra 0.122.0 → 0.124.0

package/runtime/skills/okstra-user-response/SKILL.md

@@ -18,7 +18,11 @@ Single entry point for answering the clarification questions an okstra run left
 
 ## Step 0: Preflight (shared)
 
-Before anything, run one Bash tool call whose leading token is the literal `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — a non-literal leading token defeats the `Bash(okstra:*)` permission match):
+Before anything:
+
+<!-- BEGIN FRAGMENT: bash-invocation-rule -->
+Run one Bash tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — a non-literal leading token defeats the `Bash(okstra:*)` permission match):
+<!-- END FRAGMENT: bash-invocation-rule -->
 
 ```bash
 okstra preflight --runtime claude-code --json
@@ -26,7 +30,11 @@ okstra preflight --runtime claude-code --json
 
 Branch on the stdout JSON:
 - `ok: true` → carry `projectRoot` and `projectId` as literal strings; they are the base for every step below.
-- `ok: false` → this project has no okstra setup. Tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop. If the user pointed at a specific project directory, re-run targeting it: `okstra preflight --runtime claude-code --cwd <that-dir> --json` (`--cwd` is the sanctioned way to target a project — a leading `cd` would break the permission match); only if that **also** returns `ok:false` do you stop. If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).
+- `ok: false` → this project has no okstra setup. Tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop. If the user pointed at a specific project directory, re-run targeting it: `okstra preflight --runtime claude-code --cwd <that-dir> --json` (`--cwd` is the sanctioned way to target a project — a leading `cd` would break the permission match); only if that **also** returns `ok:false` do you stop.
+
+<!-- BEGIN FRAGMENT: preflight-outdated-cli -->
+If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).
+<!-- END FRAGMENT: preflight-outdated-cli -->
 
 Then resolve the okstra home once (the `list` sub-command needs it):
 
@@ -34,7 +42,11 @@ Then resolve the okstra home once (the `list` sub-command needs it):
 okstra paths --field home
 ```
 
-Paste the printed path literally into `--home` below. Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
+Paste the printed path literally into `--home` below.
+
+<!-- BEGIN FRAGMENT: python-bootstrap-note -->
+Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
+<!-- END FRAGMENT: python-bootstrap-note -->
 
 ## Step 1: List awaiting tasks → picker
 
@@ -57,19 +69,21 @@ Carry the chosen entry's `reportPath` and `taskKey` forward.
 okstra user-response show --report <reportPath>
 ```
 
-Returns `{reportPath, rows: [{id, kind, blocks, status, statement, recommended, alternatives, contextRefs}]}`. For each open `C-*` row, present to the user:
+Returns `{reportPath, rows: [{id, kind, blocks, status, statement, recommended, alternatives, contextRefs, resolvedRefs}]}`. `resolvedRefs` is `[{ref, definition}]` — the CLI has already looked up what each internal token (`RB-002`, `FU-001`, `§4.7`, …) means in the report body; `definition` is `null` only when the report text alone could not resolve it (e.g. a `path:line` pointer).
+
+**Do NOT paste the raw `statement` as the question.** A `statement` like `Rewrite RB-002 rollback (see §4.7)` is meaningless to the user on its own — that is the whole reason this skill exists. For each open `C-*` row, you MUST present:
 
-- **`id`** and its **`statement`** (the original question).
-- **`recommended`** — the answer okstra proposed (+ rationale). It is only a recommendation.
-- **`alternatives[]`** — list them if present.
-- **`contextRefs[]`** — the report `§`/`C-id`/`path:line` references this question points at.
+- **A rewritten, self-contained question** (lead with this): rewrite `statement` in plain language with **every internal token expanded inline** from its `resolvedRefs` `definition` — the user must never have to know what `RB-002` is to answer. If a token's `definition` is `null`, resolve it yourself **using Read** on the report `§`/`path:line` before asking; only if it is genuinely unresolvable do you say so plainly.
+- **`recommended`** — the answer okstra proposed (+ rationale), also stated in plain language. It is only a recommendation.
+- **`alternatives[]`** — list them if present, each in plain language.
+- **Raw source** (secondary, for traceability): the raw `id` + `statement` so the mapping back to the report stays visible.
 
 ## Step 3: Per-item — collect the user's decision (4 branches)
 
 For each open item, the user picks one of four dispositions. You relay and transcribe; you never choose:
 
 1. **Answer** — the user accepts the recommendation or gives their own answer. `disposition: "answer"`, `value` = the user's utterance verbatim.
-2. **Ask-to-explain** — if the user asks "what does this mean?", open the report `§`/`path:line` that this item's `contextRefs[]` points at **using Read** and explain it in plain language. Only explain — **do not pick the answer for the user**; after explaining, hand the decision back to the user.
+2. **Ask-to-explain (fallback)** — Step 2 already expanded every internal token, so the question should already be self-contained. If the user still asks "what does this mean?" or a `resolvedRefs` `definition` was `null`, open the report `§`/`path:line` that this item's `contextRefs[]` points at **using Read** and explain it in plain language. Only explain — **do not pick the answer for the user**; after explaining, hand the decision back to the user.
 3. **Free-form** — the user gives a narrative answer that matches neither a recommendation nor an alternative. `value` = that narrative verbatim, with the rationale in `rationale` if needed. `disposition: "answer"`.
 4. **Hold + reframe** — if the user asks to "re-frame this question itself", record it as `disposition: "reframe"`. Put what the user wants re-asked into `value` verbatim. A reframe is not an answer, so it does not satisfy the approval gate — the next run re-frames that question.
 

package/runtime/templates/prd/brief.template.md

@@ -14,14 +14,14 @@ taskType: "{{FM_TASK_TYPE}}"
 # OKSTRA Task Brief
 
 <!--
-이 brief은 okstra 워커(Claude/Codex/Antigravity)가 코드베이스/도메인 사전지식 없이 분석할 수 있도록 준비하는 단일 source-of-truth 문서입니다.
-
-원칙:
-1. 워커는 외부 링크에 접근할 수 없음 → 모든 1차 증거는 inline으로 박을 것 (fenced code block).
-2. 워커는 도메인 용어를 모름 → Domain Glossary로 핵심 용어를 사전 정의.
-3. 운영자(operator)용 정보(okstra.sh 명령, working directory)는 brief에 두지 말 것 — 별도 runbook으로.
-4. Task Type에 따라 작성해야 할 섹션이 다름 → 해당 태스크의 conditional 블록을 채울 것.
-5. 비어 있는 섹션은 `_N/A — <reason>_`로 명시. 침묵은 워커 혼란의 원인.
+This brief is the single source-of-truth document that lets an okstra worker (Claude/Codex/Antigravity) analyze the task without any prior knowledge of the codebase or domain.
+
+Principles:
+1. Workers cannot reach external links → embed every piece of primary evidence inline (fenced code block).
+2. Workers don't know domain terms → predefine the key terms in the Domain Glossary.
+3. Keep operator-facing information (okstra.sh commands, working directory) out of the brief — put it in a separate runbook.
+4. The sections you must fill differ by Task Type → complete that task's conditional block.
+5. Mark empty sections explicitly with `_N/A — <reason>_`. Silence is a source of worker confusion.
 -->
 
 ## Identity
@@ -34,51 +34,51 @@ taskType: "{{FM_TASK_TYPE}}"
 | Task ID | `<TASK-ID>` |
 | Task Type | `requirements-discovery` \| `error-analysis` \| `implementation-planning` \| `final-verification` |
 | Issue / Ticket | `<TASK-ID> · <title in original language> (English: <translation if non-English>)` |
-| Requested Outcome | <한 문장. 이 run이 산출해야 할 핵심 결과물> |
+| Requested Outcome | <one sentence. The key deliverable this run must produce> |
 
 ---
 
 ## Request Summary
 
 - **What is being requested or changed?**
-  <한 문단 또는 bullet 3-5개>
+  <one paragraph, or 3-5 bullets>
 - **Why now?**
-  <비즈니스/기술 트리거. 마감일, 인시던트, 의존 태스크 등>
+  <business/technical trigger. Deadline, incident, dependent task, etc.>
 - **New / Continuation / Reopened?**
-  <One of the three + 직전 run 식별자(있다면)>
+  <One of the three + prior run identifier (if any)>
 - **What decision should this run produce?**
-  <이 run이 답해야 할 핵심 결정 1-3개. 모호하면 워커가 산만해짐>
+  <the 1-3 key decisions this run must answer. Vagueness distracts the worker>
 
 ---
 
 ## Inline Evidence
 
 <!--
-워커는 외부 URL/Notion/Linear/Slack에 접근할 수 없습니다. 1차 증거는 모두 여기에 inline 박을 것.
+Workers cannot reach external URLs / Notion / Linear / Slack. Embed all primary evidence inline here.
 -->
 
 ### Symptom / Sample Payload
 
 ```
-<관찰된 현상, 응답 페이로드 샘플, UI 스크린샷 caption 등 — 텍스트로>
+<observed symptom, sample response payload, UI screenshot caption, etc. — as text>
 ```
 
-### Logs / Stack Trace (해당되는 경우)
+### Logs / Stack Trace (if applicable)
 
 ```
-<로그 발췌. 민감정보는 마스킹>
+<log excerpt. Mask sensitive information>
 ```
 
 ### Relevant Code Excerpts
 
 ```typescript
 // path: src/domains/upload/dto/upload-job.view.ts:23-45
-<코드 발췌 — 워커가 파일 전체를 읽지 않아도 핵심을 파악할 수 있어야 함>
+<code excerpt — the worker should grasp the essentials without reading the whole file>
 ```
 
-### External Doc Excerpts (Notion/Linear/Confluence 발췌)
+### External Doc Excerpts (Notion/Linear/Confluence excerpts)
 
-> <원문 인용. 링크는 보조이고 인용이 본체>
+> <quote from the source. The link is secondary; the quote is the substance>
 > -- Source: <doc title + section>
 
 ---
@@ -86,27 +86,27 @@ taskType: "{{FM_TASK_TYPE}}"
 ## Domain Glossary
 
 <!--
-Codex/Antigravity는 이 코드베이스를 모릅니다. 핵심 용어 5-15개를 한 문장씩 정의.
-없는 용어를 워커가 추측하면 분석 품질이 즉시 떨어집니다.
+Codex/Antigravity don't know this codebase. Define 5-15 key terms, one sentence each.
+If a worker guesses at an undefined term, analysis quality drops immediately.
 -->
 
 | Term | Definition |
 |------|-----------|
-| `<도메인 용어 1>` | <1-2 문장 정의> |
-| `<도메인 용어 2>` | <1-2 문장 정의> |
-| `<코드 식별자 1>` | <역할 + 위치 + 다른 entity와의 관계> |
+| `<domain term 1>` | <1-2 sentence definition> |
+| `<domain term 2>` | <1-2 sentence definition> |
+| `<code identifier 1>` | <role + location + relationship to other entities> |
 
 ---
 
 ## Current Context
 
 - **Current behavior or state**:
-  <지금 시스템이 어떻게 동작하는가>
+  <how the system behaves today>
 - **Desired behavior or outcome**:
-  <어떻게 동작해야 하는가>
+  <how it should behave>
 - **Existing related implementation**:
-  - `<file-path>:<line-range>` — <역할 한 줄>
-- **Related code paths** (참조용 — 직접 발췌는 Inline Evidence에):
+  - `<file-path>:<line-range>` — <one-line role>
+- **Related code paths** (for reference — put direct excerpts in Inline Evidence):
   - `<path>`
   - `<path>`
 
@@ -115,74 +115,74 @@ Codex/Antigravity는 이 코드베이스를 모릅니다. 핵심 용어 5-15개
 ## Out of Scope
 
 <!--
-명시적 제외 목록. 워커 scope-creep 방지의 핵심.
+An explicit exclusion list. Central to preventing worker scope-creep.
 -->
 
-이 run에서는 **다루지 않을** 것들:
+Things this run will **not** address:
 
-- <out-of-scope item 1 + 제외 이유>
-- <out-of-scope item 2 + 제외 이유>
-- <별도 ticket/run으로 다룰 항목 — ticket ID 명시>
+- <out-of-scope item 1 + reason for exclusion>
+- <out-of-scope item 2 + reason for exclusion>
+- <item to be handled in a separate ticket/run — specify the ticket ID>
 
 ---
 
 ## Task-Type Focus
 
 <!--
-아래 두 블록 중 현재 task-type에 해당하는 것만 채우고, 나머지는 삭제하세요.
+Of the two blocks below, fill only the one matching the current task-type and delete the rest.
 -->
 
 ### If `requirements-discovery`
 
 - **Why might this be a bugfix?**
-  <증거 또는 "weak signal — none observed">
+  <evidence, or "weak signal — none observed">
 - **Why might this be a feature/improvement?**
-  <증거>
+  <evidence>
 - **Why might this be a refactor/ops?**
-  <증거>
-- **Classification blockers** — 무엇이 분류 확신을 막고 있는가?
-  <evidence gap을 구체적으로>
+  <evidence>
+- **Classification blockers** — what is preventing a confident classification?
+  <the evidence gap, specifically>
 
 ### If `error-analysis`
 
-- **Symptom** — 사용자/시스템이 무엇을 관찰하는가?
-- **Reproduction Steps** — 1-2-3 형식. 환경/사전조건 명시.
+- **Symptom** — what does the user/system observe?
+- **Reproduction Steps** — 1-2-3 format. State the environment/preconditions.
   ```
   1. <env: staging | local | prod>
   2. <action>
   3. <action>
   4. Expected: <…> / Actual: <…>
   ```
-- **Frequency** — 항상 / 간헐적 / 특정 조건에서만 / 1회성?
-- **Blast Radius** — 영향받는 사용자/요청/data 범위
-- **Suspected Cause(s)** — 현재까지의 가설. 각각 신뢰도(High/Med/Low)와 근거.
-- **What has been ruled out** — 이미 검증한 false leads (워커가 같은 길 가지 않게)
+- **Frequency** — always / intermittent / only under specific conditions / one-off?
+- **Blast Radius** — scope of affected users/requests/data
+- **Suspected Cause(s)** — hypotheses so far. Each with confidence (High/Med/Low) and rationale.
+- **What has been ruled out** — false leads already verified (so the worker doesn't retread them)
 
 ---
 
 ## Constraints and Risks
 
-- **Business constraints**: <e.g. 개인정보, SLA — 외부 승인/권한 항목은 적지 말 것 (사용자가 모든 권한을 가진다고 가정)>
-- **Technical constraints**: <e.g. backward-compat, 기존 client, schema>
-- **Delivery constraints**: <마감, 의존 배포, 롤아웃 게이트 — 단, 외부 승인 대기·권한 확인은 일정 요소로 적지 말 것>
-- **Approval / review checkpoints**: _N/A — 사용자가 모든 권한·승인 권한을 보유한다고 가정 (okstra 기본 규칙). 정말로 외부 차단 요소가 있을 때만 구체적으로 기술._
-- **Known assumptions**: <명시적 가정 — 워커가 검증할 항목>
-- **Open uncertainties**: <확인 필요한 것 — 답이 나오면 결정이 잠금 해제됨. 외부 권한·승인 관련 항목은 제외>
+- **Business constraints**: <e.g. PII, SLA — do not list external approval/authorization items (assume the user holds all permissions)>
+- **Technical constraints**: <e.g. backward-compat, existing client, schema>
+- **Delivery constraints**: <deadline, dependent deployment, rollout gate — but do not list waiting on external approval or permission checks as schedule factors>
+- **Approval / review checkpoints**: _N/A — assume the user holds all permission and approval authority (okstra default rule). Describe specifically only when a genuine external blocker exists._
+- **Known assumptions**: <explicit assumptions — items for the worker to verify>
+- **Open uncertainties**: <things to confirm — answering them unlocks a decision. Exclude external permission/approval items>
 
 ---
 
 ## Configuration / Deployment Context
 
 <!--
-이 섹션은 *해당되는 경우에만* 채우세요. DTO 변경, 순수 로직 수정, 문서 작업 등은 보통 _N/A_입니다.
-무관할 때는 본 섹션 전체를 다음 한 줄로 대체:
+Fill this section *only when applicable*. DTO changes, pure logic edits, docs work, etc. are usually _N/A_.
+When irrelevant, replace the entire section with this single line:
 
   _N/A — this task does not touch config or deployment._
 -->
 
-- **Config files in scope**: `<path>` — <어떤 키가 관련>
-- **Current observed values**: <key=value, 출처 명시>
-- **Expected values / invariants**: <변하면 안 되는 것 + 변해야 하는 것>
+- **Config files in scope**: `<path>` — <which keys are relevant>
+- **Current observed values**: <key=value, cite the source>
+- **Expected values / invariants**: <what must not change + what must change>
 - **Deployment manifests in scope**: `<helm chart / k8s manifest / terraform path>`
 - **Rollout invariants**: <e.g. zero-downtime, version skew window>
 
@@ -191,45 +191,45 @@ Codex/Antigravity는 이 코드베이스를 모릅니다. 핵심 용어 5-15개
 ## External Resource Hints (for Lead pre-fetch)
 
 <!--
-okstra Lead가 워커 프롬프트에 inline으로 박아야 할 외부 자원 목록.
-워커는 MCP/외부 도구에 직접 접근하지 않으므로 Lead가 사전에 snapshot해서 prompt에 embed합니다.
+A list of external resources the okstra Lead must embed inline into the worker prompt.
+Workers don't access MCP/external tools directly, so the Lead snapshots them ahead of time and embeds them in the prompt.
 -->
 
 | Resource | Type | Why needed |
 |----------|------|-----------|
-| `<table-name>` | MySQL schema | <어느 분석에서 schema 검증 필요> |
-| `<library@version>` | Library docs (`mcp__test-context7`) | <API 시그니처 확인용> |
-| `<aws-doc-keyword>` | AWS knowledge base | <설계 검증용> |
+| `<table-name>` | MySQL schema | <which analysis needs schema verification> |
+| `<library@version>` | Library docs (`mcp__test-context7`) | <to confirm API signatures> |
+| `<aws-doc-keyword>` | AWS knowledge base | <for design verification> |
 | `/Volumes/.../app/<sibling-project>/<path>` | Cross-project file | <reference impl> |
 
-자원 없음이 명확하면 본 섹션을 `_N/A_`로 표시.
+If it's clear there are no resources, mark this section `_N/A_`.
 
 ---
 
 ## Related Tasks
 
 <!--
-관계 라벨을 반드시 명시: blocker | blocked-by | sibling | follow-up | duplicate | shares-codepath
+You must specify a relation label: blocker | blocked-by | sibling | follow-up | duplicate | shares-codepath
 -->
 
 | Task | Relation | Note |
 |------|----------|------|
-| `DEV-XXXX` | `sibling` | 같은 epic, 같은 코드베이스, 동시 변경 가능성 |
-| `DEV-YYYY` | `blocker` | 이 task는 DEV-YYYY 완료 후에만 시작 가능 |
+| `DEV-XXXX` | `sibling` | same epic, same codebase, possible concurrent changes |
+| `DEV-YYYY` | `blocker` | this task can start only after DEV-YYYY completes |
 
 ---
 
 ## Definition of Done (for this run)
 
 <!--
-Requested Outcome은 큰 그림. 여기서는 "이 run의 산출물이 충족해야 할 검증 가능한 조건"을 적습니다.
+Requested Outcome is the big picture. Here you write "the verifiable conditions this run's output must satisfy."
 -->
 
-이 run의 final report는 다음을 모두 충족해야 합니다:
+This run's final report must satisfy all of the following:
 
-- [ ] <결정 항목 1에 대한 명시적 답변 또는 "결정 불가 + 이유">
-- [ ] <결정 항목 2에 대한 명시적 답변>
-- [ ] <남은 blocking question 목록>
+- [ ] <explicit answer to decision item 1, or "undecidable + reason">
+- [ ] <explicit answer to decision item 2>
+- [ ] <list of remaining blocking questions>
 - [ ] <recommended next phase + reasoning>
 
 ---
@@ -237,13 +237,13 @@ Requested Outcome은 큰 그림. 여기서는 "이 run의 산출물이 충족해
 ## Questions for Workers
 
 <!--
-P0(반드시 답해야 함) / P1(가능하면 답) / P2(보너스)로 우선순위 명시.
+Specify priority as P0 (must answer) / P1 (answer if possible) / P2 (bonus).
 -->
 
-1. **[P0]** <핵심 질문 1>
-2. **[P0]** <핵심 질문 2>
-3. **[P1]** <보조 질문>
-4. **[P2]** <탐색적 질문>
+1. **[P0]** <key question 1>
+2. **[P0]** <key question 2>
+3. **[P1]** <secondary question>
+4. **[P2]** <exploratory question>
 
 ---
 
@@ -261,26 +261,26 @@ P0(반드시 답해야 함) / P1(가능하면 답) / P2(보너스)로 우선순
 ## Notes for Lead (synthesis emphasis)
 
 <!--
-워커 셀렉션(어느 모델을 쓸지)은 task-manifest.json의 recommendedWorkers에서 자동 결정되므로 여기에 적지 마세요.
-이 섹션은 *합성 시 강조점*만 다룹니다.
+Worker selection (which model to use) is decided automatically from recommendedWorkers in task-manifest.json, so don't write it here.
+This section covers *synthesis emphasis* only.
 -->
 
-- **Synthesis priority**: <e.g. 안전성 vs 속도, public/private 경계 정확성, backward compat>
-- **Where worker disagreement matters most**: <consensus가 가장 중요한 지점>
-- **Where reduced confidence is acceptable**: <탐색 영역 — 가설만 나와도 충분>
+- **Synthesis priority**: <e.g. safety vs speed, public/private boundary accuracy, backward compat>
+- **Where worker disagreement matters most**: <the point where consensus matters most>
+- **Where reduced confidence is acceptable**: <exploratory areas — a hypothesis alone is enough>
 
 ---
 
 ## Brief Hygiene Checklist
 
-작성 후 자가 점검:
-
-- [ ] 모든 외부 링크에 대해 inline 발췌가 박혀 있다
-- [ ] Domain Glossary에 코드베이스 무지식 워커가 알아야 할 용어가 모두 있다
-- [ ] Out of Scope가 명시적으로 적혀 있다
-- [ ] Task-Type Focus의 해당 블록만 남아 있다 (다른 블록은 삭제됨)
-- [ ] error-analysis라면 Reproduction Steps가 채워져 있다
-- [ ] Definition of Done이 검증 가능한 체크리스트 형태다
-- [ ] Configuration / Deployment 섹션은 해당 시에만 내용이 있고, 무관 시 `_N/A_`로 닫혀 있다
-- [ ] 한글/영문/원어 ticket title 모두 식별 가능하다
-- [ ] Related Tasks에 관계 라벨이 명시되어 있다
+Self-check after writing:
+
+- [ ] Every external link has an inline excerpt embedded
+- [ ] The Domain Glossary has every term a codebase-blind worker needs to know
+- [ ] Out of Scope is written explicitly
+- [ ] Only the relevant block of Task-Type Focus remains (the other block is deleted)
+- [ ] If error-analysis, Reproduction Steps are filled in
+- [ ] Definition of Done is a verifiable checklist
+- [ ] The Configuration / Deployment section has content only when applicable, and is closed with `_N/A_` when irrelevant
+- [ ] The ticket title is identifiable in Korean/English/original language
+- [ ] Related Tasks have relation labels specified

package/runtime/templates/reports/error-analysis-input.template.md

@@ -20,7 +20,7 @@ taskType: "{{FM_TASK_TYPE}}"
 - Task ID:
 - Related Tasks:
 - Issue / Ticket:
-  - 값이 비면 워커는 `Task ID`로 폴백한다 (prefix 없이 `8852`처럼). 한 run이 여러 ticket을 동시에 다루면 콤마로 구분 (`TICKET-123, TICKET-456`). 어느 쪽으로도 식별 불가하면 `unknown`을 허용한다.
+  - If left empty, workers fall back to the `Task ID` (without a prefix, like `8852`). When a single run handles multiple tickets at once, separate them with commas (`TICKET-123, TICKET-456`). If neither can be identified, `unknown` is allowed.
 - Task Type: `error-analysis`
 - Requested Outcome:
 

package/runtime/templates/reports/fan-out-unit.template.md

@@ -2,24 +2,24 @@
 ---
 unit-id: {{UNIT_ID}}
 domain: {{DOMAIN}}
-<!-- depends-on 예: [unit-001] (의존 없으면 []) -->
+<!-- depends-on example: [unit-001] (use [] if there are no dependencies) -->
 depends-on: {{DEPENDS_ON}}
 recommended-next-phase: {{NEXT_PHASE}}
 ---
 
 # Fan-out Unit: {{UNIT_ID}} ({{DOMAIN}})
 
-> requirements-discovery fan-out 산출 packet. `okstra-run --task-brief <이 파일 경로>`
-> 로 새 task-key 를 시작한다. 이 파일은 그 run 의 입력 packet 이다.
+> Packet produced by requirements-discovery fan-out. Start a new task-key with `okstra-run --task-brief <this file's path>`.
+> This file is the input packet for that run.
 
 ## Scope
 
-<!-- 이 단위가 다루는 작업 항목 1개를 자족적으로 서술. 다른 단위와 섞지 말 것. -->
+<!-- Self-contained description of the single work item this unit covers. Do not mix it with other units. -->
 
 ## Evidence
 
-<!-- path:line 근거. requirements-discovery 가 file inspection 으로 확인한 위치. -->
+<!-- path:line evidence. Locations that requirements-discovery confirmed via file inspection. -->
 
 ## Depends-on rationale
 
-<!-- depends-on 에 적은 각 unit 에 왜 의존하는지 1줄씩. 없으면 _(none)_ -->
+<!-- One line per unit listed in depends-on explaining why it depends on that unit. Use _(none)_ if there are none. -->

package/runtime/templates/reports/final-report.template.md

@@ -387,6 +387,73 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 {% endfor %}
 {%- endif %}
 
+### 5.5.10 Implementation Design Preparation{% if t("implementationPlanning.designPreparation.heading") != "Implementation Design Preparation" %} ({{ t("implementationPlanning.designPreparation.heading") }}){% endif %}
+
+- **{{ t("implementationPlanning.designPreparation.mode") }}:** `{{ implementationPlanning.designPreparation.mode }}`
+- **{{ t("implementationPlanning.designPreparation.reason") }}:** {{ implementationPlanning.designPreparation.reason }}
+
+{% if implementationPlanning.designPreparation["items"] | length == 0 -%}
+{{ t("implementationPlanning.designPreparation.empty") }}
+{%- else %}
+{% for item in implementationPlanning.designPreparation["items"] %}
+#### {{ item.id }} — {{ item.title }}
+
+- **{{ t("implementationPlanning.designPreparation.kind") }}:** `{{ item.kind }}`
+- **{{ t("implementationPlanning.designPreparation.status") }}:** `{{ item.status }}`
+- **{{ t("implementationPlanning.designPreparation.stages") }}:** {{ item.stageRefs | join(", ") }}
+- **{{ t("implementationPlanning.designPreparation.need") }}:** {{ item.need }}
+{% if item.knownFacts %}
+- **{{ t("implementationPlanning.designPreparation.knownFacts") }}:**
+{% for fact in item.knownFacts %}
+  - {{ fact.statement }} — {{ fact.evidence }}
+{% endfor %}
+{% endif %}
+{% if item.openQuestions %}
+- **{{ t("implementationPlanning.designPreparation.openQuestions") }}:** {{ item.openQuestions | join("; ") }}
+{% endif %}
+- **{{ t("implementationPlanning.designPreparation.aiProposal") }}:** {{ item.aiProposal.summary }}
+  - **{{ t("implementationPlanning.designPreparation.proposalDetails") }}:** {{ item.aiProposal.details | join("; ") or t("implementationPlanning.designPreparation.none") }}
+  - **{{ t("implementationPlanning.designPreparation.proposalAssumptions") }}:** {{ item.aiProposal.assumptions | join("; ") or t("implementationPlanning.designPreparation.none") }}
+  - **{{ t("implementationPlanning.designPreparation.proposalEvidence") }}:** {{ item.aiProposal.evidence | join("; ") or t("implementationPlanning.designPreparation.none") }}
+  - **{{ t("implementationPlanning.designPreparation.proposalConfidence") }}:** `{{ item.aiProposal.confidence }}`
+- **{{ t("implementationPlanning.designPreparation.humanConfirmation") }}:**
+  - **{{ t("implementationPlanning.designPreparation.confirmationRequired") }}:** `{% if item.humanConfirmation.required %}yes{% else %}no{% endif %}`
+  - **{{ t("implementationPlanning.designPreparation.confirmationReason") }}:** {{ item.humanConfirmation.reason }}
+  - **{{ t("implementationPlanning.designPreparation.suggestedAction") }}:** {{ item.humanConfirmation.suggestedAction }}
+{% if item.replanTriggerFields %}
+- **{{ t("implementationPlanning.designPreparation.replanTriggerFields") }}:** `{{ item.replanTriggerFields | join("`, `") }}`
+{% endif %}
+{% if item.workingAssumption %}
+- **{{ t("implementationPlanning.designPreparation.workingAssumption") }}:** {{ item.workingAssumption }}
+{% endif %}
+{% if item.guardrails %}
+- **{{ t("implementationPlanning.designPreparation.guardrails") }}:** {{ item.guardrails | join("; ") }}
+{% endif %}
+{% if item.reviewAt %}
+{% if item.reviewAt.stage %}
+- **{{ t("implementationPlanning.designPreparation.reviewAt") }}:** {{ item.reviewAt.phase }} — stage {{ item.reviewAt.stage }}
+{% else %}
+- **{{ t("implementationPlanning.designPreparation.reviewAt") }}:** {{ item.reviewAt.phase }}
+{% endif %}
+{% endif %}
+{% if item.ifStillOpen %}
+- **{{ t("implementationPlanning.designPreparation.ifStillOpen") }}:** `{{ item.ifStillOpen }}`
+{% endif %}
+{% if item.requestPath %}
+- **{{ t("implementationPlanning.designPreparation.requestPath") }}:** `{{ item.requestPath }}`
+{% endif %}
+{% if item.blockReason %}
+- **{{ t("implementationPlanning.designPreparation.blockReason") }}:** {{ item.blockReason }}
+{% endif %}
+{% if item.requiredDecision %}
+- **{{ t("implementationPlanning.designPreparation.requiredDecision") }}:** {{ item.requiredDecision }}
+{% endif %}
+{% if item.notApplicableReason %}
+- **{{ t("implementationPlanning.designPreparation.notApplicableReason") }}:** {{ item.notApplicableReason }}
+{% endif %}
+{% endfor %}
+{%- endif %}
+
 {% endif %}
 {% if header.taskType == 'release-handoff' %}
 ## 5.6 Release Handoff Deliverables

package/runtime/templates/reports/final-verification-input.template.md

@@ -29,18 +29,18 @@ taskType: "{{FM_TASK_TYPE}}"
 - What was supposed to be delivered?
 - What is the intended acceptance decision?
 
-## 검증 모드
+## Verification Mode
 
-- 기본은 **전체-task** 검증입니다(`--stage auto`): 모든 Stage Map stage 가 구현·머지된 뒤 한 번 실행합니다.
-- 특정 stage 만 격리 검증하려면 `--stage N` 으로 **단독-stage** 모드를 씁니다(release-handoff 진입 불가, 부분 검증).
-- worktree / base / head 는 okstra 가 registry 와 `consumers.jsonl` 에서 자동 해소하므로 이 입력서에 수동 기입하지 않습니다.
+- The default is **whole-task** verification (`--stage auto`): it runs once after every Stage Map stage has been implemented and merged.
+- To verify only a specific stage in isolation, use **single-stage** mode with `--stage N` (cannot enter release-handoff; partial verification).
+- okstra automatically resolves worktree / base / head from the registry and `consumers.jsonl`, so do not fill them in manually in this input sheet.
 
 ## Source Implementation Report
 
 - Path (project-relative) to the originating `implementation` final-report:
 - Quoted `Commit list` / `Diff summary` excerpt from the implementation report:
 
-> 보고서 경로가 비거나 누락된 보고서를 가리키면 final-verification 은 status `blocked` 으로 끝내고 `implementation` 또는 `implementation-planning` 으로 라우팅합니다. 검증 대상(worktree/base)은 okstra 가 자동 해소하므로 수동 기입이 어긋나 막히는 일은 없습니다.
+> If the report path is empty or points to a missing report, final-verification ends with status `blocked` and routes to `implementation` or `implementation-planning`. The verification target (worktree/base) is resolved automatically by okstra, so a mismatched manual entry cannot cause a block.
 
 ## Requirement Coverage Source
 
@@ -49,7 +49,7 @@ taskType: "{{FM_TASK_TYPE}}"
 - Requirement IDs / acceptance IDs to verify:
 - Requirements intentionally excluded from this verification:
 
-> final-verification 은 위 source 의 각 requirement / acceptance id 마다 Validation Evidence 에 artifact 를 cite 해야 한다. source 가 비면 brief 의 `## Acceptance Criteria` 를 기본 source 로 사용한다.
+> final-verification MUST cite an artifact in Validation Evidence for each requirement / acceptance id in the source above. If the source is empty, use the brief's `## Acceptance Criteria` as the default source.
 
 ## Verification Evidence
 

package/runtime/templates/reports/i18n/en.json

@@ -129,6 +129,37 @@
       "decision": "Decision",
       "consequences": "Consequences",
       "alternativesConsidered": "Alternatives Considered"
+    },
+    "designPreparation": {
+      "heading": "Implementation Design Preparation",
+      "mode": "Mode",
+      "reason": "Reason",
+      "kind": "Kind",
+      "status": "Status",
+      "stages": "Stages",
+      "need": "Need",
+      "knownFacts": "Known facts",
+      "openQuestions": "Open questions",
+      "aiProposal": "AI proposal",
+      "proposalDetails": "Details",
+      "proposalAssumptions": "Assumptions",
+      "proposalEvidence": "Evidence",
+      "proposalConfidence": "Confidence",
+      "humanConfirmation": "Human confirmation",
+      "confirmationRequired": "Required",
+      "confirmationReason": "Confirmation reason",
+      "suggestedAction": "Suggested action",
+      "replanTriggerFields": "Replan trigger fields",
+      "workingAssumption": "Working assumption",
+      "guardrails": "Guardrails",
+      "reviewAt": "Review at",
+      "ifStillOpen": "If still open",
+      "requestPath": "Request path",
+      "blockReason": "Block reason",
+      "requiredDecision": "Required decision",
+      "notApplicableReason": "Not applicable reason",
+      "none": "(none)",
+      "empty": "No implementation design preparation items."
     }
   },
   "releaseHandoff": {