okstra 0.111.0 → 0.112.0

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

@@ -117,26 +117,15 @@ as source material, and never writes them. Decision files (when raised by
   via `implementation`):
   `<PROJECT_ROOT>/.okstra/decisions/<NNNN>-<slug>.md`.
 
-## Step 0: Resolve project root
+## Step 0: Preflight
 
-Reuse the same literal-token-first rule as `okstra-run`. Each command below is a **separate Bash tool call** starting with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap any of them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, or `&&`, and do **not** introduce a `$OKSTRA_CMD` variable or an `npx -y okstra@latest` fallback — those leading tokens defeat the permission match and force a confirmation prompt on every call.
+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).
 
 ```bash
-okstra ensure-installed --runtime claude-code
+okstra preflight --runtime claude-code --json
 ```
 
-If this exits non-zero, tell the user: "okstra not installed — run `/okstra-setup` first." Then stop. Do **not** try to invoke `npx -y okstra@latest ...` as a fallback.
-
-```bash
-okstra check-project --json
-```
-
-Parse the JSON from stdout:
-
-- `ok: true` → use `projectRoot` from the JSON output. Carry it as a literal string into the steps below.
-- `ok: false` → tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
-
-> If the `okstra` binary is not on `PATH` at all, the commands above will not run. In that case tell the user verbatim: "okstra not installed — run `/okstra-setup` first." Do **not** try to invoke `npx -y okstra@latest ...` from this skill — `npx` is not on the literal-token allow-list this skill targets and will force a confirmation prompt on every subsequent call.
+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.
 
 ## Step 1: Choose input source
 
@@ -234,86 +223,15 @@ Order of operations:
    preserved)`).
 
 6. **Sub-ticket / child-issue / sub-task handling — recursive**:
-   - Look at child references in the fetched ticket response:
-     - Linear: `children` / `subIssues` field
-     - Jira: `subtasks` (or `issuelinks` with the `is parent of` relation)
-     - GitHub: `gh issue view --json title,body,comments,labels,state` only
-       returns the issue body and comments — child relations are NOT in that
-       JSON. Resolve children via two paths:
-       1. **task-list parsing** — scan the fetched body and comments for
-          markdown task-list checkboxes referencing other issues
-          (`- [ ] #NNN`, `- [x] owner/repo#NNN`, `- [ ] https://github.com/...`).
-          Capture each as a child candidate.
-       2. **tracked / sub-issue GraphQL** — for GitHub Projects v2
-          "tracked issues" / sub-issue relations, the REST `gh issue view`
-          response does NOT carry them. Query GraphQL explicitly, e.g.
-          `gh api graphql -f query='query($o:String!,$r:String!,$n:Int!){repository(owner:$o,name:$r){issue(number:$n){trackedIssues(first:50){nodes{number repository{nameWithOwner}}} subIssues:trackedInIssues(first:50){nodes{number repository{nameWithOwner}}}}}}' -f o=<owner> -f r=<repo> -F n=<num>`.
-          If the GraphQL request fails (auth scope missing, feature
-          unavailable on this repo, network error), **do NOT silently
-          continue with full recursion**. Disable the "Generate the full
-          tree recursively" option for this branch, default to
-          `Parent only; list children in Related Artifacts and Related Task
-          Graph`, and surface the GraphQL failure to the user in one line so
-          they can decide whether to paste child bodies manually.
-     - Notion: child pages / sub-pages
-   - If there is **one or more** child, ask **once at the top parent**:
-     - `AskUserQuestion` (single-select)
-       - **Label**: `"This ticket has sub-tickets. How should the child tree be handled?"`
-       - **Options**:
-         1. `Full tree` (recommended) — walk children, grandchildren, …
-            via BFS/DFS and emit one brief per node.
-         2. `Parent only` — single brief. Children are not fetched; their
-            keys/URLs are recorded under Related Artifacts and as `parent-of`
-            rows in Related Task Graph.
-         3. `Selected` — multi-select the direct children; for each chosen
-            child, apply option-1 policy recursively to that branch.
-   - For options 1 / 3, **recurse into Step 1b sub-steps 3–5** for every
-     descendant. No depth limit. Maintain a visited set of
-     `<tracker>:<ticket-id>` to prevent cycles; on revisit, do not emit a
-     new brief — only add a link back to the existing brief.
-   - **Visited-set across re-runs (rebuild from disk)** — the in-memory
-     visited set is per-run and disappears between invocations. When this
-     skill runs again over a tree that already has briefs on disk, it MUST
-     reseed the visited set by scanning
-     `<PROJECT_ROOT>/.okstra/briefs/<task-group>/` recursively
-     and reading each brief's frontmatter `ticket-id` + `source-type`.
-     Reseed precedence:
-     1. On-disk frontmatter (`ticket-id` ≠ "") populates visited entries
-        as `<source-type>:<ticket-id>` — these win.
-     2. Step 2c collision policy (`Skip` / `Append timestamp` /
-        `Overwrite`) applies to any node whose path is already taken.
-     3. The fresh in-memory walk fills any gaps for tickets not yet on
-        disk.
-     A ticket present on disk is NOT refetched unless the user explicitly
-     answers `Overwrite` for that path.
-   - Each descendant's brief file at depth N is created under
-     `<task-group>/<sub/ nested N times>/<ticket-id>-<file-title>.md` per
-     Step 2b.
-   - Each node's `Related Artifacts` should list:
-     - The parent brief's relative path (`../<ticket-id>-<file-title>.md`)
-     - All direct children briefs' relative paths
-       (`sub/<ticket-id>-<file-title>.md`)
-     bidirectionally. (Non-direct ancestors/descendants are tracked via the
-     frontmatter `parent-id` chain.)
-   - Each generated brief's `Related Task Graph` should contain the same full
-     split topology, not only the current node's direct edges, so downstream
-     phases can start from any child brief without losing order or dependency
-     context. Use one row per source-backed edge with these columns:
-     `From | Relation | To | Direction | Source | Impact`.
-     - `From` / `To` use task key, brief id, tracker id, or URL. The edge
-       direction is `From` → `To`.
-     - `Relation` is one of `parent-of`, `child-of`, `depends-on`, `blocks`,
-       `blocked-by`, `follow-up-of`, `split-from`, `duplicates`, `related-to`.
-     - `Direction` is `directed` for parentage/ordering relations and
-       `undirected` for `duplicates` / `related-to`.
-     - `Source` names the evidence for the edge: tracker linked issue,
-       markdown task-list checkbox, reporter statement, manual split, or prior
-       okstra task.
-     - `Impact` states what the next phase must preserve, such as "run after
-       API contract" or "avoid duplicate implementation".
-     Do not invent graph edges from filename similarity or topic overlap; if a
-     relation is unclear, use `related-to` + `undirected` only when the source
-     explicitly says the items are related.
+   - If the fetched ticket response shows **any** child reference (Linear
+     `children`/`subIssues`, Jira `subtasks`/`issuelinks`, GitHub task-list
+     checkboxes or tracked/sub-issues, Notion child pages), **read
+     `references/tracker-recursion.md` next to this SKILL.md and follow it**
+     before writing any brief — it defines per-tracker child discovery
+     (including the GitHub GraphQL query and its failure handling), the
+     Full tree / Parent only / Selected picker, the cross-run visited-set
+     reseed from on-disk brief frontmatter, and the Related Artifacts /
+     Related Task Graph topology every emitted brief must carry.
    - If there are no children, proceed with a single brief (depth 0).
 
 ### 1c. `Link URL`
@@ -584,13 +502,11 @@ project's domain.
 
 ## Step 4: Fill in missing fields (NO full interview)
 
-> **Verbatim-source rule**: Source Material collected in Step 1 must never
-> be paraphrased, summarized, or restructured. When supplementing missing
-> information, write only into the dedicated `Augmentation` section (see
-> Step 5); never modify Source Material by a single byte. **Anything
-> learned by grilling in this step lands in `Augmentation` or `Open
-> Questions` only.** brief is a pre-discovery artifact, not a PRD —
-> decisions belong to later phases.
+> **Verbatim-source rule** (the first non-negotiable at the top of this
+> file): never modify Source Material by a single byte. **Anything learned
+> by grilling in this step lands in `Augmentation` or `Open Questions`
+> only.** brief is a pre-discovery artifact, not a PRD — decisions belong
+> to later phases.
 
 Inspect the synthesized brief draft. For each REQUIRED section below that is
 empty or trivially thin **after** reading Source Material verbatim, ask **at
@@ -903,72 +819,16 @@ If the list is non-empty, run **one** `AskUserQuestion`:
      `implementation-planning`); see each phase profile's "Brief
      consumption" addendum.
 
-### 6.5c. Batch the questions
-
-For each pending row, formulate one question. Because the
-`AskUserQuestion` tool caps options at 4 per call and questions per call
-also at 4, split into batches of ≤ 4 questions.
-
-**Cap — 12 questions per Step 6.5 run.** When the pending list
-exceeds 12 rows, sort by priority and ask only the top 12 this round:
-
-1. `conversion-block:` rows first (translation failure — highest
-   downstream risk).
-2. `intent-check:` rows next, in the order they appear in `Open
-   Questions`.
-
-Any rows beyond the cap are left unanswered in this run; set
-`reporter-confirmations: partial` in the frontmatter and tell the user
-which rows remain. The next `okstra-brief` re-run (or the downstream
-phase that consumes `Blocks=next-phase`) handles the remainder.
-
-Each question carries:
-
-- The reporter-facing phrasing (plain language, no jargon).
-- A recommended answer drawn from the brief's `intent-inference` /
-  `conversion-block:` content, marked `(Recommended)`.
-- 2–3 alternative options when the answer space is naturally enumerable;
-  otherwise a free-text fallback.
-
-### 6.5d. Record verbatim
-
-Create a new top-level section `## Reporter Confirmations` in the brief
-(if not present) with one subsection per answered row:
-
-```markdown
-## Reporter Confirmations
-
-### RC-1 — <intent-check: or conversion-block: row id / topic>
-- asked: <YYYY-MM-DD HH:MM>
-- linked-row: `<exact Open Questions row text>`
-- answer (verbatim):
-
-  > <reporter's answer, byte-for-byte>
-```
-
-Mark the linked `Open Questions` row by appending `[CONFIRMED <YYYY-MM-DD> → RC-N]` to the end of the row's line. Do NOT delete the row — the
-`CONFIRMED` marker keeps the audit trail intact.
-
-For every `intent-inference` augmentation whose paired `intent-check:`
-was confirmed, add one new line directly below the `> augmented:
-intent-inference …` blockquote:
-
-```
-> confirmed-by-reporter: RC-N — <one-line summary of confirmation>
-```
-
-This converts the inference from "unverified hypothesis" to "verified
-hypothesis" without rewriting the original augmentation.
-
-### 6.5e. Frontmatter state
-
-Update `reporter-confirmations` in the brief frontmatter:
+### 6.5c–e. Collect, record, and set frontmatter state
 
-- `complete` — every pending row was answered.
-- `partial` — some rows answered, some skipped within this run.
-- `skipped` — user picked option 2 in 6.5b.
-- `pending` — should never appear at this point; if it does, treat the
-  brief as not yet handed off and refuse to proceed.
+When 6.5b answered "Yes — collect now", **read
+`references/reporter-confirmations.md` next to this SKILL.md and follow it**:
+it defines the ≤ 4-question batching, the 12-question cap with
+`conversion-block:`-first priority, the `## Reporter Confirmations` RC-N
+record shape with `[CONFIRMED <date> → RC-N]` row markers and
+`> confirmed-by-reporter:` blockquote lines, and the final
+`reporter-confirmations` frontmatter value (`complete` / `partial` /
+`skipped`).
 
 Step 6.5 ends here. The brief now has either zero pending reporter-only
 rows (`complete` / `partial` with remainder in the same file) or an
@@ -1038,11 +898,11 @@ started.
   stays under `<PROJECT_ROOT>/.okstra/` — briefs in `.okstra/briefs/`, glossary
   in `.okstra/glossary.md` (Step 4.5). Paths outside that subtree are read-only
   source material, and only when the reporter cited them.
-- **Verbatim source**: never paraphrase, summarize, restructure, or reorder
-  the Source Material section. Only format conversion (ADF → MD, HTML → MD)
-  is allowed, and the conversion must be annotated in the `format:` meta.
-  Augmentation / interpretation goes only into the `Augmentation` section
-  or a `> augmented:` blockquote inside the required section.
+- **Verbatim source** (the two non-negotiables at the top of this file
+  govern): no line budget overrides them — if source content is large,
+  preserve it exactly as separate `Source Material` entries; if a tool
+  returns a truncated body, ask the user for the missing content or emit a
+  `conversion-block:` row. Never silently excerpt or summarize.
 - **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
@@ -1061,10 +921,6 @@ started.
   paste.
 - Never fabricate content for empty sections; use `_(none)_`.
 - Echo each `AskUserQuestion` outcome on one short line.
-- No line budget overrides the verbatim-source rule. If source content is
-  large, preserve it exactly as separate `Source Material` entries; if a
-  tool only returns a truncated body, ask the user for the missing content
-  or emit a `conversion-block:` row. Never silently excerpt or summarize.
 
 ## Failure Modes
 

package/runtime/skills/okstra-brief/references/reporter-confirmations.md

@@ -0,0 +1,71 @@
+# Reporter batch confirmation — collection procedure (Step 6.5c–e)
+
+Read this only when Step 6.5b answered "Yes — collect now" for a non-empty
+pending list of `intent-check:` / `conversion-block:` rows.
+
+## 6.5c. Batch the questions
+
+For each pending row, formulate one question. Because the `AskUserQuestion`
+tool caps options at 4 per call and questions per call also at 4, split into
+batches of ≤ 4 questions.
+
+**Cap — 12 questions per Step 6.5 run.** When the pending list exceeds 12
+rows, sort by priority and ask only the top 12 this round:
+
+1. `conversion-block:` rows first (translation failure — highest downstream
+   risk).
+2. `intent-check:` rows next, in the order they appear in `Open Questions`.
+
+Any rows beyond the cap are left unanswered in this run; set
+`reporter-confirmations: partial` in the frontmatter and tell the user which
+rows remain. The next `okstra-brief` re-run (or the downstream phase that
+consumes `Blocks=next-phase`) handles the remainder.
+
+Each question carries:
+
+- The reporter-facing phrasing (plain language, no jargon).
+- A recommended answer drawn from the brief's `intent-inference` /
+  `conversion-block:` content, marked `(Recommended)`.
+- 2–3 alternative options when the answer space is naturally enumerable;
+  otherwise a free-text fallback.
+
+## 6.5d. Record verbatim
+
+Create a new top-level section `## Reporter Confirmations` in the brief (if
+not present) with one subsection per answered row:
+
+```markdown
+## Reporter Confirmations
+
+### RC-1 — <intent-check: or conversion-block: row id / topic>
+- asked: <YYYY-MM-DD HH:MM>
+- linked-row: `<exact Open Questions row text>`
+- answer (verbatim):
+
+  > <reporter's answer, byte-for-byte>
+```
+
+Mark the linked `Open Questions` row by appending
+`[CONFIRMED <YYYY-MM-DD> → RC-N]` to the end of the row's line. Do NOT delete
+the row — the `CONFIRMED` marker keeps the audit trail intact.
+
+For every `intent-inference` augmentation whose paired `intent-check:` was
+confirmed, add one new line directly below the `> augmented: intent-inference …`
+blockquote:
+
+```
+> confirmed-by-reporter: RC-N — <one-line summary of confirmation>
+```
+
+This converts the inference from "unverified hypothesis" to "verified
+hypothesis" without rewriting the original augmentation.
+
+## 6.5e. Frontmatter state
+
+Update `reporter-confirmations` in the brief frontmatter:
+
+- `complete` — every pending row was answered.
+- `partial` — some rows answered, some skipped within this run.
+- `skipped` — user picked option 2 in 6.5b.
+- `pending` — should never appear at this point; if it does, treat the brief
+  as not yet handed off and refuse to proceed.

package/runtime/skills/okstra-brief/references/tracker-recursion.md

@@ -0,0 +1,90 @@
+# Sub-ticket / child-issue recursion (tracker sources)
+
+Read this only when a fetched tracker ticket shows one or more child references
+(okstra-brief Step 1b sub-step 6). It defines how the child tree is discovered,
+which briefs are emitted, and how re-runs stay idempotent.
+
+## 1. Discover child references per tracker
+
+- Linear: `children` / `subIssues` field.
+- Jira: `subtasks` (or `issuelinks` with the `is parent of` relation).
+- GitHub: `gh issue view --json title,body,comments,labels,state` only returns
+  the issue body and comments — child relations are NOT in that JSON. Resolve
+  children via two paths:
+  1. **task-list parsing** — scan the fetched body and comments for markdown
+     task-list checkboxes referencing other issues (`- [ ] #NNN`,
+     `- [x] owner/repo#NNN`, `- [ ] https://github.com/...`). Capture each as a
+     child candidate.
+  2. **tracked / sub-issue GraphQL** — for GitHub Projects v2 "tracked issues" /
+     sub-issue relations, query GraphQL explicitly, e.g.
+     `gh api graphql -f query='query($o:String!,$r:String!,$n:Int!){repository(owner:$o,name:$r){issue(number:$n){trackedIssues(first:50){nodes{number repository{nameWithOwner}}} subIssues:trackedInIssues(first:50){nodes{number repository{nameWithOwner}}}}}}' -f o=<owner> -f r=<repo> -F n=<num>`.
+     If the GraphQL request fails (auth scope missing, feature unavailable,
+     network error), do NOT silently continue with full recursion: disable the
+     "Full tree" option for this branch, default to `Parent only`, and surface
+     the GraphQL failure to the user in one line so they can decide whether to
+     paste child bodies manually.
+- Notion: child pages / sub-pages.
+
+## 2. Ask once at the top parent
+
+If there is one or more child, `AskUserQuestion` (single-select):
+
+- **Label**: `"This ticket has sub-tickets. How should the child tree be handled?"`
+- **Options**:
+  1. `Full tree` (recommended) — walk children, grandchildren, … via BFS/DFS
+     and emit one brief per node.
+  2. `Parent only` — single brief. Children are not fetched; their keys/URLs are
+     recorded under Related Artifacts and as `parent-of` rows in Related Task
+     Graph.
+  3. `Selected` — multi-select the direct children; for each chosen child,
+     apply option-1 policy recursively to that branch.
+
+For options 1 / 3, recurse into Step 1b sub-steps 3–5 for every descendant. No
+depth limit. Maintain a visited set of `<tracker>:<ticket-id>` to prevent
+cycles; on revisit, do not emit a new brief — only add a link back to the
+existing brief.
+
+## 3. Visited-set across re-runs (rebuild from disk)
+
+The in-memory visited set is per-run. When this skill runs again over a tree
+that already has briefs on disk, reseed the visited set by scanning
+`<PROJECT_ROOT>/.okstra/briefs/<task-group>/` recursively and reading each
+brief's frontmatter `ticket-id` + `source-type`. Reseed precedence:
+
+1. On-disk frontmatter (`ticket-id` ≠ "") populates visited entries as
+   `<source-type>:<ticket-id>` — these win.
+2. Step 2c collision policy (`Skip` / `Append timestamp` / `Overwrite`) applies
+   to any node whose path is already taken.
+3. The fresh in-memory walk fills any gaps for tickets not yet on disk.
+
+A ticket present on disk is NOT refetched unless the user explicitly answers
+`Overwrite` for that path.
+
+## 4. Per-node output
+
+- Each descendant's brief file at depth N is created under
+  `<task-group>/<sub/ nested N times>/<ticket-id>-<file-title>.md` per Step 2b.
+- Each node's `Related Artifacts` lists, bidirectionally:
+  - the parent brief's relative path (`../<ticket-id>-<file-title>.md`)
+  - all direct children briefs' relative paths
+    (`sub/<ticket-id>-<file-title>.md`)
+  (Non-direct ancestors/descendants are tracked via the frontmatter
+  `parent-id` chain.)
+- Each generated brief's `Related Task Graph` contains the same **full split
+  topology**, not only the current node's direct edges, so downstream phases
+  can start from any child brief without losing order or dependency context.
+  One row per source-backed edge with columns
+  `From | Relation | To | Direction | Source | Impact`:
+  - `From` / `To` use task key, brief id, tracker id, or URL; edge direction is
+    `From` → `To`.
+  - `Relation` is one of `parent-of`, `child-of`, `depends-on`, `blocks`,
+    `blocked-by`, `follow-up-of`, `split-from`, `duplicates`, `related-to`.
+  - `Direction` is `directed` for parentage/ordering relations, `undirected`
+    for `duplicates` / `related-to`.
+  - `Source` names the evidence for the edge: tracker linked issue, markdown
+    task-list checkbox, reporter statement, manual split, or prior okstra task.
+  - `Impact` states what the next phase must preserve (e.g. "run after API
+    contract", "avoid duplicate implementation").
+  Do not invent graph edges from filename similarity or topic overlap; if a
+  relation is unclear, use `related-to` + `undirected` only when the source
+  explicitly says the items are related.

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

@@ -16,18 +16,15 @@ Single entry point for the okstra user-test container runtime. okstra provisions
 | `stop-watcher` | Reap the watcher/tail panes only — the containers keep running. |
 | `down` | Tear down the containers (label query) and reap orphan watcher panes; `--all` covers every container group in the project. |
 
-## Step 0: Verify okstra runtime + project setup (shared)
+## Step 0: Preflight (shared)
 
-Before any sub-command, run each of the following commands as a **separate Bash tool call**. Each command starts with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap any of them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, or `&&`, and do **not** introduce a `$OKSTRA_CMD` variable or an `npx -y okstra@latest` fallback — those leading tokens defeat the permission match and force a confirmation prompt on every call. The LLM (you) inspects each command's output and decides what to do next in natural language — never in shell.
+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):
 
-1. `okstra ensure-installed --runtime claude-code`
-   If this exits non-zero, tell the user: "okstra not installed — run `/okstra-setup` first." Then stop. Do **not** try to invoke `npx -y okstra@latest ...` as a fallback.
-
-2. `okstra check-project --json`
-   Reads the project from the current working directory. Parse the JSON from stdout. The shape is `{ok, projectRoot, projectJsonPath, projectId}`.
+```bash
+okstra preflight --runtime claude-code --json
+```
 
-   - `ok: false` → tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
-   - `ok: true` → carry `projectRoot` as a literal string and pass it as `--project-root <projectRoot>` to every `okstra container` call below.
+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).
 
 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.
 
@@ -35,7 +32,7 @@ Subsequent `okstra container <subcmd>` calls self-bootstrap their Python path, s
 
 ## Step 1: Dispatch by intent
 
-Classify the user's request into one sub-command using the trigger table above.
+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:
@@ -61,8 +58,6 @@ Every sub-command needs a **task-key** (`<project-id>:<task-group>:<task-id>`)
 
 ## up
 
-Trigger phrases: "okstra container up", "컨테이너 띄워", "컨테이너 올려", "유저 테스트 환경 띄워", "docker compose 올려줘", "이 task 컨테이너로 띄워".
-
 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):
@@ -84,8 +79,6 @@ After a successful `up`, tell the user how to reach the running build (the compo
 
 ## status
 
-Trigger phrases: "okstra container status", "컨테이너 상태", "컨테이너 떠 있어?", "container status".
-
 Reports the running containers (queried by run-trace label — the source of truth for "is it up") plus the watcher metadata recorded in the registry.
 
 ```bash
@@ -106,8 +99,6 @@ If `containers` is empty, say the group is not running and offer `up`. Treat the
 
 ## logs
 
-Trigger phrases: "okstra container logs", "컨테이너 로그", "container logs", "로그 어디서 봐".
-
 The live log stream lives in the tmux watcher pane, not in a file. This sub-command points at the watcher findings directory and the per-service watcher state.
 
 ```bash
@@ -126,8 +117,6 @@ Parse the stdout JSON (`{watchersDir, watchers}`). Report the `watchersDir` host
 
 ## stop-watcher
 
-Trigger phrases: "okstra container stop-watcher", "watcher 멈춰", "감시 종료", "stop watcher", "watcher 만 꺼줘".
-
 Reaps the watcher/tail tmux panes for the task **without stopping the containers**. Use when the user wants to silence the monitor but keep the build running.
 
 ```bash
@@ -140,8 +129,6 @@ Parse the stdout JSON (`{reapedPanes, note}`). Confirm which panes were reaped a
 
 ## down
 
-Trigger phrases: "okstra container down", "컨테이너 내려", "컨테이너 종료", "container down", "전부 내려줘".
-
 Tears down the container group (removes containers found by the run-trace label) and reaps orphan watcher panes.
 
 Single task:

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

@@ -20,17 +20,17 @@ Only `.okstra/**/*.md` (final reports, `decisions/*.md`, `glossary.md`, briefs)
 | `wiki` | Agent-crawlable wiki (`index.md` + one article per community). |
 | `mcp` | Start a stdio MCP server exposing the graph to other agents (opt-in — additionally needs `pip install mcp`). |
 
-## Step 0: Verify okstra runtime + project setup (shared)
+## Step 0: Preflight (shared)
 
-Before any sub-command, run each command below as a **separate Bash tool call**. Each starts with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, `&&`, and do **not** introduce an `$OKSTRA_CMD` variable or an `npx -y okstra@latest` fallback — leading tokens defeat the permission match. You (the LLM) inspect each command's output and decide the next step in natural language, never in shell.
+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):
 
-1. `okstra ensure-installed --runtime claude-code`
-   If this exits non-zero, tell the user: "okstra not installed — run `/okstra-setup` first." Then stop. Do **not** try `npx -y okstra@latest ...` as a fallback.
+```bash
+okstra preflight --runtime claude-code --json
+```
 
-2. `okstra check-project --json`
-   Resolves PROJECT_ROOT from the Bash call's cwd, looks for `.okstra/project.json`, and prints `{ok, projectRoot, projectJsonPath, projectId}` (plus a `stage` on failure). Parse the JSON from stdout.
-   - `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 check-project --cwd <that-dir> --json` (the leading `okstra` token keeps the permission match). Only if this **also** returns `ok:false` do you tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
+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).
 
 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.