okstra 0.30.0 → 0.30.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.30.0",
+  "version": "0.30.2",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.30.0",
-  "builtAt": "2026-05-17T08:21:41.472Z",
+  "package": "0.30.2",
+  "builtAt": "2026-05-19T06:29:56.728Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/profiles/_common-contract.md

@@ -77,3 +77,12 @@ profile document.
 - Audit sidecar (shared — applies to every analysis-worker output and every final-report):
   - Reading Confirmation lines (one short line per input file confirming end-to-end reading) live in the **worker audit sidecar** at `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md`, NOT in the worker's main worker-results file. The worker-results body starts at section 1 (Findings). The validator fails worker-results files that contain a `## 0. Reading Confirmation` heading.
   - The audit sidecar carries any other meta the worker wants to log (tool-call counts, MCP query summaries, timing notes). The lead's final-report does NOT duplicate this content — it is consumed by the validator and by post-run audit tooling, not by end-user readers.
+
+- Markdown authoring (shared — applies to every markdown document produced by the lead or any worker, including final-reports, worker-results, briefs, and ad-hoc notes):
+  - every document must begin with an `Index` section.
+  - include only information necessary to fulfill the user's stated purpose and directly related requirements.
+  - follow only the sections, format, tone, and scope specified by the user, plus the required `Index` section.
+  - when writing task instructions or work orders, define the scope of work clearly and specifically, including deliverables, acceptance criteria, and verification steps when relevant.
+  - define scope positively by stating what work is included. Work outside the defined scope must not be performed.
+  - before adding any structure or content not explicitly specified, ask the user for confirmation, except for the required `Index` section.
+  - before completion, verify that the document exactly matches the requested scope and contains no unrelated material.

package/runtime/python/okstra_ctl/worktree.py

@@ -43,6 +43,7 @@ from typing import Optional
 
 from .ids import _safe_fs_segment
 from . import worktree_registry
+from .seeding import SettingsLinkError, ensure_project_settings_symlink
 
 
 # Project-root directories that hold okstra task state, ignored by git, or
@@ -361,6 +362,34 @@ def _link_sync_files(source_root: Path, worktree_path: Path) -> list[str]:
     return notes
 
 
+def _seed_worktree_settings_symlink(worktree_path: Path) -> None:
+    """Seed `.claude/settings.local.json` in the worker worktree so dispatched
+    Claude / codex / gemini sessions inherit the okstra read-only / write
+    allowlist. Mirrors the main-project seeding done in `run.py` — needed
+    because `_link_sync_dirs` skips `.claude/` whenever `git worktree add`
+    already materialised the directory (e.g. tracked `.claude/handoff-*.md`).
+    Failures degrade to stderr warning so worktree provisioning still
+    succeeds.
+    """
+    try:
+        link = ensure_project_settings_symlink(project_root=worktree_path)
+    except SettingsLinkError as exc:
+        print(
+            f"okstra-settings: failed to seed worker worktree symlink at "
+            f"{worktree_path / '.claude/settings.local.json'} — worker dispatch "
+            f"may be blocked by Claude Code permissions. ({exc})",
+            file=__import__("sys").stderr,
+        )
+        return
+    if link is None:
+        print(
+            "okstra-settings: ~/.okstra/templates/settings.local.json missing — "
+            "re-run 'npx okstra@latest install' (0.14.0+) to provision the "
+            "symlink target.",
+            file=__import__("sys").stderr,
+        )
+
+
 def _copy_snapshot_files(source_root: Path, worktree_path: Path) -> list[str]:
     """Copy fixture files from MAIN → task worktree as read-only snapshots
     (FU-V3).
@@ -485,6 +514,7 @@ def provision_task_worktree(
     existing = worktree_registry.lookup(safe_project, safe_group, safe_task)
     if existing is not None and existing.status == "active":
         worktree_registry.touch_phase(safe_project, safe_group, safe_task, task_type)
+        _seed_worktree_settings_symlink(Path(existing.worktree_path))
         return WorktreeProvision(
             status="reused",
             path=existing.worktree_path,
@@ -586,6 +616,8 @@ def provision_task_worktree(
         _git(main_root, "branch", "-D", branch)
         raise
 
+    _seed_worktree_settings_symlink(worktree_path)
+
     base_label = (
         f"{base_origin} @ {resolved_base_ref[:12]}"
         if base_origin != "HEAD"

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

@@ -107,26 +107,24 @@ at external `docs/adr/`.
 
 ## Step 0: Resolve project root
 
-Reuse the same disk-only resolution rule as `okstra-run`:
+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.
 
 ```bash
-if command -v okstra >/dev/null 2>&1; then
-  OKSTRA_CMD="okstra"
-else
-  # `~/.okstra/bin/okstra.sh` exists on every installed machine but it is
-  # the bash run-wrapper, NOT the Node CLI — it does not implement
-  # `check-project`. Do not branch into it as a fallback. Go straight to
-  # `npx` so the user always reaches a working `check-project` even when
-  # the Node CLI is off-$PATH.
-  OKSTRA_CMD="npx -y okstra@latest"
-fi
-$OKSTRA_CMD check-project --cwd "$(pwd)"
+okstra check-project --json
 ```
 
-- `ok: true` → use `projectRoot`.
-- `ok: false` → `AskUserQuestion` (free text) for an absolute project root, then
-  re-run `okstra check-project --cwd <input>`. If still not ok, tell the user
-  to run `okstra-setup` and stop.
+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` → ask the user with a **plain text prompt** for an absolute project-root path, then rerun as a separate tool call with the literal absolute path (no `$(pwd)`, no shell variables):
+
+  ```bash
+  okstra check-project --cwd /abs/path/from/user --json
+  ```
+
+  If still `ok: false`, tell the user to run `okstra-setup` and stop.
+
+> If the `okstra` binary is not on `PATH` at all, the command above will not run. In that case tell the user verbatim: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." 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.
 
 ## Step 1: Choose input source
 

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

@@ -26,27 +26,18 @@ If the user is ambiguous, ask. Defaulting to the wrong one either wastes a fresh
 
 ## Step 0: Verify okstra runtime + project setup
 
-```bash
-if command -v okstra >/dev/null 2>&1; then
-  OKSTRA_CMD="okstra"
-else
-  OKSTRA_CMD="npx -y okstra@latest"
-fi
-$OKSTRA_CMD ensure-installed >/dev/null 2>&1 || {
-  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
-  exit 1
-}
-eval "$($OKSTRA_CMD paths --shell)"
-export PYTHONPATH="$OKSTRA_PYTHONPATH"
-OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
-  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
-  echo "$OKSTRA_PROJECT_INFO" >&2
-  exit 1
-}
-```
+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.
+
+1. `okstra ensure-installed`
+   If this exits non-zero, tell the user: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." 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}`.
+
+   - `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 use it to locate `.project-docs/okstra/discovery/task-catalog.json`.
 
-`$OKSTRA_PROJECT_INFO` is JSON `{ok, projectRoot, projectJsonPath, projectId}` —
-use `projectRoot` to locate `.project-docs/okstra/discovery/task-catalog.json`.
+Subsequent `okstra <subcmd>` calls self-bootstrap their Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
 
 ## Step 1: Read the Task Catalog
 

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

@@ -36,57 +36,45 @@ multi-MB logs; analysis-phase dispatches are typically smaller.
 
 ## Step 0: Verify okstra runtime + project setup
 
-Before any other step, ensure both the okstra runtime and the current
-project's okstra metadata are in place:
+Before any other step, 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.
 
-```bash
-if command -v okstra >/dev/null 2>&1; then
-  OKSTRA_CMD="okstra"
-else
-  OKSTRA_CMD="npx -y okstra@latest"
-fi
-$OKSTRA_CMD ensure-installed >/dev/null 2>&1 || {
-  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
-  exit 1
-}
-eval "$($OKSTRA_CMD paths --shell)"
-export PYTHONPATH="$OKSTRA_PYTHONPATH"
-OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
-  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
-  echo "$OKSTRA_PROJECT_INFO" >&2
-  exit 1
-}
-```
+1. `okstra ensure-installed`
+   If this exits non-zero, tell the user: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." 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}`.
+
+   - `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 use it as the search root for the steps below.
 
-Parse `projectRoot` from the JSON and use it as the search root for the
-steps below.
+Subsequent `okstra <subcmd>` calls self-bootstrap their Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
 
 ## Step 1: Inventory
 
 Find all wrapper log files and collect metadata. Use a single `find` to
 keep the I/O cost predictable, then format the results.
 
-```bash
-PROJECT_ROOT=$(echo "$OKSTRA_PROJECT_INFO" | python3 -c 'import sys,json;print(json.load(sys.stdin)["projectRoot"])')
-LOGS_ROOT="$PROJECT_ROOT/.project-docs/okstra/tasks"
+Construct the logs root by appending `/.project-docs/okstra/tasks` to the literal `projectRoot` value parsed in Step 0, and paste it as a literal absolute path in place of `<LOGS_ROOT>` below (no shell variables, no `$(...)`):
 
-# columns: size_bytes | mtime_epoch | path
-find "$LOGS_ROOT" -type f -path '*/runs/*/prompts/*.log' \
+```bash
+find <LOGS_ROOT> -type f -path '*/runs/*/prompts/*.log' \
   -printf '%s\t%T@\t%p\n' 2>/dev/null \
   | sort -k1,1nr
 ```
 
-On macOS, `find -printf` is unavailable. Fall back to `stat`:
+The columns produced are `size_bytes | mtime_epoch | path`.
+
+On macOS, `find -printf` is unavailable. Fall back to `stat` — again substitute the literal `<LOGS_ROOT>`:
 
 ```bash
-find "$LOGS_ROOT" -type f -path '*/runs/*/prompts/*.log' 2>/dev/null \
+find <LOGS_ROOT> -type f -path '*/runs/*/prompts/*.log' 2>/dev/null \
   | while IFS= read -r p; do
       stat -f '%z%t%m%t%N' "$p"
     done \
   | sort -k1,1nr
 ```
 
-If the result is empty, report `No wrapper log files found under <PROJECT_ROOT>` and exit.
+If the result is empty, report `No wrapper log files found under <projectRoot>` and exit.
 
 ## Step 2: Summary table
 

package/runtime/skills/okstra-report-finder/SKILL.md

@@ -14,27 +14,18 @@ user-invocable: false
 
 ## Step 0: Verify okstra runtime + project setup
 
-```bash
-if command -v okstra >/dev/null 2>&1; then
-  OKSTRA_CMD="okstra"
-else
-  OKSTRA_CMD="npx -y okstra@latest"
-fi
-$OKSTRA_CMD ensure-installed >/dev/null 2>&1 || {
-  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
-  exit 1
-}
-eval "$($OKSTRA_CMD paths --shell)"
-export PYTHONPATH="$OKSTRA_PYTHONPATH"
-OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
-  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
-  echo "$OKSTRA_PROJECT_INFO" >&2
-  exit 1
-}
-```
+각 명령은 **별도 Bash tool call** 로 실행한다. 모든 명령은 리터럴 `okstra` 토큰으로 시작해 `Bash(okstra:*)` 권한 매칭을 통과해야 한다. `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, `&&` 로 감싸지 말고, `$OKSTRA_CMD` 변수나 `npx -y okstra@latest` 폴백도 도입하지 않는다 — 첫 토큰이 비리터럴이면 권한 매칭이 깨져 호출마다 확인 프롬프트가 뜬다. 각 명령의 출력은 LLM(너) 이 보고 자연어로 분기 판단을 한다 — shell 분기는 쓰지 않는다.
+
+1. `okstra ensure-installed`
+   비정상 종료 → 사용자에게 그대로 안내: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." 그리고 중단. 폴백으로 `npx -y okstra@latest ...` 를 호출하지 않는다.
+
+2. `okstra check-project --json`
+   현재 작업 디렉터리 기준 프로젝트를 읽는다. stdout 의 JSON shape: `{ok, projectRoot, projectJsonPath, projectId}`.
+
+   - `ok: false` → 사용자에게 "this project has no okstra setup. Run `/okstra-setup` first." 안내 후 중단.
+   - `ok: true` → `projectRoot` 를 리터럴 문자열로 들고 catalog/manifest 위치를 잡는다.
 
-`$OKSTRA_PROJECT_INFO` (JSON `{ok, projectRoot, projectJsonPath, projectId}`) —
-`projectRoot` 로 catalog/manifest 위치를 잡는다.
+후속 `okstra <subcmd>` 호출은 Python path 를 자체 부트스트랩하므로 본 스킬은 `okstra paths --shell` / `export PYTHONPATH=...` 를 필요로 하지 않는다.
 
 ## Step 1: Task Key로 Report 경로 찾기
 

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

@@ -37,30 +37,18 @@ If `--title` is omitted, derive a default title from `task-group` (e.g. `uploadF
 
 ## Preflight: Verify okstra runtime + project setup
 
-Run before anything else in this skill:
+Before anything else in this skill, 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.
 
-```bash
-if command -v okstra >/dev/null 2>&1; then
-  OKSTRA_CMD="okstra"
-else
-  OKSTRA_CMD="npx -y okstra@latest"
-fi
-$OKSTRA_CMD ensure-installed >/dev/null 2>&1 || {
-  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
-  exit 1
-}
-eval "$($OKSTRA_CMD paths --shell)"
-export PYTHONPATH="$OKSTRA_PYTHONPATH"
-OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
-  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
-  echo "$OKSTRA_PROJECT_INFO" >&2
-  exit 1
-}
-```
+1. `okstra ensure-installed`
+   If this exits non-zero, tell the user: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." 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}`.
+
+   - `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 use it to locate `.project-docs/okstra/discovery/task-catalog.json` and the task-group directory.
 
-`$OKSTRA_PROJECT_INFO` is JSON `{ok, projectRoot, projectJsonPath, projectId}` —
-use `projectRoot` to locate `.project-docs/okstra/discovery/task-catalog.json`
-and the task-group directory.
+Subsequent `okstra <subcmd>` calls self-bootstrap their Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
 
 ## Process Procedure
 

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

@@ -53,44 +53,32 @@ Show the final summary line back to the user (`version stamp: x.y.z`).
 If install fails, surface the stderr verbatim. Do NOT try to "fix" it by
 running the legacy `okstra-install.sh` — that path is dev-only.
 
-## Step 2: Load runtime paths
+## Step 2: Load runtime paths (no-op)
 
-```bash
-# Prefer PATH-resolved okstra (npm-installed) over npx — avoids per-call registry lookup.
-if command -v okstra >/dev/null 2>&1; then
-  OKSTRA_CMD="okstra"
-else
-  OKSTRA_CMD="npx -y okstra@latest"
-fi
-eval "$($OKSTRA_CMD paths --shell)"
-export PYTHONPATH="$OKSTRA_PYTHONPATH"
-```
+After `okstra install`, every `okstra <subcmd>` call self-bootstraps its Python path, so this skill does NOT run `okstra paths --shell` / `eval ...` / `export PYTHONPATH=...`. The previously-set `$OKSTRA_WORKSPACE`, `$OKSTRA_AGENTS_DIR`, `$OKSTRA_PYTHONPATH`, `$OKSTRA_BIN`, `$OKSTRA_HOME` env vars are NOT set by this skill. If a later step needs one of those paths, call `okstra paths --json` as a **separate Bash tool call** (literal-token-first) and read the value from JSON output.
 
-After this, `$OKSTRA_WORKSPACE`, `$OKSTRA_AGENTS_DIR`, `$OKSTRA_PYTHONPATH`,
-`$OKSTRA_BIN`, `$OKSTRA_HOME` are all set. Do not hardcode any of these — read
-them from the env vars.
+**Bash invocation rule (permission-friendly)**: from this step on, every Bash command in this skill MUST begin with the literal token `okstra` and pass literal argument values. Do not introduce shell variables (`$PROJECT_ROOT`, `$PROJECT_ID`, ...), `$(...)` command substitution, leading `VAR=...` assignments, or wrap commands in `if`/`eval`/`||`/`&&` — any of those make the leading token non-literal, defeat the `Bash(okstra:*)` permission match, and force a confirmation prompt on every call. When a prior tool call emitted a path or value, read it from the tool output and paste the literal string into the next command.
 
 ## Step 3: Resolve PROJECT_ROOT
 
 ```bash
-PROJECT_ROOT=$(okstra check-project --cwd "$(pwd)" | jq -r '.projectRoot')
+okstra check-project --json
 ```
 
-The JSON includes `projectRoot` on success. Bind it into the shell so
-Step 4 onwards can expand `$PROJECT_ROOT`. On failure (`ok: false`,
-`stage: "resolve"`) ask the user (`AskUserQuestion`, free text) for an
-absolute project root and rerun with `--cwd <their answer>`.
+Parse the JSON from stdout. The shape is `{ok, projectRoot, projectJsonPath, projectId, stage?}`.
+
+- `ok: true` → carry `projectRoot` as a literal absolute string and paste it into every subsequent command in this skill.
+- `ok: false`, `stage: "resolve"` → ask the user (`AskUserQuestion`, free text) for an absolute project root and rerun as a separate Bash tool call with the literal absolute path:
+
+  ```bash
+  okstra check-project --cwd /abs/path/from/user --json
+  ```
 
 ## Step 4: Inspect or create `project.json`
 
-```bash
-PROJECT_JSON="$PROJECT_ROOT/.project-docs/okstra/project.json"
-if [ -f "$PROJECT_JSON" ]; then
-  cat "$PROJECT_JSON"
-fi
-```
+Use the `Read` tool on the literal absolute path `<projectRoot>/.project-docs/okstra/project.json` (substitute the literal `projectRoot` value parsed in Step 3). If `Read` errors with "file does not exist", treat that as the "create" branch below; otherwise the file exists and you can inspect its contents inline.
 
-If the file exists, print its `projectId`/`projectRoot` and ask whether to
+If the file exists, surface its `projectId`/`projectRoot` and ask whether to
 keep or overwrite. Default is to keep — okstra refuses to change `projectId`
 on an existing project (see `okstra_project.resolver.upsert_project_json`),
 so overwriting requires manually deleting the file first.
@@ -104,10 +92,10 @@ If the file does NOT exist, ask via `AskUserQuestion`:
   `error: --project-id is required (no existing project.json, not a TTY)`,
   so passing the user's empty answer through is a silent failure path.
 
-Then create the file:
+Then create the file — paste the literal `projectRoot` from Step 3 and the literal `projectId` from the user's answer (no shell variables):
 
 ```bash
-okstra setup --yes --project-root "$PROJECT_ROOT" --project-id "$PROJECT_ID"
+okstra setup --yes --project-root /abs/path/to/projectRoot --project-id my-project-id
 ```
 
 > After this, **Steps 4.5–4.8 are all optional**. The built-in defaults
@@ -266,7 +254,7 @@ If the user chose `나중에`, tell them they can register later with one of:
 ## Step 5: Verify
 
 ```bash
-$OKSTRA_CMD doctor
+okstra doctor
 ```
 
 If all checks return `OK`, the setup is complete. If any check fails, surface

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

@@ -13,30 +13,18 @@ description: Use when the user asks for overall okstra task status, current life
 
 ## Step 0: Verify okstra runtime + project setup
 
-Before any other step, ensure both the okstra runtime and the current
-project's okstra metadata are in place:
-
-```bash
-if command -v okstra >/dev/null 2>&1; then
-  OKSTRA_CMD="okstra"
-else
-  OKSTRA_CMD="npx -y okstra@latest"
-fi
-$OKSTRA_CMD ensure-installed >/dev/null 2>&1 || {
-  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
-  exit 1
-}
-eval "$($OKSTRA_CMD paths --shell)"
-export PYTHONPATH="$OKSTRA_PYTHONPATH"
-OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
-  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
-  echo "$OKSTRA_PROJECT_INFO" >&2
-  exit 1
-}
-```
+Before any other step, 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.
+
+1. `okstra ensure-installed`
+   If this exits non-zero, tell the user: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." 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}`.
+
+   - `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 into the steps below; reuse it instead of re-resolving.
 
-`$OKSTRA_PROJECT_INFO` is JSON `{ok, projectRoot, projectJsonPath, projectId}` —
-parse and reuse it instead of re-resolving in the steps below.
+Subsequent `okstra <subcmd>` calls self-bootstrap their Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
 
 ## Step 1: Overall Project Status
 
@@ -255,4 +243,4 @@ This skill updates `task-manifest.json` only. `discovery/task-catalog.json` may
 
 ## Out-of-Scope Backlog
 
-- **Step 0 boilerplate duplication.** The `ensure-installed` + `paths --shell` + `check-project --json` preamble is byte-identical across every user-facing okstra skill. The Claude Code skill framework has no include/snippet mechanism today, so each skill duplicates the block. A future change should either (a) extract the preamble into a single `okstra preflight` subcommand the skill can call in one line, or (b) ship the block as a shared SKILL fragment if the framework gains include support. Not actionable inside this skill alone.
+- **Step 0 boilerplate duplication.** The `ensure-installed` + `check-project --json` preamble (literal-token-first, separate Bash calls) is near-identical across every user-facing okstra skill. The Claude Code skill framework has no include/snippet mechanism today, so each skill duplicates the prose. A future change should either (a) extract the preamble into a single `okstra preflight` subcommand the skill can call in one line, or (b) ship the block as a shared SKILL fragment if the framework gains include support. Not actionable inside this skill alone.

package/runtime/skills/okstra-time-summary/SKILL.md

@@ -29,27 +29,18 @@ If a run never reached Phase 7, its `team-state` will not have `durationMs` fill
 
 ## Step 0: Verify okstra runtime + project setup
 
-```bash
-if command -v okstra >/dev/null 2>&1; then
-  OKSTRA_CMD="okstra"
-else
-  OKSTRA_CMD="npx -y okstra@latest"
-fi
-$OKSTRA_CMD ensure-installed >/dev/null 2>&1 || {
-  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
-  exit 1
-}
-eval "$($OKSTRA_CMD paths --shell)"
-export PYTHONPATH="$OKSTRA_PYTHONPATH"
-OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
-  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
-  echo "$OKSTRA_PROJECT_INFO" >&2
-  exit 1
-}
-```
+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.
+
+1. `okstra ensure-installed`
+   If this exits non-zero, tell the user: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." 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}`.
+
+   - `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 use it to locate `.project-docs/okstra/discovery/task-catalog.json`.
 
-`$OKSTRA_PROJECT_INFO` (JSON `{ok, projectRoot, projectJsonPath, projectId}`)
-gives `projectRoot` for locating `.project-docs/okstra/discovery/task-catalog.json`.
+Subsequent `okstra <subcmd>` calls self-bootstrap their Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
 
 ## Step 1: Resolve task-id → timeline path