okstra 0.123.0 → 0.125.0

package/runtime/skills/_fragments/bash-invocation-rule.md

@@ -0,0 +1 @@
+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):

package/runtime/skills/_fragments/preflight-outdated-cli.md

@@ -0,0 +1 @@
+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).

package/runtime/skills/_fragments/python-bootstrap-note.md

@@ -0,0 +1 @@
+Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.

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

@@ -1,6 +1,6 @@
 ---
 name: okstra-brief-gen
-description: Use when the user wants to generate a task brief file for okstra from a requirements document, an existing markdown file, an issue-tracker ticket (Linear / Jira / GitHub / Notion), a link URL, conversation context, or short user input. Produces the markdown brief consumed by `okstra-run` Step 5 (task-brief). Trigger words include "okstra brief", "make a brief", "brief 생성", "요구사항 brief 만들어", "okstra 입력 만들어", "task brief 작성", "이 티켓으로 brief", "이 링크로 brief".
+description: Use when the user wants to generate a task brief file for okstra from a requirements document, an existing markdown file, an issue-tracker ticket (Linear / Jira / GitHub / Notion), a link URL, conversation context, or short user input. Produces the markdown brief consumed by `okstra-run` Step 5 (task-brief). Trigger words include "okstra brief", "make a brief", "generate a brief", "make a brief from requirements", "make an okstra input", "write a task brief", "brief from this ticket", "brief from this link".
 ---
 
 # okstra-brief-gen
@@ -10,13 +10,12 @@ Generate a single `task brief` markdown file under the okstra project domain
 [`okstra-run`](../okstra-run/SKILL.md) as `--task-brief`.
 
 **Purpose — pre-discovery artifact.** A brief is the **pre-discovery** stage
-of an okstra task: it absorbs domain alignment, codebase evidence
-collection, and reporter intent capture so that the downstream expert
-phases (`requirements-discovery` / `error-analysis` /
-`implementation-planning`) can run with **zero fill-in questions** to the
-operator. A brief is written from a report by a domain reporter (PM, CS,
-ops, QA, end-user, …) **or** by a developer themselves — the input
-provenance does not change the output contract.
+of an okstra task: it absorbs domain alignment, codebase evidence, and
+reporter intent so the downstream expert phases (`requirements-discovery` /
+`error-analysis` / `implementation-planning`) run with **zero fill-in
+questions** to the operator. It is written from a domain reporter's report
+(PM, CS, ops, QA, end-user, …) **or** by a developer — provenance does not
+change the output contract.
 
 This is a **labelled-handoff** to the next phase, built on two
 non-negotiables:
@@ -24,19 +23,19 @@ non-negotiables:
 - **Verbatim-preserving capture** — the reporter's words are kept
   byte-for-byte under `Source Material`. Format-only transformations
   (e.g. Jira ADF → Markdown) and codebase cross-references are mechanical
-  and reversible; they are recorded with the `format-conversion` and
-  `evidence-link` Augmentation labels.
+  and reversible, recorded with the `format-conversion` and `evidence-link`
+  Augmentation labels.
 - **Labelled interpretation** — anywhere the skill resolves a reporter
-  word to a project-canonical term or infers reporter meaning that was
-  not literally stated, the addition lives in `Augmentation` with the
-  `terminology-mapping` or `intent-inference` label. Unlabelled
-  augmentation is forbidden — the label is what makes the interpretation
-  auditable and (for `intent-inference`) verifiable against the reporter.
+  word to a project-canonical term or infers meaning not literally stated,
+  the addition lives in `Augmentation` with the `terminology-mapping` or
+  `intent-inference` label. Unlabelled augmentation is forbidden — the
+  label is what makes the interpretation auditable and (for
+  `intent-inference`) verifiable against the reporter.
 
 A brief still does NOT write a PRD, decompose work into vertical slices,
-or decide modules. Those belong to later okstra phases
-(`requirements-discovery`, `implementation-planning`) which use
-cross-verification and would conflict with anything decided here.
+or decide modules — those belong to later cross-verification phases
+(`requirements-discovery`, `implementation-planning`) and would conflict
+with anything decided here.
 
 ## Intended chain
 
@@ -67,7 +66,7 @@ okstra-brief-gen (error-feedback variant)
 
 - The user pastes / points at a requirements doc, support ticket, bug report,
   or rough description and wants to start the okstra pipeline.
-- The user asks to "make a brief", "okstra 입력 만들어", "brief 생성", etc.
+- The user asks to "make a brief", "make an okstra input", "generate a brief", etc.
 - A previous okstra task produced findings the user wants to convert into a
   new follow-up task's brief.
 
@@ -82,21 +81,17 @@ okstra-brief-gen (error-feedback variant)
 
 ## Artifact-home rule (okstra-wide)
 
-**All okstra-generated artifacts live under `<PROJECT_ROOT>/.okstra/`.**
-This includes briefs, run manifests, reports, worker results, status,
-sessions, and any other run output.
-
-All writes by this skill stay inside `.okstra/`. When domain
-alignment (Step 3b / Step 4.5) yields a glossary change that the user
-approves inline, the change is written to:
-
-- `<PROJECT_ROOT>/.okstra/glossary.md` — okstra's internal
-  glossary. Created if absent; appended to a `## Glossary` section
-  otherwise.
-
-Paths outside `<PROJECT_ROOT>/.okstra/**` are not okstra
-memory. This skill reads them only when the reporter explicitly cited them
-as source material, and never writes them. Decision files (when raised by
+**All okstra-generated artifacts live under `<PROJECT_ROOT>/.okstra/`** —
+briefs, run manifests, reports, worker results, status, sessions, and any
+other run output. All writes by this skill stay inside `.okstra/`. When
+domain alignment (Step 3b / Step 4.5) yields a user-approved glossary
+change, it is written to `<PROJECT_ROOT>/.okstra/glossary.md` (okstra's
+internal glossary; created if absent, else appended to a `## Glossary`
+section).
+
+Paths outside `<PROJECT_ROOT>/.okstra/**` are not okstra memory. This skill
+reads them only when the reporter explicitly cited them as source material,
+and never writes them. Decision files (when raised by
 `implementation-planning`) also live inside okstra's subtree at
 `<PROJECT_ROOT>/.okstra/decisions/<NNNN>-<slug>.md`.
 
@@ -108,9 +103,8 @@ as source material, and never writes them. Decision files (when raised by
   (single / parent) or
   `<PROJECT_ROOT>/.okstra/briefs/<task-group>/sub/<ticket-id>-<file-title>.md`
   (tracker child ticket; at depth N, `sub/` is nested N times) — output
-  location for this skill. `<ticket-id>` is the raw issue-id when the source
-  is a tracker, otherwise free-text supplied by the user. `<file-title>` is
-  auto-slugified from the tracker title, otherwise from user input.
+  location for this skill. See Step 2b for `<ticket-id>` / `<file-title>`
+  resolution.
 - okstra-internal glossary (write target of Step 4.5):
   `<PROJECT_ROOT>/.okstra/glossary.md`. Created if absent.
 - okstra-internal decisions (write target of `implementation-planning`
@@ -119,13 +113,23 @@ as source material, and never writes them. Decision files (when raised by
 
 ## Step 0: Preflight
 
-Every Bash command in this skill is a **separate 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).
+Every Bash command in this skill is a **separate Bash tool call**.
+
+<!-- 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 into the steps below. `ok: false` (or `okstra` not on `PATH` at all) → tell the user: "okstra not set up — 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). Do **not** try `npx -y okstra@latest ...` as a fallback.
+Parse the stdout JSON. `ok: true` → carry `projectRoot` as a literal string into the steps below. `ok: false` (or `okstra` not on `PATH` at all) → tell the user: "okstra not set up — 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 -->
+
+Do **not** try `npx -y okstra@latest ...` as a fallback.
 
 ## Step 1: Choose input source
 
@@ -135,9 +139,9 @@ Parse the stdout JSON. `ok: true` → carry `projectRoot` as a literal string in
 
 - **Label**: `"Brief variant?"`
 - **Options**:
-  1. `Reporter input` — reporter 발화 / 티켓 / 링크 / 자유 텍스트를 verbatim 으로 흡수. 기존 4-source 흐름.
-  2. `Codebase scan` — 코드베이스 범위 + lens 우선순위만 받아 `improvement-discovery` phase 의 입력을 생성.
-  3. `Error feedback` (`error-feedback`) — `okstra error-zip` 이 만든 `.zip` 의 빈발 클러스터 1개를 `error-analysis` brief 로 변환 (okstra 자가수정용).
+  1. `Reporter input` — absorb the reporter's utterance / ticket / link / free text verbatim. The existing 4-source flow.
+  2. `Codebase scan` — take only the codebase scope + lens priorities and generate the input for the `improvement-discovery` phase.
+  3. `Error feedback` (`error-feedback`) — convert one frequent cluster from the `.zip` produced by `okstra error-zip` into an `error-analysis` brief (for okstra self-repair).
 
 ### 1.A. Reporter input (variant 1)
 
@@ -171,28 +175,24 @@ in Source Material.
 Order of operations:
 
 0. **Task-group precondition (REQUIRED before any recursion)** — if the
-   tracker fetch may yield child tickets (which is always possible until the
-   first fetch proves otherwise), acquire `task_group` first by running Step
-   2a now. Step 2a is otherwise re-entered later for non-tracker sources;
-   when reached again it MUST reuse the value collected here without asking
-   again. Rationale: the recursion in sub-step 6 records descendant brief
-   paths under `<task-group>/sub.../`, and those paths cannot be formed
-   until `task_group` is known. Without this preflight the recursive walk
-   would either stall mid-collection or invent a placeholder group.
+   tracker fetch may yield child tickets (always possible until the first
+   fetch proves otherwise), acquire `task_group` first by running Step 2a
+   now; when Step 2a is re-entered later it MUST reuse this value without
+   asking again. Why: sub-step 6's recursion records descendant brief paths
+   under `<task-group>/sub.../`, which cannot be formed until `task_group`
+   is known — without this preflight the walk stalls or invents a
+   placeholder group.
 
    **Sequential, never batched.** Run Step 2a as its **own**
-   `AskUserQuestion` call here, then ask sub-step 1's ticket question in a
-   **separate** call. Do NOT combine the task-group question and the
-   ticket-ref question into one `AskUserQuestion` — they are asked one at a
-   time, task group first (this preflight), ticket ref second. When you
-   relay this preflight, tell the user in one line *why* task group comes
-   before the ticket (it scopes where this ticket's brief — and any
-   sub-ticket briefs — are written).
+   `AskUserQuestion` call, then ask sub-step 1's ticket question in a
+   **separate** call — never combine the task-group and ticket-ref
+   questions into one. When you relay this preflight, tell the user in one
+   line *why* task group comes first (it scopes where this ticket's brief —
+   and any sub-ticket briefs — are written).
 1. `AskUserQuestion` (free text):
    `"Ticket key or URL (e.g. LIN-1234, PROJ-42, https://linear.app/..., https://your.atlassian.net/browse/...)"` →
    `ticket_ref`. Issue this only **after** Step 2a's task-group answer is in
-   hand — never in the same `AskUserQuestion` call as the task-group
-   question.
+   hand (per sub-step 0's sequential rule).
 2. Auto-detect the tracker by URL host or key prefix (`linear.app` → Linear,
    `atlassian.net` or `JIRA_*` pattern → Jira, `github.com/.../issues/` →
    GitHub, `notion.so` → Notion). If detection fails, ask once more via
@@ -288,32 +288,32 @@ If the user picked `Codebase scan`, gather the codebase-scan-specific inputs:
 
 Validation (before Step 4 sharpening):
 
-- `scan_scope` 의 각 path 가 `<PROJECT_ROOT>` 안에 실제 존재하는지 `ls` 로 확인 — 없으면 한 질문으로 정정.
-- `priority_lenses` 가 `~/.okstra/lib/python/okstra_ctl/improvement_lenses.py` 의 `LENSES` 부분집합 (1–4) 인지 확인 — 위반 시 enum 표시 + 재선택. 최종 enforcement 는 Step 6.6 `validate-brief` (`check_codebase_scope`) 가 수행.
-- `candidate_cap` 이 1–12 정수인지 확인.
+- Confirm that each path in `scan_scope` actually exists inside `<PROJECT_ROOT>` via `ls` — if not, correct it with a single question.
+- Confirm that `priority_lenses` is a subset (1–4) of `LENSES` in `~/.okstra/lib/python/okstra_ctl/improvement_lenses.py` — on violation, show the enum + re-select. Final enforcement is done by Step 6.6 `validate-brief` (`check_codebase_scope`).
+- Confirm that `candidate_cap` is an integer in 1–12.
 
 Once validation passes, jump to Step 2 (task key).
 
-### 1.C. Error feedback (`error-feedback`, variant 3) — okstra 자가수정용
+### 1.C. Error feedback (`error-feedback`, variant 3) — for okstra self-repair
 
-If the user picked `Error feedback`, the input is a `.zip` produced by `okstra error-zip --out <path>`. 이 variant 는 빈발 에러 클러스터 1개를 골라 `error-analysis` brief 로 변환하며, **수정 대상은 okstra 레포 자신**이다.
+If the user picked `Error feedback`, the input is a `.zip` produced by `okstra error-zip --out <path>`. This variant selects one frequent error cluster and converts it into an `error-analysis` brief, and **the repair target is the okstra repo itself**.
 
-입력: `okstra error-zip` 이 만든 `.zip`. 사용자에게 zip 경로를 묻는다(이전에 받은 경로가 있으면 `Recommended:` 로 재사용 제안).
+Input: the `.zip` produced by `okstra error-zip`. Ask the user for the zip path (if a path was received earlier, propose reusing it as `Recommended:`).
 
-1. zip 의 `report.md` 를 읽어 빈발 클러스터 표를 사용자에게 보여주고, **클러스터 1개**를 고르게 한다.
-   `AskUserQuestion` (single-select, `직접 지정` always last):
-   1. top-1 클러스터 (빈도 최다) — `Recommended:` 표시.
-   2. top-2 클러스터.
-   3. `직접 지정` — 사용자가 표에서 직접 클러스터를 지정.
-2. 고른 클러스터의 익명화 레코드를 brief 의 `## Source Material` 에 인용한다 — zip 내부 `errors/anonymized.jsonl` 에서 **선택한 클러스터 번호(`report.md` 표의 `#`)와 일치하는 `clusterId` 레코드**만 추려, errorType · command · exitCode · phase · agent · 대표 메시지를 표/리스트로 옮긴다. (`#` ↔ `clusterId` 는 1:1 대응이며, 같은 errorType+phase+agent 라도 정규화 메시지가 다르면 별개 클러스터다 — 병합하지 않는다.)
-3. frontmatter `scope` 는 reporter-input 으로 둔다 — 이 variant 는 익명화 에러 레코드를 `## Source Material` 에 verbatim 으로 담는 reporter-input 계열이므로 `scope` 키를 생략한다(⇒ `reporter-input`). codebase-scan 전용 키(`priority-lenses`·`scan-scope` 등)는 쓰지 않는다. 다음 phase 신호는 Step 6 의 `Recommended next phase: error-analysis` 헤더 줄로 보낸다(별도 frontmatter 키를 만들지 않는다). 본문에는 수정 대상을 명시한다: "이 에러는 okstra 런타임/프롬프트/래퍼/권한 seed 결함 신호이며, 수정 대상은 okstra 소스(`prompts/`·`agents/`·`scripts/`·`templates/`)다."
-4. **단일 클러스터 = 단일 실패조건** 원칙을 지킨다 — 이질적 errorType 을 한 brief 에 섞지 않는다(`error-analysis` 의 symptom-lock 요건). 다른 클러스터도 고치고 싶으면 클러스터마다 별도 brief 를 만든다.
-5. 생성된 brief 끝에 다음 단계를 인라인으로 적는다: "okstra 레포에서 `okstra-run --task-type error-analysis` 로 이 brief 를 실행하세요."
+1. Read the zip's `report.md`, show the frequent-cluster table to the user, and have them pick **one cluster**.
+   `AskUserQuestion` (single-select, `Specify manually` always last):
+   1. top-1 cluster (highest frequency) — marked `Recommended:`.
+   2. top-2 cluster.
+   3. `Specify manually` — the user names a cluster directly from the table.
+2. Quote the chosen cluster's anonymized records into the brief's `## Source Material` — from `errors/anonymized.jsonl` inside the zip, pull only the `clusterId` records **matching the chosen cluster number (the `#` in `report.md`'s table)**, and move their errorType · command · exitCode · phase · agent · representative message into a table/list. (`#` ↔ `clusterId` is a 1:1 mapping, and even the same errorType+phase+agent counts as a separate cluster when the normalized message differs — do not merge them.)
+3. Leave frontmatter `scope` as reporter-input — because this variant carries anonymized error records verbatim in `## Source Material`, it belongs to the reporter-input family, so omit the `scope` key (⇒ `reporter-input`). Do not use the codebase-scan-only keys (`priority-lenses`·`scan-scope`, etc.). Send the next-phase signal via Step 6's `Recommended next phase: error-analysis` header line (do not create a separate frontmatter key). In the body, state the repair target explicitly: "this error is a signal of an okstra runtime/prompt/wrapper/permission-seed defect, and the repair target is the okstra source (`prompts/`·`agents/`·`scripts/`·`templates/`)."
+4. Keep the **single cluster = single failure condition** principle — do not mix heterogeneous errorTypes into one brief (the `error-analysis` symptom-lock requirement). To also fix another cluster, make a separate brief per cluster.
+5. At the end of the generated brief, write the next step inline: "run this brief from the okstra repo with `okstra-run --task-type error-analysis`."
 
 Validation (before Step 4 sharpening):
 
-- zip 경로가 실제 존재하고 `report.md` + `errors/anonymized.jsonl` 을 포함하는지 확인 — 없으면 한 질문으로 정정.
-- 고른 클러스터가 단일 errorType 인지 확인 — 여러 errorType 이 섞이면 한 질문으로 1개만 남긴다.
+- Confirm the zip path actually exists and contains `report.md` + `errors/anonymized.jsonl` — if not, correct it with a single question.
+- Confirm the chosen cluster is a single errorType — if multiple errorTypes are mixed, keep only one with a single question.
 
 Once validation passes, jump to Step 2 (task key).
 
@@ -334,34 +334,33 @@ okstra task-list
 Parse the JSON `tasks[]` array. The `taskGroup` field is a **raw display
 name, not a slug** — `slugify` each value (lowercase + non-alphanumeric →
 `-`) and **dedupe by slug** so case/format variants collapse (e.g.
-`uploadFont` and `uploadfont` are one group, not two). Order the distinct
-slugs by their most-recent `updatedAt`. Take the **2 most-recent** distinct
-slugs as recommendations and show them in slug form.
+`uploadFont` and `uploadfont` are one group, not two). Order distinct slugs
+by most-recent `updatedAt` and take the **2 most-recent** as recommendations,
+shown in slug form.
 
 `AskUserQuestion` (single-select):
 
 - **Label**: `"Task group?"`
-- **Options** (recommendations first, `직접 입력` always last):
+- **Options** (recommendations first, `Enter directly` always last):
   1. (and 2.) each recommended existing group, most-recent first —
-     label `<group> (기존)` (e.g. `uploadfont (기존)`).
-  3. `직접 입력` — free-text for a new or other group.
+     label `<group> (existing)` (e.g. `uploadfont (existing)`).
+  3. `Enter directly` — free-text for a new or other group.
 
 When the user picks an existing group, use its value verbatim. When they
-pick `직접 입력`, take a free-text value via a follow-up question.
+pick `Enter directly`, take a free-text value via a follow-up question.
 
 If `okstra task-list` returns an empty `tasks[]` (no prior tasks), skip the
 picker and ask one free-text question:
 `"Task group (e.g. backend-api, INV-1234, refactor)"` → `task_group`.
 
 Slug rule: same as `okstra-run` Step 3 — slugify, must have at least one
-alphanumeric character. **Always slugify the chosen value**, whether it came
-from an existing-group selection or `직접 입력` — the `taskGroup` returned by
-`okstra task-list` is a raw display name, not a slug, so picking one verbatim
-would create a non-standard directory (e.g. `briefs/uploadFont/`). The brief's
-on-disk directory segment (`briefs/<task-group>/`) and the frontmatter
-`task-group` value are both the slugified form, and `validate-brief.py`
-(Step 6.6) rejects any brief whose directory segment differs from
-`slugify(frontmatter task-group)`.
+alphanumeric character. **Always slugify the chosen value**, whether from an
+existing-group selection or `Enter directly` — the `taskGroup` from `okstra
+task-list` is a raw display name, so picking one verbatim would create a
+non-standard directory (e.g. `briefs/uploadFont/`). The on-disk directory
+segment (`briefs/<task-group>/`) and the frontmatter `task-group` are both
+the slugified form, and `validate-brief.py` (Step 6.6) rejects any brief
+whose directory segment differs from `slugify(frontmatter task-group)`.
 
 If `task_group` was already collected by Step 1b sub-step 0 (tracker
 preflight), reuse that value silently — do NOT ask again.
@@ -482,10 +481,9 @@ on a project-internal concrete object whenever possible.
   `Read` / `Grep` to locate the concrete file path (relative to
   `<PROJECT_ROOT>`) and the canonical symbol name. Record the resolution
   under `Augmentation > Domain alignment` with the `evidence-link` label,
-  and link the absolute path from `Related Artifacts`. This is what makes
-  the brief portable across downstream workers (Claude / Codex / Antigravity)
-  that may operate in separate worktrees and need to point at the same
-  object.
+  and link the absolute path from `Related Artifacts` — this keeps the brief
+  portable across downstream workers (Claude / Codex / Antigravity) in
+  separate worktrees that must point at the same object.
 - **Conversion-block signal** — when a reporter statement cannot be
   mapped to project vocabulary even after codebase exploration (e.g. the
   reporter names a UI element that does not exist by that name, or
@@ -549,22 +547,22 @@ or to a `> augmented: <label>` blockquote inside the required section, so
 it is clear that the content is the skill's / user's added interpretation
 rather than the original source.
 
-### codebase-scan variant 전용 강화 규칙 (improvement-discovery)
+### codebase-scan variant-specific sharpening rules (improvement-discovery)
 
-이 5개 규칙은 `scope: codebase` brief 에 한해 적용. budget 은 기본 6 → **8** 로 확대.
+These 5 rules apply only to `scope: codebase` briefs. The budget expands from the default 6 → **8**.
 
-1. **scan-scope 경로 존재 검증.** 각 path 를 `ls` / `Read` 로 확인. 없으면 한 질문으로 정정 (path 의 가장 가까운 후보를 `Recommended:` 로 제시).
-2. **모호 path narrowing.** `"백엔드"`, `"결제 모듈"` 같은 추상 path 는 구체 디렉토리 1개 이상으로 narrowing. codebase-first 추측 후 한 질문으로 확정.
-3. **priority-lenses 화이트리스트 검증.** `~/.okstra/lib/python/okstra_ctl/improvement_lenses.py` 의 `LENSES` 부분집합인지 확인. out-of-enum 이면 enum 내 가장 가까운 값을 `Recommended:` 로 제시.
-4. **out-of-scope 일관성.** `out-of-scope` 의 각 path 가 `scan-scope` 의 부분집합인지 확인. 무관한 path 면 한 질문으로 제거 또는 scan-scope 에 흡수.
-5. **lens 우선순위 근거 1줄.** 각 priority lens 가 *왜* 이 scope 에서 우선인지 brief 본문에 한 줄 없으면, codebase 1차 훑은 결과를 `Recommended:` 로 제시 후 한 질문.
+1. **scan-scope path existence check.** Confirm each path via `ls` / `Read`. If missing, correct it with a single question (offer the nearest path candidate as `Recommended:`).
+2. **Ambiguous path narrowing.** Narrow abstract paths like `"backend"`, `"payment module"` down to one or more concrete directories. Guess codebase-first, then confirm with a single question.
+3. **priority-lenses whitelist check.** Confirm it is a subset of `LENSES` in `~/.okstra/lib/python/okstra_ctl/improvement_lenses.py`. If out-of-enum, offer the nearest in-enum value as `Recommended:`.
+4. **out-of-scope consistency.** Confirm each path in `out-of-scope` is a subset of `scan-scope`. If a path is unrelated, remove it with a single question or absorb it into scan-scope.
+5. **One line of lens-priority rationale.** If the brief body lacks a line on *why* each priority lens takes precedence in this scope, offer the result of a first codebase pass as `Recommended:` and ask one question.
 
-stop conditions (codebase-scan 한정 추가):
+stop conditions (codebase-scan-specific additions):
 
-- `scan-scope` 의 모든 path 가 codebase 에 존재
-- `priority-lenses` 가 valid enum 부분집합 (1–4개)
+- Every path in `scan-scope` exists in the codebase
+- `priority-lenses` is a valid enum subset (1–4 of them)
 
-위 두 조건이 모두 만족되면 budget 이 남아 있어도 sharpening 종료 가능.
+When both of the above conditions hold, sharpening may end even if budget remains.
 
 ### Augmentation labels (REQUIRED — no unlabelled augmentation)
 
@@ -577,7 +575,7 @@ labels. Unlabelled augmentation is rejected as half-formed translation.
 | `evidence-link` | Cross-reference / file path / symbol resolved from the source against the actual codebase. Pure fact, verified by `Read` / `Grep`. | Trust without verification. |
 | `format-conversion` | Format-only transform (Jira ADF → Markdown, HTML → Markdown, etc.). Semantics unchanged. | Trust without verification. |
 | `terminology-mapping` | Reporter's word mapped to an okstra-canonical term from Step 3b. | Verify against `.okstra/glossary.md`; if mismatch, treat as a clarification candidate. |
-| `intent-inference` | Reporter did NOT literally state this — the skill inferred meaning from context (e.g. classifying "가끔 안 됨" as "intermittent failure on a specific path"). Qualitative only — **never** invent quantitative thresholds (numbers, latencies, percentages, counts). | **Verify with the reporter before acting.** Auto-mirrored into `Open Questions`. |
+| `intent-inference` | Reporter did NOT literally state this — the skill inferred meaning from context (e.g. classifying "sometimes it doesn't work" as "intermittent failure on a specific path"). Qualitative only — **never** invent quantitative thresholds (numbers, latencies, percentages, counts). | **Verify with the reporter before acting.** Auto-mirrored into `Open Questions`. |
 
 **Inline form** — `> augmented: intent-inference — <one line>`.
 **Section form** — `- intent-inference: <one line>` under `Augmentation`.
@@ -585,12 +583,11 @@ labels. Unlabelled augmentation is rejected as half-formed translation.
 ### Auto-mirroring rule
 
 Every `intent-inference` entry must have a paired entry in `Open Questions`
-with the prefix `intent-check:` describing what the reporter must confirm.
-This is what makes the inference auditable end-to-end: the inference is
-visible (Augmentation), and the verification need is visible (Open
-Questions). If a downstream worker resolves the inference without going
-back to the reporter, the `intent-check:` row stays open as a record of
-unverified translation.
+with the prefix `intent-check:` describing what the reporter must confirm —
+the inference stays visible (Augmentation) and its verification need stays
+visible (Open Questions). If a downstream worker resolves the inference
+without going back to the reporter, the `intent-check:` row stays open as a
+record of unverified translation.
 
 `terminology-mapping` and `conversion-block:` follow the same dual-record
 discipline (Augmentation observation ↔ `Open Questions` `terminology:` /
@@ -906,15 +903,13 @@ started.
 - **No template author-guidance in the artifact body.** The Step 5
   template carries author guidance in HTML comments (`<!-- ... -->`);
   **strip every such comment when writing the brief** — the final artifact
-  contains zero `<!-- ... -->` blocks. (The validator now ignores comment
-  regions, but a clean artifact is the contract, and it is what the
-  passing reference briefs look like.) Section headings stay clean — never
-  copy parenthetical reviewer notes onto the heading itself (e.g. emit
-  `## Source Material`, not `## Source Material (verbatim — do not modify)`).
-  Placeholder prose inside angle brackets (`<Background / scope / why
-  now…>`) is NOT a comment — it is intentional scaffolding meant to be
-  replaced with the reporter's actual content; replace those placeholders,
-  do not leave them in.
+  contains zero `<!-- ... -->` blocks (the validator ignores comment
+  regions, but a clean artifact is the contract). Section headings stay
+  clean — never copy parenthetical reviewer notes onto the heading (e.g.
+  emit `## Source Material`, not `## Source Material (verbatim — do not
+  modify)`). Placeholder prose inside angle brackets (`<Background / scope
+  / why now…>`) is NOT a comment — it is scaffolding to replace with the
+  reporter's actual content, not to leave in.
 - If the tracker MCP is not connected, do not guess — ask the user to paste
   the body or skip the source.
 - If a URL fetch fails or hits an auth wall, do not guess — ask for a

package/runtime/skills/okstra-container-build/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: okstra-container-build
 description: |
-  Use to bring up, inspect, or tear down the okstra user-test container runtime for an implementation task — the docker-compose group okstra deploys from a task's worktree so a human can poke at the running build. Trigger words include "okstra container", "okstra container up", "okstra container down", "컨테이너 띄워", "컨테이너 올려", "컨테이너 내려", "컨테이너 상태", "컨테이너 로그", "유저 테스트 환경", "user test environment", "docker compose 띄워줘", "이 task 컨테이너로 띄워", "watcher 멈춰", "stop watcher", "감시 종료".
+  Use to bring up, inspect, or tear down the okstra user-test container runtime for an implementation task — the docker-compose group okstra deploys from a task's worktree so a human can poke at the running build. Trigger words include "okstra container", "okstra container up", "okstra container down", "bring up the container", "spin up the container", "tear down the container", "container status", "container logs", "user-test environment", "user test environment", "docker compose up please", "spin up this task in a container", "stop the watcher", "stop watcher", "stop monitoring".
 ---
 
 # OKSTRA Container Build
@@ -18,35 +18,45 @@ Single entry point for the okstra user-test container runtime. okstra provisions
 
 ## Step 0: Preflight (shared)
 
-Before any sub-command, 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):
+Before any sub-command:
+
+<!-- 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 pass it as `--project-root <projectRoot>` to every `okstra container` call below. `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 pass it as `--project-root <projectRoot>` to every `okstra container` call below. `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 -->
 
 Docker itself must be installed and running for `up`/`status`/`down` to work. If a sub-command fails with a docker connection error, tell the user to start Docker (Desktop / daemon) and retry — do not try to start docker yourself.
 
-Subsequent `okstra container <subcmd>` calls self-bootstrap their Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
+<!-- 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: Dispatch by intent
 
 Classify the user's request into one sub-command using the sub-command table above.
 
-- Clear verbs route directly: "띄워/올려/up" → `up`; "상태/status" → `status`; "로그/logs" → `logs`; "watcher 멈춰/stop-watcher" → `stop-watcher`; "내려/down" → `down`.
-- If the request is ambiguous (e.g. "okstra container 좀 봐줘"), present a numbered picker. Recommend the 1–2 most likely facets first, and make the **last option always "직접 입력"** so the user can name any facet:
+- Clear verbs route directly: "bring up/deploy/up" → `up`; "status" → `status`; "logs" → `logs`; "stop watcher/stop-watcher" → `stop-watcher`; "tear down/down" → `down`.
+- If the request is ambiguous (e.g. "take a look at the okstra container"), present a numbered picker. Recommend the 1–2 most likely facets first, and make the **last option always "Enter directly"** so the user can name any facet:
 
   ```
-  무엇을 할까요?
-  1. status — 실행 중인 컨테이너 / watcher 상태 확인 (추천)
-  2. up — 이 task 의 컨테이너를 띄우기
-  3. 직접 입력 (up / status / logs / stop-watcher / down 중에서)
+  What would you like to do?
+  1. status — check running containers / watcher state (recommended)
+  2. up — bring up this task's containers
+  3. Enter directly (one of up / status / logs / stop-watcher / down)
   ```
 
-  The full facet list is the `Sub-command | What it does` table above — never hide a facet; if the user picks "직접 입력", let them name any row.
+  The full facet list is the `Sub-command | What it does` table above — never hide a facet; if the user picks "Enter directly", let them name any row.
 
-When the user chains multiple facets in one message (e.g. "올렸다가 상태 보여줘"), execute them sequentially — Step 0 runs once, each sub-command section runs once.
+When the user chains multiple facets in one message (e.g. "bring it up, then show me the status"), execute them sequentially — Step 0 runs once, each sub-command section runs once.
 
 Every sub-command needs a **task-key** (`<project-id>:<task-group>:<task-id>`) — the container group is bound to one implementation task's worktree. Resolve it the same way across sub-commands:
 
@@ -61,8 +71,8 @@ Every sub-command needs a **task-key** (`<project-id>:<task-group>:<task-id>`)
 Brings up the task's container group: integrates the implementation stages into the task worktree, synthesizes the compose env override, runs `docker compose up -d`, polls healthchecks, and attaches a tmux watcher pane.
 
 **Preconditions** (state them if unmet, do not guess):
-- The task must be an `implementation` task whose worktree is registered in `~/.okstra/worktrees/registry.json`. If `up` fails with "task worktree 가 registry 에 없" → the task has no implementation worktree yet; tell the user to run the `implementation` phase first.
-- The worktree root must contain a `docker-compose.yml`. If `up` fails with "worktree 루트에 ... 가 없습니다" → no compose file shipped with this task; surface the message verbatim.
+- The task must be an `implementation` task whose worktree is registered in `~/.okstra/worktrees/registry.json`. If `up` fails with "task worktree is not in the registry" → the task has no implementation worktree yet; tell the user to run the `implementation` phase first.
+- The worktree root must contain a `docker-compose.yml`. If `up` fails with "there is no ... at the worktree root" → no compose file shipped with this task; surface the message verbatim.
 - Every stage declared in the approved plan's Stage Map must be `done`. `up` integrates the whole task, so a partially-finished task (e.g. only stage 1 of 3 done) is refused rather than deployed as if complete (gate in `stage_targets.py`, shared with whole-task `final-verification`). If `up` fails with `final-verification(whole-task): stage N not done — run implementation --stage N first`, surface that message verbatim and tell the user to finish the named stage via the `implementation` phase with `--stage N`.
 
 Run:

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

@@ -1,7 +1,7 @@
 ---
 name: okstra-graphify
 description: >-
-  Use when the user wants to build, query, or navigate a knowledge graph over an okstra project's own `.okstra/` memory — its reports, decision records, and glossary. Turns that docs corpus into a persistent graph with community detection and an honest EXTRACTED/INFERRED/AMBIGUOUS audit trail, then answers cross-document questions the flat files can't. Trigger phrases include "okstra graphify", "graph the .okstra docs", "build okstra knowledge graph", "query okstra graph", "what connects to X in the okstra docs", "okstra graph 만들어", "결정 레코드 그래프". NOT for graphing arbitrary code or non-okstra folders (that is the standalone /graphify), and NOT for single-task inspection (okstra-inspect) or rollups (okstra-rollup).
+  Use when the user wants to build, query, or navigate a knowledge graph over an okstra project's own `.okstra/` memory — its reports, decision records, and glossary. Turns that docs corpus into a persistent graph with community detection and an honest EXTRACTED/INFERRED/AMBIGUOUS audit trail, then answers cross-document questions the flat files can't. Trigger phrases include "okstra graphify", "graph the .okstra docs", "build okstra knowledge graph", "query okstra graph", "what connects to X in the okstra docs", "build the okstra graph", "graph the decision records". NOT for graphing arbitrary code or non-okstra folders (that is the standalone /graphify), and NOT for single-task inspection (okstra-inspect) or rollups (okstra-rollup).
 trigger: /okstra-graphify
 ---
 
@@ -22,7 +22,11 @@ Only `.okstra/**/*.md` (final reports, `decisions/*.md`, `glossary.md`, briefs)
 
 ## Step 0: Preflight (shared)
 
-Before any sub-command, 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):
+Before any sub-command:
+
+<!-- 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
@@ -30,13 +34,17 @@ okstra preflight --runtime claude-code --json
 
 Parse the stdout JSON:
 - `ok: true` → carry `projectRoot` as a literal string; it is the `--project-root` value for every sub-command below.
-- `ok: false` → before concluding "no setup", ask whether the user pointed at a specific project directory. If so, re-run `okstra preflight --runtime claude-code --cwd <that-dir> --json`. Only if this **also** returns `ok:false` do you tell the user: "this project has no okstra setup. 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).
+- `ok: false` → before concluding "no setup", ask whether the user pointed at a specific project directory. If so, re-run `okstra preflight --runtime claude-code --cwd <that-dir> --json`. Only if this **also** returns `ok:false` do you tell the user: "this project has no okstra setup. 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 -->
 
 Every `okstra graphify` call below passes `--project-root <projectRoot>` — `--project-root` is REQUIRED and there is no cwd injection; a bare `okstra graphify build` fails with a usage error.
 
 ## Step 1: Dispatch by intent
 
-Classify the request into one sub-command using the table above. If ambiguous ("okstra graph 보여줘"), ask which — enumerate the full sub-command table as a numbered text list and let the user pick. `build` is the prerequisite for `query`/`path`/`explain`/`wiki`/`mcp`; if the user asks to query before a graph exists, the CLI will fail cleanly with `no graph … Run \`okstra graphify build\` first` — run `build` first.
+Classify the request into one sub-command using the table above. If ambiguous ("show me the okstra graph"), ask which — enumerate the full sub-command table as a numbered text list and let the user pick. `build` is the prerequisite for `query`/`path`/`explain`/`wiki`/`mcp`; if the user asks to query before a graph exists, the CLI will fail cleanly with `no graph … Run \`okstra graphify build\` first` — run `build` first.
 
 ---