okstra 0.122.0 → 0.124.0

package/docs/pr-template-usage.md

@@ -1,65 +1,65 @@
-# PR template 사용 가이드
+# PR template usage guide
 
-`release-handoff` 단계에서 `Claude lead` 가 PR 본문을 작성할 때 사용하는 마크다운 템플릿의 해석 규칙·저장 위치·설정 방법을 정리한다.
+Summarizes the resolution rules, storage locations, and configuration methods for the Markdown template that `Claude lead` uses to write the PR body during the `release-handoff` phase.
 
-해석 로직의 권위 출처: [`scripts/okstra_ctl/pr_template.py`](../scripts/okstra_ctl/pr_template.py).
+Authoritative source of the resolution logic: [`scripts/okstra_ctl/pr_template.py`](../scripts/okstra_ctl/pr_template.py).
 
-## 1. 4 단계 lookup 우선순위
+## 1. The 4-step lookup priority
 
-높은 우선순위가 먼저 매치된다. 상위 단계가 매치되면 하위 단계는 조회하지 않는다.
+Higher priority matches first. Once an upper step matches, the lower steps are not consulted.
 
-| # | source | 위치 | 비고 |
+| # | source | Location | Notes |
 |---|--------|------|------|
-| 1 | **per-run override** | `okstra render-bundle --pr-template-path <path>` 또는 wizard 의 한 번성 입력 | 상대경로는 호출자 cwd 기준 (override) 또는 `project_root` 기준 (project scope 와 동일 함수 사용). |
-| 2 | **project scope** | `<project_root>/.okstra/project.json` 의 `prTemplatePath` 필드 | 상대경로는 `project_root` 기준으로 해석. |
-| 3 | **global scope** | `~/.okstra/config.json` 의 `prTemplatePath` 필드 | **절대경로 또는 `~/` 시작 경로만** 허용. 상대경로는 모호하므로 거절. |
-| 4 | **default (skill bundle)** | 후보 경로 중 먼저 존재하는 파일 (아래 §2) | `npx okstra install` 직후의 폴백 경로. |
+| 1 | **per-run override** | `okstra render-bundle --pr-template-path <path>` or the wizard's one-time input | A relative path is resolved against the caller cwd (override) or against `project_root` (using the same function as project scope). |
+| 2 | **project scope** | the `prTemplatePath` field in `<project_root>/.okstra/project.json` | A relative path is resolved against `project_root`. |
+| 3 | **global scope** | the `prTemplatePath` field in `~/.okstra/config.json` | **Only an absolute path or a `~/`-prefixed path** is allowed. A relative path is ambiguous and rejected. |
+| 4 | **default (skill bundle)** | the first existing file among the candidate paths (§2 below) | The fallback path right after `npx okstra install`. |
 
-위 4 단계 중 어느 하나에서 명시된 파일이 존재하지 않으면 `PrTemplateError` 로 즉시 실패한다 (silent fallback 없음).
+If the file named in any of the 4 steps does not exist, it fails immediately with `PrTemplateError` (no silent fallback).
 
-## 2. default 후보 경로
+## 2. Default candidate paths
 
-1. `$OKSTRA_SKILLS_DIR/templates/prd/pr-body.template.md` — 환경변수 `OKSTRA_SKILLS_DIR` 가 설정돼 있을 때만.
-2. `~/.claude/skills/templates/prd/pr-body.template.md` — `npx okstra install` 이 깔아두는 표준 위치.
+1. `$OKSTRA_SKILLS_DIR/templates/prd/pr-body.template.md` — only when the `OKSTRA_SKILLS_DIR` environment variable is set.
+2. `~/.claude/skills/templates/prd/pr-body.template.md` — the standard location `npx okstra install` installs to.
 
-후보들은 우선순위 순서대로 시도되며, 모두 부재 시 다음과 같이 명시적인 에러로 끝난다.
+The candidates are tried in priority order, and if all are absent it ends with an explicit error as follows.
 
 > `no PR template available: default skill template not found. Reinstall okstra (npx okstra install) or set prTemplatePath in project.json / ~/.okstra/config.json.`
 
-## 3. 소스 리포지토리 안 원본
+## 3. The original inside the source repository
 
-- [`templates/prd/pr-body.template.md`](../templates/prd/pr-body.template.md) — `npx okstra install` 이 §2 의 default 위치로 복사하는 원본. 카피를 바꾸고 싶으면 이 파일을 수정한 뒤 다시 install 한다.
+- [`templates/prd/pr-body.template.md`](../templates/prd/pr-body.template.md) — the original that `npx okstra install` copies to the §2 default location. To change the copy, edit this file and install again.
 
-## 4. 설정 명령 — 영속화
+## 4. Configuration commands — persistence
 
-per-run override 보다 길게 유지하려면 wizard 가 자동 호출하거나 직접 다음 명령으로 기록한다.
+To keep it longer than a per-run override, either the wizard invokes it automatically or you record it directly with the following commands.
 
 ```bash
-# project scope: <project_root>/.okstra/project.json 의 prTemplatePath 갱신
+# project scope: update prTemplatePath in <project_root>/.okstra/project.json
 okstra config set pr-template-path "<path>" --scope project
 
-# global scope: ~/.okstra/config.json 의 prTemplatePath 갱신 (절대경로 필수)
+# global scope: update prTemplatePath in ~/.okstra/config.json (absolute path required)
 okstra config set pr-template-path "<absolute-path>" --scope global
 ```
 
-wizard 흐름에서는 `pr_template_pick` 단계에서 `한 번만 / 프로젝트에 저장 / 전역 저장` 중 선택한다. `프로젝트` 또는 `전역` 을 고르면 위 명령과 동일한 효과로 `prTemplatePath` 가 영속화된다.
+In the wizard flow, the `pr_template_pick` step lets you choose among `Once / Save to project / Save globally`. Choosing `project` or `global` persists `prTemplatePath` with the same effect as the commands above.
 
-## 5. 소스 추적
+## 5. Source tracking
 
-매 run 의 prepare 단계에서 실제로 채택된 단계가 ctx 에 기록되어 final report 등에서 추적할 수 있다.
+Each run's prepare step records the step actually adopted into ctx, so it can be traced from the final report and elsewhere.
 
-| ctx key | 값 |
+| ctx key | Value |
 |---------|-----|
-| `PR_TEMPLATE_PATH` | 실제 해석된 절대경로 |
-| `PR_TEMPLATE_SOURCE` | `"override" \| "project" \| "global" \| "default"` 중 하나 |
+| `PR_TEMPLATE_PATH` | the actually resolved absolute path |
+| `PR_TEMPLATE_SOURCE` | one of `"override" \| "project" \| "global" \| "default"` |
 
-`PR_TEMPLATE_SOURCE` 가 `default` 인데 프로젝트 컨벤션상 별도 PR 본문이 필요하다면, §4 의 영속화 명령으로 `prTemplatePath` 를 등록한다.
+If `PR_TEMPLATE_SOURCE` is `default` but the project convention requires a distinct PR body, register `prTemplatePath` with the §4 persistence command.
 
-## 6. 트러블슈팅
+## 6. Troubleshooting
 
-| 증상 | 원인 | 조치 |
+| Symptom | Cause | Action |
 |------|------|------|
-| `override PR template not found: <path>` | per-run override 로 지정한 경로가 없음 | 경로 오타 점검 또는 영속화된 설정을 사용. |
-| `project.json prTemplatePath points to missing file: <path>` | `project.json` 의 `prTemplatePath` 가 가리키는 파일 부재 | 해당 파일을 복원하거나 `okstra config set pr-template-path <path> --scope project` 로 재설정. |
-| `global config prTemplatePath must be absolute or start with '~/'` | `~/.okstra/config.json` 에 상대경로가 들어감 | 절대경로 또는 `~/` 접두 경로로 갱신. |
-| `no PR template available` | install 누락 또는 default 파일까지 모두 부재 | `npx okstra install` 재실행 또는 §4 명령으로 명시 설정. |
+| `override PR template not found: <path>` | the path given as a per-run override does not exist | Check for a path typo or use a persisted configuration. |
+| `project.json prTemplatePath points to missing file: <path>` | the file pointed at by `prTemplatePath` in `project.json` is absent | Restore that file or reconfigure with `okstra config set pr-template-path <path> --scope project`. |
+| `global config prTemplatePath must be absolute or start with '~/'` | a relative path was put in `~/.okstra/config.json` | Update to an absolute path or a `~/`-prefixed path. |
+| `no PR template available` | install is missing or even the default file is absent | Re-run `npx okstra install` or set it explicitly with the §4 command. |

package/docs/project-structure-overview.md

@@ -1,47 +1,47 @@
-# Okstra — 폴더 구조 및 기능 요약
+# Okstra — Folder structure and feature summary
 
-> 현재 저장소 기준의 living map입니다. 빠른 사용법은 [`README.md`](../README.md), 내부 실행 계약은 [`docs/architecture.md`](architecture.md), 저장 구조는 [`docs/architecture/storage-model.md`](architecture/storage-model.md), CLI 세부 옵션은 [`docs/cli.md`](cli.md)를 함께 보세요.
+> A living map based on the current repository. For quick usage see [`README.md`](../README.md), for the internal execution contract see [`docs/architecture.md`](architecture.md), for the storage model see [`docs/architecture/storage-model.md`](architecture/storage-model.md), and for detailed CLI options see [`docs/cli.md`](cli.md).
 
 ---
 
-## 목차
+## Table of contents
 
-- [1. 프로젝트 정체성](#1-프로젝트-정체성)
-- [2. 최상위 구조](#2-최상위-구조)
-- [3. Build / install 경계](#3-build--install-경계)
-- [4. 폴더별 역할](#4-폴더별-역할)
-- [5. 주요 런타임 모듈](#5-주요-런타임-모듈)
-- [6. 설치 후 저장소 구조](#6-설치-후-저장소-구조)
-- [7. 핵심 워크플로우](#7-핵심-워크플로우)
-- [8. 문서 유지보수 체크리스트](#8-문서-유지보수-체크리스트)
-- [부록 A. Report / row ID 용어](#부록-a-report--row-id-용어)
+- [1. Project identity](#1-project-identity)
+- [2. Top-level structure](#2-top-level-structure)
+- [3. Build / install boundary](#3-build--install-boundary)
+- [4. Folder responsibilities](#4-folder-responsibilities)
+- [5. Key runtime modules](#5-key-runtime-modules)
+- [6. Post-install layout](#6-post-install-layout)
+- [7. Core workflows](#7-core-workflows)
+- [8. Doc maintenance checklist](#8-doc-maintenance-checklist)
+- [Appendix A. Report / row ID glossary](#appendix-a-report--row-id-glossary)
 
 ---
 
-## 1. 프로젝트 정체성
+## 1. Project identity
 
-`okstra`는 npm package `okstra`로 배포되는 Claude Code용 multi-agent cross-verification runtime입니다. 단발성 reviewer가 아니라 stable task key를 중심으로 lead + worker 모델을 여러 lifecycle phase에 걸쳐 운영합니다.
+`okstra` is a multi-agent cross-verification runtime for Claude Code, distributed as the npm package `okstra`. It is not a one-shot reviewer; it runs a lead + worker model across multiple lifecycle phases around a stable task key.
 
-현재 기준:
+Current baseline:
 
 - package version: see `package.json`
 - Node CLI entrypoint: `bin/okstra`
 - Python orchestration authority: `scripts/okstra_ctl/run.py::prepare_task_bundle`
 - lifecycle: `requirements-discovery → error-analysis → implementation-planning → implementation → final-verification → release-handoff`
-- installed skills: 8개
+- installed skills: 8
 - worker agents: `claude`, `codex`, `antigravity`, `report-writer`
 - final report SSOT: `schemas/final-report-v1.0.schema.json` + `*.data.json`
 
-설계 원칙:
+Design principles:
 
-1. **Single prepare authority**: slash skill, Bash CLI, Node preview 모두 `prepare_task_bundle()`로 수렴합니다.
-2. **Stable task identity**: `<project-id>/<task-group>/<task-id>`가 phase, run, worktree, report를 관통합니다.
-3. **Artifact-home rule**: okstra-owned project artifact root는 `<PROJECT_ROOT>/.okstra/**` 하나입니다.
-4. **Template/schema/validator lockstep**: `templates/`, `schemas/`, `validators/`, worker/report-writer 계약이 같은 report shape를 강제합니다.
+1. **Single prepare authority**: the slash skill, the Bash CLI, and the Node preview all converge on `prepare_task_bundle()`.
+2. **Stable task identity**: `<project-id>/<task-group>/<task-id>` runs through phase, run, worktree, and report.
+3. **Artifact-home rule**: the okstra-owned project artifact root is the single `<PROJECT_ROOT>/.okstra/**`.
+4. **Template/schema/validator lockstep**: `templates/`, `schemas/`, `validators/`, and the worker/report-writer contract enforce the same report shape.
 
 ---
 
-## 2. 최상위 구조
+## 2. Top-level structure
 
 ```text
 okstra/
@@ -77,7 +77,7 @@ okstra/
 
 ---
 
-## 3. Build / install 경계
+## 3. Build / install boundary
 
 ### 3.1 npm package
 
@@ -142,7 +142,7 @@ Runtime/install asset changes follow this checklist:
 
 ---
 
-## 4. 폴더별 역할
+## 4. Folder responsibilities
 
 ### 4.1 `bin/` and `src/` — Node CLI
 
@@ -182,7 +182,9 @@ Runtime/install asset changes follow this checklist:
 | `spawn-followups`, `error-log` | `src/commands/execute/*.mjs` | Follow-up task bundle creation and run error-log append helpers |
 | `memory` | `src/commands/memory/memory.mjs` | Store/find global conversation memory under `~/.okstra/memory-book` |
 | `pr` | `src/commands/pr/pr.mjs` | `okstra pr <template\|branches\|gen>` — PR body template store under `~/.okstra/template/pr/` (bundled fallback `src/commands/pr/default.md`), base-branch recommendation, and the `gen` JSON bundle (template + `<base>..HEAD` commits + `<base>...HEAD` diffstat) backing the okstra-pr-gen skill. Git-only; no project registration required |
-| `recap` | `src/commands/inspect/recap.mjs` | `okstra recap <assemble\|record>` Node wrapper backing the okstra-inspect `recap` facet |
+| `recap` | `src/commands/inspect/recap.mjs` | `okstra recap <assemble\|record\|note>` Node wrapper backing the okstra-inspect `recap` facet — `assemble` is a read-only phase-transition summary, `record` appends one line to `recap/recap-log.jsonl`, and `note` writes an agent-authored note under `notes/` and prints the `--clarification-response` argument for a follow-up run |
+| `stage-map` | `src/commands/inspect/stage-map.mjs` | `okstra stage-map <task-key>` — exposes a task's implementation-planning Stage Map as JSON (`stages[].{stage_number,title,depends_on,step_count}` + consumer-state-based `doneStages[]`). If there is no Stage Map, `stages: []`. The read-side basis from which `okstra-schedule-gen` derives stage units and dependency closure |
+| `design-prep` | `src/commands/inspect/design-prep.mjs` | `okstra design-prep <list\|show\|write>` thin shim into `scripts/okstra_ctl/design_prep.py` — queries (`list`/`show`) the design items that implementation-planning pre-authored with AI, and records the user-confirmed responses as an append-only sidecar under `design-prep-inputs/` (`write`, `--confirmed` required). It never modifies the report snapshot |
 | `rollup` | `src/commands/inspect/rollup.mjs` | `okstra rollup` thin shim into `scripts/okstra_ctl/rollup.py` — read-only cross-task roll-up backing the okstra-rollup skill |
 | `usage-report` | `src/commands/inspect/usage-report.mjs` | `okstra usage-report` thin shim into `scripts/okstra_ctl/usage_report.py` — read-only project usage snapshot backing the okstra-usage skill |
 | `container` | `src/commands/inspect/container.mjs` | `bin okstra container` thin shim into `scripts/okstra_ctl/container.py` for the okstra-container-build skill |
@@ -206,8 +208,8 @@ Top-level scripts:
 | `okstra-render-report-views.py` | Render self-contained HTML views from final-report Markdown |
 | `okstra-error-log.py` | Normalize worker/lead error sidecars |
 | `okstra-spawn-followups.py` | Follow-up spawning helper |
-| `okstra-trace-cleanup.sh` | tmux okstra pane cleanup (worker-agent + trace, lead pane 제외); `--reclaim-completed` 모드는 `@okstra_status` 가 종료(stage=exited)인 trace pane 만 회수하고 진행 중 pane 은 보존 |
-| `okstra-subagent-reclaim.sh` | 활성 run 을 순회하며 완료된 trace pane 만 회수하는 엔트리 (`SubagentStop`/`TaskCompleted` 훅 배선) |
+| `okstra-trace-cleanup.sh` | tmux okstra pane cleanup (worker-agent + trace, excluding the lead pane); the `--reclaim-completed` mode reclaims only trace panes whose `@okstra_status` is terminated (stage=exited) and preserves in-progress panes |
+| `okstra-subagent-reclaim.sh` | entry that walks active runs and reclaims only completed trace panes (wired to the `SubagentStop`/`TaskCompleted` hooks) |
 
 ### 4.3 `scripts/okstra_ctl/` — Python orchestration core
 
@@ -216,50 +218,68 @@ Important modules:
 | Module | Role |
 |---|---|
 | `run.py` | `prepare_task_bundle()` single authority and CLI parser |
-| `implementation_stage.py` | `implementation` 단일-stage run 오케스트레이션 — Stage Lifecycle Snapshot 읽기 → 가용 Stage Map entry 선택 → 격리 stage worktree provision → 선택 stage 를 run context 로 발행 (`run.py` 에서 추출) |
-| `stage_targets.py` | Stage readiness/verification 정책 SSOT — Stage Lifecycle Snapshot(`consumers.jsonl` ledger + carry sidecar backfill + active registry reservation)으로 어떤 stage 가 실행 가능한지, 어느 commit 에서 분기하는지, final-verification 이 무엇을 검사하는지 결정. `order_stage_closure` 는 wizard 멀티선택 stage 집합의 의존성 closure 를 Kahn 위상정렬해 `chain-stages` 무인 연쇄 순서를 산출 |
-| `stage_reconcile.py` | stage prepare 흐름 공용 best-effort git reconciliation (`git_reconcile.auto_reconcile` 위임; advisory — 실패는 stderr 보고만, dependency gate 가 권위 판정 유지) |
-| `incremental_scope.py` | `implementation-planning` clarification 재실행의 증분 재검증 판정 (결정적 순수 함수) — 직전 run data.json 의 `implementationPlanning.stageMap` 에서 의존성 그래프를 읽고, base-ref SHA 불변 + 영향 stage 의 `downstream_stage_closure` 가 전체 stage 의 과반 이하일 때만 `mode="incremental"` 을 반환. CLI: `okstra incremental-scope` |
-| `incremental_carry.py` | 증분 재실행의 carry 병합 — 직전 run 의 plan-item verdict 중 이번 run 이 재검증하지 않은 항목을 `carriedForwardFromSeq` 태그와 함께 현재 data.json 에 병합. `schemaVersion` drift 시 `CarryError` 로 비영 종료해 full 폴백을 유도. CLI: `okstra incremental-carry` |
+| `implementation_stage.py` | `implementation` single-stage run orchestration — read the Stage Lifecycle Snapshot → pick an available Stage Map entry → provision an isolated stage worktree → publish the selected stage as run context (extracted from `run.py`) |
+| `stage_targets.py` | Stage readiness/verification policy SSOT — from the Stage Lifecycle Snapshot (`consumers.jsonl` ledger + carry sidecar backfill + active registry reservation) it decides which stage is runnable, which commit it branches from, and what final-verification checks. `order_stage_closure` topologically sorts (Kahn) the dependency closure of the wizard's multi-selected stage set to produce the unattended `chain-stages` chaining order |
+| `stage_reconcile.py` | best-effort git reconciliation shared by the stage prepare flow (delegates to `git_reconcile.auto_reconcile`; advisory — failures are only reported to stderr, the dependency gate stays authoritative) |
+| `design_surfaces.py` | deterministic detection of an `implementation-planning` stage's design surface — matches the stage's file-path tokens/suffixes/patterns and action wording via `SurfaceRule` to derive which design input the stage needs among domain contract, DB/table schema, external interface, transaction/consistency, transformation mapping, lifecycle, rollout/observability, and manual user test, plus its evidence (`TriggerEvidence`). An unmappable structure raises `DesignSurfaceError` |
+| `design_prep.py` | fingerprint / materialize / resolve backend for design-preparation requests (CLI: `okstra design-prep <list\|show\|write>`) — computes an assessment fingerprint from the approved planning snapshot's `ASSESSMENT_FIELDS`, idempotently writes an Okstra-owned request under `design-prep-requests/`, and resolves the highest-revision append-only user response under `design-prep-inputs/` whose fingerprint matches as the effective response. Keeps the three authorities (report snapshot / Okstra request / user input) separate and never modifies the report or existing revisions. Sidecar I/O is protected by a directory-fd anchor + flock |
+| `incremental_scope.py` | incremental re-verification decision for an `implementation-planning` clarification re-run (deterministic pure function) — reads the dependency graph from the previous run data.json's `implementationPlanning.stageMap` and returns `mode="incremental"` only when the base-ref SHA is unchanged and the affected stages' `downstream_stage_closure` is at most half of all stages. CLI: `okstra incremental-scope` |
+| `incremental_carry.py` | carry merge for an incremental re-run — merges the previous run's plan-item verdicts that this run does not re-verify into the current data.json with a `carriedForwardFromSeq` tag. On `schemaVersion` drift it exits non-zero with `CarryError` to force a full fallback. CLI: `okstra incremental-carry` |
 | `run_context.py` | Per-task mutex, run context and run-input persistence; `consumers_mutex` helper for atomic `consumers.jsonl` writes |
-| `path_hints.py` | Compact path-hint persistence + legacy context hydration — `run-context` / `active-run-context` 를 schemaVersion `2.0` 의 `identity` + `pathHints` compact schema 로 저장하고, host-side reader 가 읽는 순간 기존 flat path key(`RUN_MANIFEST_RELATIVE_PATH`, `TEAM_STATE_PATH` 등)를 메모리에서 hydrate |
+| `path_hints.py` | Compact path-hint persistence + legacy context hydration — stores `run-context` / `active-run-context` in the schemaVersion `2.0` `identity` + `pathHints` compact schema, and hydrates the legacy flat path keys (`RUN_MANIFEST_RELATIVE_PATH`, `TEAM_STATE_PATH`, etc.) in memory the moment the host-side reader reads them |
 | `consumers.py` | Append-only `consumers.jsonl` writer + reader — records which `implementation` runs consumed which `implementation-planning` stage |
-| `implementation_outcome.py` | Artifact-derived implementation phase outcome 재조합 — `runs/implementation/carry/stage-<N>.json` + `consumers.jsonl` + 승인 Stage Map 을 읽어 `phaseOutcome.implementation` 도출, 모든 stage 가 pass-grade carry evidence 면 `workflow.nextRecommendedPhase` 를 `final-verification` 으로 보정 (`contract-violated` 감사 정보는 유지) |
-| `paths.py` | Path/sequence computation for task/run artifacts (recap 디렉터리/로그 경로 포함) |
-| `recap.py` | okstra-inspect `recap` facet 의 결정론적 백엔드 — `assemble` 은 timeline 에서 run 간 phase 전이를 조립, `record` 는 `<task-root>/recap/recap-log.jsonl` 에 요약·Q&A append-only 기록 (다른 task 산출물 불변) |
+| `implementation_outcome.py` | Artifact-derived reconstruction of the implementation phase outcome — reads `runs/implementation/carry/stage-<N>.json` + `consumers.jsonl` + the approved Stage Map to derive `phaseOutcome.implementation`, and when every stage has pass-grade carry evidence it corrects `workflow.nextRecommendedPhase` to `final-verification` (keeping the `contract-violated` audit information) |
+| `paths.py` | Path/sequence computation for task/run artifacts (including recap directory/log paths) |
+| `recap.py` | deterministic backend for the okstra-inspect `recap` facet — `assemble` builds the cross-run phase transitions from the timeline, `record` append-only writes a summary/Q&A to `<task-root>/recap/recap-log.jsonl` (other task artifacts unchanged) |
 | `render.py` | task manifest, run manifest, timeline, task index, discovery, team-state, prompt/template render |
 | `workflow.py` | Phase sequence, allowed outputs, forbidden actions, next phase |
 | `workers.py`, `models.py` | Worker roster; `models.py` is the model catalog SSOT (`ModelSpec` per alias + `ROLE_DEFAULTS`) — add-a-model single reference point from which picker options, codex pricing, and role defaults all derive |
 | `worktree.py`, `worktree_registry.py` | One worktree per task-key, branch registry, sync dirs/files/snapshots |
 | `project_meta.py`, `resolver.py`, `path_resolve.py` | Project/task/run resolution |
 | `clarification_items.py` | Unified §5 clarification table parser and approval blockers |
-| `md_table.py` | Markdown pipe-table escape/split SSOT — `mdcell` 필터(`escape_pipes`)와 `\|` 인식 `split_pipe_row`; renderer·HTML view·validators 공용 |
+| `md_table.py` | Markdown pipe-table escape/split SSOT — the `mdcell` filter (`escape_pipes`) and the `\|`-aware `split_pipe_row`; shared by the renderer, HTML view, and validators |
 | `qa_commands.py` | QA command deny-list validation for plans |
 | `pr_template.py` | PR body template resolution for release-handoff |
 | `report_views.py`, `render_final_report.py`, `final_report_schema.py` | Final-report data.json → Markdown → Report View Model → self-contained HTML pipeline |
-| `final_report_paths.py`, `report_view_artifacts.py` | Final-report markdown/data.json 쌍 및 생성 view artifact(HTML view, user-responses 디렉터리) 경로 helper SSOT |
+| `final_report_paths.py`, `report_view_artifacts.py` | Path-helper SSOT for the final-report markdown/data.json pair and the generated view artifacts (HTML view, user-responses directory) |
 | `wizard.py` | `okstra-run` prompt state machine; user-facing Korean strings live in `prompts/wizard/prompts.ko.json` |
-| `wizard_stage_intent.py` | `okstra-run` wizard 출력의 stage 관련 intent projection — whole-task(`__whole_task__`) vs 단일/멀티 stage 선택을 render-args 로 정규화 (`resolve_wizard_stage_intent`) |
+| `wizard_stage_intent.py` | stage-related intent projection of the `okstra-run` wizard output — normalizes whole-task (`__whole_task__`) vs single/multi stage selection into render-args (`resolve_wizard_stage_intent`) |
 | `index.py`, `jsonl.py`, `reconcile.py`, `listing.py`, `batch.py`, `backfill.py` | `~/.okstra` run index and history operations |
-| `run_index_row.py` | `~/.okstra` run-index row 의 생성/축약(slim)/복원(hydrate) 단일 참조점 — runId SSOT, projectId raw 보존 |
-| `error_report.py`, `error_log_core.py`, `error_zip.py` | okstra-inspect errors/error-zip facet 백엔드 — `error_log_core` 는 `errors-*.jsonl` 글롭·파싱·집계 read-only 코어, `error_report` 는 errors facet 렌더, `error_zip` 은 cross-project run 디렉터리 수집·allowlist 익명화·클러스터 집계·zip 생성 |
-| `log_report.py`, `time_report.py` | okstra-inspect logs/time facet 의 read-side 백엔드 (`okstra log-report` 는 wrapper sidecar 로그 인벤토리, `okstra time-report` 는 task 단위 시간 집계) |
-| `rollup.py` | okstra-rollup 스킬의 read-side 백엔드 — catalog 를 task-group(또는 프로젝트 전체) 단위로 fan-out 해 task 별 run 수·소요 시간(raw ms)·에러 수·최신 report 경로와 group 차원 합계/상태·카테고리·phase 분포를 deterministic 하게 집계. `time_report`/`error_log_core` 함수 재사용, report 본문 종합은 skill 에 위임 |
+| `run_index_row.py` | single reference point for creating / slimming / hydrating a `~/.okstra` run-index row — runId SSOT, preserves projectId raw |
+| `error_report.py`, `error_log_core.py`, `error_zip.py` | backend for the okstra-inspect errors/error-zip facets — `error_log_core` is the read-only core that globs/parses/aggregates `errors-*.jsonl`, `error_report` renders the errors facet, and `error_zip` collects cross-project run directories, allowlist-anonymizes, aggregates clusters, and produces a zip |
+| `log_report.py`, `time_report.py` | read-side backend for the okstra-inspect logs/time facets (`okstra log-report` is the wrapper sidecar log inventory, `okstra time-report` is per-task time aggregation) |
+| `rollup.py` | read-side backend for the okstra-rollup skill — fans the catalog out per task-group (or the whole project) and deterministically aggregates each task's run count, elapsed time (raw ms), error count, and latest report path, plus group-level totals/status, category, and phase distribution. Reuses the `time_report`/`error_log_core` functions and delegates report-body synthesis to the skill |
 | `usage_report.py` | Read-only okstra-usage backend — scans the whole current project's recent run timelines, defaults to 30 days, and returns task-type coverage, raw/billable tokens, known USD cost, CPU-sum and wall-clock milliseconds, unavailable reason counts, and unmatched pricing models |
-| `json_registry.py` | 작은 okstra 레지스트리 공용 flock + atomic JSON persistence (`registry_lock`/`load_registry_json`/`save_registry_json`) — `container_registry`·`worktree_registry` 가 공유 |
-| `stage_integrate.py` | whole-task stage 통합(머지)+worktree teardown 코어 (`integrate_stages`) — whole-task final-verification 진입·`okstra integrate-stages`·container up 이 공유 |
-| `resolve_task_key.py` | bare task-id → `task-catalog.json` 후보 entry 해석 skill 공용 helper (`okstra resolve-task-key`) |
+| `json_registry.py` | shared flock + atomic JSON persistence for small okstra registries (`registry_lock`/`load_registry_json`/`save_registry_json`) — shared by `container_registry` and `worktree_registry` |
+| `stage_integrate.py` | whole-task stage integration (merge) + worktree teardown core (`integrate_stages`) — shared by whole-task final-verification entry, `okstra integrate-stages`, and container up |
+| `resolve_task_key.py` | shared skill helper resolving a bare task-id → `task-catalog.json` candidate entries (`okstra resolve-task-key`) |
 | `session.py`, `tmux.py`, `seeding.py`, `locks.py`, `invocation.py`, `sequence.py`, `ids.py`, `material.py` | Supporting lifecycle helpers |
-| `pane_reclaim.py` | 완료 trace pane 회수 대상 판정; 진행-중 status 집합을 `reconcile.NON_TERMINAL_RECENT_STATUSES` SSOT 에서 import |
-| `improvement_lenses.py` | improvement-discovery phase 의 lens enum SSOT + cap 상수 (DEFAULT 8, ABSOLUTE 12, MIN/MAX PRIORITY 1/4, SOURCE_WORKERS) |
-| `container.py` | okstra-container-build 공개 스킬의 `okstra container` 수렴 entrypoint — `provision_container_group` + `up`/`status`/`logs`/`stop-watcher`/`down` 디스패치, env override 합성, compose argv 조립, 컨테이너별 watcher 기동 |
-| `container_registry.py` | flock-guarded 보조 인덱스 — 컨테이너 그룹별 tmux session/pane 및 watcher findings 추적 |
-| `plan_run_root.py` | `approved_plan_path` → `plan_run_root` 파생 + task-key 역추적 공유 헬퍼 |
+| `pane_reclaim.py` | decides which completed trace panes are reclaim targets; imports the in-progress status set from the `reconcile.NON_TERMINAL_RECENT_STATUSES` SSOT |
+| `improvement_lenses.py` | lens enum SSOT + cap constants for the improvement-discovery phase (DEFAULT 8, ABSOLUTE 12, MIN/MAX PRIORITY 1/4, SOURCE_WORKERS) |
+| `container.py` | the `okstra container` convergence entrypoint of the okstra-container-build public skill — `provision_container_group` + `up`/`status`/`logs`/`stop-watcher`/`down` dispatch, env-override synthesis, compose argv assembly, and per-container watcher startup |
+| `container_registry.py` | flock-guarded auxiliary index — tracks per-container-group tmux session/pane and watcher findings |
+| `plan_run_root.py` | shared helper deriving `approved_plan_path` → `plan_run_root` and back-tracing the task-key |
 | `manager_cli.py` | `okstra manager` Python entrypoint — manager init/discover/new/task subcommands and JSON output |
 | `manager_paths.py` | Manager state path SSOT under `~/.okstra/managers/<manager-id>/`; slug fallback uses `u-<sha1-prefix>` when a safe segment would be empty |
 | `manager_store.py` | Manager-owned state mutation — project membership, task planning, assignment, directives, event append |
 | `manager_sync.py` | One-way child project `.okstra` snapshot reader; corrupt child state becomes row-level `error` so other children continue |
 | `manager_launch.py` | Child launch packet and manager child context renderer; records `prepared` launch metadata/events without changing project-local task state |
+| `dispatch_core.py` | Backend-neutral worker dispatch core — worker execution/collection logic shared by any lead runtime (Claude/Codex/external) |
+| `codex_dispatch.py` | Codex lead CLI-worker dispatcher — the `okstra codex-dispatch` backend. Reads the run manifest to run the Codex-side supported worker subset and performs token-usage substitution, view render, follow-up, and validation |
+| `analysis_packet.py` | assembles the compact analysis-worker input packet for a task run (error-analysis phase worker input) |
+| `context_cost.py` | read-side context-cost estimator for a prepared okstra task bundle (the `okstra context-cost` backend) |
+| `schema_excerpt.py` | generates a task-type-scoped excerpt of the final-report schema — a schema reduction to inject into the worker/lead prompt |
+| `work_categories.py` | requirements-discovery work-category (domain) **SSOT** (`is_valid_category`) — the work-category allowlist is defined only here |
+| `model_discovery.py` | pre-dispatch model-identity normalization for CLI workers — roster-gated label correction + a per-role reasoning-effort policy (deterministic, no per-run improvisation) for CLIs (agy) that bake effort into the model name |
+| `lead_runtime.py` | lead runtime metadata shared by the render and prepare paths (`LeadRuntimeInfo`) |
+| `lead_events.py` | structured JSONL events emitted by non-Claude lead runtimes |
+| `team_reconcile.py` | stale team-member reconciliation at run-end teardown |
+| `worker_prompt_headers.py` | shared rendering of the worker prompt anchor header (`worker_prompt_headers`) |
+| `wrapper_status.py` | worker wrapper status sidecar reader — the host-side reader of the sidecar written by `okstra-wrapper-status.py` (the heartbeat writer) |
+| `task_target.py` | shared helper resolving `task-key → (task_root, project_root)` (`resolve_task_root`) |
+| `graphify_cmd.py` | scope wrapper for the okstra-graphify skill — `resolve_scope` + `assemble` + `okstra graphify` subcommand dispatch. Forces the corpus to `.okstra` and outputs to `.okstra/graph/` |
+
+> `i18n.py` (the final-report i18n dictionary loader + Jinja2 lookup) is an intentionally undocumented internal helper — it is a render helper that users and contributors do not need to know about in the canonical docs, so it is excluded from the module map.
 
 ### 4.4 `scripts/okstra_project/`
 
@@ -302,10 +322,10 @@ Token/cost accounting:
 
 `schemas/final-report-v1.0.schema.json` is the final-report data.json contract. The report-writer worker writes `final-report-<task-type>-<seq>.data.json`; the renderer produces Markdown from that JSON.
 
-Optional (v1.0 하위호환) 최상위 키:
+Optional (v1.0 backward-compatible) top-level keys:
 
-- `readerSummary` — 사람이 먼저 읽는 요약 블록. 존재하면 5개 필드(`decision`, `humanActionRequired`, `blockingItems`, `safeToSkip`, `recommendedCommand`)가 모두 필수. 없는 기존 data.json 도 그대로 렌더됩니다(HTML dashboard 는 `verdictCard` 로 폴백).
-- `implementationPlanning.incrementalDecision` — 증분 재검증 판정 (`mode`, `reverifyStages`, `carryStages`, `reason`). `mode == "incremental"` 이면 렌더러가 `### 0.1 Incremental Re-Verification Scope` 감사 블록을 emit 하고 `validators/validate-run.py` 가 그 부재를 차단합니다.
+- `readerSummary` — the summary block a human reads first. When present, all five fields (`decision`, `humanActionRequired`, `blockingItems`, `safeToSkip`, `recommendedCommand`) are required. Existing data.json without it still renders as-is (the HTML dashboard falls back to `verdictCard`).
+- `implementationPlanning.incrementalDecision` — the incremental re-verification decision (`mode`, `reverifyStages`, `carryStages`, `reason`). When `mode == "incremental"`, the renderer emits the `### 0.1 Incremental Re-Verification Scope` audit block and `validators/validate-run.py` blocks its absence.
 
 ### 4.9 `validators/`
 
@@ -313,10 +333,10 @@ Optional (v1.0 하위호환) 최상위 키:
 |---|---|
 | `validate-run.py` | Run/final-report contract validation |
 | `validate-brief.py`, `validate-brief.sh` | Brief frontmatter/body contract validation |
-| `validate-report-views.py` | HTML view validation (form-control 위치 / 외부 URL 부재 / stale source digest / Response ID parity) |
+| `validate-report-views.py` | HTML view validation (form-control placement / no external URLs / stale source digest / Response ID parity) |
 | `validate-schedule.py` | Schedule section/order/code validation |
-| `validate-implementation-plan-stages.py` | Stage Map 구조 강제 — S1–S8 규칙 검사 (`## 5.5 Stage Map` + `## 5.5.<i> Stage <i>` 섹션, stage 당 step ≤ 8 등) |
-| `validate_improvement_report.py` | improvement-discovery final-report 의 11항목 contract 강제. `validate-run.py` 가 `task_type == "improvement-discovery"` 일 때 자동 호출 |
+| `validate-implementation-plan-stages.py` | enforces the Stage Map structure — checks the S1–S8 rules (`## 5.5 Stage Map` + `## 5.5.<i> Stage <i>` sections, ≤ 8 steps per stage, etc.) |
+| `validate_improvement_report.py` | enforces the 11-item contract of the improvement-discovery final-report. Automatically invoked by `validate-run.py` when `task_type == "improvement-discovery"` |
 | `validate-workflow.sh` | End-to-end fixture workflow validation |
 | `lib/*.sh` | Shared shell validator helpers and fixtures |
 
@@ -332,7 +352,7 @@ Optional (v1.0 하위호환) 최상위 키:
 | `okstra-inspect` | yes | Unified read-side — sub-commands `status` (lifecycle + workStatus), `history` (past runs / re-run / resume), `report` (find final-report), `time` (elapsed-time breakdown), `logs` (wrapper log inventory + cleanup), `cost` (task bundle context/read cost) |
 | `okstra-rollup` | yes | Cross-task roll-up — aggregate runs/time/errors across a task-group (or whole project) and synthesize a digest from the report files |
 | `okstra-usage` | yes | Read-only project usage snapshot — aggregate recent run coverage, tokens, known cost, CPU, and wall-clock time by task type (default: 30 days) |
-| `okstra-schedule` | yes | Generate task-group schedule |
+| `okstra-schedule-gen` | yes | Generate task-group schedule |
 | `okstra-container-build` | yes | Non-linear deploy tool — deploy a verified task's code as a docker compose group and watch each container (sub-commands `up` / `status` / `logs` / `stop-watcher` / `down`) |
 | `okstra-graphify` | yes | Knowledge graph over the project's own `.okstra/` memory — final reports, `decisions/*.md`, `glossary.md`; scope restricted to `.okstra/`, output under `.okstra/graph/` (sub-commands `build` / `query` / `path` / `explain` / `mcp` / `wiki`) |
 | `okstra-pr-gen` | yes | Register PR body templates under `~/.okstra/template/pr/` and generate a PR description from a branch diff (drives `okstra pr template` / `branches` / `gen`). **Global skill** — needs a Git repo, not `<PROJECT_ROOT>/.okstra/project.json` |
@@ -347,20 +367,20 @@ Optional (v1.0 하위호환) 최상위 키:
 | File | Role |
 |---|---|
 | `agents/workers/claude-worker.md` | Claude analyzer/verifier/executor spec |
-| `agents/workers/codex-worker.params.json` | Codex analyzer/verifier/executor wrapper params (build 가 `_cli-wrapper-template.md` 로 `.md` 렌더) |
-| `agents/workers/antigravity-worker.params.json` | Antigravity analyzer/verifier/executor wrapper params (build 가 `_cli-wrapper-template.md` 로 `.md` 렌더) |
+| `agents/workers/codex-worker.params.json` | Codex analyzer/verifier/executor wrapper params (build renders `.md` via `_cli-wrapper-template.md`) |
+| `agents/workers/antigravity-worker.params.json` | Antigravity analyzer/verifier/executor wrapper params (build renders `.md` via `_cli-wrapper-template.md`) |
 | `agents/workers/report-writer-worker.md` | data.json SSOT author and audit sidecar writer |
 
 The neutral lead lifecycle contract lives at `prompts/lead/okstra-lead-contract.md`. Host mappings live under `prompts/lead/adapters/`: `claude-code.md`, `codex.md`, and `external.md`. All are runtime resources installed under `~/.okstra/prompts/lead/`, not agent skills.
 
 ### 4.12 `tests/` and `tests-e2e/`
 
-- `tests/`: pytest modules, 도메인별 하위폴더로 계층화 — `run/`(prepare·dispatch·run-index 코어), `contract/`(validator·repo/docs 계약·phase 규칙·profile), `report/`(render·convergence·language·template), `inspect/`(recap·error·context-cost·token-usage), `worktree/`(worktree·stage 격리·reconcile·reclaim), `wizard/`, `handoff/`. 공용 경로 SSOT 는 `tests/_paths.py`(`REPO_ROOT`/`TESTS_DIR`/`FIXTURES`), `tests/` 를 import 경로에 올리는 설정은 repo 루트 `pytest.ini`(`pythonpath = tests`). 픽스처는 `tests/fixtures/`.
-- `tests-e2e/`: `scenario-<id>-<name>.sh` 셸 시나리오 (record-start/reconcile, rerun, task lock, agent install, report view 등).
+- `tests/`: pytest modules, layered into per-domain subfolders — `run/` (prepare/dispatch/run-index core), `contract/` (validator, repo/docs contract, phase rules, profile), `report/` (render, convergence, language, template), `inspect/` (recap, error, context-cost, token-usage), `worktree/` (worktree, stage isolation, reconcile, reclaim), `wizard/`, `handoff/`. The shared path SSOT is `tests/_paths.py` (`REPO_ROOT`/`TESTS_DIR`/`FIXTURES`), and the setting that puts `tests/` on the import path is the repo-root `pytest.ini` (`pythonpath = tests`). Fixtures live in `tests/fixtures/`.
+- `tests-e2e/`: `scenario-<id>-<name>.sh` shell scenarios (record-start/reconcile, rerun, task lock, agent install, report view, etc.).
 
 ---
 
-## 5. 주요 런타임 모듈
+## 5. Key runtime modules
 
 ### 5.1 Prepare flow
 
@@ -414,7 +434,7 @@ The Markdown is derived, not the authoring source. The schema is the contract.
 
 ---
 
-## 6. 설치 후 저장소 구조
+## 6. Post-install layout
 
 ```text
 ~/.okstra/
@@ -455,16 +475,18 @@ The Markdown is derived, not the authoring source. The schema is the contract.
         ├── sessions/
         ├── worker-results/
         ├── user-responses/
-        ├── carry/                    # implementation 전용: stage-<N>.json evidence sidecar
+        ├── design-prep-requests/     # implementation-planning only: Okstra-owned AI draft request (deterministic, idempotent)
+        ├── design-prep-inputs/       # implementation-planning only: user/wizard confirmation responses (append-only revision)
+        ├── carry/                    # implementation only: stage-<N>.json evidence sidecar
         ├── logs/
-        └── (consumers.jsonl)         # implementation-planning 전용: impl-run 역링크 누적 파일
+        └── (consumers.jsonl)         # implementation-planning only: impl-run backlink accumulation file
 ```
 
 Project-local `<PROJECT_ROOT>/.claude/settings.local.json` is provisioned as a symlink so spawned agents can load okstra worker-wrapper permissions.
 
 ---
 
-## 7. 핵심 워크플로우
+## 7. Core workflows
 
 ### 7.1 First setup
 
@@ -486,7 +508,7 @@ Project-local `<PROJECT_ROOT>/.claude/settings.local.json` is provisioned as a s
 |---|---|---|
 | `requirements-discovery` | Classify and route work | `error-analysis` or `implementation-planning` |
 | `error-analysis` | Reproduce and explain failure | `implementation-planning` |
-| `implementation-planning` | Compare options, produce approval-ready plan; 산출은 항상 `## 5.5 Stage Map` + N 개의 `## 5.5.<i> Stage <i>` 섹션 구조. `implementation` 은 stage 단위로 분할 실행 가능 | `implementation` after approval |
+| `implementation-planning` | Compare options, produce approval-ready plan; the output is always the `## 5.5 Stage Map` + N `## 5.5.<i> Stage <i>` section structure. `implementation` can be split and run per stage | `implementation` after approval |
 | `implementation` | Executor changes code, verifiers check independently | `final-verification` |
 | `final-verification` | Read-only acceptance verification | `release-handoff` if accepted |
 | `release-handoff` | User-selected commit/PR handoff | done or follow-up |
@@ -497,7 +519,7 @@ Final report artifacts live under `runs/<task-type>/reports/`. Human responses f
 
 ---
 
-## 8. 문서 유지보수 체크리스트
+## 8. Doc maintenance checklist
 
 When changing code, keep these docs in sync:
 
@@ -511,7 +533,7 @@ When changing code, keep these docs in sync:
 
 ---
 
-## 부록 A. Report / row ID 용어
+## Appendix A. Report / row ID glossary
 
 | Prefix / token | Meaning |
 |---|---|

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` |