okstra 0.122.0 → 0.124.0

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)

package/docs/task-process/implementation-planning.md

@@ -2,23 +2,23 @@
 
 ## Index
 
-- [1. 목적](#1-목적)
-- [2. okstra-run wizard 흐름](#2-okstra-run-wizard-흐름)
-- [3. prepare_task_bundle 처리](#3-prepare_task_bundle-처리)
-- [4. lead 실행 흐름](#4-lead-실행-흐름)
-- [5. final report gate](#5-final-report-gate)
-- [6. 금지선](#6-금지선)
-- [7. 확인한 코드](#7-확인한-코드)
+- [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. design preparation and final report gate](#5-design-preparation-and-final-report-gate)
+- [6. Forbidden actions](#6-forbidden-actions)
+- [7. Verified code](#7-verified-code)
 
-## 1. 목적
+## 1. Purpose
 
-`implementation-planning`은 coding 전에 구현 방향을 정하는 phase다. 최소 두 개의 implementation option, trade-off, recommended option, stepwise execution order, validation checklist, rollback strategy를 만들고 사용자 approval gate를 둔다.
+`implementation-planning` is the phase that decides the implementation direction before coding. It produces at least two implementation options, trade-offs, a recommended option, a stepwise execution order, a validation checklist, and a rollback strategy, and it places a user approval gate.
 
-## 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 = implementation-planning]
     Type --> Worktree{active task worktree?}
     Worktree -->|yes| Defaults[Use defaults / Customize]
@@ -33,9 +33,9 @@ flowchart TD
     Confirm --> Render[render-bundle]
 ```
 
-wizard는 현재 `--no-plan-verification`을 묻지 않는다. okstra-run 경로에서는 plan-body verification이 기본 enabled로 준비된다. shell/CLI 경로에는 `--no-plan-verification` flag가 있다.
+The wizard currently does not ask about `--no-plan-verification`. On the okstra-run path, plan-body verification is prepared as enabled by default. The shell/CLI path has a `--no-plan-verification` flag.
 
-## 3. prepare_task_bundle 처리
+## 3. prepare_task_bundle handling
 
 ```mermaid
 sequenceDiagram
@@ -55,9 +55,9 @@ sequenceDiagram
     P-->>W: prepared lead prompt
 ```
 
-runtime prepare 단계는 source edit를 막는 것이 아니라 "현재 phase boundary를 lead prompt와 manifest에 박아 넣는" 방식이다. 실제 no-edit/no-build 규칙은 lead와 worker가 profile을 읽고 지켜야 한다.
+The runtime prepare stage does not block source edits itself; instead it "bakes the current phase boundary into the lead prompt and manifest." The actual no-edit/no-build rules must be honored by the lead and workers reading the profile.
 
-## 4. lead 실행 흐름
+## 4. lead execution flow
 
 ```mermaid
 flowchart TD
@@ -74,37 +74,62 @@ flowchart TD
     NoApproval --> P7
 ```
 
-Plan-body verification은 Phase 5.5와 다른 queue를 쓴다. Phase 5.5는 worker finding을 검증하고, Phase 6 sub-step은 report-writer가 만든 consolidated plan body를 `P-*` plan item 단위로 다시 검증한다.
+Plan-body verification uses a different queue from Phase 5.5. Phase 5.5 verifies worker findings, and the Phase 6 sub-step re-verifies the consolidated plan body produced by the report-writer at the `P-*` plan-item level.
 
-## 5. final report gate
+## 5. design preparation and final report gate
+
+The lead deterministically detects domain contract, persistence schema, external interface, transaction/consistency, transformation mapping, lifecycle state machine, rollout/observability, and manual user test surface from the Stage Map. The report-writer does not ask the user starting from blanks; instead it first writes a concrete AI draft for each surface using known facts and evidence.
+
+The status of `designPreparation.items[]` does not forcibly pin completeness to a single stage.
+
+| Status | Meaning | Handling on implementation entry |
+|---|---|---|
+| `ready` | The implementation contract is sufficiently finalized within the planning snapshot | Proceed with that stage |
+| `provisional` | There is a reversible working assumption and guardrail, so it is safe to proceed now | Proceed with that stage, inject the assumption into the executor prompt, and re-confirm at the designated review point |
+| `blocked` | There is no safe default and it needs an external authorization, business policy, or destructive-change decision | Only the stage in this item's `stageRefs` waits for input or is replanned |
+| `not-applicable` | The surface found by the detector does not require a separate contract in this stage | Record a concrete reason and proceed |
+
+If there is no detected surface and no manual test input that changes the interface/acceptance, write `mode: no-design-inputs` with a concrete reason. So there is no need to create a formal empty document for a simple task.
+
+`manual-user-test` does not have to fully fix the execution method at planning time. If there is a safe default procedure even before seeing the actual diff, proceed with `provisional` and `ifStillOpen: follow-up`, and the implementation report finally owns the `implementation.manualUserTest` aligned to the actual change. Conversely, use `blocked` only when the stage cannot be safely completed without an acceptance method that only the user can provide.
+
+Phase 7 deterministically creates a `design-prep-requests/` document filled with an AI proposal for each `provisional`/`blocked` item. When the user or wizard approves, edits, rejects, or holds the draft, only after confirmation does it append a new revision sidecar under `design-prep-inputs/`. This response does not modify the approved planning report.
+
+Plan approval and design-preparation status are independent gates. If plan-body verification passed, the plan itself can be approved even when there is a `blocked` item. The actual `implementation` preflight resolves only the items of the selected stage, and unrelated stages keep proceeding.
 
 ```mermaid
 flowchart LR
     Options[Option Candidates] --> Matrix[Trade-off Matrix]
     Matrix --> Rec[Recommended Option]
-    Rec --> Steps[Stepwise Execution Order]
-    Steps --> Dep[Dependency / Migration Risk]
+    Rec --> Stages[Stage Map + Stage Exit/Validation]
+    Stages --> Prep[Implementation Design Preparation]
+    Prep --> Dep[Dependency / Migration Risk]
     Dep --> Val[Validation Checklist]
     Val --> Rb[Rollback Strategy]
     Rb --> Verify[Plan Body Verification]
-    Verify --> Approval[User Approval Request]
+    Verify --> Approval[YAML frontmatter approval]
     Approval --> Impl[Next run: implementation]
 ```
 
-validator가 section heading의 영문 substring을 찾기 때문에 다음 문자열은 heading line에 그대로 남아야 한다.
+Because the validator searches for the English substring of the section heading, the following strings must remain verbatim on the heading line.
 
 - `Option Candidates`
 - `Trade-off`
 - `Recommended Option`
-- `Stepwise Execution Order`
+- `Stage Map`
+- `Stage Exit Contract`
+- `Stage Validation`
 - `Dependency`
+- `Cross-Project Dependencies`
+- `Decision Drafts`
 - `Validation Checklist`
 - `Rollback`
-- `User Approval Request`
+- `Requirement Coverage`
+- `Implementation Design Preparation`
 
-approval marker는 top-of-report `User Approval Request` block의 `- [ ] Approved` line이다. 사용자가 `- [x] Approved`로 바꿔야 implementation run이 시작된다. `Blocks=approval` clarification row가 unresolved이면 approved marker가 있어도 implementation prepare에서 거부된다.
+Approval is recorded with `approved: true` in the YAML frontmatter and the chosen `implementation-option`. If a `Blocks=approval` clarification row is unresolved, the implementation prepare rejects it even when the frontmatter is in an approved state. The `blocked` status of design-preparation is not the same as `Blocks=approval`, and it operates only at that stage's implementation preflight.
 
-## 6. 금지선
+## 6. Forbidden actions
 
 ```mermaid
 flowchart TD
@@ -115,9 +140,9 @@ flowchart TD
     Plan -. forbidden .-> NextPhase[start implementation in same run]
 ```
 
-이 phase는 plan document만 만든다. code-level micro-optimization, source edit, build, migration, deployment, run artifact directory 밖 write는 금지된다.
+This phase only produces the plan document. Code-level micro-optimization, source edit, build, migration, deployment, and any write outside the run artifact directory are forbidden.
 
-## 7. 확인한 코드
+## 7. Verified code
 
 - [`prompts/profiles/implementation-planning.md`](../../prompts/profiles/implementation-planning.md)
 - [`templates/reports/implementation-planning-input.template.md`](../../templates/reports/implementation-planning-input.template.md)
@@ -125,4 +150,3 @@ flowchart TD
 - [`scripts/okstra_ctl/render.py`](../../scripts/okstra_ctl/render.py)
 - [`validators/validate-run.py`](../../validators/validate-run.py)
 - [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)
-