okstra 0.123.0 → 0.125.0

package/docs/for-ai/skills/okstra-run.md

@@ -1,52 +1,52 @@
 # okstra-run AI Manual
 
-## 원천
+## Source
 
-- 스킬 원문: [`skills/okstra-run/SKILL.md`](../../../skills/okstra-run/SKILL.md)
+- Skill source: [`skills/okstra-run/SKILL.md`](../../../skills/okstra-run/SKILL.md)
 - wizard CLI wrapper: [`src/commands/execute/wizard.mjs`](../../../src/commands/execute/wizard.mjs)
 - wizard state machine: [`scripts/okstra_ctl/wizard.py`](../../../scripts/okstra_ctl/wizard.py)
 - render-bundle CLI: [`src/commands/execute/render-bundle.mjs`](../../../src/commands/execute/render-bundle.mjs)
 - prepare entrypoint: [`scripts/okstra_ctl/run.py`](../../../scripts/okstra_ctl/run.py)
 
-## 목적
+## Purpose
 
-`okstra-run`은 현재 Claude Code 세션 안에서 okstra task run을 시작한다. 입력 수집은 `okstra wizard` state machine이 전담하고, 스킬은 wizard prompt를 사용자에게 relay한 뒤 `okstra render-bundle`로 task bundle을 준비한다. bundle이 준비되면 현재 세션이 Claude lead로 전환된다.
+`okstra-run` starts an okstra task run inside the current Claude Code session. Input collection is owned entirely by the `okstra wizard` state machine; the skill relays the wizard prompts to the user and then prepares the task bundle via `okstra render-bundle`. Once the bundle is ready, the current session takes over as Claude lead.
 
-단일 권위:
+Single authority:
 
-- 질문 순서, 분기, validation: `scripts/okstra_ctl/wizard.py`
+- Question order, branching, validation: `scripts/okstra_ctl/wizard.py`
 - task bundle materialization: `prepare_task_bundle()`
-- 스킬 문서: thin prompt-relay loop
+- Skill document: thin prompt-relay loop
 
-## 사용 조건
+## When to Use
 
-사용한다:
+Use it when:
 
-- 사용자가 현재 세션에서 okstra task를 시작하려고 한다.
-- 기존 task의 다음 phase를 이어서 실행하려고 한다.
-- "okstra run", "okstra start", "이 세션에서 okstra 시작", "다음 단계 실행" 등.
+- The user wants to start an okstra task in the current session.
+- The user wants to continue the next phase of an existing task.
+- "okstra run", "okstra start", "start okstra in this session", "run the next phase", etc.
 
-사용하지 않는다:
+Do not use it when:
 
-- 상태만 보려는 경우: `okstra-inspect status`
-- 과거 run이나 resume command를 보려는 경우: `okstra-inspect history`
-- 사용자가 새 terminal/new claude process를 명시한 경우: inspect history/resume 안내
+- The user only wants status: `okstra-inspect status`
+- The user wants past runs or a resume command: `okstra-inspect history`
+- The user explicitly named a new terminal / new claude process: point them to inspect history/resume
 
 ## Preflight
 
-단일 Bash 호출:
+A single Bash call:
 
 ```bash
 okstra preflight --runtime claude-code --json
 ```
 
-runtime이나 project setup이 없으면(`ok:false`) `/okstra-setup`을 안내하고 멈춘다. `export PYTHONPATH`를 만들지 않는다.
+If there is no runtime or project setup (`ok:false`), point the user to `/okstra-setup` and stop. Do not create an `export PYTHONPATH`.
 
-## Bash 호출 규칙
+## Bash invocation rule
 
-모든 okstra 호출은 literal token `okstra`로 시작한다. `--state-file`, `--answer`, path, model, worker 값은 이전 JSON/tool output에서 읽어 literal string으로 붙인다.
+Every okstra call begins with the literal token `okstra`. Read the `--state-file`, `--answer`, path, model, and worker values from the prior JSON/tool output and paste them as literal strings.
 
-피해야 한다:
+Avoid:
 
 - `$STATE_FILE`, `$ANSWER`
 - `$(...)`
@@ -54,21 +54,21 @@ runtime이나 project setup이 없으면(`ok:false`) `/okstra-setup`을 안내
 - `eval`, `export`
 - `okstra ... && okstra ...`
 
-empty answer도 flag를 생략하지 않는다.
+Do not drop the flag even for an empty answer.
 
 ```bash
 okstra wizard step --state-file /tmp/okstra-wizard/state.json --answer ""
 ```
 
-## wizard 초기화
+## wizard initialization
 
-state file 생성:
+Create the state file:
 
 ```bash
 okstra wizard new-state-file
 ```
 
-출력 absolute path를 그대로 들고 간다.
+Carry the printed absolute path verbatim.
 
 wizard init:
 
@@ -76,61 +76,61 @@ wizard init:
 okstra wizard init --state-file /tmp/okstra-wizard/state.json --project-root /abs/project --project-id project-id
 ```
 
-결과는 `{ok, next}` JSON이다. 첫 step은 `task_pick`이다.
+The result is `{ok, next}` JSON. The first step is `task_pick`.
 
-## wizard JSON 해석
+## Interpreting the wizard JSON
 
-`next.kind`에 따라 UI를 고른다.
+Pick the UI according to `next.kind`.
 
-| kind | 처리 |
+| kind | Handling |
 |---|---|
-| `pick`, `multi: false` | 모든 `options[]`를 그대로 selectable choice로 렌더. 선택 option의 `value` 제출 |
-| `pick`, `multi: true` | 모든 선택 value를 comma-separated string으로 제출. 선택 없음도 `--answer ""` 제출 |
-| `pick_group` | wizard의 `questions[]`를 한 번의 multi-question UI로 렌더. step별 value를 JSON object로 만들어 한 번에 제출 |
-| `text` | picker를 쓰지 않고 plain text label을 보여준 뒤 다음 사용자 메시지를 verbatim 제출 |
-| `done` | 입력 수집 종료. render-args로 이동 |
-| `aborted` | state file을 지우고 중단. render-args/render-bundle 호출 금지 |
+| `pick`, `multi: false` | Render every `options[]` verbatim as a selectable choice. Submit the chosen option's `value` |
+| `pick`, `multi: true` | Submit all chosen values as a comma-separated string. An empty selection still submits `--answer ""` |
+| `pick_group` | Render the wizard's `questions[]` as a single multi-question UI. Build a JSON object of per-step values and submit it in one shot |
+| `text` | Show a plain text label without a picker, then submit the user's next message verbatim |
+| `done` | Input collection finished. Move to render-args |
+| `aborted` | Delete the state file and stop. Do not call render-args/render-bundle |
 
-`progress.label`은 wizard가 만든 문자열이다. UI prompt 뒤에 그대로 붙이고, 직접 계산하지 않는다.
+`progress.label` is a string the wizard composed. Append it verbatim after the UI prompt; do not compute it yourself.
 
 ## wizard loop
 
-1. prompt 렌더.
-2. 사용자 답변을 literal `--answer`로 제출.
-3. `ok: true`: `result.echo`를 한 줄로 사용자에게 보여주고 다음 step.
-4. `ok: false`: `result.error`를 그대로 보여주고 `result.current`로 같은 step 재시도.
-5. `current: null`: prompt를 재구성할 수 없는 terminal 오류다. 에러를 보여주고 멈춘다.
+1. Render the prompt.
+2. Submit the user's answer as a literal `--answer`.
+3. `ok: true`: show `result.echo` to the user on one line and advance to the next step.
+4. `ok: false`: show `result.error` verbatim and retry the same step via `result.current`.
+5. `current: null`: a terminal error where the prompt cannot be reconstructed. Show the error and stop.
 
-중요: wizard가 제공한 option을 줄이거나 숨기거나 "추천 + 직접 입력"으로 재구성하지 않는다. wizard의 `options[]`가 완전한 선택지다.
+Important: never trim, hide, or restructure the wizard-provided options into a "recommended + Enter directly" form. The wizard's `options[]` is the complete choice set.
 
-## brief 후보 정렬
+## brief candidate ordering
 
-entry phase(`requirements-discovery`, `error-analysis`, `improvement-discovery`)의 brief 선택은 wizard가 처리한다.
+The brief selection for entry phases (`requirements-discovery`, `error-analysis`, `improvement-discovery`) is handled by the wizard.
 
-- task-group 후보는 task catalog의 최근 사용 이력과 `.okstra/briefs/<group>/` 아래 최근 brief 생성/수정 시각을 합산해 최신순으로 보여준다.
-- brief 파일 후보는 선택된 group의 `.okstra/briefs/<task-group>/**/*.md` 안에서 고른다.
-- brief 파일 정렬 키는 `max(파일 생성/수정 시각, 해당 brief를 사용한 task catalog updatedAt)`이다.
-- direct input은 항상 마지막이다.
+- task-group candidates are shown newest-first by combining recent task-catalog use with the recent brief creation/modification times under `.okstra/briefs/<group>/`.
+- brief file candidates are chosen from within the selected group's `.okstra/briefs/<task-group>/**/*.md`.
+- The brief-file sort key is `max(file created/modified time, task-catalog updatedAt of the task that used this brief)`.
+- direct input is always last.
 
 ## confirm step
 
-`next.step == "confirm"`이면 먼저 confirmation summary를 가져온다.
+When `next.step == "confirm"`, first fetch the confirmation summary.
 
 ```bash
 okstra wizard confirmation --state-file /tmp/okstra-wizard/state.json
 ```
 
-`text`를 사용자에게 보여준 뒤 Proceed/Edit/중단 picker를 렌더한다. `Edit`은 wizard가 이전 step으로 rewind한다.
+Show `text` to the user, then render the Proceed/Edit/Abort picker. `Edit` rewinds the wizard to an earlier step.
 
-## outcome과 render-bundle
+## outcome and render-bundle
 
-`next.kind == "done"`이면:
+When `next.kind == "done"`:
 
 ```bash
 okstra wizard outcome --state-file /tmp/okstra-wizard/state.json
 ```
 
-`outcome.persistActions[]`를 먼저 실행한 뒤 `outcome.renderArgs` object의 key를 `okstra render-bundle` flag로 전달한다. 빈 string 값도 명시적으로 전달한다. 예외: `chain-stages` key는 render-bundle flag가 아니다 — Step 7 무인 연쇄 루프를 구동하는 값이라 flag로 넘기지 않는다(`run.py`는 `--stage`/`--stages`만 받는다). render-bundle block의 `--stage`는 implementation·final-verification 전용, `--stages`는 release-handoff 전용(빈 값 = whole-task)이다.
+Run `outcome.persistActions[]` first, then pass each key of the `outcome.renderArgs` object as an `okstra render-bundle` flag. Pass empty string values explicitly too. Exception: the `chain-stages` key is not a render-bundle flag — it drives the Step 7 unattended-chaining loop, so do not pass it as a flag (`run.py` accepts only `--stage`/`--stages`). In the render-bundle block, `--stage` is implementation·final-verification only, and `--stages` is release-handoff only (empty value = whole-task).
 
 ```bash
 okstra render-bundle \
@@ -160,52 +160,52 @@ okstra render-bundle \
   --fix-cycle "<args.fix-cycle>"
 ```
 
-stdout에서 다음 labeled line을 파싱한다.
+Parse the following labeled lines from stdout.
 
 - `okstra task root:`
 - `okstra instruction-set:`
-- 선택적으로 `okstra concurrent-run stages:`
+- optionally `okstra concurrent-run stages:`
 
-render-bundle은 `prepare_task_bundle()`을 render-only로 호출해 manifests, run context, instruction set, discovery files를 준비하고 `~/.okstra/recent.jsonl`에 `prepared`로 등록한다.
+render-bundle calls `prepare_task_bundle()` in render-only mode to prepare the manifests, run context, instruction set, and discovery files, and registers the run as `prepared` in `~/.okstra/recent.jsonl`.
 
 ## conformance waiver
 
-implementation에서 Tier 3 conformance가 환경상 불가능할 때만 사용자에게 waiver를 제안한다. waiver는 사용자 승인과 verbatim reason이 있어야 한다. AI lead나 worker가 자체 면제를 만들지 않는다.
+Offer a waiver to the user only when Tier 3 conformance is genuinely impossible in the environment during implementation. A waiver requires user approval and a verbatim reason. Neither the AI lead nor a worker creates a self-exemption.
 
-선택 시 `render-bundle`에만 추가한다.
+When chosen, add it to `render-bundle` only.
 
 ```bash
 --qa-waiver "<stageKey>:<reason>"
 ```
 
-값이 없으면 flag 자체를 생략한다.
+Omit the flag entirely when there is no value.
 
-## concurrent-run 분기
+## concurrent-run branch
 
-`render-bundle` stdout에 `okstra concurrent-run stages:`가 있으면 이미 no-team background gate가 prompt에 반영된 상태다.
+If `render-bundle` stdout carries `okstra concurrent-run stages:`, the no-team background gate is already reflected in the prompt.
 
-사용자에게 세 선택지를 준다.
+Give the user three options.
 
-1. no-team background로 진행.
-2. 대기 — dispatch 보류, stage worktree·run context 보존. 점유 run 종료 후 같은 stage를 resume으로 재개하도록 resume 명령(`okstra-inspect` history → resume)을 사용자에게 출력한다.
-3. 직접 입력.
+1. Proceed as no-team background.
+2. Wait — hold the dispatch, preserve the stage worktree·run context. After the occupying run finishes, print the resume command (`okstra-inspect` history → resume) so the user can resume the same stage.
+3. Enter directly.
 
-이 picker는 스킬이 만드는 것이므로 wizard option 축약 금지 규칙과 별개다.
+This picker is authored by the skill, so it is separate from the wizard-option-abbreviation ban.
 
 ## stale git SHA recovery
 
-`Recorded stage SHAs no longer match the git history`류 `PrepareError`가 나오면 registry/consumers를 수동 수정하지 않는다.
+When a `PrepareError` such as `Recorded stage SHAs no longer match the git history` appears, do not fix the registry/consumers by hand.
 
-1. 에러 메시지에 나온 `okstra git-reconcile ... --check --json`을 그대로 실행한다.
-2. confirm 항목마다 사용자에게 current branch tip, 다른 ref, 중단을 묻는다.
-3. 선택 ref로 `okstra git-reconcile ... --apply --stage <N> --use-ref <ref>`를 실행한다.
-4. 실패했던 render-bundle을 같은 인자로 재시도한다.
+1. Run the `okstra git-reconcile ... --check --json` printed in the error message verbatim.
+2. For each confirm item, ask the user for the current branch tip, a different ref, or abort.
+3. Run `okstra git-reconcile ... --apply --stage <N> --use-ref <ref>` with the chosen ref.
+4. Retry the failed render-bundle with the same arguments.
 
-anchor가 unresolvable이면 `--reset-anchor <ref>`는 사용자 확인 후 실행한다.
+If the anchor is unresolvable, run `--reset-anchor <ref>` after user confirmation.
 
 ## PR template persistence
 
-release-handoff에서 `outcome.persistActions[]`가 `config.set` / `pr-template-path` action을 반환하면 render-bundle 전에 config를 저장한다.
+In release-handoff, when `outcome.persistActions[]` returns a `config.set` / `pr-template-path` action, save the config before render-bundle.
 
 ```bash
 # action.scope == "project"
@@ -214,40 +214,40 @@ okstra config set pr-template-path "<path>" --scope project
 okstra config set pr-template-path "<path>" --scope global
 ```
 
-scope와 path는 wizard state file이 아니라 `okstra wizard outcome`의 persist action에서 읽는다. raw state file을 직접 읽지 않는다.
+Read the scope and path from the persist action of `okstra wizard outcome`, not from the wizard state file. Do not read the raw state file directly.
 
-## Claude lead 전환
+## Claude lead takeover
 
-render-bundle 후 `<INSTRUCTION_SET_PATH>/claude-execution-prompt.md`를 verbatim으로 읽고, 그 prompt 순서대로 Phase 1부터 진행한다.
+After render-bundle, read `<INSTRUCTION_SET_PATH>/claude-execution-prompt.md` verbatim and proceed from Phase 1 in that prompt's order.
 
-사용자에게 한 줄로 알린다.
+Inform the user on one line.
 
 ```text
 Took over as Claude lead for `<taskKey>` (`<task-type>`). Run dir: `<RUN_DIR_RELATIVE_PATH>`. Beginning Phase 1 (context loading).
 ```
 
-단일 원소 chain이면 Step 6 종료가 곧 run 종료다. 아래 Step 7은 `chain-stages` CSV가 2개 이상일 때만 적용된다.
+For a single-element chain, the end of Step 6 is the end of the run. Step 7 below applies only when the `chain-stages` CSV has 2 or more elements.
 
-## implementation 무인 연쇄 (chain-stages)
+## implementation unattended chaining (chain-stages)
 
-`task-type == implementation`이고 render-args `chain-stages` CSV가 원소 2개 이상이면, 현재 세션이 오케스트레이터로서 stage를 의존성 순서대로 무인 연쇄 실행한다. 큐 = `chain-stages`를 `,`로 분해한 위상정렬 stage 리스트. 큐의 각 stage `N`에 대해 순서대로:
+When `task-type == implementation` and the render-args `chain-stages` CSV has 2 or more elements, the current session acts as the orchestrator and runs the stages as an unattended chain in dependency order. Queue = the topologically-sorted stage list from splitting `chain-stages` on `,`. For each stage `N` in the queue, in order:
 
-1. render-bundle을 같은 인자로, 단 `--stage N`으로 재호출한다(base commit은 prepare가 predecessor의 done `head_commit`으로 자동 계산 — 손으로 넘기지 않는다). conformance waiver·concurrent-run·git-reconcile 게이트는 매 stage의 render-bundle마다 동일 적용.
-2. Step 6대로 Claude lead가 되어 그 stage의 Phase 1~7을 인라인 실행한다. Phase 6의 lead persistence가 `runs/<plan-task-key>/consumers.jsonl`에 그 stage의 `status:"done"` 행을 append한다.
-3. `done` 행 기록을 확인한 뒤 다음 stage로 넘어간다. stage 경계마다 컨텍스트(잔여 pane·완료 teammate)를 정리한다.
-4. stage 시작/완료마다 한 줄 보고: `stage N/<총개수> 시작` / `stage N done → 다음 K`.
+1. Re-call render-bundle with the same arguments but `--stage N` (the base commit is auto-computed by prepare from the predecessor's done `head_commit` — do not pass it by hand). The conformance waiver·concurrent-run·git-reconcile gates apply identically to each stage's render-bundle.
+2. As in Step 6, become Claude lead and run that stage's Phase 1–7 inline. Phase 6's lead persistence appends that stage's `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl`.
+3. After confirming the `done` row was written, move to the next stage. Clean up context (leftover panes·finished teammates) at each stage boundary.
+4. One-line report at each stage start/finish: `stage N/<total> start` / `stage N done → next K`.
 
-큐를 모두 소화하면 연쇄를 종료하고 완료를 보고한다.
+Once the whole queue is consumed, end the chain and report completion.
 
-- **다음 stage가 아직 ready 아님 — 정상 종료:** 큐의 stage가 다른 implementation run에 started/reserved로 점유돼 render-bundle이 `--stage N already in progress or reserved by another run`(StageTargetError)으로 거부되면, 이는 예외가 아니다 — 연쇄를 **정상 종료**하고 남은 큐를 보고한다(예: `남은 큐: stage 4, 5 — 점유 해제 후 okstra-run으로 재개`).
-- **연쇄 중 예외 게이트:** render-bundle이 concurrent-run 충돌이나 git stale-SHA 재조정을 띄우면 **그 stage에서 연쇄를 멈추고** 게이트를 Step 5 절차대로 사용자에게 제시한다. 사용자가 해소하면 그 자리에서 남은 큐를 이어 재개한다. 데이터 손상·동시 점유 충돌은 사람이 확인 — 무인 연쇄의 안전 경계다.
+- **Next stage not yet ready — normal termination:** When a stage in the queue is occupied by another implementation run as started/reserved and render-bundle is rejected with `--stage N already in progress or reserved by another run` (StageTargetError), this is not an exception — **terminate the chain normally** and report the remaining queue (e.g. `remaining queue: stage 4, 5 — resume with okstra-run after occupancy is released`).
+- **Exception gate during chaining:** If render-bundle raises a concurrent-run conflict or git stale-SHA reconciliation, **stop the chain at that stage** and present the gate to the user per the Step 5 procedure. Once the user resolves it, resume the remaining queue in place. Data corruption·concurrent-occupancy conflicts are confirmed by a human — this is the safety boundary of unattended chaining.
 
-## 금지 패턴
+## Forbidden patterns
 
-- wizard가 내준 질문 순서를 바꾸기.
-- wizard option을 숨기거나 추천만 남기기.
-- `text` prompt를 picker로 바꾸기.
-- empty answer에서 `--answer` flag를 생략하기.
-- `okstra.sh`를 호출해 wizard/render-bundle 경로를 우회하기.
-- render-bundle 전에 사용자가 abort한 state로 render-args를 호출하기.
-- Claude lead prompt를 읽기 전에 phase 작업을 임의로 시작하기.
+- Changing the question order the wizard emitted.
+- Hiding wizard options or keeping only the recommendations.
+- Turning a `text` prompt into a picker.
+- Dropping the `--answer` flag on an empty answer.
+- Bypassing the wizard/render-bundle path by calling `okstra.sh`.
+- Calling render-args on a state the user aborted before render-bundle.
+- Starting phase work arbitrarily before reading the Claude lead prompt.