okstra 0.123.0 → 0.125.0

package/docs/task-process/README.md

@@ -2,21 +2,21 @@
 
 ## Index
 
-- [1. 읽는 순서](#1-읽는-순서)
-- [2. 전체 그림](#2-전체-그림)
-- [3. task-type 문서](#3-task-type-문서)
-- [4. 핵심 코드 위치](#4-핵심-코드-위치)
-- [5. 빠른 비교표](#5-빠른-비교표)
+- [1. Reading order](#1-reading-order)
+- [2. Big picture](#2-big-picture)
+- [3. task-type documents](#3-task-type-documents)
+- [4. Key code locations](#4-key-code-locations)
+- [5. Quick comparison table](#5-quick-comparison-table)
 
-## 1. 읽는 순서
+## 1. Reading order
 
-`okstra-run`은 Claude Code 세션 안에서 task를 시작하는 경로다. 이 폴더는 그 실행 흐름을 두 층으로 나눠 정리한다.
+`okstra-run` is the path that starts a task inside a Claude Code session. This folder organizes that execution flow into two layers.
 
-1. 먼저 [common-flow.md](common-flow.md)를 읽는다. 모든 task-type이 공유하는 wizard, render-bundle, lead phase, artifact 흐름이다.
-2. 그 다음 실행하려는 task-type 문서를 읽는다.
-3. task-type별 차이는 "wizard에서 더 묻는 것", "`prepare_task_bundle()`이 runtime에서 막는 것", "lead profile이 phase 안에서 지키는 것" 세 군데로 나눠 확인한다.
+1. First read [common-flow.md](common-flow.md). It is the wizard, render-bundle, lead phase, and artifact flow shared by every task-type.
+2. Then read the document for the task-type you want to run.
+3. Check the per-task-type differences across three places: "what the wizard additionally asks", "what `prepare_task_bundle()` blocks in the runtime", and "what the lead profile enforces within the phase".
 
-## 2. 전체 그림
+## 2. Big picture
 
 ```mermaid
 flowchart TD
@@ -32,30 +32,30 @@ flowchart TD
     F --> O[final-report + manifests + status]
 ```
 
-`okstra-run`은 `scripts/okstra.sh`를 호출하지 않는다. 대신 `okstra wizard`와 `okstra render-bundle`을 거쳐 같은 Python 단일 진입점인 `prepare_task_bundle()`로 수렴한다.
+`okstra-run` does not call `scripts/okstra.sh`. Instead it goes through `okstra wizard` and `okstra render-bundle` and converges on the same single Python entrypoint, `prepare_task_bundle()`.
 
-## 3. task-type 문서
+## 3. task-type documents
 
-| task-type | 문서 | 한 줄 목적 |
+| task-type | Document | One-line purpose |
 |---|---|---|
-| `requirements-discovery` | [requirements-discovery.md](requirements-discovery.md) | 요청을 분류하고 다음 안전 phase를 고른다. |
-| `error-analysis` | [error-analysis.md](error-analysis.md) | 증상과 evidence로 원인 후보와 검증 경로를 찾는다. |
-| `implementation-planning` | [implementation-planning.md](implementation-planning.md) | 구현 옵션, 검증, rollback, approval gate가 있는 계획을 만든다. |
-| `implementation` | [implementation.md](implementation.md) | 승인된 계획을 executor가 구현하고 verifier가 독립 검증한다. |
-| `final-verification` | [final-verification.md](final-verification.md) | 구현 결과의 whole-task 또는 single-stage acceptance를 판정한다. |
-| `release-handoff` | [release-handoff.md](release-handoff.md) | accepted verdict 뒤 push/PR handoff를 lead-only로 수행한다. |
+| `requirements-discovery` | [requirements-discovery.md](requirements-discovery.md) | Classify the request and choose the next safe phase. |
+| `error-analysis` | [error-analysis.md](error-analysis.md) | Find cause candidates and validation paths from symptoms and evidence. |
+| `implementation-planning` | [implementation-planning.md](implementation-planning.md) | Produce a plan with implementation options, verification, rollback, and an approval gate. |
+| `implementation` | [implementation.md](implementation.md) | The executor implements the approved plan and the verifier verifies it independently. |
+| `final-verification` | [final-verification.md](final-verification.md) | Judge whole-task or single-stage acceptance of the implementation result. |
+| `release-handoff` | [release-handoff.md](release-handoff.md) | Perform the push/PR handoff lead-only after an accepted verdict. |
 
-## 4. 핵심 코드 위치
+## 4. Key code locations
 
-| 관심사 | 정본 |
+| Concern | Source of truth |
 |---|---|
-| okstra-run skill 절차 | [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md) |
+| okstra-run skill procedure | [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md) |
 | wizard state machine | [`scripts/okstra_ctl/wizard.py`](../../scripts/okstra_ctl/wizard.py) |
 | wizard prompt text | [`prompts/wizard/prompts.ko.json`](../../prompts/wizard/prompts.ko.json) |
 | render-bundle Node shim | [`src/commands/execute/render-bundle.mjs`](../../src/commands/execute/render-bundle.mjs) |
-| bundle 생성 단일 진입점 | [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py) |
-| implementation stage 선택/provision | [`scripts/okstra_ctl/implementation_stage.py`](../../scripts/okstra_ctl/implementation_stage.py) |
-| Stage Lifecycle Snapshot + stage target/base/verification 정책 | [`scripts/okstra_ctl/stage_targets.py`](../../scripts/okstra_ctl/stage_targets.py) |
+| single entrypoint for bundle creation | [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py) |
+| implementation stage selection/provisioning | [`scripts/okstra_ctl/implementation_stage.py`](../../scripts/okstra_ctl/implementation_stage.py) |
+| Stage Lifecycle Snapshot + stage target/base/verification policy | [`scripts/okstra_ctl/stage_targets.py`](../../scripts/okstra_ctl/stage_targets.py) |
 | phase boundary | [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py) |
 | task worktree | [`scripts/okstra_ctl/worktree.py`](../../scripts/okstra_ctl/worktree.py) |
 | stage-group handoff | [`scripts/okstra_ctl/handoff.py`](../../scripts/okstra_ctl/handoff.py) |
@@ -64,13 +64,13 @@ flowchart TD
 | phase profiles | [`prompts/profiles/`](../../prompts/profiles/) |
 | final report shape / HTML view | [`templates/reports/final-report.template.md`](../../templates/reports/final-report.template.md), [`scripts/okstra_ctl/report_views.py`](../../scripts/okstra_ctl/report_views.py) |
 
-## 5. 빠른 비교표
+## 5. Quick comparison table
 
-| task-type | wizard 특수 질문 | runtime prepare gate | lead/worker mode | 다음 phase 기본값 |
+| task-type | wizard special question | runtime prepare gate | lead/worker mode | next phase default |
 |---|---|---|---|---|
-| `requirements-discovery` | 공통 질문만 | profile/brief/base-ref 존재 | multi-worker analysis, convergence 1 round default | `pending-routing-decision` |
-| `error-analysis` | 공통 질문만 | profile/brief/base-ref 존재 | multi-worker analysis, convergence 2 rounds default | `implementation-planning` |
-| `implementation-planning` | 공통 질문만 | profile/brief/base-ref 존재 | multi-worker analysis + Phase 6 plan-body verification | `implementation` |
+| `requirements-discovery` | common questions only | profile/brief/base-ref exist | multi-worker analysis, convergence 1 round default | `pending-routing-decision` |
+| `error-analysis` | common questions only | profile/brief/base-ref exist | multi-worker analysis, convergence 2 rounds default | `implementation-planning` |
+| `implementation-planning` | common questions only | profile/brief/base-ref exist | multi-worker analysis + Phase 6 plan-body verification | `implementation` |
 | `implementation` | approved plan, stage multi-pick, executor | approved marker, Stage Lifecycle Snapshot, stage-key reservation, QA command deny-list | one run = one stage; executor writes in isolated stage worktree, verifiers read-only | `final-verification` |
-| `final-verification` | approved plan, stage pick(whole-task or single-stage) | `VERIFICATION_TARGET` 해소; whole-task 자동 통합/teardown 또는 single-stage worktree reuse | whole-task may integrate stages first; analyser verification itself is read-only | `pending-release-handoff` |
-| `release-handoff` | handoff scope(stage-group or whole-task), PR template override/scope | Stage Lifecycle Snapshot eligibility, generated `release-handoff-input.md`, empty worker roster | single-lead; whole-task PR or stage-group collector branch/PR | `done-or-follow-up` |
+| `final-verification` | approved plan, stage pick (whole-task or single-stage) | `VERIFICATION_TARGET` resolved; whole-task auto integration/teardown or single-stage worktree reuse | whole-task may integrate stages first; analyser verification itself is read-only | `pending-release-handoff` |
+| `release-handoff` | handoff scope (stage-group or whole-task), PR template override/scope | Stage Lifecycle Snapshot eligibility, generated `release-handoff-input.md`, empty worker roster | single-lead; whole-task PR or stage-group collector branch/PR | `done-or-follow-up` |

package/docs/task-process/common-flow.md

@@ -2,20 +2,20 @@
 
 ## Index
 
-- [1. 한 줄 요약](#1-한-줄-요약)
-- [2. 두 entrypoint가 만나는 지점](#2-두-entrypoint가-만나는-지점)
-- [3. wizard 입력 수집 흐름](#3-wizard-입력-수집-흐름)
-- [4. render-bundle과 prepare_task_bundle](#4-render-bundle과-prepare_task_bundle)
+- [1. One-line summary](#1-one-line-summary)
+- [2. Where the two entrypoints meet](#2-where-the-two-entrypoints-meet)
+- [3. wizard input collection flow](#3-wizard-input-collection-flow)
+- [4. render-bundle and prepare_task_bundle](#4-render-bundle-and-prepare_task_bundle)
 - [5. Claude lead phase 1-7](#5-claude-lead-phase-1-7)
 - [6. artifact layout](#6-artifact-layout)
-- [7. 공통 분기 규칙](#7-공통-분기-규칙)
-- [8. 주의할 불일치 지점](#8-주의할-불일치-지점)
+- [7. Common branching rules](#7-common-branching-rules)
+- [8. Inconsistencies to watch for](#8-inconsistencies-to-watch-for)
 
-## 1. 한 줄 요약
+## 1. One-line summary
 
-`okstra-run`은 "질문을 직접 판단하는 skill"이 아니라 `okstra wizard` JSON state machine을 사용자에게 relay하는 얇은 loop다. 입력 수집이 끝나면 `okstra render-bundle`을 호출하고, 이 명령이 `python3 -m okstra_ctl.run --render-only`를 통해 task bundle을 만든다. 그 뒤 현재 Claude Code 세션이 `Claude lead`로 전환된다.
+`okstra-run` is not a "skill that decides questions on its own" but a thin loop that relays the `okstra wizard` JSON state machine to the user. Once input collection finishes, it calls `okstra render-bundle`, and that command builds the task bundle through `python3 -m okstra_ctl.run --render-only`. After that, the current Claude Code session switches over to `Claude lead`.
 
-## 2. 두 entrypoint가 만나는 지점
+## 2. Where the two entrypoints meet
 
 ```mermaid
 flowchart LR
@@ -36,9 +36,9 @@ flowchart LR
     H -->|non-render-only| J[exec claude --session-id ...]
 ```
 
-공통 원칙은 `prepare_task_bundle()`가 task bundle 생성의 단일 권위라는 점이다. wizard나 shell wrapper가 path 계산, manifest 생성, worktree 생성 로직을 복제하지 않는다.
+The common principle is that `prepare_task_bundle()` is the single authority for task bundle creation. Neither the wizard nor the shell wrapper duplicates the path computation, manifest creation, or worktree creation logic.
 
-## 3. wizard 입력 수집 흐름
+## 3. wizard input collection flow
 
 ```mermaid
 stateDiagram-v2
@@ -67,9 +67,9 @@ stateDiagram-v2
     Confirm --> Done: Proceed
 ```
 
-새 task는 brief를 먼저 받는다. brief frontmatter에 `task-group:`과 `brief-id:`가 있으면 wizard가 task group/id를 추천값 pick으로 보여준다. 기존 task는 manifest의 `workflow.nextRecommendedPhase`를 task-type 추천값으로 보여주고, 기존 brief path가 있으면 유지/변경을 묻는다.
+A new task receives its brief first. If the brief frontmatter has `task-group:` and `brief-id:`, the wizard shows the task group/id as recommended picks. An existing task shows the manifest's `workflow.nextRecommendedPhase` as the recommended task-type, and if an existing brief path exists it asks whether to keep or change it.
 
-## 4. render-bundle과 prepare_task_bundle
+## 4. render-bundle and prepare_task_bundle
 
 ```mermaid
 sequenceDiagram
@@ -96,7 +96,7 @@ sequenceDiagram
     Skill->>FS: read claude-execution-prompt.md
 ```
 
-`render-bundle`의 Node shim은 [`src/commands/execute/render-bundle.mjs`](../../src/commands/execute/render-bundle.mjs)다. 이 shim이 `--workspace-root`, `--render-only`, runtime resolution 인자를 직접 붙인다. 따라서 okstra-run 경로의 initial run status는 `prepared`, task status는 `instruction-set-generated`로 시작한다.
+The Node shim for `render-bundle` is [`src/commands/execute/render-bundle.mjs`](../../src/commands/execute/render-bundle.mjs). This shim attaches the `--workspace-root`, `--render-only`, and runtime resolution arguments directly. As a result, on the okstra-run path the initial run status starts at `prepared` and the task status starts at `instruction-set-generated`.
 
 ## 5. Claude lead phase 1-7
 
@@ -116,7 +116,7 @@ flowchart TD
     P7 --> Done[final report + manifests updated]
 ```
 
-분석 worker와 report-writer의 역할은 분리된다. `report-writer`는 Phase 4/5 분석 worker가 아니라 Phase 6 final report author다. 단, `release-handoff`는 single-lead phase이므로 이 phase graph를 일부러 타지 않는다.
+The roles of the analysis workers and the report-writer are separated. `report-writer` is not a Phase 4/5 analysis worker but the Phase 6 final report author. Note, however, that `release-handoff` is a single-lead phase, so it deliberately does not follow this phase graph.
 
 ## 6. artifact layout
 
@@ -141,11 +141,11 @@ flowchart TD
     Root --> Handoff[release-handoff-input.md]
 ```
 
-`implementation`과 단일-stage `final-verification`은 run 산출물을 `stage-<N>/` 아래에 격리한다. `implementation`의 carry sidecar와 `consumers.jsonl`은 stage 간 조율 ledger라 phase root에 남는다. runtime은 이 ledger와 registry 예약을 Stage Lifecycle Snapshot으로 읽어 stage 선택과 handoff eligibility를 계산한다. `release-handoff`는 brief를 받지 않고 prepare가 `release-handoff-input.md`를 생성한다.
+`implementation` and single-stage `final-verification` isolate their run deliverables under `stage-<N>/`. The `implementation` carry sidecar and `consumers.jsonl` are cross-stage coordination ledgers, so they remain at the phase root. The runtime reads this ledger and the registry reservations as a Stage Lifecycle Snapshot to compute stage selection and handoff eligibility. `release-handoff` does not receive a brief; prepare generates `release-handoff-input.md`.
 
-`runtime/`은 build output이므로 이 흐름을 고칠 때는 source인 `scripts/`, `skills/`, `agents/`, `prompts/`, `templates/`, `validators/`를 수정하고 `npm run build`로 갱신한다.
+`runtime/` is build output, so when you fix this flow you edit the sources `scripts/`, `skills/`, `agents/`, `prompts/`, `templates/`, `validators/` and refresh with `npm run build`.
 
-## 7. 공통 분기 규칙
+## 7. Common branching rules
 
 ```mermaid
 flowchart TD
@@ -165,14 +165,14 @@ flowchart TD
     PR --> Confirm
 ```
 
-중요한 점은 `Use defaults`가 model 기본값을 뜻한다는 것이다. non-implementation task-type에서는 defaults를 골라도 worker roster 질문은 계속 나온다. 반대로 `implementation`은 worker override 질문이 없다. profile default roster와 executor binding을 사용한다.
+The important point is that `Use defaults` means the model defaults. For non-implementation task-types, the worker roster question still appears even if you choose defaults. Conversely, `implementation` has no worker override question; it uses the profile default roster and executor binding.
 
-Worktree 규칙은 phase별로 다르다. `requirements-discovery`부터 `implementation-planning`까지는 task-key worktree를 재사용한다. `implementation`은 task-key worktree를 anchor로 삼되 실제 실행은 stage-key(`stage-<N>`) worktree와 `runs/implementation/stage-<N>/` 산출물에서 한 stage씩 격리한다. `final-verification --stage N`은 해당 implementation stage worktree를 읽기 대상으로 재사용하고, whole-task 모드는 task-key worktree에 stage commit을 자동 통합한 뒤 검증 target을 만든다. Stage Lifecycle Snapshot은 이 저장 구조를 변경하지 않는 read-side view다.
+Worktree rules differ per phase. From `requirements-discovery` through `implementation-planning`, the task-key worktree is reused. `implementation` uses the task-key worktree as an anchor but does the actual execution isolated one stage at a time in a stage-key (`stage-<N>`) worktree and the `runs/implementation/stage-<N>/` deliverables. `final-verification --stage N` reuses that implementation stage worktree as a read target, and whole-task mode auto-integrates the stage commits into the task-key worktree and then builds the verification target. The Stage Lifecycle Snapshot is a read-side view that does not change this storage structure.
 
-## 8. 주의할 불일치 지점
+## 8. Inconsistencies to watch for
 
-- `okstra-run` wizard 경로는 implementation approved plan에 이미 approval marker가 있어야 통과한다. `scripts/okstra.sh`에는 `--approve`가 있어 checkbox를 CLI ack로 flip할 수 있지만, 현재 wizard `render_args()`에는 `approve` flag가 없다.
-- `release-handoff`는 brief가 없다. prepare가 accepted final-verification report를 인용해 `release-handoff-input.md`를 만들고, wizard의 `handoff_stage_pick` 또는 CLI `--stages`가 whole-task/stage-group 범위를 고정한다.
-- `release-handoff`도 task worktree provisioning 대상이다. 정상적인 handoff는 같은 task-key의 implementation/final-verification 결과를 재사용하는 흐름이 안전하다. 새 task로 시작하면 새 worktree가 만들어지고, profile의 "implementation commit이 있어야 함" entry gate에서 막힐 수 있다.
-- `release-handoff`는 profile에 `Required workers:` block이 없다. runtime도 worker roster를 강제로 empty로 만든다.
-- 모든 task-type은 한 run 안에서 다음 lifecycle phase를 시작하지 않는다. "다음 단계 진행해"는 현재 phase 산출을 마무리하라는 뜻으로만 해석한다.
+- The `okstra-run` wizard path passes only if the implementation approved plan already has an approval marker. `scripts/okstra.sh` has `--approve`, which can flip the checkbox with a CLI ack, but the current wizard `render_args()` has no `approve` flag.
+- `release-handoff` has no brief. Prepare cites the accepted final-verification report to build `release-handoff-input.md`, and the wizard's `handoff_stage_pick` or the CLI `--stages` fixes the whole-task/stage-group scope.
+- `release-handoff` is also a target for task worktree provisioning. A healthy handoff is safest when it reuses the implementation/final-verification results of the same task-key. Starting a new task creates a new worktree, which may be blocked at the profile's "an implementation commit must exist" entry gate.
+- `release-handoff` has no `Required workers:` block in its profile. The runtime also forces the worker roster to be empty.
+- No task-type starts the next lifecycle phase within a single run. "Proceed to the next step" is interpreted only as wrapping up the current phase's output.

package/docs/task-process/error-analysis.md

@@ -2,22 +2,22 @@
 
 ## Index
 
-- [1. 목적](#1-목적)
-- [2. okstra-run wizard 흐름](#2-okstra-run-wizard-흐름)
-- [3. prepare_task_bundle 처리](#3-prepare_task_bundle-처리)
-- [4. lead 실행 흐름](#4-lead-실행-흐름)
-- [5. 산출물과 금지선](#5-산출물과-금지선)
-- [6. 확인한 코드](#6-확인한-코드)
+- [1. Purpose](#1-purpose)
+- [2. okstra-run wizard flow](#2-okstra-run-wizard-flow)
+- [3. prepare_task_bundle handling](#3-prepare_task_bundle-handling)
+- [4. lead execution flow](#4-lead-execution-flow)
+- [5. Deliverables and prohibitions](#5-deliverables-and-prohibitions)
+- [6. Code reviewed](#6-code-reviewed)
 
-## 1. 목적
+## 1. Purpose
 
-`error-analysis`는 보고된 error 또는 incident를 분석해 symptom, trigger, root-cause candidate, reproduction gap, validation path를 정리한다. fix 자체나 implementation design을 만드는 phase가 아니다.
+`error-analysis` analyzes a reported error or incident to organize the symptom, trigger, root-cause candidate, reproduction gap, and validation path. It is not the phase that produces the fix itself or an implementation design.
 
-## 2. okstra-run wizard 흐름
+## 2. okstra-run wizard flow
 
 ```mermaid
 flowchart TD
-    Start[/okstra-run/] --> Common[공통 task identity flow]
+    Start[/okstra-run/] --> Common[common task identity flow]
     Common --> Type[task-type = error-analysis]
     Type --> Worktree{active worktree exists?}
     Worktree -->|yes| Defaults[Use defaults / Customize]
@@ -32,9 +32,9 @@ flowchart TD
     Confirm --> Render[render-bundle --render-only]
 ```
 
-기본 required roster는 `claude`, `codex`, `report-writer`다. `antigravity`는 optional worker이고, 선택하면 analyser set에 들어간다.
+The default required roster is `claude`, `codex`, `report-writer`. `antigravity` is an optional worker, and if selected it joins the analyser set.
 
-## 3. prepare_task_bundle 처리
+## 3. prepare_task_bundle handling
 
 ```mermaid
 sequenceDiagram
@@ -54,9 +54,9 @@ sequenceDiagram
     Run->>Art: task-manifest workflow next=implementation-planning
 ```
 
-`workflow.py`의 static next phase는 `implementation-planning`이다. 실제 final report는 더 조사해야 한다고 할 수 있지만, lifecycle상 fix는 바로 가지 않고 planning으로 넘어간다.
+The static next phase in `workflow.py` is `implementation-planning`. The actual final report may say more investigation is needed, but in the lifecycle the fix does not go straight ahead; it moves on to planning.
 
-## 4. lead 실행 흐름
+## 4. lead execution flow
 
 ```mermaid
 flowchart TD
@@ -69,9 +69,9 @@ flowchart TD
     Report --> Persist[Phase 7 persist + validate]
 ```
 
-worker들은 symptom과 evidence를 독립적으로 분석한다. report-writer는 Phase 4/5에 분석하지 않고 Phase 6에서 final report를 작성한다.
+The workers analyze the symptom and evidence independently. The report-writer does not analyze during Phase 4/5 but writes the final report in Phase 6.
 
-## 5. 산출물과 금지선
+## 5. Deliverables and prohibitions
 
 ```mermaid
 flowchart LR
@@ -82,20 +82,19 @@ flowchart LR
     Hyp -. forbidden .-> Fix[Code fix in this run]
 ```
 
-final report는 다음을 담아야 한다.
+The final report must contain the following.
 
 - evidence-backed cause analysis
 - uncertainty boundary
 - practical next diagnostic steps
-- blocking uncertainty가 있으면 `## 1. Clarification Items`, 보통 `Blocks=next-phase`
+- if there is blocking uncertainty, `## 1. Clarification Items`, usually `Blocks=next-phase`
 
-금지되는 것은 source edit, refactor, fix attempt, implementation design artifact, build/migration/deploy 실행이다. code나 log로 답할 수 있는 ambiguity를 사용자 질문으로 넘기는 것도 profile상 defect다.
+What is prohibited is source edit, refactor, fix attempt, implementation design artifact, and running build/migration/deploy. Deferring ambiguity that could be answered from code or logs to a user question is also a defect per the profile.
 
-## 6. 확인한 코드
+## 6. Code reviewed
 
 - [`prompts/profiles/error-analysis.md`](../../prompts/profiles/error-analysis.md)
 - [`templates/reports/error-analysis-input.template.md`](../../templates/reports/error-analysis-input.template.md)
 - [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py)
 - [`scripts/okstra_ctl/wizard.py`](../../scripts/okstra_ctl/wizard.py)
 - [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)
-

package/docs/task-process/final-verification.md

@@ -2,24 +2,24 @@
 
 ## Index
 
-- [1. 목적](#1-목적)
-- [2. okstra-run wizard 흐름](#2-okstra-run-wizard-흐름)
+- [1. Purpose](#1-purpose)
+- [2. okstra-run wizard flow](#2-okstra-run-wizard-flow)
 - [3. entry gate](#3-entry-gate)
-- [4. 검증 실행 흐름](#4-검증-실행-흐름)
-- [5. verdict와 routing](#5-verdict와-routing)
-- [6. 산출물](#6-산출물)
-- [7. 금지선](#7-금지선)
-- [8. 확인한 코드](#8-확인한-코드)
+- [4. Verification execution flow](#4-verification-execution-flow)
+- [5. Verdict and routing](#5-verdict-and-routing)
+- [6. Deliverables](#6-deliverables)
+- [7. Forbidden actions](#7-forbidden-actions)
+- [8. Verified code](#8-verified-code)
 
-## 1. 목적
+## 1. Purpose
 
-`final-verification`은 `implementation`이 만든 committed diff를 최종 수락할 수 있는지 판정한다. source edit나 follow-up fix를 수행하지 않고, 구현 report와 실제 checkout이 일치하는지 확인한 뒤 acceptance blocker, residual risk, release recommendation을 남긴다.
+`final-verification` determines whether the committed diff produced by `implementation` can be finally accepted. Without performing any source edit or follow-up fix, it confirms that the implementation report matches the actual checkout, then records acceptance blockers, residual risk, and a release recommendation.
 
-## 2. okstra-run wizard 흐름
+## 2. okstra-run wizard flow
 
 ```mermaid
 flowchart TD
-    Start[/okstra-run/] --> Common[공통 task identity flow]
+    Start[/okstra-run/] --> Common[common task identity flow]
     Common --> Type[task-type = final-verification]
     Type --> PlanPick[approved plan pick]
     PlanPick --> Approved[approval marker confirm]
@@ -33,9 +33,9 @@ flowchart TD
     Confirm --> Render[render-bundle]
 ```
 
-`final-verification`은 analyser roster가 있는 non-implementation phase다. 따라서 `Use defaults`를 골라도 worker roster prompt는 계속 나온다. 기본 required workers는 `claude`, `codex`, `report-writer`이고, `antigravity`는 opt-in이다.
+`final-verification` is a non-implementation phase that has an analyser roster. So even if you pick `Use defaults`, the worker roster prompt still appears. The default required workers are `claude`, `codex`, and `report-writer`, and `antigravity` is opt-in.
 
-이 phase는 `base-ref`를 직접 묻지 않는다. wizard는 approved plan의 Stage Map을 기준으로 whole-task 또는 단일 stage를 선택하고, prepare가 registry/`consumers.jsonl`/git 상태에서 `VERIFICATION_TARGET`을 해소한다.
+This phase does not ask for `base-ref` directly. The wizard selects whole-task or a single stage from the approved plan's Stage Map, and prepare resolves `VERIFICATION_TARGET` from the registry / `consumers.jsonl` / git state.
 
 ## 3. entry gate
 
@@ -60,17 +60,17 @@ sequenceDiagram
     Lead->>Lead: verify against injected target only
 ```
 
-prepare는 worker dispatch 전에 verification target을 고정한다. 다음 중 하나라도 실패하면 lead prompt가 시작되지 않고 `PrepareError`로 멈춘다.
+prepare fixes the verification target before worker dispatch. If any of the following fails, the lead prompt does not start and it stops with `PrepareError`.
 
-- approved plan의 Stage Map을 읽을 수 없다.
-- whole-task인데 Stage Map의 모든 stage가 `done`이 아니다.
-- whole-task 자동 통합 중 merge conflict가 난다.
-- single-stage인데 선택 stage의 implementation stage worktree가 없거나 dirty다.
-- verification worktree가 `.okstra/` 밖 dirty state다.
+- The approved plan's Stage Map cannot be read.
+- It is whole-task but not every stage in the Stage Map is `done`.
+- A merge conflict occurs during whole-task auto-integration.
+- It is single-stage but the selected stage's implementation stage worktree is missing or dirty.
+- The verification worktree is in a dirty state outside `.okstra/`.
 
-시작된 lead는 `VERIFICATION_TARGET`을 권위로 취급한다. worktree/base/head/stage/source report를 brief에서 다시 고르지 않는다.
+Once started, the lead treats `VERIFICATION_TARGET` as authoritative. It does not re-pick worktree/base/head/stage/source report from the brief.
 
-## 4. 검증 실행 흐름
+## 4. Verification execution flow
 
 ```mermaid
 flowchart TD
@@ -90,7 +90,7 @@ flowchart TD
     SelfReview --> Persist[final report + manifests]
 ```
 
-검증 command는 자동 추측하지 않는다. 독립 재검증이 필요하면 command source는 두 tier뿐이다.
+The validation command is never guessed automatically. When independent re-verification is needed, there are only two tiers of command source.
 
 ```mermaid
 flowchart LR
@@ -103,9 +103,9 @@ flowchart LR
     Deny -->|denied token| Reject[record rejected command<br/>do not execute]
 ```
 
-`implementation` runtime은 `qaCommands` deny-list를 prepare 단계에서 검증하지만, `final-verification`은 그 fail-fast gate가 없다. profile contract상 lead가 실행 직전에 직접 deny-list를 self-check해야 한다.
+The `implementation` runtime validates the `qaCommands` deny-list at the prepare stage, but `final-verification` has no such fail-fast gate. Per the profile contract, the lead must self-check the deny-list directly right before execution.
 
-## 5. verdict와 routing
+## 5. Verdict and routing
 
 ```mermaid
 flowchart TD
@@ -117,15 +117,15 @@ flowchart TD
     Blockers --> Followup
 ```
 
-`## 7. Final Verdict`에는 `Verdict Token` field가 정확히 하나 들어가야 하며 값은 다음 셋 중 하나다.
+`## 7. Final Verdict` must contain exactly one `Verdict Token` field, and its value is one of the following three.
 
-- `accepted`: whole-task이면 plain `release-handoff`, single-stage이면 `release-handoff(stage-group)` 후보가 되는 상태
-- `conditional-accept`: 조건을 모두 명시해야 하며, 조건이 gate면 다음 phase를 막는다
-- `blocked`: acceptance blocker가 있어 release-handoff로 갈 수 없는 상태
+- `accepted`: a state that becomes a candidate for plain `release-handoff` when whole-task, or `release-handoff(stage-group)` when single-stage
+- `conditional-accept`: all conditions must be stated explicitly, and when a condition is a gate it blocks the next phase
+- `blocked`: a state that has acceptance blockers and cannot proceed to release-handoff
 
-애매한 표현인 "looks good", "mostly ready"는 허용되지 않는다.
+Vague phrasings such as "looks good" or "mostly ready" are not allowed.
 
-## 6. 산출물
+## 6. Deliverables
 
 ```mermaid
 flowchart TD
@@ -138,21 +138,21 @@ flowchart TD
     Report --> Route[routing recommendation]
 ```
 
-final report에는 최소 다음이 필요하다.
+The final report requires at least the following.
 
 - originating implementation final-report path
-- verification scope(`whole-task` 또는 `single-stage`)와 injected `VERIFICATION_TARGET`
+- verification scope (`whole-task` or `single-stage`) and the injected `VERIFICATION_TARGET`
 - inspected worktree path
-- implementation base ref와 run start head SHA
+- implementation base ref and run start head SHA
 - quoted commit list / diff summary
 - `Verdict Token`
-- blocker table 또는 `No acceptance blockers found.`
-- residual risk와 escalation trigger
-- requirement별 coverage artifact
-- read-only command log와 exit code
-- 다음 safe phase recommendation
+- blocker table or `No acceptance blockers found.`
+- residual risk and escalation trigger
+- coverage artifact per requirement
+- read-only command log and exit code
+- next safe phase recommendation
 
-## 7. 금지선
+## 7. Forbidden actions
 
 ```mermaid
 flowchart TD
@@ -165,9 +165,9 @@ flowchart TD
     FV -. forbidden .-> Hide[hide verifier dissent]
 ```
 
-whole-task mode의 stage merge/teardown은 prepare가 수행하는 runtime-owned 통합 단계다. 그 이후 lead 검증은 read-only다. source edit, follow-up fix, scope expansion은 전부 금지다. 결함을 발견하면 현재 run 안에서 고치지 않고 final report에 blocker로 기록한 뒤 새 `error-analysis` 또는 `implementation-planning` 입력으로 넘긴다.
+The stage merge/teardown of whole-task mode is a runtime-owned integration step that prepare performs. After that, lead verification is read-only. Source edit, follow-up fix, and scope expansion are all forbidden. When a defect is found, it is not fixed within the current run; instead it is recorded as a blocker in the final report and handed off as new `error-analysis` or `implementation-planning` input.
 
-## 8. 확인한 코드
+## 8. Verified code
 
 - [`prompts/profiles/final-verification.md`](../../prompts/profiles/final-verification.md)
 - [`templates/reports/final-verification-input.template.md`](../../templates/reports/final-verification-input.template.md)