okstra 0.123.0 → 0.125.0

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

@@ -1,77 +1,77 @@
 # okstra-schedule-gen AI Manual
 
-## 원천
+## Source
 
-- 스킬 원문: [`skills/okstra-schedule-gen/SKILL.md`](../../../skills/okstra-schedule-gen/SKILL.md)
-- schedule 템플릿: [`templates/reports/schedule.template.md`](../../../templates/reports/schedule.template.md)
+- Skill source: [`skills/okstra-schedule-gen/SKILL.md`](../../../skills/okstra-schedule-gen/SKILL.md)
+- schedule template: [`templates/reports/schedule.template.md`](../../../templates/reports/schedule.template.md)
 - schedule validator: [`validators/validate-schedule.py`](../../../validators/validate-schedule.py)
-- workStatus inference 참조: [`skills/okstra-inspect/SKILL.md`](../../../skills/okstra-inspect/SKILL.md)
+- workStatus inference reference: [`skills/okstra-inspect/SKILL.md`](../../../skills/okstra-inspect/SKILL.md)
 
-## 목적
+## Purpose
 
-`okstra-schedule-gen`은 task-group 안의 non-done task들을 모아 클라이언트용 작업 일정 Markdown을 만든다. 실행 task를 시작하는 스킬이 아니며, 단일 task 분석도 아니다.
+`okstra-schedule-gen` gathers the non-done tasks within a task-group and produces a client-facing work-schedule Markdown. It is not a skill for starting an execution task, and it is not a single-task analysis.
 
-출력 위치:
+Output location:
 
 ```text
 <PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/<task-group-segment>-plan-<YYYY-MM-DD_HH-MM-SS>.md
 ```
 
-## 사용 조건
+## When to Use
 
-사용한다:
+Use it when:
 
-- 사용자가 task-group 전체의 "일정", "schedule", "작업 계획표"를 요청한다.
-- `.okstra/discovery/task-catalog.json`에 해당 task-group이 있고, `done`이 아닌 task가 하나 이상 있다.
+- The user requests a "schedule", "work plan", or work-schedule table for an entire task-group.
+- `.okstra/discovery/task-catalog.json` contains that task-group and it has at least one task that is not `done`.
 
-사용하지 않는다:
+Do not use it when:
 
-- 단일 task 상태/분석: `okstra-inspect status`
-- 실제 phase 실행: `okstra-run`
-- 이미 완료된 task-group: 파일을 만들지 않고 모든 task가 done이라고 말한다.
+- Single-task status/analysis: `okstra-inspect status`
+- Actual phase execution: `okstra-run`
+- An already-completed task-group: do not create a file; state that all tasks are done.
 
 ## Preflight
 
-단일 Bash 호출:
+A single Bash call:
 
 ```bash
 okstra preflight --runtime claude-code --json
 ```
 
-runtime이나 project setup이 없으면 `/okstra-setup` 안내 후 멈춘다.
+If there is no runtime or project setup, point the user to `/okstra-setup` and stop.
 
-## task-group 해석
+## Resolving the task-group
 
-1. `.okstra/discovery/task-catalog.json`을 읽는다.
-2. 사용자 입력 task-group을 lowercase하고 `[a-z0-9]` 외 문자를 제거한다.
-3. catalog entry의 `taskGroupPathSegment`에도 같은 변환을 적용해 비교한다.
-4. raw `taskGroup` fallback은 쓰지 않는다.
-5. 매칭된 각 task의 `task-manifest.json`을 직접 읽는다. catalog는 stale일 수 있고 manifest가 authoritative다.
+1. Read `.okstra/discovery/task-catalog.json`.
+2. Lowercase the user-supplied task-group and strip characters outside `[a-z0-9]`.
+3. Apply the same transform to each catalog entry's `taskGroupPathSegment` and compare.
+4. Do not fall back to the raw `taskGroup`.
+5. Read each matched task's `task-manifest.json` directly. The catalog may be stale; the manifest is authoritative.
 
-0개 매칭이면 `해당 task-group을 찾을 수 없습니다.`를 출력하고 멈춘다.
+On zero matches, output `That task-group could not be found.` and stop.
 
 ## workStatus filter
 
-각 manifest에서 workStatus를 확인한다. 없거나 비어 있으면 `okstra-inspect`의 `status.4` inference table을 적용한다.
+Check the workStatus in each manifest. When it is missing or empty, apply `okstra-inspect`'s `status.4` inference table.
 
-제외:
+Exclude:
 
 - explicit `done`
 - inferred `done`
 
-포함:
+Include:
 
 - `todo`
 - `in-progress`
 - `blocked`
 - `phase-done`
-- 그 밖의 non-done inferred/display 상태
+- other non-done inferred/display states
 
-필터 후 0개면 schedule file을 만들지 않고 `해당 task-group의 모든 task가 done 상태입니다. 생성할 schedule이 없습니다.`를 출력한다.
+If 0 remain after filtering, do not create a schedule file; output `All tasks in this task-group are done. There is no schedule to generate.`
 
 ## per-task data extraction
 
-manifest에서 읽는다:
+Read from the manifest:
 
 - `taskId`, `taskGroup`, `taskKey`
 - `workCategory`
@@ -81,7 +81,7 @@ manifest에서 읽는다:
 - `workStatus`
 - `latestReportPath`
 
-report에서 파싱한다:
+Parse from the report:
 
 - Title / Problem statement
 - Solution / Architecture
@@ -90,45 +90,45 @@ report에서 파싱한다:
 - Rollback strategy
 - Effort, Risk, Priority, Scope, Repos
 
-report가 없거나 manifest pointer가 stale이면 fallback:
+If there is no report or the manifest pointer is stale, fall back:
 
-1. `taskRootPath`를 기준으로 `runs/<taskType>/reports/final-report-*.md`에서 mtime이 최신인 파일을 찾는다.
-2. 없으면 `runs/*/reports/final-report-*.md`도 본다.
-3. 찾으면 parse하고 schedule task block에 fallback note를 넣는다.
-4. 끝까지 없으면 `[NEEDS-OKSTRA-RUN]`으로 표시하고 manifest metadata만 사용한다.
+1. From `taskRootPath`, find the newest-mtime file under `runs/<taskType>/reports/final-report-*.md`.
+2. If none, also look at `runs/*/reports/final-report-*.md`.
+3. If found, parse it and put a fallback note in the schedule task block.
+4. If still nothing, mark it `[NEEDS-OKSTRA-RUN]` and use only the manifest metadata.
 
-특정 section parse 실패는 `[PARSE-ERROR: <section>]`으로 표시하고 계속한다.
+Mark a specific section's parse failure as `[PARSE-ERROR: <section>]` and continue.
 
 ## client-facing audience rule
 
-schedule은 클라이언트용 작업 계획이다. 내부 report의 approval, blocking decision, 사용자 확인 필요 항목을 schedule에 노출하지 않는다.
+The schedule is a client-facing work plan. Do not surface the internal report's approval, blocking decisions, or items requiring user confirmation in the schedule.
 
-출력에서 제거한다:
+Remove from the output:
 
-- permission/authority 확인 step
+- permission/authority confirmation steps
 - approval waiting buffer
 - stakeholder coordination
-- 법무/조직 sign-off
+- legal/organizational sign-off
 - `Consolidated User Decision Checklist`
-- `#### 사용자 확인 필요 항목`
+- `#### Items requiring user confirmation`
 - `Done`, `Ready?`, `Blocking Decisions` column
 - checkbox list/cell
 
-effort와 Gantt는 engineering duration만 반영한다.
+effort and Gantt reflect engineering duration only.
 
 ## phase classification
 
-기본 mapping:
+Default mapping:
 
 | workCategory | phase |
 |---|---|
-| `bugfix` | High/Med-High risk이면 Phase 1, 아니면 Phase 2 |
+| `bugfix` | Phase 1 when High/Med-High risk, otherwise Phase 2 |
 | `feature` | Phase 2 |
 | `improvement` | Phase 2 |
 | `refactor` | Phase 3 |
 | `ops` | Phase 3 |
 | `docs` / `doc` | Phase 2 |
-| `unknown` 또는 미정의 | Phase 2, rationale note 추가 |
+| `unknown` or undefined | Phase 2, add a rationale note |
 
 priority override:
 
@@ -136,16 +136,16 @@ priority override:
 - `P1`, `P2`: Phase 2
 - `P3`: Phase 3
 
-ambiguous하면 가장 가까운 phase에 두고 rationale을 phase section 상단에 쓴다. 이 rationale은 현재 validator gap으로 문서에서 책임진다.
+When ambiguous, place it in the closest phase and write the rationale at the top of the phase section. This rationale is a current validator gap, so the document owns it.
 
 ## section contract
 
-템플릿의 heading 순서와 spelling을 따른다. `validate-schedule.py`가 section order, title suffix, metadata, field labels, enum, Gantt axis 등을 검사한다.
+Follow the template's heading order and spelling. `validate-schedule.py` checks section order, title suffix, metadata, field labels, enum, Gantt axis, and more.
 
-top-level 계약 sections:
+top-level contract sections:
 
 1. `## At a Glance`
-2. `## Executive Summary` (필수 subsection `### Effort Sizing 기준` 포함 — `validate-schedule.py`가 검사)
+2. `## Executive Summary` (includes the mandatory subsection `### Effort Sizing Criteria` — checked by `validate-schedule.py`)
 3. `## Task Dependency Graph`
 4. `## Phase 1: Critical Fixes`
 5. `## Phase 2: Enhancements`
@@ -157,14 +157,14 @@ top-level 계약 sections:
 
 optional sections:
 
-- `## Gantt Chart`: `Task Dependency Graph`와 `Phase 1` 사이.
-- `## Glossary`: 마지막 section. opaque code가 본문에 남을 때만 사용.
+- `## Gantt Chart`: between `Task Dependency Graph` and `Phase 1`.
+- `## Glossary`: last section. Use only when opaque codes remain in the body.
 
-phase에 task가 없어도 heading을 유지하고 `_없음_`을 쓴다.
+Keep the heading even when a phase has no task, and write `_none_`.
 
 ## top header
 
-형태:
+Shape:
 
 ```markdown
 # <Title> — Work Schedule
@@ -173,32 +173,32 @@ phase에 task가 없어도 heading을 유지하고 `_없음_`을 쓴다.
 > Source: okstra <mode> (<N> tasks included, <M> done excluded)
 ```
 
-title suffix `— Work Schedule`은 validator가 검사한다. `<project-id>`는 `task-catalog.json` 최상위 `projectId`를 우선 쓰고, 없으면 첫 매칭 manifest의 `projectId`를 쓴다. 임의 값 생성 금지.
+The validator checks the title suffix `— Work Schedule`. For `<project-id>`, prefer `task-catalog.json`'s top-level `projectId`, and if absent use the first matched manifest's `projectId`. Do not invent a value.
 
 ## At a Glance
 
-다음 totals line이 정확히 있어야 한다.
+This totals line must be present exactly.
 
 ```markdown
-**총 <N>개 task / 예상 소요: <X.X> ~ <Y.Y> days (Effort 합산)**
+**<N> tasks total / estimated effort: <X.X> ~ <Y.Y> days (Effort sum)**
 ```
 
-Effort-to-day mapping은 template의 `### Effort Sizing 기준` table이 SSOT다. lower/upper 합산으로 total day range를 만든다.
+The Effort-to-day mapping's SSOT is the template's `### Effort Sizing Criteria` table. Build the total day range by summing the lower/upper bounds.
 
-enum 값:
+enum values:
 
-| Field | 값 |
+| Field | value |
 |---|---|
 | Effort | `S`, `M`, `L`, `XL`, `XXL` |
 | Priority | `P0`, `P1`, `P2`, `P3` |
 | Risk | `Very Low`, `Low`, `Medium`, `Med-High`, `High` |
 | Phase | `1`, `2`, `3` |
 
-`Med-High`가 canonical이다.
+`Med-High` is canonical.
 
 ## per-task block
 
-모든 task block은 `| Item | Detail |` table을 가진다. field row 순서:
+Every task block has a `| Item | Detail |` table. field row order:
 
 1. `**Category**`
 2. `**Priority**`
@@ -208,25 +208,25 @@ enum 값:
 6. `**Scope**`
 7. `**Repo**`
 
-그 뒤 subsection 순서:
+Then the subsection order:
 
 1. `**Problem**:`
 2. `**Solution**:`
-3. `**Work Breakdown**:` — 뒤에 `| Step | File | Action | Detail |` table
-4. `**Verification Commands**:` — 뒤에 ` ```bash ` fenced block
+3. `**Work Breakdown**:` — followed by a `| Step | File | Action | Detail |` table
+4. `**Verification Commands**:` — followed by a ` ```bash ` fenced block
 5. `**Rollback**:`
 
-`[NEEDS-OKSTRA-RUN]` 또는 `[PARSE-ERROR: <section>]` task는 가능한 field만 채우되 marker를 task heading 바로 아래 둔다.
+For a `[NEEDS-OKSTRA-RUN]` or `[PARSE-ERROR: <section>]` task, fill only the available fields but place the marker right below the task heading.
 
 ## Task Dependency Graph
 
-dependency가 없으면 literal:
+When there is no dependency, literal:
 
 ```markdown
-_의존 정보 없음_
+_none_
 ```
 
-dependency가 있으면 plain fenced block을 사용한다. language tag를 붙이지 않는다.
+When dependencies exist, use a plain fenced block. Do not attach a language tag.
 
 ````
 ```
@@ -235,28 +235,28 @@ DEV-2 -> DEV-4
 ```
 ````
 
-arrow는 ASCII `->`만 사용한다.
+Use only the ASCII arrow `->`.
 
 ## Gantt Chart
 
-**directive override (최우선):** 아래 휴리스틱 적용 전 directive source의 `## Directive` section을 먼저 확인한다. 해석 순서(first hit): (1) `--directive-file <abs-path>` 인자, (2) `<PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/instruction-set/analysis-material.md`, (3) 없으면 휴리스틱 그대로(정상 경로 — 경고·중단 없음). directive가 Gantt 렌더/생략을 지시하면 휴리스틱·skip 규칙을 덮어쓰고, 해당 section에 `> _Per Directive directive: <verbatim 발췌>._` 한 줄을 남긴다. directive가 day allocation·phase weight·sub-task 분해를 주면 bar 길이에 verbatim 반영한다.
+**directive override (highest priority):** before applying the heuristic below, first check the directive source's `## Directive` section. Resolution order (first hit): (1) the `--directive-file <abs-path>` argument, (2) `<PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/instruction-set/analysis-material.md`, (3) if none, the heuristic as-is (normal path — no warning·stop). When the directive instructs Gantt render/skip, it overrides the heuristic·skip rules, and leave one line in that section: `> _Per Directive directive: <verbatim short excerpt>._`. When the directive supplies day allocation·phase weight·sub-task decomposition, reflect it verbatim in bar length.
 
-기본은 렌더한다. day signal이 하나라도 있으면 rough estimate라도 chart를 만든다.
+By default, render. If there is any day signal, produce a chart even as a rough estimate.
 
-렌더 조건 예:
+Render-condition examples:
 
-- 2개 이상 task에 effort sizing이 있다.
-- 1개 task라도 effort range가 있다.
-- source report에 Part/Phase/Step decomposition이 있다.
-- total effort가 3 days 이상이다.
+- 2+ tasks have effort sizing.
+- Even 1 task has an effort range.
+- The source report has Part/Phase/Step decomposition.
+- Total effort is 3 days or more.
 
-skip은 모든 task가 XXL이고 decomposition이 없거나, 모든 task에 effort와 decomposition이 없을 때만 한다. skip하면 `Gantt Chart` 위치에 다음 blockquote를 둔다.
+Skip only when every task is XXL with no decomposition, or when all tasks lack both effort and decomposition. On skip, place the following blockquote at the `Gantt Chart` position.
 
 ```markdown
-> _Gantt Chart 생략: <actual data를 근거로 한 이유>._
+> _Gantt Chart skipped: <concrete reason referencing the actual data>._
 ```
 
-Gantt는 plain fenced ASCII다. Mermaid, PlantUML, Graphviz, date axis를 쓰지 않는다.
+The Gantt is plain fenced ASCII. Do not use Mermaid, PlantUML, Graphviz, or a date axis.
 
 ````
 ```
@@ -269,52 +269,52 @@ Phase 2
 ```
 ````
 
-axis는 relative day count만 사용한다. calendar date, weekday, "오늘 + N"을 넣지 않는다.
+The axis uses relative day count only. Do not put in a calendar date, weekday, or "today + N".
 
-## opaque code 처리
+## handling opaque code
 
-내부 report code(`FC-5`, `UC-3`, `M2` 등)는 그대로 노출하지 않는다.
+Do not surface internal report codes (`FC-5`, `UC-3`, `M2`, etc.) as-is.
 
-선택 A: 짧은 설명으로 inline replacement.
+Option A: inline replacement with a short description.
 
-선택 B: 반복되는 code가 많으면 마지막 `## Glossary`에 모든 code를 해석한다. glossary table header는 정확히 `| Code | Description |`(영문 literal — validator가 검사). milestone code(`M1`, `M2` …)도 `FC-N`과 동일하게 glossary 미해석 시 validator fail.
+Option B: when many codes recur, resolve every code in a final `## Glossary`. The glossary table header is exactly `| Code | Description |` (English literal — checked by the validator). Milestone codes (`M1`, `M2` …) also fail the validator when left unresolved in the glossary, just like `FC-N`.
 
-decision-item letter code(`A1`, `B2`, `C3`, `D4`)는 schedule에 넣지 않는다.
+Do not put decision-item letter codes (`A1`, `B2`, `C3`, `D4`) in the schedule.
 
 ## validation
 
-작성 후 완료 메시지 전에 다시 읽고 validator를 실행한다.
+After writing, re-read it and run the validator before the completion message.
 
 ```bash
 python3 ~/.okstra/lib/validators/validate-schedule.py <output-path>
 ```
 
-설치본 validator가 없으면 repo validator를 쓴다.
+If the installed validator is absent, use the repo validator.
 
 ```bash
 python3 validators/validate-schedule.py <output-path>
 ```
 
-실패하면 파일을 고치고 재검증한다. validator가 없을 때만 manual checklist로 대체한다.
+On failure, fix the file and re-validate. Fall back to a manual checklist only when there is no validator.
 
-## 완료 메시지
+## completion message
 
 ```text
-Schedule 생성 완료: <relative-path>
-- 포함 task: N개
-- 제외(done) task: M개
-- 예상 소요: X.X ~ Y.Y days (Effort 합산)
-- 모드: lightweight
+Schedule generated: <relative-path>
+- Included tasks: N
+- Excluded (done) tasks: M
+- Estimated effort: X.X ~ Y.Y days (Effort sum)
+- Mode: lightweight
 ```
 
-## 금지 패턴
-
-- heading을 한국어/프랑스어 등으로 번역하기.
-- `## Cumulative Timeline` 추가.
-- `## Effort-to-Day 매핑` 같은 extra top-level section 추가.
-- Gantt를 mermaid로 렌더하기.
-- Gantt axis에 calendar date를 넣기.
-- checkbox, Done, Ready, Blocking Decisions column 만들기.
-- internal approval/blocker/user-decision 항목을 클라이언트 schedule에 노출하기.
-- report가 없다고 task를 제외하기. `[NEEDS-OKSTRA-RUN]`으로 포함한다.
-- timestamp collision 시 기존 파일을 덮어쓰기. `-2`, `-3` suffix를 붙인다.
+## Forbidden patterns
+
+- Translating a heading into Korean/French/etc.
+- Adding `## Cumulative Timeline`.
+- Adding an extra top-level section such as `## Effort-to-Day mapping`.
+- Rendering the Gantt as mermaid.
+- Putting a calendar date on the Gantt axis.
+- Creating a checkbox, Done, Ready, or Blocking Decisions column.
+- Surfacing internal approval/blocker/user-decision items in the client schedule.
+- Excluding a task because it has no report. Include it as `[NEEDS-OKSTRA-RUN]`.
+- Overwriting an existing file on a timestamp collision. Append a `-2`, `-3` suffix.

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

@@ -1,52 +1,52 @@
 # okstra-setup AI Manual
 
-## 원천
+## Source
 
-- 스킬 원문: [`skills/okstra-setup/SKILL.md`](../../../skills/okstra-setup/SKILL.md)
+- Skill source: [`skills/okstra-setup/SKILL.md`](../../../skills/okstra-setup/SKILL.md)
 - CLI registry: [`src/cli-registry.mjs`](../../../src/cli-registry.mjs)
-- project 등록 구현: `src/commands/lifecycle/setup.mjs`
-- install/ensure-installed 구현: `src/commands/lifecycle/install.mjs`
+- project registration impl: `src/commands/lifecycle/setup.mjs`
+- install/ensure-installed impl: `src/commands/lifecycle/install.mjs`
 
-## 목적
+## Purpose
 
-`okstra-setup`은 두 가지를 처리한다.
+`okstra-setup` handles two things.
 
-1. 머신 단위 runtime 설치: `~/.okstra/`, `~/.claude/skills/`, `~/.claude/agents/`
-2. 프로젝트 단위 등록: `<PROJECT_ROOT>/.okstra/project.json`
+1. Machine-level runtime install: `~/.okstra/`, `~/.claude/skills/`, `~/.claude/agents/`
+2. Project-level registration: `<PROJECT_ROOT>/.okstra/project.json`
 
-일상적인 task 실행 스킬이 아니다. task가 이미 준비된 상태면 `okstra-run` 또는 `okstra-inspect`로 라우팅한다.
+It is not a day-to-day task-running skill. If a task is already prepared, route to `okstra-run` or `okstra-inspect`.
 
-## 사용 조건
+## When to use
 
-사용한다:
+Use it when:
 
-- 사용자가 "okstra setup", "setup okstra", "initialize okstra", "okstra init", "처음 설정"을 요청한다.
-- `~/.okstra/version`이 없거나 오래된 것으로 보인다.
-- 현재 프로젝트에 `.okstra/project.json`이 없다.
+- The user asks for "okstra setup", "setup okstra", "initialize okstra", "okstra init", "first time setup".
+- `~/.okstra/version` is missing or looks stale.
+- The current project has no `.okstra/project.json`.
 
-사용하지 않는다:
+Do not use it when:
 
-- task run을 시작하려는 경우. 이때는 `okstra-run`.
-- status/history/report를 보려는 경우. 이때는 `okstra-inspect`.
-- 이미 `.okstra/project.json`이 있고 day-to-day 사용만 필요한 경우.
+- The user wants to start a task run. Use `okstra-run` instead.
+- The user wants to view status/history/report. Use `okstra-inspect` instead.
+- `.okstra/project.json` already exists and only day-to-day usage is needed.
 
-## 실행 전 확인
+## Pre-run checks
 
-사용자에게 Node 18+, Python 3.10+가 필요하다고 알린다. 현재 working directory가 okstra 메타데이터를 둘 프로젝트 안인지 불명확하면, 프로젝트 루트를 먼저 확인한다.
+Tell the user that Node 18+ and Python 3.10+ are required. If it is unclear whether the current working directory is inside the project that will host the okstra metadata, confirm the project root first.
 
-설치 명령:
+Install command:
 
 ```bash
 npx -y okstra@latest install --runtime claude-code
 ```
 
-이 명령은 idempotent로 취급한다. 이미 설치되어 있어도 다시 실행해 runtime, skill, agent payload를 현재 package 버전과 맞춘다(agent payload = `~/.claude/agents/<worker>.md` worker 정의 + `~/.okstra/installed-agents.json` manifest). 실패하면 stderr를 그대로 사용자에게 보여준다. legacy `okstra-install.sh`로 우회하지 않는다.
+Treat this command as idempotent. Even if already installed, re-run it to align the runtime, skill, and agent payload with the current package version (agent payload = the `~/.claude/agents/<worker>.md` worker definitions + the `~/.okstra/installed-agents.json` manifest). If it fails, show the stderr to the user verbatim. Do not fall back to the legacy `okstra-install.sh`.
 
-## 명령 호출 규칙
+## Command invocation rule
 
-`okstra install` 이후에는 후속 명령이 모두 `okstra` literal token으로 시작해야 한다.
+After `okstra install`, every subsequent command must begin with the literal `okstra` token.
 
-허용되는 형태:
+Allowed forms:
 
 ```bash
 okstra check-project --json
@@ -54,87 +54,86 @@ okstra setup --yes --project-root /abs/project --project-id my-project
 okstra doctor --runtime claude-code
 ```
 
-피해야 하는 형태:
+Forms to avoid:
 
 - `export PYTHONPATH=...`
 - `eval "$(okstra paths --shell)"`
-- `$PROJECT_ROOT` 같은 shell 변수
+- shell variables like `$PROJECT_ROOT`
 - `$(...)` command substitution
-- `if`, `&&`, `||`로 감싼 okstra 호출
+- okstra calls wrapped in `if`, `&&`, `||`
 
-`okstra <subcmd>`가 자체적으로 Python path를 부트스트랩하므로 `okstra paths --shell`은 이 스킬에서 쓰지 않는다. 경로가 필요하면 `okstra paths --json`을 별도 호출로 실행하고 JSON 값을 읽는다.
+Because `okstra <subcmd>` bootstraps its own Python path, do not use `okstra paths --shell` in this skill. If you need a path, run `okstra paths --json` as a separate call and read the JSON value.
 
-## 프로젝트 루트 해석
+## Project root resolution
 
-먼저 실행:
+Run first:
 
 ```bash
 okstra check-project --json
 ```
 
-결과 처리:
+Handle the result:
 
-- `ok: true`: 이미 등록된 프로젝트다. `projectRoot`, `projectJsonPath`, `projectId`를 사용자에게 보여주고 유지 여부를 확인한다.
-- `ok: false`, `stage: "resolve"`: 사용자에게 절대 project root를 받아 `okstra check-project --cwd /abs/path --json`을 다시 실행한다.
-- `ok: false`, `stage: "project_json_missing"`: 정상 생성 경로로 진행한다.
-- 그 외 실패 stage: JSON의 `reason`을 그대로 보여주고, 원문이 지시하는 recovery를 따른다.
+- `ok: true`: already a registered project. Show `projectRoot`, `projectJsonPath`, `projectId` to the user and confirm whether to keep it.
+- `ok: false`, `stage: "resolve"`: get an absolute project root from the user and re-run `okstra check-project --cwd /abs/path --json`.
+- `ok: false`, `stage: "project_json_missing"`: proceed with the normal create path.
+- any other failure stage: show the JSON `reason` verbatim and follow the recovery the source names.
 
-## project.json 생성 또는 유지
+## Create or keep project.json
 
-`<PROJECT_ROOT>/.okstra/project.json`이 있으면 `projectId`와 `projectRoot`를 보여주고 유지/덮어쓰기 여부를 확인한다. 기본은 유지다. 기존 `projectId`를 바꾸려면 파일 삭제가 필요하므로 자동으로 덮어쓰지 않는다.
+If `<PROJECT_ROOT>/.okstra/project.json` exists, show `projectId` and `projectRoot` and confirm whether to keep or overwrite. The default is keep. Changing the existing `projectId` requires deleting the file, so do not overwrite automatically.
 
-파일이 없으면 project id를 물어본다. 답변은 비어 있지 않고 alphanumeric 문자를 하나 이상 포함해야 한다. 빈 값으로 `okstra setup --yes`를 호출하면 실패하므로 다시 묻는다.
+If the file does not exist, ask for a project id. The answer must be non-empty and contain at least one alphanumeric character. Calling `okstra setup --yes` with an empty value fails, so re-ask.
 
-생성 명령:
+Create command:
 
 ```bash
 okstra setup --yes --project-root /abs/project --project-id my-project
 ```
 
-## 선택 설정
+## Optional configuration
 
-원문상 Step 3.5 는 사용자가 명시적으로 원할 때만 수행하는 선택 설정이다 — 상세 절차는 스킬 디렉터리의 `references/project-config.md` 를 읽는다. 기본값으로 충분하면 건너뛰고 doctor로 간다.
+Per the source, Step 3.5 is optional configuration performed only when the user explicitly wants it — read `references/project-config.md` in the skill directory for the detailed procedure. If the defaults are enough, skip it and go to doctor.
 
-선택 설정:
+Optional settings:
 
-- `worktreeSyncDirs`: task worktree에 symlink할 프로젝트 상대 디렉터리 목록. 기본은 `.project-docs`, `.scratch`, `graphify-out`, `.claude`.
-- `qaCommands`: implementation verifier가 실행할 check-only lint/format/typecheck/test 명령.
-- `qaEnv`: Tier 3 conformance script가 사용할 replica/test DB, local app URL, env file, surface patterns.
+- `worktreeSyncDirs`: a list of project-relative directories to symlink into the task worktree. The default is `.project-docs`, `.scratch`, `graphify-out`, `.claude`.
+- `qaCommands`: check-only lint/format/typecheck/test commands the implementation verifier runs.
+- `qaEnv`: the replica/test DB, local app URL, env file, and surface patterns the Tier 3 conformance script uses.
 - PR body template: `okstra config set pr-template-path "<path>" --scope project|global`
 - final report language: `okstra config set report-language <en|ko|auto> --scope project`
 
-`qaCommands.cmd`는 mutation을 암시하는 token을 담으면 verifier가 거부한다. deny-list의 실제 권위는 `scripts/okstra_ctl/qa_commands.py`다.
+If `qaCommands.cmd` contains a token implying mutation, the verifier refuses it. The actual authority for the deny-list is `scripts/okstra_ctl/qa_commands.py`.
 
-## 자동 Claude 설정 symlink
+## Automatic Claude settings symlink
 
-`okstra setup`은 `<PROJECT_ROOT>/.claude/settings.local.json`을 `~/.okstra/templates/settings.local.json` symlink로 provision한다. 기존 regular file이 있으면 `.bak.<timestamp>`로 백업한 뒤 symlink를 둔다. 실패 메시지가 나오면 사용자가 기존 project-specific rule을 수동 병합해야 한다.
+`okstra setup` provisions `<PROJECT_ROOT>/.claude/settings.local.json` as a symlink to `~/.okstra/templates/settings.local.json`. If an existing regular file is present, it backs it up as `.bak.<timestamp>` and then places the symlink. If a failure message appears, the user must manually merge the existing project-specific rules.
 
-## 검증
+## Verify
 
-마지막에 실행:
+Run last:
 
 ```bash
 okstra doctor --runtime claude-code
 ```
 
-모든 check가 OK면 setup 완료로 보고한다. 실패가 있으면 출력 내용을 그대로 보여주고, 재설치/스킵 여부는 사용자가 결정하게 한다.
+If every check is OK, report setup complete. If any check fails, show the output verbatim and let the user decide whether to reinstall or skip.
 
-## 완료 메시지
+## Completion message
 
-짧게 다음 정보를 포함한다.
+Keep it short and include the following.
 
-- runtime 위치: `~/.okstra` (설치 요약의 `version stamp: x.y.z` 줄을 함께 보여준다)
+- runtime location: `~/.okstra` (also show the `version stamp: x.y.z` line from the install summary)
 - project metadata: `<PROJECT_ROOT>/.okstra/project.json`
 - `projectId`
-- 다음 단계: `/okstra-run`
+- next step: `/okstra-run`
 
-## 흔한 실패 처리
+## Common failure handling
 
-| 증상 | 처리 |
+| Symptom | Handling |
 |---|---|
-| `command not found: npx` | Node 18+ 설치 안내 |
-| `--project-id is required` | project id를 다시 물어보고 non-empty 값으로 재실행 |
-| `projectId mismatch` | 어떤 id가 canonical인지 사용자에게 확인. 자동 삭제하지 않음 |
-| `.okstra/` 쓰기 EACCES | ownership/writability 문제를 설명 |
-| `.claude/settings.local.json` symlink warning | 백업 파일과 symlink 상태를 사용자에게 보여주고 수동 병합 안내 |
-
+| `command not found: npx` | Point to installing Node 18+ |
+| `--project-id is required` | Re-ask for the project id and re-run with a non-empty value |
+| `projectId mismatch` | Confirm with the user which id is canonical. Do not delete automatically |
+| `.okstra/` write EACCES | Explain the ownership/writability problem |
+| `.claude/settings.local.json` symlink warning | Show the backup file and symlink state to the user and guide a manual merge |