okstra 0.123.0 → 0.125.0

package/docs/for-ai/skills/okstra-user-response.md

@@ -0,0 +1,48 @@
+# okstra-user-response AI Manual
+
+## Sources
+
+- Skill source: [`skills/okstra-user-response/SKILL.md`](../../../skills/okstra-user-response/SKILL.md)
+- Response core (CLI): [`scripts/okstra_ctl/user_response.py`](../../../scripts/okstra_ctl/user_response.py)
+- Node wrapper: [`src/commands/inspect/user-response.mjs`](../../../src/commands/inspect/user-response.mjs)
+
+## Purpose
+
+`okstra-user-response` answers the **unresolved clarification questions** an okstra run left behind (the open `C-*` rows under the final report's `## 1. Clarification Items`) **in-session**, and records those answers as a `runs/<type>/user-responses/` sidecar. The next `/okstra-run` auto-attaches this sidecar via `--clarification-response`.
+
+**Core principle — the skill never picks an answer for the user.** It only *presents* recommendations and alternatives; every `value` is the user's verbatim input. It does not call `write` until the user has explicitly confirmed (`confirmed`).
+
+Distinguish it from starting a run (`okstra-run`), inspecting a finished task (`okstra-inspect`), and generating a brief (`okstra-brief-gen`).
+
+## Sub-commands
+
+| Sub-command | What it does |
+|---|---|
+| `list` | List tasks that still have approval-open clarification (newest report first) |
+| `show` | Expand one report's open `C-*` rows (statement + recommended + alternatives + contextRefs) |
+| `write` | Record the collected answers (+ optional approval) as a `user-responses/` sidecar |
+
+## Preflight
+
+A single Bash call with the literal `okstra` token (not wrapped):
+
+```bash
+okstra preflight --runtime claude-code --json
+```
+
+`ok:true` → carry `projectRoot` and `projectId` as literals. `ok:false` → point to `/okstra-setup` and stop (retry a specific directory with `--cwd <dir>` — a leading `cd` breaks the permission match). Then resolve home once: `okstra paths --field home` → paste it literally into `--home`.
+
+## Flow
+
+1. **list**: `okstra user-response list --home <home> --project <projectId> --limit 3` → an array of `{taskKey, taskType, seq, reportPath, reportMtime, openApprovalCount, unreadable}`. If the array is empty, stop with "no open clarification". A 3-option picker (top recommendations + the final option always "Enter directly" for pasting a `reportPath`/`task-key` directly). `unreadable:true` is a §1 format drift — flag it with `⚠` and do not proceed (do not fabricate rows).
+2. **show**: `okstra user-response show --report <reportPath>` → `rows[]` with `resolvedRefs` (the `definition` of internal tokens such as `RB-002`/`§4.7`). **Do not paste the raw `statement` as the question.** For each open row present: (a) a **self-contained question** with internal tokens expanded inline first, (b) `recommended` (only a recommendation) in plain language, (c) `alternatives[]`, (d) the raw `id`+`statement` as a secondary traceability aid. If `definition` is `null`, resolve the report `§`/`path:line` yourself **using Read**.
+3. **decision (4 branches)**: the user picks one per item — Answer (accept the recommendation / own answer, verbatim), Ask-to-explain (explain only and hand the decision back to the user), Free-form (narrative verbatim), Hold+reframe (`disposition:"reframe"`, does not satisfy the approval gate). Each item's JSON: `{id, kind, value, rationale?, disposition}`.
+4. **echo → confirmed gate**: before `write`, echo the whole collection (each `id`·`disposition`·`value`·`rationale`·approval) as-is and get explicit confirmation. Never `write` before `confirmed`. On any change, re-echo and re-confirm.
+5. **approval (optional)**: only when the approval-blocking items are **all filled with an answer** and the user explicitly approved, `--approval '{"approved":true,"implementationOption":"<selected option>"}'`. If any item is unfilled/reframe, do not approve and say the gate is still open.
+6. **write**: `okstra user-response write --report <reportPath> --answers '<json>' [--approval '<json>'] --task-key <taskKey>` → report the returned `{sidecar:<path>}`. (When a same-named sidecar exists, the same `id` is overwritten with the new value and merged.)
+
+## Output Rules
+
+- Concise, in the language the user is using.
+- Give path guidance host-relative (`~/.okstra/...` or relative to `projectRoot`). Use repo paths only when pointing at a code source.
+- **Never hand-edit a rendered report** (`runs/*/reports/*.md` / `*.data.json`). Sidecar recording goes only through the `okstra user-response write` CLI.

package/docs/performance-improvement-plan-v2.md

@@ -105,7 +105,7 @@ The four default worker definitions are under `agents/workers/`.
 | B4 | Multiple renders/writes run serially during prepare | Low–medium | `scripts/okstra_ctl/run.py` render block | Lower priority |
 | B5 | The token usage collector scans session JSONL linearly | Low–medium | `scripts/okstra_token_usage/` | **Resolved** — P6 incremental cache implemented |
 | B6 | Simple work uses the same full workflow | Medium | task-type lifecycle / requirements routing | Fast-track design needed — largest remaining lever |
-| B7 | The report writer's final-report/data.json **output volume itself** is large (90–140 KB) | High | Measurements in §4.1 item 3 — 8–19 minutes of generation per run | Slim the report contract or select a report-writer model — **user decision required** |
+| B7 | The report writer's final-report/data.json **output volume itself** is large (90–140 KB) | High | Measurements in §4.1 item 3 — 8–19 minutes of generation per run | **Resolved** — default report-writer model lowered to `sonnet` (catalog `ROLE_DEFAULTS`) and a prose-budget dedup contract landed on the narrative blocks (`tests/contract/test_report_prose_budget.py`); fix runs additionally author reports incrementally (see the fix-run incremental reverification section in `docs/architecture.md`) |
 
 Established assumptions:
 
@@ -226,13 +226,13 @@ Goals:
 
 Cautions:
 
-- Before extracting `agents/workers/_common.md`, confirm that install/packaging paths and skill/agent loaders support includes.
+- Before extracting shared worker text into `agents/workers/_cli-wrapper-template.md`, confirm that install/packaging paths and skill/agent loaders support includes.
 - Merely moving text into a separate file can increase cost if the runtime does not inline it and the worker must read another file.
 
 Change targets:
 
-- `agents/workers/codex-worker.md`
-- `agents/workers/antigravity-worker.md`
+- `agents/workers/codex-worker.params.json`
+- `agents/workers/antigravity-worker.params.json`
 - `prompts/lead/team-contract.md`
 - Install/build packaging
 
@@ -253,7 +253,7 @@ Change targets:
 - `prompts/profiles/requirements-discovery.md`
 - `scripts/okstra_ctl/workflow.py`
 - Next-phase selection UI in `skills/okstra-run/SKILL.md`
-- `skills/okstra-status/SKILL.md`
+- `skills/okstra-inspect/SKILL.md` (the former `okstra-status` skill folded into `okstra-inspect`)
 - Validator expectations
 
 Caution:
@@ -363,7 +363,7 @@ The current plan correctly makes P1 the top priority, but the earlier phrases "7
 
 **2026-06-11 update** — Measurements in §4.1 confirm that P0/P1/P6, critic parallelization, and phaseTimeline instrumentation are complete, while B3 (report-writer input compression) was rejected. Only two priorities remain, and both require a user decision first:
 
-1. **B7 — reduce report-writer output-side cost**: slim the report contract (reduce the template/schema and change validator contracts) or lower the default report-writer model. Estimated saving: 5–12 minutes per run.
+1. **B7 — reduce report-writer output-side cost**: **done** — the default report-writer model is now `sonnet`, and the prose-budget contract deduplicates the narrative blocks. Remaining follow-up if further reduction is needed: evidence pointer-ization (option B of the slimming decision).
 2. **B6/P3 — fast-track routing**: shorten the lifecycle for simple work. Requires an approval-gate policy decision.
 
 ### Implementation Plan Links

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,8 +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\|note>` Node wrapper backing the okstra-inspect `recap` facet — `assemble` 는 read-only 위상 전이 요약, `record` 는 `recap/recap-log.jsonl` 1행 append, `note` 는 `notes/` 에 agent 작성 노트를 쓰고 후속 run 용 `--clarification-response` 인자를 출력 |
-| `stage-map` | `src/commands/inspect/stage-map.mjs` | `okstra stage-map <task-key>` — task 의 implementation-planning Stage Map 을 JSON 으로 노출 (`stages[].{stage_number,title,depends_on,step_count}` + consumer state 기반 `doneStages[]`). Stage Map 이 없으면 `stages: []`. `okstra-schedule-gen` 이 stage 단위와 의존성 폐포를 유도하는 read-side 근거 |
+| `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 |
@@ -207,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
 
@@ -217,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/`
 
@@ -303,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/`
 
@@ -314,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 |
 
@@ -348,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
 
@@ -415,7 +434,7 @@ The Markdown is derived, not the authoring source. The schema is the contract.
 
 ---
 
-## 6. 설치 후 저장소 구조
+## 6. Post-install layout
 
 ```text
 ~/.okstra/
@@ -456,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
 
@@ -487,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 |
@@ -498,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:
 
@@ -512,7 +533,7 @@ When changing code, keep these docs in sync:
 
 ---
 
-## 부록 A. Report / row ID 용어
+## Appendix A. Report / row ID glossary
 
 | Prefix / token | Meaning |
 |---|---|