okstra 0.180.0 → 0.183.2

package/runtime/python/okstra_token_usage/grok.py

@@ -0,0 +1,127 @@
+"""Grok Build session collectors.
+
+공식 세션 문서는 대화를 ``~/.grok/sessions/`` 에 둔다. cwd 는 퍼센트 인코딩된
+디렉터리 이름이다. 누적 사용량은 ``updates.jsonl`` 의
+``params.update.usage.modelUsage`` 마지막 스냅샷이다.
+"""
+from __future__ import annotations
+
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Mapping
+from urllib.parse import quote, unquote
+
+from .jsonl_io import iter_jsonl
+from .paths import ts_in_window
+
+
+def grok_sessions_root(
+    home: Path | None = None,
+    env: Mapping[str, str] | None = None,
+) -> Path:
+    environ = env if env is not None else os.environ
+    configured = str(environ.get("GROK_HOME") or "").strip()
+    base = Path(configured).expanduser() if configured else (home or Path.home()) / ".grok"
+    return base / "sessions"
+
+
+def _iso_from_unix(value: object) -> str | None:
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        return None
+    return datetime.fromtimestamp(value, timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _usage_payload(record: dict) -> dict | None:
+    params = record.get("params")
+    if not isinstance(params, dict):
+        return None
+    update = params.get("update")
+    if not isinstance(update, dict):
+        return None
+    usage = update.get("usage")
+    return usage if isinstance(usage, dict) else None
+
+
+def _model_snapshot(usage: dict) -> tuple[dict, str | None]:
+    models = usage.get("modelUsage")
+    if isinstance(models, dict) and len(models) == 1:
+        name, payload = next(iter(models.items()))
+        if isinstance(payload, dict):
+            return payload, name if isinstance(name, str) else None
+    return usage, None
+
+
+def grok_session_total(updates_path: Path) -> dict:
+    """마지막 modelUsage 스냅샷. 세션 누적이라 더하지 않는다."""
+    last: dict | None = None
+    model: str | None = None
+    started: str | None = None
+    ended: str | None = None
+    for record in iter_jsonl(updates_path):
+        usage = _usage_payload(record)
+        if usage is None:
+            continue
+        iso = _iso_from_unix(record.get("timestamp"))
+        if iso and started is None:
+            started = iso
+        if iso:
+            ended = iso
+        snapshot, snapshot_model = _model_snapshot(usage)
+        last = snapshot
+        if snapshot_model:
+            model = snapshot_model
+    if last is None:
+        return {"totalTokens": 0, "available": False}
+    return {
+        "totalTokens": last.get("totalTokens", 0) or 0,
+        "inputTokens": last.get("inputTokens", 0) or 0,
+        "outputTokens": last.get("outputTokens", 0) or 0,
+        "cachedInputTokens": last.get("cachedReadTokens", 0) or 0,
+        "reasoningOutputTokens": last.get("reasoningTokens", 0) or 0,
+        "durationMs": last.get("apiDurationMs", 0) or 0,
+        "model": model,
+        "startedAt": started,
+        "endedAt": ended,
+        "available": True,
+    }
+
+
+def _session_in_window(updates_path: Path, started_at: str, ended_at: str) -> bool:
+    for record in iter_jsonl(updates_path):
+        iso = _iso_from_unix(record.get("timestamp"))
+        if iso and ts_in_window(iso, started_at, ended_at):
+            return True
+    return False
+
+
+def find_grok_sessions(
+    cwd: Path,
+    started_at: str,
+    ended_at: str,
+    *,
+    session_root: Path | None = None,
+) -> list[Path]:
+    """cwd 로 인코딩된 세션 중 창 안에 갱신이 있는 updates.jsonl."""
+    if not started_at or not ended_at:
+        return []
+    root = session_root or grok_sessions_root()
+    if not root.is_dir():
+        return []
+    target = str(cwd)
+    matches: list[Path] = []
+    for child in root.iterdir():
+        if not child.is_dir():
+            continue
+        decoded = unquote(child.name)
+        if decoded != target:
+            continue
+        for session in child.iterdir():
+            updates = session / "updates.jsonl"
+            if updates.is_file() and _session_in_window(updates, started_at, ended_at):
+                matches.append(updates)
+    return sorted(matches)
+
+
+def grok_session_dir_name(cwd: Path) -> str:
+    return quote(str(cwd), safe="")

package/runtime/schemas/final-report-v2.0.schema.json

@@ -8943,6 +8943,7 @@
       ],
       "additionalProperties": false,
       "properties": {
+        "stageRefs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "integer", "minimum": 1}},
         "id": {
           "type": "string",
           "pattern": "^VC-\\d{3,}$"
@@ -9142,6 +9143,8 @@
       ],
       "additionalProperties": false,
       "properties": {
+        "setAside": {"type": "array", "items": {"type": "object", "required": ["id", "reason"], "additionalProperties": false, "properties": {"id": {"type": "string", "minLength": 1}, "reason": {"type": "string", "enum": ["record", "observed", "deferred"]}}}},
+        "stageLedger": {"type": "object", "additionalProperties": {"type": "string", "enum": ["done", "active", "ready", "blocked"]}},
         "uniformVerifiers": {
           "type": "array",
           "description": "Verifiers whose every vote this round was one verdict. Advisory: a unanimous round is legitimate, but the gate reads as a three-way cross-check unless this sits beside it.",
@@ -9242,6 +9245,8 @@
             ],
             "additionalProperties": false,
             "properties": {
+              "block": {"type": "string", "enum": ["execution", "record"]},
+              "stageScope": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "integer", "minimum": 1}},
               "id": {
                 "type": "string",
                 "minLength": 1
@@ -9280,6 +9285,9 @@
                   ],
                   "additionalProperties": false,
                   "properties": {
+                    "claimKind": {"description": "Set only on DISAGREE. `fact` claims are settled by reproduction, `judgement` by quorum.", "enum": ["fact", "judgement", null]},
+                    "reproduction": {"description": "Set only on a `fact` claim. The probe okstra runs; see okstra_ctl/claim_reproduction.py.", "type": ["object", "null"]},
+                    "reproductionResult": {"description": "Written by okstra, not by the worker.", "enum": ["reproduced", "not-reproduced", "not-runnable", null]},
                     "worker": {
                       "type": "string",
                       "minLength": 1
@@ -9752,6 +9760,7 @@
       ],
       "additionalProperties": false,
       "properties": {
+        "stageRefs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "integer", "minimum": 1}},
         "id": {
           "type": "string",
           "pattern": "^R-\\d{3,}$"

package/runtime/schemas/final-report-v3.0.schema.json

@@ -8938,6 +8938,7 @@
       ],
       "additionalProperties": false,
       "properties": {
+        "stageRefs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "integer", "minimum": 1}},
         "id": {
           "type": "string",
           "pattern": "^VC-\\d{3,}$"
@@ -9137,6 +9138,8 @@
       ],
       "additionalProperties": false,
       "properties": {
+        "setAside": {"type": "array", "items": {"type": "object", "required": ["id", "reason"], "additionalProperties": false, "properties": {"id": {"type": "string", "minLength": 1}, "reason": {"type": "string", "enum": ["record", "observed", "deferred"]}}}},
+        "stageLedger": {"type": "object", "additionalProperties": {"type": "string", "enum": ["done", "active", "ready", "blocked"]}},
         "uniformVerifiers": {
           "type": "array",
           "description": "Verifiers whose every vote this round was one verdict. Advisory: a unanimous round is legitimate, but the gate reads as a three-way cross-check unless this sits beside it.",
@@ -9237,6 +9240,8 @@
             ],
             "additionalProperties": false,
             "properties": {
+              "block": {"type": "string", "enum": ["execution", "record"]},
+              "stageScope": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "integer", "minimum": 1}},
               "id": {
                 "type": "string",
                 "minLength": 1
@@ -9272,6 +9277,9 @@
                   ],
                   "additionalProperties": false,
                   "properties": {
+                    "claimKind": {"description": "Set only on DISAGREE. `fact` claims are settled by reproduction, `judgement` by quorum.", "enum": ["fact", "judgement", null]},
+                    "reproduction": {"description": "Set only on a `fact` claim. The probe okstra runs; see okstra_ctl/claim_reproduction.py.", "type": ["object", "null"]},
+                    "reproductionResult": {"description": "Written by okstra, not by the worker.", "enum": ["reproduced", "not-reproduced", "not-runnable", null]},
                     "worker": {
                       "type": "string",
                       "minLength": 1
@@ -9744,6 +9752,7 @@
       ],
       "additionalProperties": false,
       "properties": {
+        "stageRefs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "integer", "minimum": 1}},
         "id": {
           "type": "string",
           "pattern": "^R-\\d{3,}$"

package/runtime/schemas/report-synthesis-packet-v1.0.schema.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://okstra.dev/schemas/report-synthesis-packet-v1.0.schema.json",
+  "title": "Okstra report synthesis packet",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "taskKey",
+    "taskType",
+    "authoringContract",
+    "accountingSnapshot",
+    "sources"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "const": "1.0"
+    },
+    "taskKey": {
+      "type": "string",
+      "minLength": 1
+    },
+    "taskType": {
+      "type": "string",
+      "minLength": 1
+    },
+    "authoringContract": {
+      "type": "object",
+      "required": [
+        "resultPath",
+        "format",
+        "sourcePolicy",
+        "instructions",
+        "runtimeOwnedContent",
+        "validationRules"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "resultPath": {
+          "type": "string",
+          "minLength": 1
+        },
+        "format": {
+          "const": "report-narrative-v3.0"
+        },
+        "sourcePolicy": {
+          "const": "read-only-synthesis-packet"
+        },
+        "instructions": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "runtimeOwnedContent": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "validationRules": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "accountingSnapshot": {
+      "type": "object",
+      "required": [
+        "leadSessionIds",
+        "leadUsage",
+        "workerUsage",
+        "usageSummary"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "leadSessionIds": {
+          "type": "array",
+          "items": {"type": "string"}
+        },
+        "leadUsage": {"type": "object"},
+        "workerUsage": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["workerId", "role", "usage"],
+            "additionalProperties": false,
+            "properties": {
+              "workerId": {"type": "string", "minLength": 1},
+              "role": {"type": "string"},
+              "usage": {"type": "object"}
+            }
+          }
+        },
+        "usageSummary": {"type": "object"}
+      }
+    },
+    "sources": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["label", "owner", "path", "digest", "content"],
+        "additionalProperties": false,
+        "properties": {
+          "label": {
+            "type": "string",
+            "minLength": 1
+          },
+          "owner": {
+            "type": "string",
+            "minLength": 1
+          },
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
+          "digest": {
+            "type": "string",
+            "pattern": "^sha256:[0-9a-f]{64}$"
+          },
+          "content": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -120,10 +120,10 @@ Run one Bash tool call, starting with the literal token `okstra` (never wrapped
 <!-- END FRAGMENT: bash-invocation-rule -->
 
 ```bash
-okstra preflight --runtime claude-code --json
+okstra preflight --runtime claude-code
 ```
 
-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.
+On `Okstra preflight: ready`, carry the fixed `Project root` line as a literal string into the steps below. On `Okstra preflight: failed` (or `okstra` not on `PATH` at all), show the fixed `Reason` and `Recovery` lines, 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).
@@ -328,16 +328,18 @@ command is its own Bash call starting with the literal token `okstra`, per
 Step 0):
 
 ```bash
-okstra task-list
+okstra task-list --text
 ```
 
-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.
+Read each fixed `Task group` and `Updated at` line. `Task group` 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 distinct slugs
 by most-recent `updatedAt` and take the **2 most-recent** as recommendations,
 shown in slug form.
 
+If `Status` is `error`, report `Failure stage` and `Failure reason`, then stop.
+
 `AskUserQuestion` (single-select):
 
 - **Label**: `"Task group?"`
@@ -349,7 +351,7 @@ shown in slug form.
 When the user picks an existing group, use its value verbatim. When they
 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
+If `okstra task-list --text` returns `Task count: 0` (no prior tasks), skip the
 picker and ask one free-text question:
 `"Task group (e.g. backend-api, INV-1234, refactor)"` → `task_group`.
 

package/runtime/skills/okstra-code-review/SKILL.md

@@ -38,12 +38,12 @@ Run one Bash tool call, starting with the literal token `okstra` (never wrapped
 <!-- END FRAGMENT: bash-invocation-rule -->
 
 ```bash
-okstra preflight --runtime claude-code --json
+okstra preflight --runtime claude-code
 ```
 
-Branch on the stdout JSON:
-- `ok: true` → carry `projectRoot` as a literal string; every later step is anchored on it.
-- `ok: false` → the check only sees the cwd of the Bash call, so a project that is not the cwd reads as missing setup. Ask whether the user pointed at a specific project directory; if they did, 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 this **also** returns `ok:false` do you tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
+Branch on the fixed first line:
+- `Okstra preflight: ready` → carry `Project root` as a literal string; every later step is anchored on it.
+- `Okstra preflight: failed` → the check only sees the cwd of the Bash call, so a project that is not the cwd can read as missing setup. Ask whether the user pointed at a specific project directory; if they did, re-run targeting it: `okstra preflight --runtime claude-code --cwd <that-dir>` (`--cwd` is the sanctioned way to target a project — a leading `cd` would break the permission match). Only if this also fails do you show `Reason` and `Recovery`, 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).
@@ -63,8 +63,8 @@ Pick the mode from what the user actually gave you:
 
 **Stage mode.**
 
-1. `okstra resolve-task-key <token> --project-root <projectRoot> --json` → branch on `matches[]`: **0** → report the task cannot be found and stop; **1** → take that entry's `taskKey`; **N** → list the candidates (with `updatedAt`) and ask via a 3-option picker (1–2 recommendations + `Enter directly`).
-2. `okstra stage-map <taskKey> --project <projectRoot> --json` → `stages[]` (`stage_number`, `title`, `depends_on`) and `doneStages[]`.
+1. A full `project-id:task-group:task-id` token is already the task key. For a bare token, run `okstra model-io task-selection-input --project-root <projectRoot> --task-ref <token>` and branch on the fixed `Match count`, `Task`, and `Updated at` rows: **0** → report the task cannot be found and stop; **1** → take `Task`; **N** → list the candidates and ask via a 3-option picker (1–2 recommendations + `Enter directly`).
+2. `okstra stage-map <taskKey> --project <projectRoot> --text` → use the fixed `Stages` and `Done stages` count/name/value rows.
 3. Choose the stage with a 3-option picker — recommend the highest done stage (the work that just finished) first, a second plausible stage if there is one, and `Enter directly` last. Pick silently only when exactly one stage exists.
 
 **Branch mode.**
@@ -75,13 +75,23 @@ Pick the mode from what the user actually gave you:
 **Then call the target CLI.** One call resolves everything the rest of this skill needs; the only reason to call it again is a base the user overrides in the confirmation step below.
 
 ```bash
-okstra code-review target --task-key <taskKey> --stage <N> --project-root <projectRoot> --json
-okstra code-review target --branch <name> [--base <ref>] --project-root <projectRoot> --json
+okstra code-review target --task-key <taskKey> --stage <N> --project-root <projectRoot> --text
+okstra code-review target --branch <name> [--base <ref>] --project-root <projectRoot> --text
 ```
 
-`ok: true` carries `projectRoot`, `mode`, `worktreePath`, `branch`, `baseCommit`, `headCommit`, `reviewPath`, `round`; stage mode adds `taskKey`, `taskRoot`, `stage`. Carry every field verbatim into the later steps — none of them is recomputed anywhere below.
+`Status: ready` carries `Project root`, `Mode`, `Worktree path`, `Branch`, `Base commit`, `Head commit`, `Review path`, and `Round`; stage mode adds `Task key`, `Task root`, and `Stage`. Carry every field verbatim into the later steps — none of them is recomputed anywhere below.
 
-`ok: false` carries `stage` (a failure code) and `reason`. Report both and stop, unless the Exceptions table names that case.
+`Status: error` carries `Failure stage` and `Failure reason`. Report both and stop, unless the Exceptions table names that case.
+
+After the range is resolved, render the only project identity and range values
+that later model prompts may consume:
+
+```bash
+okstra model-io code-review-input --project-root <projectRoot> --base <baseCommit> --head <headCommit>
+```
+
+Carry this fixed Markdown view into the census and reviewer prompts. Do not
+pass task manifests, target-CLI JSON, or arbitrary JSON fields to a reviewer.
 
 **You never derive the base.** Pass `--base <ref>` only when the user named one; otherwise the CLI resolves it. `baseCommit` is a **ref, not necessarily a commit id** — a caller-supplied `--base` passes through verbatim — so use it as given in `git diff <baseCommit>..<headCommit>` and never present it as "commit `<sha>`".
 
@@ -181,7 +191,7 @@ generatedAt: <YYYY-MM-DD HH:MM>
 
 | Situation | Handling |
 |---|---|
-| `preflight` returns `ok:false` | retry with `--cwd <dir>`; if that also fails, tell the user to run `/okstra-setup` first and stop |
+| `preflight` reports `Okstra preflight: failed` | retry with `--cwd <dir>`; if that also fails, tell the user to run `/okstra-setup` first and stop |
 | `unknown command: code-review` | the `okstra` binary predates this skill — tell the user to update it (`npm i -g okstra@latest`) and stop |
 | `worktreePath` is empty | not a hard stop and not a missing stage: run git in `projectRoot` against the stage's `branch` ref and continue |
 | `baseCommit` is not an ancestor of `headCommit` — `git -C <workdir> rev-list --count <headCommit>..<baseCommit>` returns a **non-zero** count, meaning a rebase or squash rewrote the history the stage was recorded against, and `<baseCommit>..<headCommit>` would drag predecessor work in backwards | code-review is read-only, so do not force a reconcile. Offer two options: review against the branch's current tip, or run `okstra git-reconcile` first and retry |

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

@@ -25,10 +25,10 @@ Run one Bash tool call, starting with the literal token `okstra` (never wrapped
 <!-- END FRAGMENT: bash-invocation-rule -->
 
 ```bash
-okstra preflight --runtime claude-code --json
+okstra preflight --runtime claude-code
 ```
 
-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.
+On `Okstra preflight: ready`, carry the fixed `Project root` line and pass it as `--project-root <projectRoot>` to every `okstra container` call below. On `Okstra preflight: failed`, show `Reason` and `Recovery`, 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).
@@ -61,7 +61,7 @@ When the user chains multiple facets in one message (e.g. "bring it up, then sho
 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:
 
 1. If the user gave a full task-key, use it.
-2. If the user gave only a task-id, resolve it via `okstra resolve-task-key <task-id> --project-root <projectRoot> --json` and branch on the stdout `matches[]`: single → use its `taskKey`; multiple → list candidates and ask (3-option picker); none → report not found.
+2. If the user gave only a task-id, run `okstra model-io task-selection-input --project-root <projectRoot> --task-ref <task-id>`. Use the fixed `Selection status`, `Task key`, and numbered `Candidate` lines: one match → use its task key; multiple → list candidates and ask (3-option picker); none → report not found.
 3. `down --all` is the only call that does not need a task-key (see `down`).
 
 ---
@@ -78,12 +78,12 @@ Brings up the task's container group: integrates the implementation stages into
 Run:
 
 ```bash
-okstra container up --project-root <projectRoot> --task-key <task-key>
+okstra container up --project-root <projectRoot> --task-key <task-key> --text
 ```
 
-Parse the stdout JSON and report the provisioned services and the watcher pane. If a service failed its healthcheck, the call surfaces the failing services and the `docker compose ... logs` line to inspect — relay that line; do not invent your own.
+Read the fixed output fields and report the provisioned services and watcher pane. If a service failed its healthcheck, the call surfaces the failing services and the `docker compose ... logs` line to inspect — relay that line; do not invent your own.
 
-After a successful `up`, tell the user how to reach the running build (the compose file's published ports) and that `okstra container status <task-key>` / `okstra container down <task-key>` manage it from here. For *what to verify* once it is up, point the user to the implementation report's §5.7.9 Manual User Test (Draft) — its steps and expected results are the manual test script for this build.
+After a successful `up`, run the `status --text` command below and read its numbered container `ports` fields to tell the user how to reach the running build. Also explain that `okstra container status <task-key>` / `okstra container down <task-key>` manage it from here. For *what to verify* once it is up, point the user to the implementation report's §5.7.9 Manual User Test (Draft) — its steps and expected results are the manual test script for this build.
 
 ---
 
@@ -92,10 +92,10 @@ After a successful `up`, tell the user how to reach the running build (the compo
 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
-okstra container status --project-root <projectRoot> --task-key <task-key>
+okstra container status --project-root <projectRoot> --task-key <task-key> --text
 ```
 
-Parse the stdout JSON (`{projectName, containers, watchers}`) and report:
+Read the fixed `Project name`, `Containers`, and `Watchers` fields and report:
 
 | Field | Meaning |
 |---|---|
@@ -112,16 +112,16 @@ If `containers` is empty, say the group is not running and offer `up`. Treat the
 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
-okstra container logs --project-root <projectRoot> --task-key <task-key>
+okstra container logs --project-root <projectRoot> --task-key <task-key> --text
 ```
 
 Add `--service <name>` to scope to one service:
 
 ```bash
-okstra container logs --project-root <projectRoot> --task-key <task-key> --service <service>
+okstra container logs --project-root <projectRoot> --task-key <task-key> --service <service> --text
 ```
 
-Parse the stdout JSON (`{watchersDir, watchers}`). Report the `watchersDir` host path (under `~/.okstra/...`-style project artifacts — display the absolute path the CLI returns) and the watcher entries. Explain that the live stream is in the attached tmux pane; to see raw container logs the user runs `docker compose -p <projectName> logs -f <service>` (get `<projectName>` from `status`).
+Read the fixed `Watchers dir` and numbered `Watchers` fields. Report the host path and watcher entries. Explain that the live stream is in the attached tmux pane; to see raw container logs the user runs `docker compose -p <projectName> logs -f <service>` (get `<projectName>` from `status`).
 
 ---
 
@@ -130,10 +130,10 @@ Parse the stdout JSON (`{watchersDir, watchers}`). Report the `watchersDir` host
 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
-okstra container stop-watcher --project-root <projectRoot> --task-key <task-key>
+okstra container stop-watcher --project-root <projectRoot> --task-key <task-key> --text
 ```
 
-Parse the stdout JSON (`{reapedPanes, note}`). Confirm which panes were reaped and that the containers are still running (the `note` says so). If the user actually wants the containers gone, route to `down`.
+Read the fixed `Reaped panes` and `Note` fields. Confirm which panes were reaped and that the containers are still running. If the user actually wants the containers gone, route to `down`.
 
 ---
 
@@ -144,23 +144,23 @@ Tears down the container group (removes containers found by the run-trace label)
 Single task:
 
 ```bash
-okstra container down --project-root <projectRoot> --task-key <task-key>
+okstra container down --project-root <projectRoot> --task-key <task-key> --text
 ```
 
 Every container group in the project (no task-key needed):
 
 ```bash
-okstra container down --project-root <projectRoot> --all
+okstra container down --project-root <projectRoot> --all --text
 ```
 
-Parse the stdout JSON (`{downed, orphanPanesReaped}`). Report each torn-down `projectName` and the orphan panes reaped. `down` runs `docker compose -p <name> down --remove-orphans` — a compose-native teardown that removes the project's containers and the compose network, but deliberately keeps named volumes (e.g. DB data) by NOT passing `-v`. Confirm with the user before running `--all`, since it takes down every okstra container group in the project at once. A single-task `down` is safe to run directly once the task-key is resolved.
+Read the fixed `Downed` and `Orphan panes reaped` fields. Report each torn-down project name and the orphan panes reaped. `down` runs `docker compose -p <name> down --remove-orphans` — a compose-native teardown that removes the project's containers and the compose network, but deliberately keeps named volumes (e.g. DB data) by NOT passing `-v`. Confirm with the user before running `--all`, since it takes down every okstra container group in the project at once. A single-task `down` is safe to run directly once the task-key is resolved.
 
 ---
 
 ## Output Rules (shared)
 
 - Responses should be concise and written in Korean unless the user requests otherwise.
-- The stdout JSON from each `okstra container` call is the source of truth — do not run raw `docker` commands to second-guess it unless the CLI fails and the user explicitly asks for a manual fallback.
+- The fixed text fields from each `okstra container` call are the source of truth — do not run raw `docker` commands to second-guess them unless the CLI fails and the user explicitly asks for a manual fallback.
 - Show the resolved `<task-key>` in the heading so the user can confirm disambiguation.
 - Surface failure messages from the CLI verbatim (compose-up failures, missing worktree/compose file) — do not paraphrase the remediation line.
-- Display container/service states as-is from the JSON; do not normalize or remap.
+- Display container/service states as-is from the fixed fields; do not normalize or remap.

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

@@ -28,14 +28,14 @@ Run one Bash tool call, starting with the literal token `okstra` (never wrapped
 <!-- END FRAGMENT: bash-invocation-rule -->
 
 ```bash
-okstra preflight --runtime claude-code --json
+okstra preflight --runtime claude-code
 ```
 
-The project check only sees the cwd of the Bash call. When the user is asking about a project that is **not** the cwd (a sibling repo, a monorepo subdir, or a project named explicitly in the request), the bare form resolves to the wrong project or none and returns `ok:false` — a false negative, not a missing setup; do not hard-stop on it.
+The project check only sees the cwd of the Bash call. When the user is asking about a project that is **not** the cwd (a sibling repo, a monorepo subdir, or a project named explicitly in the request), the bare form can report `Okstra preflight: failed` — a false negative, not a missing setup; do not hard-stop on it.
 
-Branch on the stdout JSON:
-- `ok: true` → carry `projectRoot` as a literal string; it is the base for every sub-command step below.
-- `ok: false` → before concluding "no setup", ask whether the user pointed at a specific project directory. If they did, 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 this **also** returns `ok:false` do you tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
+Branch on the fixed first line:
+- `Okstra preflight: ready` → carry `Project root` as a literal string; it is the base for every sub-command step below.
+- `Okstra preflight: failed` → before concluding "no setup", ask whether the user pointed at a specific project directory. If they did, re-run targeting it: `okstra preflight --runtime claude-code --cwd <that-dir>` (`--cwd` is the sanctioned way to target a project — a leading `cd` would break the permission match). Only if this also fails do you show `Reason` and `Recovery`, 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).
@@ -59,13 +59,14 @@ When the user chains multiple facets in one message (e.g. "status, and then time
 
 ### Standard task-key resolution (0/1/N)
 
-Facets that accept a bare token (a task-id like `DEV-9184` **or** a task-group like `PROD`) resolve it with the shared resolver (SSOT — `scripts/okstra_ctl/resolve_task_key.py` / `okstra_project.resolve_task_reference`). The resolver matches the token as a task-id **and** as a task-group, unioning both (a group expands to its member tasks); each entry carries `_matchedVia` (`"taskId"` | `"taskGroup"`):
+Facets that accept a bare token (a task-id like `DEV-9184` **or** a task-group like `PROD`) resolve it through the fixed text projection:
 
 ```bash
-okstra resolve-task-key <token> --project-root <projectRoot> --json
+okstra model-io task-selection-input --project-root <projectRoot> --task-ref <token>
 ```
 
-Branch on the stdout JSON `matches[]`:
+Branch on `Match count` in the projection and use only its repeated `Task`,
+`Updated at`, and `Matched via` lines:
 - **0** → report the task cannot be found. Do not guess.
 - **1** → use that entry's `taskKey`.
 - **N** → list the candidate `taskKey`s (with `updatedAt`, and `_matchedVia` so the user sees which came from a task-id vs a task-group) and ask via a 3-option picker (1–2 recommendations + `Enter directly`), then use the chosen `taskKey`.
@@ -74,8 +75,8 @@ Branch on the stdout JSON `matches[]`:
 
 When a facet needs a task but the user did not name one:
 
-1. Read `.okstra/discovery/task-catalog.json`.
-2. If exactly one task exists, use it.
+1. Run `okstra model-io task-selection-input --project-root <projectRoot>`.
+2. Branch on `Match count`; if exactly one task exists, use it.
 3. If multiple tasks exist, show the latest 10 by `updatedAt` as real task-keys and ask which one. Do not guess, and do not answer with placeholder forms only.
 
 ## Output Rules (shared)
@@ -84,7 +85,7 @@ When a facet needs a task but the user did not name one:
   status values the first time each appears — the reader has not seen the report you are summarizing.
 - Use project-relative paths whenever possible.
 - If there is no recent report, display `--`.
-- If a specific task does not exist, explicitly state that it cannot be found based on `task-catalog.json`.
+- If a specific task does not exist, explicitly state that the task resolver returned no match.
 - If `awaitingApproval` is true, clearly indicate that the task is awaiting user approval.
 - Display status fields as-is from disk (`completed`, `contract-violated`, `todo`, `error`, empty, ...). Do not normalize or remap.
 - Dates in `YYYY-MM-DD HH:MM` format.