okstra 0.122.0 → 0.124.0

package/docs/for-ai/skills/okstra-brief-gen.md

@@ -1,72 +1,72 @@
 # okstra-brief-gen AI Manual
 
-## 원천
+## Source
 
-- 스킬 원문: [`skills/okstra-brief-gen/SKILL.md`](../../../skills/okstra-brief-gen/SKILL.md)
-- brief 템플릿: [`templates/reports/brief.template.md`](../../../templates/reports/brief.template.md)
+- Skill source: [`skills/okstra-brief-gen/SKILL.md`](../../../skills/okstra-brief-gen/SKILL.md)
+- brief template: [`templates/reports/brief.template.md`](../../../templates/reports/brief.template.md)
 - brief validator: [`validators/validate-brief.py`](../../../validators/validate-brief.py)
 - lens enum SSOT: [`scripts/okstra_ctl/improvement_lenses.py`](../../../scripts/okstra_ctl/improvement_lenses.py)
 
-## 목적
+## Purpose
 
-`okstra-brief-gen`는 okstra pipeline에 넣을 task brief를 만든다. brief는 pre-discovery 산출물이다. 요구사항을 구현 계획으로 바꾸는 문서가 아니라, reporter가 준 원문과 AI가 확인한 증거/해석을 라벨로 분리해 다음 phase가 질문 없이 출발하게 만드는 handoff 문서다.
+`okstra-brief-gen` produces a task brief to feed into the okstra pipeline. A brief is a pre-discovery artifact. It is not a document that turns requirements into an implementation plan; it is a handoff document that separates the reporter's verbatim material from the AI-verified evidence/interpretation using labels, so the next phase can start without questions.
 
-출력 위치:
+Output location:
 
 ```text
 <PROJECT_ROOT>/.okstra/briefs/<task-group>/<brief-id>.md
 <PROJECT_ROOT>/.okstra/briefs/<task-group>/sub/.../<brief-id>.md
 ```
 
-## 세 가지 variant
+## Three variants
 
-| Variant | 입력 | Recommended next phase |
+| Variant | Input | Recommended next phase |
 |---|---|---|
-| Reporter input | 파일, 티켓, URL, 대화/자유 텍스트 | `requirements-discovery` 또는 `error-analysis` |
+| Reporter input | files, tickets, URLs, conversation/free text | `requirements-discovery` or `error-analysis` |
 | Codebase scan | scan scope, priority lenses, candidate cap, context | `improvement-discovery` |
-| Error feedback | `okstra error-zip`이 만든 zip의 단일 error cluster | `error-analysis` |
+| Error feedback | a single error cluster from the zip produced by `okstra error-zip` | `error-analysis` |
 
-## 핵심 불변식
+## Core invariants
 
-1. Source Material은 원문 보존 영역이다. paraphrase, 요약, 재정렬을 하지 않는다.
-2. AI의 해석, 파일 링크, 용어 매핑, format 변환은 모두 `Augmentation` 또는 `> augmented:` blockquote에 둔다.
-3. augmentation은 네 label 중 하나를 가진다: `evidence-link`, `format-conversion`, `terminology-mapping`, `intent-inference`.
-4. `intent-inference`는 `Open Questions`의 `intent-check:`와 짝을 이룬다. 이 관계는 `validators/validate-brief.py`가 검사한다.
-5. `terminology-mapping` augmentation은 `Open Questions`의 `terminology:`와 짝을 이룬다(validator 검사). 단 Step 4.5 결과 marker `applied glossary:` / `skipped glossary:`는 예외 — 짝 row가 필요 없다.
-6. reporter만 답할 수 있는 질문은 Step 6.5에서 모아 `## Reporter Confirmations`에 verbatim으로 기록한다.
-7. 티켓 분리/연결/순서 관계는 `## Related Task Graph`의 구조화된 table에 둔다. parent-id만으로 작업 순서를 추론하지 않는다.
-8. 모든 okstra-owned write는 `<PROJECT_ROOT>/.okstra/` 안에 둔다. 외부 파일은 reporter가 source로 명시한 경우에만 읽는다.
-9. `Open Questions`의 모든 row는 다섯 prefix 중 하나로 시작한다: `general:`, `terminology:`, `intent-check:`, `conversion-block:`, `adr-candidate:` (validator 강제). `adr-candidate:`는 신호일 뿐 — decision file은 `implementation-planning`이 `<PROJECT_ROOT>/.okstra/decisions/`에 쓴다.
+1. Source Material is a verbatim-preservation area. Do not paraphrase, summarize, or reorder.
+2. The AI's interpretation, file links, terminology mapping, and format conversion all go under `Augmentation` or a `> augmented:` blockquote.
+3. An augmentation carries one of four labels: `evidence-link`, `format-conversion`, `terminology-mapping`, `intent-inference`.
+4. `intent-inference` is paired with `intent-check:` in `Open Questions`. This relationship is checked by `validators/validate-brief.py`.
+5. A `terminology-mapping` augmentation is paired with `terminology:` in `Open Questions` (validator-checked). Exception: the Step 4.5 result markers `applied glossary:` / `skipped glossary:` need no paired row.
+6. Questions only the reporter can answer are collected in Step 6.5 and recorded verbatim under `## Reporter Confirmations`.
+7. Ticket split/link/order relations go in the structured table of `## Related Task Graph`. Do not infer work order from parent-id alone.
+8. Every okstra-owned write stays inside `<PROJECT_ROOT>/.okstra/`. External files are read only when the reporter explicitly cited them as source.
+9. Every row in `Open Questions` starts with one of five prefixes: `general:`, `terminology:`, `intent-check:`, `conversion-block:`, `adr-candidate:` (validator-enforced). `adr-candidate:` is only a signal — the decision file is written by `implementation-planning` into `<PROJECT_ROOT>/.okstra/decisions/`.
 
 ## Preflight
 
-단일 호출로 실행한다.
+Run as a single call.
 
 ```bash
 okstra preflight --runtime claude-code --json
 ```
 
-runtime이나 project setup이 없으면 `/okstra-setup`을 안내하고 멈춘다. 이 스킬에서 `npx` fallback을 쓰지 않는다.
+If runtime or project setup is missing, guide the user to `/okstra-setup` and stop. This skill does not use an `npx` fallback.
 
-## 입력 수집
+## Input collection
 
 ### Reporter input
 
-소스 종류는 하나 이상 가능하지만 각 소스는 `Source Material`에 별도 block으로 저장한다.
+More than one source type is allowed, but each source is stored as a separate block under `Source Material`.
 
-- File: 전체 파일을 읽고 그대로 넣는다.
-- Issue tracker ticket: Linear/Jira/GitHub/Notion을 감지하고 MCP 또는 `gh` CLI를 사용한다. 접근 도구가 없으면 사용자에게 body paste 또는 skip을 묻는다.
-- Link URL: fetch한다. 실패/로그인 wall/본문 truncation이면 사용자에게 paste를 요청한다.
-- User input: 대화 맥락이 충분하면 conversation synthesis, 부족하면 한 번만 free-text를 받는다.
+- File: read the entire file and insert it as-is.
+- Issue tracker ticket: detect Linear/Jira/GitHub/Notion and use MCP or the `gh` CLI. If no access tool is available, ask the user to paste the body or skip.
+- Link URL: fetch it. On failure / login wall / body truncation, ask the user to paste.
+- User input: if conversation context is sufficient, use conversation synthesis; if thin, take a single free-text input.
 
-티켓에 child/sub-task가 있으면 parent에서 한 번만 tree 처리 방식을 묻는다.
+If a ticket has children/sub-tasks, ask once at the parent how to handle the tree.
 
-- Full tree: descendant별 brief 생성.
-- Parent only: child key/URL을 Related Artifacts에 두고 `Related Task Graph`에는 `parent-of` edge를 남긴다.
-- Selected: 선택한 direct child branch만 재귀 처리.
+- Full tree: generate a brief per descendant.
+- Parent only: put child keys/URLs in Related Artifacts and leave a `parent-of` edge in `Related Task Graph`.
+- Selected: recurse only into the chosen direct-child branch.
 
-재귀 시 visited set은 `<tracker>:<ticket-id>`로 관리하고, 재실행에서는 기존 brief frontmatter의 `ticket-id` + `source-type`으로 reseed한다.
-Full tree 또는 Selected로 여러 brief를 만들면 모든 생성 brief에 같은 `Related Task Graph`를 복사한다. 그래야 child brief 하나만 downstream phase에 전달돼도 split topology, 선행/후행 관계, 중복 방지 신호가 유지된다.
+During recursion, manage the visited set as `<tracker>:<ticket-id>`, and on re-run reseed from the existing brief frontmatter's `ticket-id` + `source-type`.
+When Full tree or Selected produces multiple briefs, copy the same `Related Task Graph` into every generated brief. That way, even if only one child brief is passed to a downstream phase, the split topology, predecessor/successor relations, and de-duplication signals are preserved.
 
 `Related Task Graph` table schema:
 
@@ -77,39 +77,39 @@ Full tree 또는 Selected로 여러 brief를 만들면 모든 생성 brief에
 | To | task key, brief id, tracker id, or URL |
 | Direction | `directed` or `undirected` |
 | Source | tracker linked issue, task-list checkbox, reporter statement, manual split, prior okstra task |
-| Impact | downstream phase가 보존해야 할 의미 |
+| Impact | meaning the downstream phase must preserve |
 
-`depends-on`, `blocks`, parent/child, follow-up, split 관계는 `directed`다. `duplicates`, `related-to`는 `undirected`다. source가 없는 관계는 만들지 않는다.
+`depends-on`, `blocks`, parent/child, follow-up, and split relations are `directed`. `duplicates` and `related-to` are `undirected`. Do not create a relation with no source.
 
 ### Codebase scan
 
-수집값:
+Collected values:
 
-- `scan_scope`: 프로젝트 내부 실제 경로 목록.
-- `priority_lenses`: `LENSES` enum 중 1-4개.
-- `out_of_scope`: 선택.
-- `candidate_cap`: 1-12, 기본 8.
+- `scan_scope`: a list of real paths inside the project.
+- `priority_lenses`: 1–4 of the `LENSES` enum.
+- `out_of_scope`: optional.
+- `candidate_cap`: 1–12, default 8.
 - context, desired outcome, constraints.
 
-경로 존재, lens enum subset, candidate cap 범위는 작성 전 확인한다. 최종 검증은 `validate-brief.py`가 `scope: codebase`, `Scan Scope`, `Priority Lenses`를 검사한다.
+Verify path existence, the lens enum subset, and the candidate-cap range before writing. Final validation is done by `validate-brief.py`, which checks `scope: codebase`, `Scan Scope`, and `Priority Lenses`.
 
 ### Error feedback
 
-입력은 `okstra error-zip --out <path>`가 만든 zip이다.
+The input is the zip produced by `okstra error-zip --out <path>`.
 
-처리:
+Processing:
 
-1. zip에 `report.md`, `errors/anonymized.jsonl`이 있는지 확인한다.
-2. 빈발 cluster 표에서 cluster 하나만 선택한다.
-3. 선택 cluster의 anonymized records만 Source Material에 옮긴다.
-4. 서로 다른 errorType을 한 brief에 섞지 않는다.
-5. 다음 단계 안내는 `error-analysis`로 둔다.
+1. Confirm the zip contains `report.md` and `errors/anonymized.jsonl`.
+2. Pick exactly one cluster from the frequent-cluster table.
+3. Move only the chosen cluster's anonymized records into Source Material.
+4. Do not mix different errorTypes into one brief.
+5. Set the next-step guidance to `error-analysis`.
 
-## task-group과 파일명
+## task-group and filename
 
-task-group은 기존 group 추천을 먼저 보여준다. `okstra task-list`를 호출해 `tasks[]`의 distinct `taskGroup`을 최신순으로 뽑고, 최근 2개 + 직접 입력을 제공한다. tracker recursion에서는 child path를 만들기 전에 task-group을 먼저 받아야 한다.
+For task-group, show existing-group recommendations first. Call `okstra task-list`, extract the distinct `taskGroup` values from `tasks[]` in most-recent order, and offer the 2 most recent + enter-directly. In tracker recursion, task-group must be obtained before building any child path.
 
-파일 경로 규칙:
+File path rule:
 
 ```text
 depth 0: .okstra/briefs/<task-group>/<ticket-id>-<file-title>.md
@@ -117,56 +117,56 @@ depth 1: .okstra/briefs/<task-group>/sub/<ticket-id>-<file-title>.md
 depth N: .okstra/briefs/<task-group>/<sub/ repeated N>/<ticket-id>-<file-title>.md
 ```
 
-frontmatter의 `depth`는 path의 `sub/` 개수와 같아야 한다. validator가 검사한다.
+The frontmatter's `depth` must equal the number of `sub/` segments in the path. The validator checks this.
 
-충돌 시 기본은 Skip이다. Append suffix 또는 Overwrite를 제공할 수 있다. tracker multi-generation에서 bulk overwrite를 조용히 수행하지 않는다.
+On collision, the default is Skip. You may offer Append suffix or Overwrite. Do not silently perform a bulk overwrite in tracker multi-generation.
 
 ## Domain alignment
 
-먼저 okstra 내부 memory를 본다.
+First look at okstra's internal memory.
 
 - `<PROJECT_ROOT>/.okstra/glossary.md`
 - `<PROJECT_ROOT>/.okstra/decisions/`
-- 관련 task의 `history/fix-cycles.jsonl`
+- the related task's `history/fix-cycles.jsonl`
 
-외부 domain docs는 reporter가 source material로 명시했을 때만 읽는다. 충돌/모호 용어는 `Augmentation > Domain alignment`에 `terminology-mapping`으로 기록하고, `Open Questions`에 `terminology:` row를 둔다.
+Read external domain docs only when the reporter explicitly cited them as source material. Record conflicting/ambiguous terms under `Augmentation > Domain alignment` with `terminology-mapping`, and put a `terminology:` row in `Open Questions`.
 
-파일 path나 symbol이 언급되면 `Read`/`Grep`으로 실제 in-repo reference를 찾고 `evidence-link`로 남긴다. 매핑할 수 없으면 추측하지 않고 `conversion-block:` row로 둔다.
+When a file path or symbol is mentioned, find the actual in-repo reference with `Read`/`Grep` and record it as `evidence-link`. If it cannot be mapped, do not guess — leave a `conversion-block:` row.
 
 ## Sharpening pass
 
-full interview를 하지 않는다. source와 codebase로 채울 수 없는 gap만 묻는다.
+Do not run a full interview. Ask only about gaps that source and codebase cannot fill.
 
-기본 budget:
+Default budget:
 
-- 원문 스킬이 채움 대상으로 지정한 section당 최대 1문항.
-- terminology/fuzzy disambiguation 최대 2문항.
-- 전체 최대 6문항.
-- codebase-scan은 최대 8문항.
+- at most 1 question per section the source skill designates as fill-in.
+- at most 2 questions for terminology/fuzzy disambiguation.
+- at most 6 questions overall.
+- codebase-scan up to 8 questions.
 
-질문보다 codebase-first 확인을 우선한다. 남은 gap은 `_(none)_` 또는 `Open Questions`에 둔다.
+Prefer codebase-first checks over questions. Put remaining gaps in `_(none)_` or `Open Questions`.
 
-## template 작성 규칙
+## template writing rules
 
-템플릿은 `templates/reports/brief.template.md`가 SSOT다. section 순서, frontmatter key, top blockquote shape, HTML comment guidance를 따른다.
+The template `templates/reports/brief.template.md` is the SSOT. Follow the section order, frontmatter keys, top blockquote shape, and HTML comment guidance.
 
-Reporter input과 Error feedback:
+Reporter input and Error feedback:
 
-- `## Source Material` 유지.
-- `## Problem / Symptom` 유지.
-- `## Scan Scope`, `## Priority Lenses` 생략.
+- keep `## Source Material`.
+- keep `## Problem / Symptom`.
+- omit `## Scan Scope`, `## Priority Lenses`.
 
 Codebase scan:
 
-- frontmatter에 `scope: codebase`.
-- `## Source Material`, `## Problem / Symptom` 생략.
-- `## Scan Scope`, `## Priority Lenses` 유지.
+- `scope: codebase` in frontmatter.
+- omit `## Source Material`, `## Problem / Symptom`.
+- keep `## Scan Scope`, `## Priority Lenses`.
 
-빈 섹션을 날조하지 않는다. 값이 없으면 `_(none)_`를 사용한다.
+Do not fabricate empty sections. When there is no value, use `_(none)_`.
 
 ## frontmatter key
 
-모든 brief는 다음 key를 가진다. key set은 `validate-brief.py`에서 검사한다.
+Every brief carries the following keys. The key set is checked by `validate-brief.py`.
 
 - `type`
 - `brief-id`
@@ -179,42 +179,42 @@ Codebase scan:
 - `generator`
 - `reporter-confirmations`
 
-`brief-id`는 filename stem과 같아야 한다. depth 0의 `parent-id`는 `self`, descendant의 `parent-id`는 direct parent의 `brief-id`다.
+`brief-id` must equal the filename stem. At depth 0 the `parent-id` is `self`; a descendant's `parent-id` is its direct parent's `brief-id`.
 
 ## Recommended next phase
 
-brief 본문 top blockquote의 `Recommended next phase:`에 쓴다.
+Write it into the `Recommended next phase:` of the brief body's top blockquote.
 
 - observable error, repro, stack trace, error-zip record: `error-analysis`
-- ambiguity나 Open Questions가 큰 요구사항: `requirements-discovery`
+- a requirement with ambiguity or large Open Questions: `requirements-discovery`
 - `scope: codebase`: `improvement-discovery`
-- 애매하면 `requirements-discovery`
+- if ambiguous: `requirements-discovery`
 
-`okstra-run`을 자동으로 시작하지 않는다.
+Do not auto-start `okstra-run`.
 
 ## Reporter Confirmations
 
-`Open Questions`에서 reporter만 답할 수 있는 row를 모은다.
+Collect the rows in `Open Questions` that only the reporter can answer.
 
 - `intent-check:`
 - `conversion-block:`
 
-이미 `[CONFIRMED <date> → RC-N]` marker가 있으면 pending에서 제외한다. 사용자에게 지금 답할지 묻고, 답하면 `## Reporter Confirmations`에 verbatim으로 기록한다. row는 삭제하지 않고 marker를 붙인다.
+If a `[CONFIRMED <date> → RC-N]` marker already exists, exclude it from pending. Ask the user whether to answer now; if they answer, record it verbatim under `## Reporter Confirmations`. Do not delete the row — attach a marker.
 
-한 run당 최대 12문항. pending이 12개를 넘으면 `conversion-block:` → `intent-check:` 순으로 상위 12개만 묻고, 나머지는 `partial`로 남긴 뒤 어떤 row가 남았는지 사용자에게 알린다.
+At most 12 questions per run. If pending exceeds 12, ask only the top 12 in `conversion-block:` → `intent-check:` order, leave the rest as `partial`, then tell the user which rows remain.
 
-상태값:
+Status values:
 
-- `complete`: pending reporter-only row가 모두 답변됨. validator는 모든 `intent-check:`/`conversion-block:` row에 `[CONFIRMED …]` marker가 있는지 검사한다.
-- `partial`: 일부만 답변됨. validator는 최소 1개 row에 `[CONFIRMED …]` marker가 있는지 검사한다(아무것도 못 받았으면 `skipped`).
-- `skipped`: 사용자가 downstream phase에 넘기기로 함.
-- `pending`: handoff 전 상태로 보고 진행하지 않는다.
+- `complete`: all pending reporter-only rows are answered. The validator checks that every `intent-check:`/`conversion-block:` row has a `[CONFIRMED …]` marker.
+- `partial`: only some are answered. The validator checks that at least one row has a `[CONFIRMED …]` marker (if nothing was received, `skipped`).
+- `skipped`: the user chose to defer to a downstream phase.
+- `pending`: treated as a pre-handoff state; do not proceed.
 
-## 검증
+## Validation
 
-작성 후 handoff 메시지를 내기 전에 validator를 실행한다.
+After writing, run the validator before emitting the handoff message.
 
-설치본:
+Installed copy:
 
 ```bash
 ~/.okstra/lib/validators/validate-brief.sh "<PROJECT_ROOT>/.okstra/briefs" --briefs-root "<PROJECT_ROOT>/.okstra/briefs"
@@ -226,19 +226,19 @@ repo checkout:
 validators/validate-brief.sh "<PROJECT_ROOT>/.okstra/briefs" --briefs-root "<PROJECT_ROOT>/.okstra/briefs"
 ```
 
-실패하면 cited brief를 고치고 재실행한다. validator가 없을 때만 manual checklist로 대체한다.
-validator는 `Related Task Graph`가 있으면 table header, relation enum, direction enum, directed/undirected mismatch도 검사한다.
+On failure, fix the cited brief and re-run. Fall back to a manual checklist only when the validator is absent.
+When a `Related Task Graph` is present, the validator also checks the table header, relation enum, direction enum, and directed/undirected mismatch.
 
-## 완료 메시지
+## Completion message
 
-단일 brief:
+Single brief:
 
 ```text
 brief saved: <abs-path>
 next: /okstra-run  (recommended task-type: <phase>)
 ```
 
-multi-brief:
+Multi-brief:
 
 ```text
 briefs saved (N):
@@ -247,12 +247,12 @@ briefs saved (N):
 next: /okstra-run
 ```
 
-## 금지 패턴
+## Forbidden patterns
 
-- Source Material을 요약하거나 정리해서 넣기.
-- tracker/URL 내용을 도구 확인 없이 추측하기.
-- unlabelled augmentation 작성하기.
-- `intent-inference`를 `intent-check:` 없이 남기기.
-- 외부 docs/ADR에 decision file을 쓰기. okstra decision은 `<PROJECT_ROOT>/.okstra/decisions/`에만 해당한다.
-- child tree 전체를 silent overwrite하기.
-- brief 생성 직후 자동으로 `okstra-run` 시작하기.
+- Summarizing or tidying Source Material before inserting it.
+- Guessing tracker/URL content without tool verification.
+- Writing unlabelled augmentation.
+- Leaving `intent-inference` without `intent-check:`.
+- Writing a decision file into external docs/ADR. okstra decisions belong only in `<PROJECT_ROOT>/.okstra/decisions/`.
+- Silently overwriting an entire child tree.
+- Auto-starting `okstra-run` right after brief generation.

package/docs/for-ai/skills/okstra-container-build.md

@@ -1,89 +1,89 @@
 # okstra-container-build AI Manual
 
-## 원천
+## Source
 
-- 스킬 원문: [`skills/okstra-container-build/SKILL.md`](../../../skills/okstra-container-build/SKILL.md)
+- Skill source: [`skills/okstra-container-build/SKILL.md`](../../../skills/okstra-container-build/SKILL.md)
 - container CLI wrapper: [`src/commands/inspect/container.mjs`](../../../src/commands/inspect/container.mjs)
 - container runtime: [`scripts/okstra_ctl/container.py`](../../../scripts/okstra_ctl/container.py)
 - container registry: [`scripts/okstra_ctl/container_registry.py`](../../../scripts/okstra_ctl/container_registry.py)
 - stage integration gate: [`scripts/okstra_ctl/stage_targets.py`](../../../scripts/okstra_ctl/stage_targets.py)
 
-## 목적
+## Purpose
 
-`okstra-container-build`는 implementation task worktree의 `docker-compose.yml`을 이용해 사용자 테스트용 container group을 관리한다. okstra는 compose group에 task/run trace label을 붙이고, tmux watcher pane으로 로그/상태를 관찰한다.
+`okstra-container-build` manages a user-test container group using the `docker-compose.yml` in an implementation task worktree. okstra labels the compose group with the task/run trace and observes logs/status through a tmux watcher pane.
 
 ## sub-command
 
-| Sub-command | 역할 | side effect |
+| Sub-command | Role | side effect |
 |---|---|---|
-| `up` | implementation stages를 task worktree에 통합하고 `docker compose up -d`, healthcheck poll, watcher pane attach | container 생성/시작, watcher pane 생성 |
-| `status` | label query 기반 running container와 watcher metadata 확인 | 읽기 |
-| `logs` | watcher findings dir와 watcher entries 안내 | 읽기 |
-| `stop-watcher` | watcher/tail tmux panes만 회수 | container 유지, pane 제거 |
-| `down` | label query로 container group 제거, orphan watcher panes 회수 | container 종료/제거 |
+| `up` | Integrate the implementation stages into the task worktree, then `docker compose up -d`, poll healthchecks, attach the watcher pane | create/start containers, create watcher pane |
+| `status` | Check running containers (by label query) plus watcher metadata | read |
+| `logs` | Point at the watcher findings dir and watcher entries | read |
+| `stop-watcher` | Reap the watcher/tail tmux panes only | keep containers, remove panes |
+| `down` | Remove the container group by label query, reap orphan watcher panes | stop/remove containers |
 
 ## Preflight
 
-단일 호출:
+Single call:
 
 ```bash
 okstra preflight --runtime claude-code --json
 ```
 
-project setup이 없으면 `/okstra-setup` 안내 후 멈춘다. Docker daemon이 필요하다. Docker connection error가 나오면 Docker Desktop/daemon을 시작하라고 안내하고, 직접 Docker를 시작하지 않는다.
+If the project is not set up, point to `/okstra-setup` and stop. A Docker daemon is required. On a Docker connection error, tell the user to start Docker Desktop/daemon; do not start Docker yourself.
 
-## task-key 해석
+## task-key resolution
 
-대부분 sub-command는 full task-key가 필요하다.
+Most sub-commands need a full task-key.
 
-1. full task-key가 있으면 그대로 사용.
-2. bare task-id는 resolver 사용:
+1. If a full task-key is given, use it as-is.
+2. For a bare task-id, use the resolver:
 
 ```bash
 okstra resolve-task-key <task-id> --project-root <projectRoot> --json
 ```
 
-3. multiple match면 후보를 보여주고 선택 받는다.
-4. `down --all`만 task-key 없이 실행할 수 있다.
+3. On multiple matches, show the candidates and let the user pick.
+4. Only `down --all` can run without a task-key.
 
 ## intent routing
 
-명확한 동사:
+Clear verbs:
 
-- "띄워", "올려", "up": `up`
-- "상태", "status": `status`
-- "로그", "logs": `logs`
-- "watcher 멈춰", "stop-watcher": `stop-watcher`
-- "내려", "down", "종료": `down`
+- "bring up/deploy", "up": `up`
+- "status": `status`
+- "logs": `logs`
+- "stop watcher", "stop-watcher": `stop-watcher`
+- "tear down", "down": `down`
 
-애매하면 full facet list를 보여주고 직접 입력 option을 둔다. 여러 facet이 한 메시지에 있으면 Step 0은 한 번만 실행하고 sub-command를 순차 실행한다.
+If ambiguous, show the full facet list and offer an Enter directly option. When multiple facets are in one message, run Step 0 once and execute the sub-commands sequentially.
 
 ## up
 
-실행:
+Run:
 
 ```bash
 okstra container up --project-root <projectRoot> --task-key <task-key>
 ```
 
-전제:
+Preconditions:
 
-- task는 implementation worktree가 registry에 있어야 한다.
-- worktree root에 `docker-compose.yml`이 있어야 한다.
-- approved plan의 모든 stage가 `done`이어야 한다. partial stage 상태를 완성 task처럼 deploy하지 않는다.
+- The task must have an implementation worktree registered in the registry.
+- The worktree root must contain a `docker-compose.yml`.
+- Every stage of the approved plan must be `done`. Do not deploy a partial-stage state as if it were a complete task.
 
-실패 메시지 처리:
+Handling failure messages:
 
-- registry에 task worktree가 없다는 메시지: implementation phase를 먼저 실행하라고 말한다.
-- compose file 없음: CLI 메시지를 그대로 보여준다.
-- `final-verification(whole-task): stage N not done`: 해당 stage를 implementation으로 끝내야 한다고 말한다.
-- healthcheck 실패: failing service와 CLI가 제공한 `docker compose ... logs` line을 그대로 전달한다.
+- Message that the task worktree is not in the registry: tell the user to run the implementation phase first.
+- No compose file: show the CLI message verbatim.
+- `final-verification(whole-task): stage N not done`: tell the user to finish that stage via implementation.
+- healthcheck failure: relay the failing service and the `docker compose ... logs` line the CLI provides, verbatim.
 
-성공하면 stdout JSON을 파싱해 services, watcher pane, published ports를 요약한다. 이후 관리는 `okstra container status <task-key>`와 `down <task-key>`로 한다고 안내한다. 띄운 뒤 *무엇을 확인할지*는 implementation 리포트의 §5.7.9 Manual User Test (Draft)를 가리킨다 — 그 단계와 기대 결과가 이 빌드의 수동 테스트 스크립트다.
+On success, parse the stdout JSON and summarize services, watcher pane, and published ports. Tell the user that management from here is via `okstra container status <task-key>` and `down <task-key>`. For *what to verify* once it is up, point to the implementation report's §5.7.9 Manual User Test (Draft) — those steps and expected results are the manual test script for this build.
 
 ## status
 
-실행:
+Run:
 
 ```bash
 okstra container status --project-root <projectRoot> --task-key <task-key>
@@ -92,14 +92,14 @@ okstra container status --project-root <projectRoot> --task-key <task-key>
 stdout JSON:
 
 - `projectName`: compose project name
-- `containers`: run-trace label로 찾은 running containers
-- `watchers`: registry의 watcher metadata
+- `containers`: running containers found by run-trace label
+- `watchers`: watcher metadata from the registry
 
-alive 여부는 `containers` label query가 authoritative다. watcher registry는 lag할 수 있다. `containers`가 비어 있으면 group이 실행 중이 아니라고 말하고 `up`을 제안한다.
+The `containers` label query is authoritative for whether it is alive. The watcher registry can lag. If `containers` is empty, say the group is not running and offer `up`.
 
 ## logs
 
-실행:
+Run:
 
 ```bash
 okstra container logs --project-root <projectRoot> --task-key <task-key>
@@ -111,49 +111,49 @@ service scope:
 okstra container logs --project-root <projectRoot> --task-key <task-key> --service <service>
 ```
 
-stdout JSON의 `watchersDir`, `watchers`를 보여준다. live stream은 file이 아니라 tmux watcher pane에 있다. raw compose logs가 필요하면 `status`에서 `projectName`을 확인한 뒤 사용자가 `docker compose -p <projectName> logs -f <service>`를 실행할 수 있다고 안내한다.
+Show the stdout JSON's `watchersDir` and `watchers`. The live stream is in the tmux watcher pane, not a file. If raw compose logs are needed, get `projectName` from `status`, then tell the user they can run `docker compose -p <projectName> logs -f <service>`.
 
 ## stop-watcher
 
-실행:
+Run:
 
 ```bash
 okstra container stop-watcher --project-root <projectRoot> --task-key <task-key>
 ```
 
-watcher/tail panes만 제거하고 containers는 유지한다. stdout JSON의 `reapedPanes`, `note`를 요약한다. 사용자가 containers까지 내리려는 의도면 `down`으로 라우팅한다.
+Remove only the watcher/tail panes and keep the containers. Summarize the stdout JSON's `reapedPanes` and `note`. If the user actually intends to bring the containers down, route to `down`.
 
 ## down
 
-단일 task:
+Single task:
 
 ```bash
 okstra container down --project-root <projectRoot> --task-key <task-key>
 ```
 
-프로젝트 전체:
+Whole project:
 
 ```bash
 okstra container down --project-root <projectRoot> --all
 ```
 
-단일 task down은 task-key 해석 후 실행해도 된다. `--all`은 프로젝트의 모든 okstra container group을 내리므로 실행 전 사용자 확인을 받는다.
+A single-task down is fine to run after resolving the task-key. `--all` takes down every okstra container group in the project, so confirm with the user before running it.
 
-stdout JSON의 `downed`, `orphanPanesReaped`를 보고한다. 각 `projectName`과 회수된 panes를 표시한다.
+Report the stdout JSON's `downed` and `orphanPanesReaped`. Show each `projectName` and the reaped panes.
 
-## 출력 규칙
+## Output rules
 
-- stdout JSON이 source of truth다.
-- raw `docker` 명령으로 second-guess하지 않는다. CLI가 실패했고 사용자가 manual fallback을 요청한 경우만 예외다.
-- resolved task-key를 heading이나 첫 줄에 표시한다.
-- CLI failure message는 remediation line을 포함해 그대로 보여준다.
-- container/service state는 JSON 값을 normalize하지 않고 보여준다.
+- The stdout JSON is the source of truth.
+- Do not second-guess it with raw `docker` commands. The only exception is when the CLI failed and the user asked for a manual fallback.
+- Show the resolved task-key in the heading or on the first line.
+- Show CLI failure messages verbatim, including the remediation line.
+- Show container/service state as the JSON values, without normalizing.
 
-## 금지 패턴
+## Forbidden patterns
 
-- Docker daemon을 직접 시작하려고 하기.
-- `up` 실패 원인을 추측해서 compose를 수정하기.
-- partial stage task를 deploy 가능한 것으로 포장하기.
-- watcher registry만 보고 container alive라고 판단하기.
-- `down --all`을 사용자 확인 없이 실행하기.
-- raw docker query로 CLI 결과를 임의로 덮어쓰기.
+- Trying to start the Docker daemon yourself.
+- Guessing the cause of an `up` failure and editing the compose file.
+- Dressing up a partial-stage task as deployable.
+- Judging a container as alive from the watcher registry alone.
+- Running `down --all` without user confirmation.
+- Overriding the CLI result arbitrarily with a raw docker query.