okstra 0.123.0 → 0.125.0

package/runtime/skills/okstra-schedule-gen/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: okstra-schedule-gen
-description: Use when the user asks for a task-group work schedule, a consolidated implementation plan across multiple tasks in a task-group, or wants to generate a "schedule" / "일정" / "작업 계획표" for non-done tasks. Trigger words include "okstra schedule", "<task-group> 일정 만들어", "<task-group> schedule 생성", "task-group 작업 계획".
+description: Use when the user asks for a task-group work schedule, a consolidated implementation plan across multiple tasks in a task-group, or wants to generate a "schedule" / "work plan" for non-done tasks. Trigger words include "okstra schedule", "make a schedule for <task-group>", "generate a <task-group> schedule", "task-group work plan".
 model: opus
 ---
 
@@ -10,7 +10,7 @@ Generate a consolidated work schedule for the selected `implementation-planning`
 
 ## When to Use
 
-- User asks to generate a work schedule / plan / "일정" for an entire `task-group`
+- User asks to generate a work schedule / plan / "schedule" for an entire `task-group`
 - User wants a single document that summarizes all non-done tasks with effort, risk, and dependencies
 
 **Do NOT use** for single-task analysis (use `okstra-inspect status`) or to execute one task (use `okstra-run`).
@@ -19,37 +19,43 @@ Explicit command form: `okstra schedule <task-group> [--title "<custom title>"]
 
 ## Step 0: Preflight
 
+<!-- BEGIN FRAGMENT: bash-invocation-rule -->
 Run one Bash tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — a non-literal leading token defeats the `Bash(okstra:*)` permission match):
+<!-- END FRAGMENT: bash-invocation-rule -->
 
 ```bash
 okstra preflight --runtime claude-code --json
 ```
 
-Parse the stdout JSON. `ok: true` → carry `projectRoot` as a literal string and use it to locate `.okstra/discovery/task-catalog.json` and the task-group directory. `ok: false` → tell the user to run `/okstra-setup` first, then stop. If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).
+Parse the stdout JSON. `ok: true` → carry `projectRoot` as a literal string and use it to locate `.okstra/discovery/task-catalog.json` and the task-group directory. `ok: false` → tell the user to run `/okstra-setup` first, then stop.
+
+<!-- BEGIN FRAGMENT: preflight-outdated-cli -->
+If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).
+<!-- END FRAGMENT: preflight-outdated-cli -->
 
 ## Audience & authority (READ FIRST — drives everything below)
 
-**The schedule is a client-facing work plan.** It assumes the team has all permissions and can proceed without further approval. Even when the underlying per-task reports flag blocking items, missing approvals, or "사용자 확인 필요 항목", **the schedule MUST NOT surface them** — those belong in the internal report. Never emit a decision checklist, a `#### 사용자 확인 필요 항목` sub-section, `Done`/`Ready?`/`Blocking Decisions` columns, or checkbox lists; "Status" reflects work phase only.
+**The schedule is a client-facing work plan.** It assumes the team has all permissions and can proceed without further approval. Even when the underlying per-task reports flag blocking items, missing approvals, or "items requiring user confirmation", **the schedule MUST NOT surface them** — those belong in the internal report. Never emit a decision checklist, a `#### Items requiring user confirmation` sub-section, `Done`/`Ready?`/`Blocking Decisions` columns, or checkbox lists; "Status" reflects work phase only.
 
 **Assume the user and their team hold full authority and every permission required.** External approvals, access grants, sign-off, and vendor coordination are treated as already satisfied unless a report names a concrete external dependency outside the user's control. Concretely:
 
 - **Effort sizing & day totals** count engineering work only — strip approval-waiting / coordination buffers from source sizings (note the adjustment in `## Executive Summary` if material).
 - **Gantt bars** represent engineering duration only; no dead-time gaps for approval cycles. `(after <TASK-ID>)` marks genuine engineering dependencies only.
 - **Risk Mitigation Strategy** lists real engineering risks (data loss, regression surface, rollback path) — permission/coordination items are dropped.
-- **Recommended Immediate Actions / Next Action** are concrete engineering steps; "권한 확인", "승인 요청", "이해관계자 정렬" 류는 출력 금지.
+- **Recommended Immediate Actions / Next Action** are concrete engineering steps; items like "permission check", "approval request", "stakeholder alignment" MUST NOT be emitted.
 - **Cross-Task Dependencies** covers engineering coupling only (shared modules, release order, package versions).
 
-**The schedule must be self-contained.** Opaque codes pulled from internal reports (`FC-5`, `UC-12`, `M1`, decision-item letters, …) must not appear unresolved. Choose one per identifier: **Form A** (≤3 codes) — replace the code inline with a 5–20자 one-line description of the item; **Form B** (≥4 recurring codes) — keep the codes and emit a `## Glossary` table as the last section resolving every one. Decision-item letters (`A1`, `B2`, …) are approval items and may not appear at all. TASK-IDs listed in `## At a Glance` need neither.
+**The schedule must be self-contained.** Opaque codes pulled from internal reports (`FC-5`, `UC-12`, `M1`, decision-item letters, …) must not appear unresolved. Choose one per identifier: **Form A** (≤3 codes) — replace the code inline with a 5–20 character one-line description of the item; **Form B** (≥4 recurring codes) — keep the codes and emit a `## Glossary` table as the last section resolving every one. Decision-item letters (`A1`, `B2`, …) are approval items and may not appear at all. TASK-IDs listed in `## At a Glance` need neither.
 
 ## Contract SSOT — template + validator
 
-The installed template `~/.okstra/templates/reports/schedule.template.md` is the **byte-for-byte SSOT** for the output shape: frontmatter, top header block, the mandatory `##` heading list and order, per-task `Item / Detail` field labels and sub-section order, table column shapes, the ASCII Gantt format (relative day axis, plain fence, `█`/`░`/`! crit`/`est` legend), the dependency-graph shapes, and the optional `## Glossary` gate. **Read the template before writing the schedule and follow it exactly** — do not re-derive section shapes from memory. Headings and field labels stay English literals regardless of the source-report language; body prose is Korean. When a section has no data, render its heading with `_없음_` — never delete or reorder headings. Never emit mermaid or any graph DSL.
+The installed template `~/.okstra/templates/reports/schedule.template.md` is the **byte-for-byte SSOT** for the output shape: frontmatter, top header block, the mandatory `##` heading list and order, per-task `Item / Detail` field labels and sub-section order, table column shapes, the ASCII Gantt format (relative day axis, plain fence, `█`/`░`/`! crit`/`est` legend), the dependency-graph shapes, and the optional `## Glossary` gate. **Read the template before writing the schedule and follow it exactly** — do not re-derive section shapes from memory. Headings and field labels stay English literals regardless of the source-report language; body prose is Korean. When a section has no data, render its heading with `_none_` — never delete or reorder headings. Never emit mermaid or any graph DSL.
 
 `~/.okstra/lib/validators/validate-schedule.py` is the enforcement for all of the above (heading order, field labels, controlled vocabulary — e.g. `Med-High` is the canonical risk form — forbidden translations, checkbox bans, Gantt fence rules, unresolved-code detection). The Step 4 ambiguous-classification rationale line is the one rule the validator does not yet enforce — emit it yourself.
 
 One computation rule the template scaffold cannot carry inline:
 
-- **Effort-to-Day mapping**: day ranges per size are defined once in the template's `### Effort Sizing 기준` table. For the At a Glance totals line, sum that table's lower bounds across in-scope tasks for the lower total and upper bounds for the upper total.
+- **Effort-to-Day mapping**: day ranges per size are defined once in the template's `### Effort Sizing Criteria` table. For the At a Glance totals line, sum that table's lower bounds across in-scope tasks for the lower total and upper bounds for the upper total.
 
 ## Procedure
 
@@ -58,10 +64,10 @@ One computation rule the template scaffold cannot carry inline:
 1. Read `.okstra/discovery/task-catalog.json`.
 2. **Resolve which task-group to schedule — never silently guess.**
    - The user **explicitly named a task-group** (as the `okstra schedule <task-group>` argument or unambiguously in the request) → use that token; skip the picker and go to sub-step 3.
-   - The user **named no task-group, or the named token matches 0 or ≥2 groups** → present a 3-option picker via `AskUserQuestion` and do NOT proceed until the user chooses. Build the options from the catalog: walk `tasks[]` in catalog order (already `updatedAt` desc — see `scripts/okstra_ctl/render.py:654`), collect distinct `taskGroupPathSegment` values that have ≥1 entry whose resolved `workStatus` is **non-done** (defer to Step 2's inference table), and offer the newest **1–2** such groups as recommendations. The **last option is always `직접 입력`** (free-text group token, fed into sub-step 3). Label each recommendation with its non-done task count (e.g. `uploadFont (non-done 3)`).
-   - If **zero groups have a non-done task** (or the catalog is empty), do NOT open a picker — emit `해당 task-group의 모든 task가 done 상태입니다. 생성할 schedule이 없습니다.` (or `해당 task-group을 찾을 수 없습니다.` when the catalog has no tasks at all) and stop **without creating a file**.
+   - The user **named no task-group, or the named token matches 0 or ≥2 groups** → present a 3-option picker via `AskUserQuestion` and do NOT proceed until the user chooses. Build the options from the catalog: walk `tasks[]` in catalog order (already `updatedAt` desc — see `scripts/okstra_ctl/render.py:654`), collect distinct `taskGroupPathSegment` values that have ≥1 entry whose resolved `workStatus` is **non-done** (defer to Step 2's inference table), and offer the newest **1–2** such groups as recommendations. The **last option is always `Enter directly`** (free-text group token, fed into sub-step 3). Label each recommendation with its non-done task count (e.g. `uploadFont (non-done 3)`).
+   - If **zero groups have a non-done task** (or the catalog is empty), do NOT open a picker — emit `All tasks in this task-group are done. There is no schedule to generate.` (or `That task-group could not be found.` when the catalog has no tasks at all) and stop **without creating a file**.
 3. **Normalise the resolved `<task-group>`:** lowercase it, then strip every character that is not `[a-z0-9]`. Apply the same transform to each entry's `taskGroupPathSegment`. Match on equality — this is the single comparison rule; do NOT also fall back to the raw `taskGroup` field.
-4. If no tasks found, output `해당 task-group을 찾을 수 없습니다.` and stop.
+4. If no tasks found, output `That task-group could not be found.` and stop.
 5. For each matched task, read `.okstra/tasks/<task-group-segment>/<task-id-segment>/task-manifest.json` directly. Catalog data may be stale; the manifest is authoritative.
 6. **Derive `<project-id>`** for the header: prefer `task-catalog.json`'s top-level `projectId`, otherwise the first matched manifest's `projectId`. Do not invent a value.
 
@@ -69,7 +75,7 @@ One computation rule the template scaffold cannot carry inline:
 
 For inference when `workStatus` is missing or empty, defer to the inference table in `skills/okstra-inspect/SKILL.md` (`status.4` → "Default value convention") — do not duplicate it here. Then filter: resolved `done` → exclude; everything else (`todo` / `in-progress` / `blocked` / `phase-done` / inferred non-done) → include.
 
-If 0 tasks remain, output `해당 task-group의 모든 task가 done 상태입니다. 생성할 schedule이 없습니다.` and stop **without creating a file**.
+If 0 tasks remain, output `All tasks in this task-group are done. There is no schedule to generate.` and stop **without creating a file**.
 
 ### Step 3: Per-task stage extraction (Stage Map source)
 
@@ -83,7 +89,7 @@ For each in-scope task, the **authoritative source is its `implementation-planni
 
 **No planning Stage Map** (`stage-map` returned `stages: []`) → this task cannot be stage-scheduled. Tag it `[NEEDS-PLANNING]`, skip the Step 3.5 stage picker for it, and render it under its phase section as a single banner line with task-level metadata only (no Gantt bars, no day total). Continue with the remaining tasks.
 
-**`remainingStages` is empty** (every stage done but `workStatus` not `done`) → not a scheduling target. Render the task as `_완료 — 남은 stage 없음_` under its phase section; contribute no forward day total.
+**`remainingStages` is empty** (every stage done but `workStatus` not `done`) → not a scheduling target. Render the task as `_Complete — no remaining stage_` under its phase section; contribute no forward day total.
 
 ### Step 3.5: Stage selection (per task, user input)
 
@@ -96,8 +102,8 @@ Run this **once per in-scope task that has a non-empty `remainingStages`**, sequ
 3. If `remainingStages` has ≤2 stages, emit only the bundles that are distinct (1–2), never pad to 3.
 
 **Render the picker** with `AskUserQuestion` (one question for this task):
-- Options = the distinct bundles + a final `"남은 stage 전부"` option. `AskUserQuestion`'s built-in Other slot serves the `직접 입력` (arbitrary stage subset) case; when the user supplies a custom subset, close it under `depends_on` before accepting.
-- **Degenerate skip:** if only one distinct bundle exists AND it already equals all remaining stages, skip the picker for this task and set `selectedStages = remainingStages` (log `> _Stage picker 생략: 남은 stage가 단일 의존성 체인._`).
+- Options = the distinct bundles + a final `"All remaining stages"` option. `AskUserQuestion`'s built-in Other slot serves the `Enter directly` (arbitrary stage subset) case; when the user supplies a custom subset, close it under `depends_on` before accepting.
+- **Degenerate skip:** if only one distinct bundle exists AND it already equals all remaining stages, skip the picker for this task and set `selectedStages = remainingStages` (log `> _Stage picker skipped: remaining stages form a single dependency chain._`).
 
 Record the chosen `selectedStages` for this task. Any custom selection that breaks `depends_on` closure is rejected — re-prompt the same task.
 
@@ -110,19 +116,19 @@ Record the chosen `selectedStages` for this task. Any custom selection that brea
 | `bugfix` | Phase 1 when risk is High/Med-High; otherwise Phase 2 |
 | `feature` / `improvement` / `docs` / `doc` | Phase 2 |
 | `refactor` / `ops` | Phase 3 |
-| `unknown` (or unmatched / missing) | Phase 2, with rationale `> _workCategory '<raw-value>' 미정의 — Phase 2로 기본 분류._` at the top of that phase section |
+| `unknown` (or unmatched / missing) | Phase 2, with rationale `> _workCategory '<raw-value>' undefined — defaulting to Phase 2._` at the top of that phase section |
 
 Priority overrides category: `P0` → Phase 1; `P1`/`P2` → Phase 2; `P3` or multi-repo + infrastructure scope → Phase 3. When still ambiguous, place the task in the closest phase and add a one-line rationale at the top of that phase section (not validator-enforced — emit it yourself).
 
-Phase bucketing stays **task-level** (a task lands in one Phase by its `workCategory`/Priority). Within a task's per-task section, the **selected stages become the Work Breakdown rows**: one row per `selectedStages` entry with its `title`, `step_count`-derived effort, and `depends_on`. Stages excluded from `selectedStages` because they are already done are listed once as `> _완료 stage: stage <n>, …_` and carry no forward effort. This keeps the mandatory heading skeleton unchanged while moving the unit of work to the stage.
+Phase bucketing stays **task-level** (a task lands in one Phase by its `workCategory`/Priority). Within a task's per-task section, the **selected stages become the Work Breakdown rows**: one row per `selectedStages` entry with its `title`, `step_count`-derived effort, and `depends_on`. Stages excluded from `selectedStages` because they are already done are listed once as `> _Done stages: stage <n>, …_` and carry no forward effort. This keeps the mandatory heading skeleton unchanged while moving the unit of work to the stage.
 
 ### Step 5: Gantt decision (render by default)
 
-`## Gantt Chart` is **rendered by default** — skip ONLY when literally no day signal exists (every task is effort=XXL with no visible decomposition, or all tasks lack both effort sizing and decomposition). Render whenever any of these hold: 2+ tasks with effort sizing; 1 task whose effort yields a range (mid-point bar, or `lo`/`hi` two-bar form); 1 task with Part/Phase/Step decomposition in the source (bars at decomposition-unit level); total estimated effort ≥ 3 days. When per-unit day allocations aren't itemized, split the parent range across the visible units yourself and append the `est` annotation (or add `> 일별 배분은 추정치이며 차단 항목 해소 후 갱신 권장.`). "Range is wide", "single task", "user decisions pending" are NOT skip reasons — render an estimate-tagged chart instead.
+`## Gantt Chart` is **rendered by default** — skip ONLY when literally no day signal exists (every task is effort=XXL with no visible decomposition, or all tasks lack both effort sizing and decomposition). Render whenever any of these hold: 2+ tasks with effort sizing; 1 task whose effort yields a range (mid-point bar, or `lo`/`hi` two-bar form); 1 task with Part/Phase/Step decomposition in the source (bars at decomposition-unit level); total estimated effort ≥ 3 days. When per-unit day allocations aren't itemized, split the parent range across the visible units yourself and append the `est` annotation (or add `> Per-day allocation is an estimate; refresh recommended after blocking items are resolved.`). "Range is wide", "single task", "user decisions pending" are NOT skip reasons — render an estimate-tagged chart instead.
 
 When the source is a Stage Map, the Gantt **bars are the selected stages** (one bar per `selectedStages` entry), day length split from `step_count` (or the effort range across the stage's steps), and cross-stage `(after stage <n>)` / `(after <TASK-ID>)` edges follow `depends_on`. Already-done stages never get a bar. A task tagged `[NEEDS-PLANNING]` contributes no bars.
 
-When you do skip, insert in the section's position exactly: `> _Gantt Chart 생략: <concrete reason referencing the actual data>._`
+When you do skip, insert in the section's position exactly: `> _Gantt Chart skipped: <concrete reason referencing the actual data>._`
 
 **Directive override (highest priority).** Before applying the heuristic, check for a `## Directive` section, first hit wins: (1) the `--directive-file <abs-path>` argument; (2) `<PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/instruction-set/analysis-material.md`; (3) none → apply the default heuristic silently. A found directive overrides the render/skip heuristic for the affected section — note it inline as `> _Per Directive directive: <verbatim short excerpt>._` — and its pre-supplied day allocations / phase weights are used verbatim as bar lengths. A directive file without a `## Directive` heading counts as "no directive".
 
@@ -159,11 +165,11 @@ Reached only after Step 5.5 returns `pass`. **Promote** the verified staging dra
 ### Step 8: Completion message (Korean)
 
 ```
-✓ Schedule 생성 완료: <relative-path>
-- 포함 task: N개
-- 제외(done) task: M개
-- 예상 소요: X.X ~ Y.Y days (Effort 합산)
-- 모드: lead + verifier
+✓ Schedule generated: <relative-path>
+- Included tasks: N
+- Excluded (done) tasks: M
+- Estimated effort: X.X ~ Y.Y days (Effort sum)
+- Mode: lead + verifier
 ```
 
 ## Edge Cases
@@ -171,12 +177,12 @@ Reached only after Step 5.5 returns `pass`. **Promote** the verified staging dra
 | Case | Handling |
 |------|----------|
 | `workStatus` absent or empty | Resolve via the `okstra-inspect status.4` inference table; include unless resolved `done` |
-| Filtered task count is 0 | Emit "모든 task가 done" message; do NOT create a file |
-| implementation-planning 리포트 없음 | `[NEEDS-PLANNING]` 배너로만 나열, stage picker·Gantt·day total 없음 |
-| 남은 stage 0개(전부 done, workStatus 미표기) | `_완료 — 남은 stage 없음_`, forward 산출 없음 |
-| 남은 stage ≤2개 | 누적 묶음을 나오는 만큼만(1~2), 단일 체인이면 picker 생략·전부 진행 |
-| verifier 2회 미통과 | 최종 파일 미작성, 잔여 missing/extra/order 사용자 보고 |
-| `task-group` matches no tasks | "해당 task-group을 찾을 수 없습니다." and stop |
+| Filtered task count is 0 | Emit the "all tasks are done" message; do NOT create a file |
+| No implementation-planning report | List with a `[NEEDS-PLANNING]` banner only; no stage picker / Gantt / day total |
+| 0 remaining stages (all done, workStatus unmarked) | `_Complete — no remaining stage_`, no forward computation |
+| ≤2 remaining stages | Emit only as many cumulative bundles as arise (1–2); a single chain skips the picker and proceeds with all |
+| verifier fails twice | Final file not written; report residual missing/extra/order to the user |
+| `task-group` matches no tasks | "That task-group could not be found." and stop |
 | Catalog and manifest disagree on `workStatus` | Manifest wins (catalog may be stale) |
 | task-group casing / punctuation variants | Normalise both sides (lowercase + strip non-`[a-z0-9]`), compare against `taskGroupPathSegment` only; use the manifest's segment verbatim for path output |
 

package/runtime/skills/okstra-setup/SKILL.md

@@ -140,7 +140,7 @@ Inform the user with a short summary:
 | `command not found: npx` | Node missing | Install node 18+. |
 | `okstra ensure-installed` keeps reinstalling | `~/.okstra/version` write fails (permissions) | Check `~/.okstra` ownership and writability. |
 | `error: --project-id is required (no existing project.json, not a TTY)` | `okstra setup --yes` invoked without `--project-id`, or with empty answer to Step 3 prompt | Re-ask Step 3 and pass a non-empty id via `--project-id`. |
-| `projectId mismatch` / `projectId 불일치` | `project.json` already exists with a different id | Decide which id is canonical; manually delete `<PROJECT_ROOT>/.okstra/project.json` to re-register, or re-run with the existing id. |
+| `projectId mismatch` / `projectId mismatch` | `project.json` already exists with a different id | Decide which id is canonical; manually delete `<PROJECT_ROOT>/.okstra/project.json` to re-register, or re-run with the existing id. |
 | `EACCES` writing under `.okstra/` | directory owned by another user (e.g. created by a previous root-shell run) | `chown -R "$USER" <PROJECT_ROOT>/.okstra` or delete and let setup recreate. |
 | `warning: failed to provision .claude/settings.local.json symlink` | a non-symlink `.claude/settings.local.json` already exists and the backup-and-replace step failed | Inspect `<PROJECT_ROOT>/.claude/settings.local.json{,.bak.*}`; manually merge project-specific rules, then re-run setup. |
 | `npx okstra@latest install` succeeds but `doctor` shows FAIL | runtime/{python,bin,skills} sync not yet performed (pre-release package) | Use dev install: clone the repo and run `node bin/okstra install --link <repo>`. |

package/runtime/skills/okstra-setup/references/project-config.md

@@ -140,19 +140,19 @@ overwriting silently.
 `~/.okstra/templates/prd/pr-body.template.md`. Most projects want their own
 (e.g. `.github/PULL_REQUEST_TEMPLATE.md`). Pre-registration during setup is
 opt-in; the same prompt is offered again on the first `release-handoff` run,
-so deferring (`나중에`) is safe.
+so deferring (`Later`) is safe.
 
 Ask with `AskUserQuestion` (fixed options — file path entry happens in the
 follow-up plain text prompt):
 
-- **Question**: `"이 프로젝트에서 release-handoff 가 사용할 PR 본문 템플릿을 등록할까요?"`
+- **Question**: `"Register the PR body template that release-handoff will use for this project?"`
 - **Options**:
-  1. `이번 프로젝트만 (project scope)` — writes `prTemplatePath` to `<PROJECT_ROOT>/.okstra/project.json`.
-  2. `전역 (global scope)` — writes `prTemplatePath` to `~/.okstra/config.json`.
-  3. `나중에` — skip.
+  1. `This project only (project scope)` — writes `prTemplatePath` to `<PROJECT_ROOT>/.okstra/project.json`.
+  2. `Global (global scope)` — writes `prTemplatePath` to `~/.okstra/config.json`.
+  3. `Later` — skip.
 
 If scope 1 or 2, follow up with a plain text prompt:
-`"PR 본문 템플릿 파일 경로를 알려주세요. project 스코프는 project-root 기준 상대경로 또는 절대경로, global 스코프는 절대경로 또는 ~/ 시작 경로만 허용됩니다."`
+`"Tell me the PR body template file path. project scope accepts a project-root-relative or absolute path; global scope accepts only an absolute path or a ~/ path."`
 Consume the next user message, then run:
 
 ```bash
@@ -160,23 +160,24 @@ okstra config set pr-template-path "<typed-path>" --scope <project|global>
 ```
 
 The command validates the value (global rejects relative paths) and writes
-atomically. Surface its stdout JSON. If the user chose `나중에`, tell them
+atomically. Surface its stdout JSON. If the user chose `Later`, tell them
 they can register later via the same `okstra config set` command or the
 per-run override prompt during the next release-handoff run.
 
 ## E. Final report language (`reportLanguage`)
 
-기본은 영어. Skip 하면 `reportLanguage` 필드를 두지 않고 runtime 이 `auto` 로
-처리한다 — task brief 의 주 서술 언어를 따라간다 (한국어 brief → 한국어
-report, 영어 brief → 영어 report).
+The default is English. If you skip, no `reportLanguage` field is written and
+the runtime treats it as `auto` — it follows the task brief's primary
+narration language (Korean brief → Korean report, English brief → English
+report).
 
 AskUserQuestion (fixed options):
-- Question: `"Final report 를 어느 언어로 작성할까요?"`
+- Question: `"Which language should the final report be written in?"`
 - Options:
   1. `English (recommended)` → `en`
-  2. `한국어` → `ko`
-  3. `Auto (task brief 언어로 추론, 불분명하면 영어)` → `auto`
-  4. `나중에` → skip (필드 미설정 → runtime 이 auto 로 처리)
+  2. `Korean` → `ko`
+  3. `Auto (infer from the task brief language; English if unclear)` → `auto`
+  4. `Later` → skip (no field set → runtime treats it as auto)
 
 If the user picks 1/2/3:
 
@@ -184,5 +185,5 @@ If the user picks 1/2/3:
 okstra config set report-language <en|ko|auto> --scope project
 ```
 
-전역 기본값은 README 의 "global config" 안내대로 `--scope global` 로 수동
-설정한다 — 이 flow 에서는 project 스코프만 제공한다.
+Set the global default manually with `--scope global` as described in the
+README's "global config" guidance — this flow offers only project scope.

package/runtime/skills/okstra-usage/SKILL.md

@@ -21,8 +21,11 @@ okstra preflight --runtime claude-code --json
 ```
 
 On `ok:true`, carry `projectRoot`. On `ok:false`, tell the user to run `/okstra-setup` first
-and stop. On `unknown command: preflight`, tell the user to run
-`npm i -g okstra@latest` and stop.
+and stop.
+
+<!-- BEGIN FRAGMENT: preflight-outdated-cli -->
+If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).
+<!-- END FRAGMENT: preflight-outdated-cli -->
 
 ## Step 1: Resolve the day window
 

package/runtime/skills/okstra-user-response/SKILL.md

@@ -18,7 +18,11 @@ Single entry point for answering the clarification questions an okstra run left
 
 ## Step 0: Preflight (shared)
 
-Before anything, run one Bash tool call whose leading token is the literal `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — a non-literal leading token defeats the `Bash(okstra:*)` permission match):
+Before anything:
+
+<!-- BEGIN FRAGMENT: bash-invocation-rule -->
+Run one Bash tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — a non-literal leading token defeats the `Bash(okstra:*)` permission match):
+<!-- END FRAGMENT: bash-invocation-rule -->
 
 ```bash
 okstra preflight --runtime claude-code --json
@@ -26,7 +30,11 @@ okstra preflight --runtime claude-code --json
 
 Branch on the stdout JSON:
 - `ok: true` → carry `projectRoot` and `projectId` as literal strings; they are the base for every step below.
-- `ok: false` → this project has no okstra setup. Tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop. If the user pointed at a specific project directory, re-run targeting it: `okstra preflight --runtime claude-code --cwd <that-dir> --json` (`--cwd` is the sanctioned way to target a project — a leading `cd` would break the permission match); only if that **also** returns `ok:false` do you stop. If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).
+- `ok: false` → this project has no okstra setup. Tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop. If the user pointed at a specific project directory, re-run targeting it: `okstra preflight --runtime claude-code --cwd <that-dir> --json` (`--cwd` is the sanctioned way to target a project — a leading `cd` would break the permission match); only if that **also** returns `ok:false` do you stop.
+
+<!-- BEGIN FRAGMENT: preflight-outdated-cli -->
+If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).
+<!-- END FRAGMENT: preflight-outdated-cli -->
 
 Then resolve the okstra home once (the `list` sub-command needs it):
 
@@ -34,7 +42,11 @@ Then resolve the okstra home once (the `list` sub-command needs it):
 okstra paths --field home
 ```
 
-Paste the printed path literally into `--home` below. Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
+Paste the printed path literally into `--home` below.
+
+<!-- BEGIN FRAGMENT: python-bootstrap-note -->
+Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
+<!-- END FRAGMENT: python-bootstrap-note -->
 
 ## Step 1: List awaiting tasks → picker