okstra 0.15.0 → 0.17.0

package/bin/okstra

@@ -9,6 +9,11 @@ const COMMANDS = new Map([
   ["doctor", () => import("../src/doctor.mjs").then((m) => m.run)],
   ["setup", () => import("../src/setup.mjs").then((m) => m.run)],
   ["check-project", () => import("../src/check-project.mjs").then((m) => m.run)],
+  ["task-list", () => import("../src/task-list.mjs").then((m) => m.run)],
+  ["task-show", () => import("../src/task-show.mjs").then((m) => m.run)],
+  ["worktree-lookup", () => import("../src/worktree-lookup.mjs").then((m) => m.run)],
+  ["plan-validate", () => import("../src/plan-validate.mjs").then((m) => m.run)],
+  ["render-bundle", () => import("../src/render-bundle.mjs").then((m) => m.run)],
 ]);
 
 const USAGE = `okstra — multi-agent cross-verification orchestrator for Claude Code
@@ -37,6 +42,14 @@ Admin commands:
   check-project          Verify the current project has been registered with setup
   paths                  Print runtime paths (workspace/agents/pythonpath/bin/home/version)
 
+Introspection commands (JSON output, used by skills to avoid python heredocs):
+  task-list              List tasks registered in the current project
+  task-show              Summarize a task's manifest + workflow phase state
+  worktree-lookup        Look up registered worktree for a task-key
+  plan-validate          Check an approved-plan file for the approval marker
+  render-bundle          Preview prepare_task_bundle() output (forwards to
+                         python3 -m okstra_ctl.run --render-only)
+
 Global options:
   --version              Print okstra version and exit
   --help                 Print this help

package/package.json

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

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.15.0",
-  "builtAt": "2026-05-13T06:06:19.054Z",
+  "package": "0.17.0",
+  "builtAt": "2026-05-13T10:55:45.579Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/profiles/final-verification.md

@@ -24,6 +24,7 @@
   - **Residual Risk block** (under section 4): risks that are not blockers but should be tracked, each with mitigation owner and a trigger that would escalate them to a blocker.
   - **Validation Evidence**: for every requirement in the originating plan or task brief, cite the artifact (commit SHA, test output, log line, MCP SELECT result) that demonstrates coverage. Paraphrased "verified" claims without an artifact are rejected.
   - **Read-only command log**: any pre-existing test/validation command executed during this run MUST be listed with its exact command line and exit code. No mutating commands may appear here.
+  - **Two-tier command lookup (shared with `implementation`):** when this phase performs its own independent re-validation, the command source is exactly the same two tiers `implementation` verifiers use — Tier 1 is the originating task brief / approved plan's `validation` set, Tier 2 is `<PROJECT_ROOT>/.project-docs/okstra/project.json` under `qaCommands`. Auto-detecting tools from manifest files is forbidden; missing tiers are recorded as `qa-command not configured: <category>` and do NOT trigger a guess. The `cmd` deny-list (`--fix`, `--write`, ` -w`, ` -u`, `--snapshot-update`, `INSTA_UPDATE=<not-no>`, `cargo update`, `npm install` without `ci`, etc.) is enforced identically. NOTE: runtime fail-fast validation (`okstra_ctl.qa_commands.validate_qa_commands`) only fires at `--task-type implementation` run-prep, so this phase MUST self-check each `qaCommands` entry against the deny-list before executing it — if a denied token is present, skip the command and record it as a `Read-only command log` line `qa-command rejected (denied token: <token>): <label>`.
   - **Routing recommendation**: brief note on the next safe phase (`done`, `error-analysis`, `implementation-planning`) tied to the verdict and blocker list.
 - Clarification request policy (phase-specific addendum — shared policy is in `_common-contract.md`):
   - populate section 5 only when a blocker hinges on information only the user can supply (deployment intent, intended target environment, business-rule interpretation)

package/runtime/prompts/profiles/implementation.md

@@ -17,6 +17,27 @@
 - Team contract (phase-specific overrides — `Claude worker` is replaced by `Executor` + verifier set in this phase):
   - **Executor role:** the `Executor` (bound above) is the **only worker permitted to use Edit / Write / state-mutating Bash commands** on project files. All other workers run read-only. When the executor provider is `codex` or `gemini`, the actual file mutation happens inside the executor CLI's own auto-edit mode (e.g. `codex exec --sandbox workspace-write`, gemini's equivalent) — not through Claude-side Edit/Write tools — but the safety rules in this profile still apply identically.
   - **Verifier roles:** the verifier slots are `Claude verifier` and `Codex verifier`, plus `Gemini verifier` **only when `gemini` is in the resolved `--workers` roster**. Every verifier in the resolved roster is dispatched regardless of which provider holds the executor role; the executor's own provider is run *separately* as a verifier (a fresh CLI session with no shared context) so that no verdict is produced from the same session that wrote the diff. Verifiers MUST NOT call Edit, Write, or any Bash command that mutates files outside the run's artifact directories. If a verifier wants a fix, it records the recommendation in its worker result; it does not apply the fix itself.
+  - **Verifier QA duties (independent re-run mandate):** every verifier acts as a QA gate, not just a diff reviewer. Trusting the executor's reported evidence is forbidden — verifiers MUST reproduce it themselves from the same worktree path the executor used.
+    - **Two-tier command lookup (NO auto-detection):** verifier obtains the QA command set from exactly two declared sources, in order — there is **no fallback to guessing tools from manifest files**.
+      1. **Tier 1 — plan validation set (task-specific):** every command listed under the approved plan's `validation` block (pre / mid / post).
+      2. **Tier 2 — project baseline (`project.json.qaCommands`):** the project's standing QA baseline declared in `<PROJECT_ROOT>/.project-docs/okstra/project.json` under the `qaCommands` key. Schema (each category is an array of `{ "label", "cmd", "language"? }` objects):
+         ```json
+         {
+           "qaCommands": {
+             "lint":      [{ "label": "cargo clippy", "cmd": "cargo clippy --all-targets -- -D warnings", "language": "rust" }],
+             "format":    [{ "label": "cargo fmt",    "cmd": "cargo fmt --check",                          "language": "rust" }],
+             "typecheck": [{ "label": "tsc",          "cmd": "pnpm exec tsc --noEmit",                     "language": "ts"   }],
+             "test":      [{ "label": "cargo test",   "cmd": "cargo test --workspace --locked",            "language": "rust" }]
+           }
+         }
+         ```
+         `language` is optional; when present, verifier MAY skip categories whose `language` is not represented in this run's diff (recorded as `qa-command skipped: <label> (language=<x> not in diff)`). Absent `language` means "always run".
+    - **Execution rule:** Tier 1 commands run verbatim first. Then every Tier 2 entry runs once. Each command runs in the worktree cwd, and is recorded in the worker result with its exact command line, exit code, and the tail of stdout/stderr. Substituting or paraphrasing a Tier 1 command is forbidden (see Forbidden actions).
+    - **Missing-tier handling:** if a tier is empty or absent, verifier records the single line `qa-command not configured: <category>` per missing category (`lint` / `format` / `typecheck` / `test`) in the worker result and proceeds — silent omission is a contract violation. Verifier MUST NOT auto-detect or invent a command in this case; the user/operator must declare it in `project.json.qaCommands` or in the plan.
+    - **`cmd` field deny-list (Tier 2 validation):** the runtime AND the verifier MUST reject any `cmd` containing tokens that imply mutation: `--fix`, `--write`, ` -w` (gofmt write), ` -u` (jest snapshot update), `--update-snapshots`, `--snapshot-update`, `--update-goldens`, `INSTA_UPDATE=` (with any value other than `no`), `cargo insta accept`, `npm install` (without `ci`), `cargo update`, `pip install -U`, `pnpm add`, `bun add`. Encountering a denied token aborts the verifier run with `contract-violated` and the operator is asked to re-declare the command in check-only form.
+    - **Discrepancy rule:** if the verifier's re-run result differs from what the executor reported (a passing test fails on re-run, a clean lint surfaces warnings, an exit code mismatches), the verifier MUST issue verdict `FAIL` with the divergence cited. `Claude lead` MUST NOT silently prefer the executor's evidence over a verifier's reproduced result during synthesis; if it overrides, it MUST cite a concrete reproduction-time reason (flaky-test commit-cited, environment delta documented) — handwaving is not allowed.
+    - **Read-only command log (per verifier):** the worker result MUST contain a `Read-only command log` block listing every command executed during the verifier run with its exact invocation and exit code, in execution order. No mutating command may appear in this block. This log is copied into the final report's verifier result section verbatim.
+    - **Verifier evidence is independent of executor evidence:** the final report keeps both — executor's `Validation evidence` AND each verifier's `Read-only command log` — so reviewers can compare them line-by-line.
   - Session isolation — not model-variant divergence — is the primary self-review safeguard: each verifier is a separate CLI invocation with its own context window, so reusing the same model variant for executor and same-provider verifier is acceptable. Different model variants (e.g. executor=opus / Claude verifier=sonnet) remain recommended when available.
   - Phase-specific model defaults override the shared defaults: `Claude verifier`=`sonnet`, `Codex verifier`=`gpt-5.5`, `Gemini verifier`=`auto` (only when present in the roster). The `Executor`'s model is taken from the provider-specific worker model corresponding to `--executor`: claude→`--claude-model` (default `sonnet`, override to `opus` recommended when this run's executor is claude), codex→`--codex-model` (default `gpt-5.5`), gemini→`--gemini-model` (default `auto`).
   - **All-verifier-failure policy**: if every verifier present in the resolved roster (`Claude verifier`, `Codex verifier`, and `Gemini verifier` when opted in) ends with a non-result terminal status (`timeout`, `error`, `not-run`) — i.e. zero independent verdicts were produced — the run MUST end with status `blocked` and route to a follow-up `error-analysis` run. `Claude lead` MUST NOT substitute its own verdict in place of the missing verifier outputs; synthesis requires at least one independent verifier's verdict. If one or more verifiers fail but at least one returns a verdict, the run proceeds with the surviving verdict(s) and the final report MUST explicitly notate which verifiers were unavailable, with the captured error / timeout evidence per failed verifier.
@@ -79,6 +100,14 @@
   - dispatching parallel sub-agents beyond the required worker roster
   - silent scope expansion — adding files, dependencies, or features that the approved plan did not list, without recording an `Out-of-plan edits` justification
   - leaving placeholders such as TBD / TODO / "implement later" / "handle edge cases" in committed code
+  - **(verifier-specific)** running lint / formatter auto-fix modes during a verifier's re-run — `eslint --fix`, `prettier --write`, `ruff check --fix`, `rustfmt` (writes by default; verifiers MUST use `cargo fmt --check` or `rustfmt --check`), `gofmt -w`, `black .` (use `black --check`), `isort .` (use `isort --check-only`), or any equivalent rewrite mode
+  - **(verifier-specific)** updating snapshots / golden fixtures during verification — `jest -u` / `--updateSnapshot`, `pytest --snapshot-update`, `INSTA_UPDATE=*` (any value other than `no`), `cargo insta accept`, `--update-goldens`, or any equivalent "make the test agree with current output" flag
+  - **(verifier-specific)** masking test failure with selection or shell tricks during re-run — `-k <expr>` / `--ignore` / `--deselect` to skip subsets, trailing `|| true`, `set +e` followed by a manually softened comparison, redirecting non-zero exit to success. The plan's listed test command MUST run in full
+  - **(verifier-specific)** substituting the plan's validation commands — verifier MUST run the plan's pre/mid/post validation commands verbatim; replacing them with paraphrased or "equivalent" commands is forbidden. Adding supplementary check-only lint/type-check is allowed and is logged separately in the verifier's Read-only command log
+  - **(verifier-specific)** mutating lockfiles or dependency manifests — `npm install <pkg>`, `npm install` (without lockfile freeze; use `npm ci`), `pnpm add`, `bun add`, `cargo add`, `cargo update`, `pip install -U`, or any dependency install that is not lockfile-frozen (`--locked` / `--frozen-lockfile` / `npm ci` / `pip install --require-hashes`)
+  - **(verifier-specific)** git state mutations — `git add`, `git commit`, `git stash`, `git checkout -- <file>`, `git restore`, `git reset`, `git rebase`, `git merge`, branch creation/deletion, tag creation. Only read-only git queries (`git status`, `git diff`, `git log`, `git show`, `git rev-parse`, `git blame`) are permitted for verifiers
+  - **(verifier-specific)** running integration / end-to-end tests that produce non-local side effects (DB writes against a non-local datastore, external API writes, docker compose against a non-isolated environment) unless that exact command is listed in the approved plan's validation set
+  - **(verifier-specific)** redirecting tool caches or output to paths outside the worktree — e.g. setting `CARGO_TARGET_DIR`, `PYTEST_CACHE_DIR`, `NODE_OPTIONS=--require=<external>`, or any env var that causes the verifier's command to write outside the worktree's normal build artifact paths
 - Required deliverable shape (final report, in addition to the standard sections):
   - **Plan link & approval evidence**: path to the approved `final-report.md` and the exact quoted approval marker
   - **Commit list**: each commit's SHA (or short SHA), message, and the plan step it satisfies
@@ -86,7 +115,14 @@
   - **Out-of-plan edits block**: every file edited that was not in the approved plan's file list, with rationale (empty block is acceptable and preferred)
   - **Validation evidence**: actual command output (stdout/stderr) for every `pre / mid / post` validation command from the plan. Truncated output is acceptable but the command line and exit code MUST be exact. No paraphrasing of test results.
   - **TDD evidence (when applicable)**: for steps that should be TDD-ordered, show the failing-test output BEFORE the implementation commit and the passing-test output AFTER, with commit SHAs framing the transition.
-  - **Verifier results**: a section per verifier present in the resolved roster (`Claude verifier`, `Codex verifier`, and `Gemini verifier` when opted in) containing their independent verdict (PASS / CONCERNS / FAIL), their cited diff snippets, and any fix recommendations they declined to apply. `Claude lead` synthesises a unified verdict but MUST preserve dissent — do not collapse opinions into one paragraph.
+  - **Verifier results**: a section per verifier present in the resolved roster (`Claude verifier`, `Codex verifier`, and `Gemini verifier` when opted in) containing:
+    - their independent verdict (PASS / CONCERNS / FAIL),
+    - cited diff snippets supporting the verdict,
+    - the verifier's `Read-only command log` (every command they ran with exact invocation and exit code, in execution order — copied verbatim from the worker result),
+    - **independent validation re-run results** — per plan-validation command: command line, exit code, and tail of output captured by the verifier (not the executor); any divergence from the executor's reported result MUST be called out as a `Discrepancy` line citing both sides,
+    - **style / lint / type-check results** — each check-only tool the verifier ran, its exit code, and the count of new findings attributable to lines this run introduced. When no tool is configured for a touched language, record the single line `no lint/style tool configured for <language>`,
+    - any fix recommendations the verifier declined to apply.
+    `Claude lead` synthesises a unified verdict but MUST preserve dissent — do not collapse opinions into one paragraph. If any verifier issued `FAIL` on a `Discrepancy` line, the synthesised verdict MUST be `FAIL` unless lead cites a concrete reproduction-time reason (committed flaky-test record, documented environment delta) for overriding.
   - **Rollback verification**: confirmation that the plan's rollback path is still valid after the changes. Strength of verification depends on the change category:
     - **Pure code changes** (no persisted state, no infra mutation): a reachable revert SHA is sufficient. Record the exact `git revert <SHA>` command that would undo the change, and confirm `git rev-parse <SHA>` resolves.
     - **Feature-flag-gated changes**: confirm the off-switch path was exercised in this run's validation evidence (i.e. one of the validation commands ran with the flag off and succeeded). A plan that ships a flag without exercising the off-path does NOT satisfy this requirement.

package/runtime/python/okstra_ctl/__init__.py

@@ -28,6 +28,14 @@ from .project_meta import (
     load_project_meta,
     upsert_project_meta,
 )
+from .qa_commands import (
+    ALLOWED_CATEGORIES,
+    QaCommandsError,
+    find_denied_tokens,
+    format_errors,
+    validate_qa_cmd,
+    validate_qa_commands,
+)
 from .index import (
     _replace_or_append_active_row,
     _replace_or_append_project_row,

package/runtime/python/okstra_ctl/qa_commands.py

@@ -0,0 +1,165 @@
+"""`project.json.qaCommands` 검증 헬퍼.
+
+implementation phase 의 verifier QA gate 는 plan 의 `validation` 셋(Tier 1) 과
+project-wide baseline 인 `qaCommands`(Tier 2) 를 함께 실행한다. Tier 2 는
+사용자가 `project.json` 에 직접 선언하며, mutation 을 유발하는 토큰이 포함된
+명령을 미리 차단해야 verifier 가 read-only 계약을 깨지 않는다.
+
+본 모듈은 두 가지 책임을 갖는다.
+
+1. `cmd` 문자열에서 mutation 유발 토큰을 검출 (`validate_qa_cmd`).
+2. `qaCommands` 블록 전체를 순회하며 모든 위반을 모은다 (`validate_qa_commands`).
+
+본 모듈은 런타임 검증에만 사용된다. 런타임 외 (verifier 가 실제 실행 단계에서
+self-enforce 하는 측면) 의 계약은 `prompts/profiles/implementation.md` 의
+"Two-tier command lookup" 단락에 명문화돼 있다.
+"""
+from __future__ import annotations
+
+import re
+from typing import Iterable
+
+# 카테고리 화이트리스트. 알 수 없는 카테고리는 오타 가능성이 높으므로 거부.
+ALLOWED_CATEGORIES: tuple[str, ...] = ("lint", "format", "typecheck", "test")
+
+# Mutation 을 유발하거나 lockfile 을 갱신하는 토큰. 각 토큰은 `cmd` 문자열을
+# 공백으로 단순 분해한 결과 또는 부분 일치 패턴(prefix/suffix sensitive) 로 검출한다.
+# 새로운 도구를 추가할 때마다 한 줄씩 늘려가는 것이 정상 — 정규식 흑마법 금지.
+_DENIED_LITERAL_TOKENS: tuple[str, ...] = (
+    "--fix",
+    "--write",
+    "-w",  # gofmt -w, prettier -w
+    "-u",  # jest -u
+    "--updateSnapshot",
+    "--update-snapshot",
+    "--snapshot-update",
+    "--update-goldens",
+    "--update-golden",
+)
+
+# 공백 분해로는 잡기 어려운 패턴 (substring 검사로 잡는다).
+_DENIED_SUBSTRINGS: tuple[str, ...] = (
+    "cargo insta accept",
+    "cargo update",
+    "pip install -U",
+    "pip install --upgrade",
+    "pnpm add",
+    "bun add",
+    "cargo add",
+)
+
+
+def _has_npm_install_without_ci(cmd: str) -> bool:
+    """`npm install` 은 lockfile mutation 위험이라 거부, `npm ci` 는 허용.
+
+    부분 문자열 매칭에서 `npm install` 이 잡히면, 그 뒤에 오는 토큰 시퀀스가
+    `npm ci` 의 변종이 아닌 한 항상 거부.
+    """
+    # 단순화: 정확히 `npm install` (또는 `npm i`) 가 등장하는지 검사. `ci` 는 별개
+    # 서브커맨드라 `npm ci` 는 이 정규식에 걸리지 않는다.
+    return re.search(r"\bnpm\s+(install|i)\b", cmd) is not None
+
+
+def _has_insta_update_set(cmd: str) -> bool:
+    """`INSTA_UPDATE=<value>` 에서 value 가 `no` 가 아닌 경우 거부."""
+    match = re.search(r"\bINSTA_UPDATE=([A-Za-z0-9_-]+)", cmd)
+    if match is None:
+        return False
+    return match.group(1).lower() != "no"
+
+
+def find_denied_tokens(cmd: str) -> list[str]:
+    """`cmd` 안에 포함된 모든 denied 토큰 목록을 반환. 비어 있으면 안전."""
+    if not isinstance(cmd, str):
+        return ["<not-a-string>"]
+    found: list[str] = []
+    tokens = cmd.split()
+    for tok in _DENIED_LITERAL_TOKENS:
+        if tok in tokens:
+            found.append(tok)
+    for sub in _DENIED_SUBSTRINGS:
+        if sub in cmd:
+            found.append(sub)
+    if _has_npm_install_without_ci(cmd):
+        found.append("npm install (use 'npm ci' instead)")
+    if _has_insta_update_set(cmd):
+        found.append("INSTA_UPDATE=<not-no>")
+    return found
+
+
+class QaCommandsError(ValueError):
+    """`qaCommands` 블록이 계약을 어긴 경우 발생."""
+
+
+def validate_qa_cmd(cmd: str, *, label: str = "<unnamed>", category: str = "<uncategorised>") -> None:
+    """단일 `cmd` 문자열을 검사. 위반이 있으면 `QaCommandsError`.
+
+    `label` / `category` 는 에러 메시지를 사람이 읽을 수 있게 하는 데만 쓰인다.
+    """
+    denied = find_denied_tokens(cmd)
+    if denied:
+        joined = ", ".join(denied)
+        raise QaCommandsError(
+            f"qaCommands.{category}[{label!r}] contains mutation token(s): {joined}. "
+            f"Re-declare in check-only form."
+        )
+
+
+def validate_qa_commands(qa: object) -> list[str]:
+    """`qaCommands` 블록 전체를 검증. 위반 메시지 리스트를 반환 (비면 안전).
+
+    런타임이 fail-fast 하려면 반환값이 비어있지 않을 때 `PrepareError` 로 승격.
+    여기서는 raise 하지 않고 메시지를 모아서 호출자가 일괄 보고할 수 있게 한다.
+    """
+    errors: list[str] = []
+    if qa is None:
+        return errors  # 옵션 필드 — 미선언은 합법.
+    if not isinstance(qa, dict):
+        return [f"qaCommands must be an object, got {type(qa).__name__}"]
+    for category, entries in qa.items():
+        if category not in ALLOWED_CATEGORIES:
+            errors.append(
+                f"qaCommands.{category}: unknown category "
+                f"(allowed: {', '.join(ALLOWED_CATEGORIES)})"
+            )
+            continue
+        if not isinstance(entries, list):
+            errors.append(
+                f"qaCommands.{category} must be an array, got {type(entries).__name__}"
+            )
+            continue
+        for idx, entry in enumerate(entries):
+            if not isinstance(entry, dict):
+                errors.append(
+                    f"qaCommands.{category}[{idx}] must be an object, got {type(entry).__name__}"
+                )
+                continue
+            label = entry.get("label")
+            cmd = entry.get("cmd")
+            if not isinstance(label, str) or not label.strip():
+                errors.append(
+                    f"qaCommands.{category}[{idx}].label must be a non-empty string"
+                )
+            if not isinstance(cmd, str) or not cmd.strip():
+                errors.append(
+                    f"qaCommands.{category}[{idx}].cmd must be a non-empty string"
+                )
+                continue
+            denied = find_denied_tokens(cmd)
+            if denied:
+                pretty_label = label if isinstance(label, str) else f"index {idx}"
+                errors.append(
+                    f"qaCommands.{category}[{pretty_label!r}] contains mutation token(s): "
+                    f"{', '.join(denied)}. Re-declare in check-only form."
+                )
+    return errors
+
+
+def format_errors(errors: Iterable[str]) -> str:
+    """`PrepareError` 등에 그대로 박을 수 있는 멀티라인 문자열."""
+    lines = list(errors)
+    if not lines:
+        return ""
+    head = "qaCommands validation failed:"
+    body = "\n".join(f"  - {line}" for line in lines)
+    return f"{head}\n{body}"

package/runtime/python/okstra_ctl/run.py

@@ -25,6 +25,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from okstra_project import upsert_project_json
+from .qa_commands import format_errors as _format_qa_errors, validate_qa_commands
 from .material import (
     build_analysis_material,
     related_tasks_bullets,
@@ -456,6 +457,22 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         # is preserved by the `: {exc}` suffix and the `raise ... from exc`.
         raise PrepareError(f"project.json upsert failed for {project_root}: {exc}") from exc
 
+    # `qaCommands` 는 implementation phase verifier 의 QA gate baseline 으로만
+    # 쓰이므로 검증도 implementation 진입 시에만 수행한다. 다른 task-type 에서는
+    # 잘못된 선언이 있어도 동작에 영향이 없어 fail-fast 할 이유가 없다.
+    if inp.task_type == "implementation":
+        project_json_path = Path(project_root) / ".project-docs" / "okstra" / "project.json"
+        if project_json_path.is_file():
+            try:
+                project_meta = json.loads(project_json_path.read_text())
+            except (OSError, json.JSONDecodeError) as exc:
+                raise PrepareError(
+                    f"project.json read failed at {project_json_path}: {exc}"
+                ) from exc
+            qa_errors = validate_qa_commands(project_meta.get("qaCommands"))
+            if qa_errors:
+                raise PrepareError(_format_qa_errors(qa_errors))
+
     # ---- workers resolution ----
     # release-handoff is intentionally single-lead (no worker dispatch, no
     # TeamCreate, no convergence). The profile has no `- Required workers:`

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

@@ -75,35 +75,23 @@ After Step 0 the following are guaranteed:
 
 ## Step 1: Resolve PROJECT_ROOT and projectId
 
+Prefer `$OKSTRA_PROJECT_INFO` from Step 0 — it already carries `{ok, projectRoot, projectJsonPath, projectId}`. Only re-resolve when that JSON's `ok` is false (cwd outside an okstra project):
+
 ```bash
-python3 - <<'PY'
-import sys, json
-from okstra_project import resolve_project_root, ResolverError
-try:
-    pr = resolve_project_root(explicit_root="", cwd=".")
-except ResolverError as e:
-    print(f"FAIL\t{e}"); raise SystemExit(0)
-print(f"OK\t{pr}")
-PY
+okstra check-project --cwd "$(pwd)"
 ```
 
-- If `OK`: read `<PROJECT_ROOT>/.project-docs/okstra/project.json` and extract `projectId`.
-- If `FAIL`: ask the user (`AskUserQuestion`, free text) for an absolute project-root path; rerun the resolver with `explicit_root=<their input>`.
+- If `ok: true`: read `projectRoot` and `projectId` from the JSON.
+- If `ok: false`: ask the user (`AskUserQuestion`, free text) for an absolute project-root path; rerun with `okstra check-project --cwd <their input>`.
 
 ## Step 2: Choose task — existing vs new
 
 ```bash
-python3 -c "
-import json, sys
-from pathlib import Path
-from okstra_project import list_project_tasks, read_latest_task
-pr = Path(sys.argv[1])
-tasks = list_project_tasks(pr)
-latest = read_latest_task(pr)
-print(json.dumps({'tasks': tasks, 'latest': latest}))
-" "$PROJECT_ROOT"
+okstra task-list --project "$PROJECT_ROOT"
 ```
 
+Output is JSON `{ok, projectRoot, tasks: [...], latest: {...}|null}`.
+
 Use `AskUserQuestion`:
 
 - **Label**: "Which task?"
@@ -151,21 +139,12 @@ silently inherits an unrelated branch you happen to be checked out on.
 First, decide whether to ask:
 
 ```bash
-python3 - <<PY
-import sys
-from pathlib import Path
-sys.path.insert(0, "$OKSTRA_PYTHONPATH".split(":")[0])
-from okstra_ctl import worktree_registry
-from okstra_ctl.ids import _safe_fs_segment
-entry = worktree_registry.lookup(
-    _safe_fs_segment("<project-id>"),
-    _safe_fs_segment("<task-group>"),
-    _safe_fs_segment("<task-id>"),
-)
-print("REUSE" if (entry and entry.status == "active") else "ASK")
-PY
+okstra worktree-lookup "<project-id>" "<task-group>" "<task-id>"
 ```
 
+Output JSON: `{ok: true, entry: null}` means no active worktree → **ASK**. A
+non-null `entry` with `status: "active"` → **REUSE**.
+
 - `REUSE` → the registered worktree is reused; set `base_ref=""` and skip the
   question (the registered base is authoritative).
 - `ASK` → this is the first phase for this task-key. Continue.
@@ -235,7 +214,7 @@ For prompts whose target worker is NOT in the resolved workers list (after overr
 
 ## Step 6.5: Confirm selections before rendering
 
-Before calling `prepare_task_bundle`, echo the resolved selections back to the user in a compact block so they can verify what will be passed. Show the **effective** values, not the raw input — i.e. when the user left a field blank, display `default` (and where known, the actual default such as `opus` / `sonnet`). Example for an `implementation` run:
+Before invoking `okstra render-bundle`, echo the resolved selections back to the user in a compact block so they can verify what will be passed. Show the **effective** values, not the raw input — i.e. when the user left a field blank, display `default` (and where known, the actual default such as `opus` / `sonnet`). Example for an `implementation` run:
 
 ```
 선택 확인:
@@ -255,50 +234,40 @@ Before calling `prepare_task_bundle`, echo the resolved selections back to the u
 
 Then `AskUserQuestion`: `"이대로 진행할까요?"` with options `Proceed` / `Edit`. On `Edit`, return to the relevant Step 6 sub-prompt.
 
-## Step 7: Call `prepare_task_bundle` directly
+## Step 7: Call `okstra render-bundle`
 
-This is the single line that materializes the entire task bundle. **Pass `render_only=True`** — the current claude session itself takes over as lead; we do not exec a new claude.
+This is the single command that materializes the entire task bundle. The
+subcommand auto-supplies `--workspace-root` (from `okstra paths --field
+workspace`) and forces `--render-only`, so the current claude session itself
+takes over as lead — no new claude is spawned.
 
 ```bash
-python3 - <<PY
-import os
-from pathlib import Path
-from okstra_ctl.run import PrepareInputs, prepare_task_bundle
-from okstra_ctl.path_resolve import resolve_user_file
-
-project_root = Path("<project-root>")
-brief_abs = resolve_user_file("<brief-path-from-user>", project_root)
-clarification_abs = resolve_user_file("<clarification-or-empty>", project_root) if "<clarification-or-empty>" else None
-
-out = prepare_task_bundle(PrepareInputs(
-    workspace_root=Path(os.environ["OKSTRA_WORKSPACE"]),
-    project_root=project_root,
-    project_id="<project-id>",
-    task_group="<task-group>",
-    task_id="<task-id>",
-    task_type="<task-type>",
-    brief_path=brief_abs,
-    directive="<directive or empty>",
-    workers_override="<comma-separated worker list, or empty for profile default; MUST be empty for implementation>",
-    lead_model="...", claude_model="...", codex_model="...",
-    gemini_model="...", report_writer_model="...",
-    related_tasks_raw="...",
-    executor="<claude|codex|gemini or empty>",  # implementation only; empty → default (claude / OKSTRA_DEFAULT_EXECUTOR)
-    base_ref="<chosen-ref-from-step-4.6 or empty when reusing existing worktree>",
-    approved_plan_path="<approved-plan-or-empty>",
-    clarification_response_path=str(clarification_abs) if clarification_abs else "",
-    render_only=True,
-))
-
-# Print key paths so the next step can read them.
-ctx = out.ctx
-print("TASK_ROOT", ctx["TASK_ROOT"])
-print("INSTRUCTION_SET_DIR", ctx["INSTRUCTION_SET_DIR"])
-print("LEAD_PROMPT", str(Path(ctx["INSTRUCTION_SET_DIR"]) / "claude-execution-prompt.md"))
-PY
+okstra render-bundle \
+  --project-root "<project-root>" \
+  --project-id "<project-id>" \
+  --task-group "<task-group>" \
+  --task-id "<task-id>" \
+  --task-type "<task-type>" \
+  --task-brief "<brief-path-from-user>" \
+  --executor "<claude|codex|gemini or empty for default>" \
+  --approved-plan "<approved-plan-or-empty>" \
+  --base-ref "<chosen-ref-from-step-4.6 or empty when reusing existing worktree>" \
+  --workers "<comma-separated worker list, or empty for profile default; MUST be empty for implementation>" \
+  --directive "<directive or empty>" \
+  --lead-model "..." --claude-model "..." --codex-model "..." \
+  --gemini-model "..." --report-writer-model "..." \
+  --related-tasks "..." \
+  --clarification-response "<clarification-or-empty>"
 ```
 
-The python function is mutex-protected (`~/.okstra/.locks/<task-key>.lock`), writes `run-context-*.json` + `run-inputs-*.json` + all manifests + discovery files, and registers the run in `~/.okstra/recent.jsonl` with status `prepared`.
+Stdout prints `okstra task root:`, `okstra instruction-set:`, and the full
+rendered lead-prompt text (because `--render-only` is on). Parse the labelled
+lines to get `TASK_ROOT`, `INSTRUCTION_SET_DIR`, and from there the
+`claude-execution-prompt.md` path used by Step 8.
+
+The python function underneath is mutex-protected (`~/.okstra/.locks/<task-key>.lock`),
+writes `run-context-*.json` + `run-inputs-*.json` + all manifests + discovery
+files, and registers the run in `~/.okstra/recent.jsonl` with status `prepared`.
 
 ## Step 8: Take over as Claude lead
 
@@ -327,7 +296,7 @@ Inform the user with one short line:
 |---|---|---|
 | `okstra runtime missing: ...` | First run on this machine, or stale install | `npx okstra@latest install` once, retry. |
 | `OKSTRA_PYTHONPATH unbound` / `ModuleNotFoundError: okstra_project` | Step 0 was skipped or env vars dropped | Re-run Step 0; never invoke python without exporting `PYTHONPATH=$OKSTRA_PYTHONPATH`. |
-| `task root not found for <key>` | catalog entry stale or task-key typo | Re-run Step 2; show available keys from `list_project_tasks` |
+| `task root not found for <key>` | catalog entry stale or task-key typo | Re-run Step 2 (`okstra task-list`) and show available keys |
 | `PROJECT_ROOT 를 해석할 수 없습니다` | cwd outside okstra project, no git toplevel | Ask user for absolute path |
 | `approved plan has no recognised user-approval marker` | `implementation` without proper approval | Ask user to add `APPROVED` to the plan, or pick a different task-type |
 | `task brief not found` | brief-path doesn't resolve relative to cwd or project-root | Re-ask Step 5 |

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

@@ -72,19 +72,12 @@ them from the env vars.
 ## Step 3: Resolve PROJECT_ROOT
 
 ```bash
-python3 - <<'PY'
-from okstra_project import resolve_project_root, ResolverError
-try:
-    pr = resolve_project_root(explicit_root="", cwd=".")
-    print(f"OK\t{pr}")
-except ResolverError as e:
-    print(f"FAIL\t{e}")
-PY
+okstra check-project --cwd "$(pwd)"
 ```
 
-- `OK` line → use that as `PROJECT_ROOT`.
-- `FAIL` line → ask the user (`AskUserQuestion`, free text) for an absolute
-  project root. Re-run with `explicit_root=<their answer>`.
+The JSON includes `projectRoot` on success. On failure (`ok: false`,
+`stage: "resolve"`) ask the user (`AskUserQuestion`, free text) for an
+absolute project root and rerun with `--cwd <their answer>`.
 
 ## Step 4: Inspect or create `project.json`
 
@@ -108,12 +101,7 @@ If the file does NOT exist, ask via `AskUserQuestion`:
 Then create the file:
 
 ```bash
-python3 - <<PY
-from pathlib import Path
-from okstra_project import upsert_project_json
-result = upsert_project_json(Path("$PROJECT_ROOT"), "$PROJECT_ID")
-print(result)
-PY
+okstra setup --yes --project-root "$PROJECT_ROOT" --project-id "$PROJECT_ID"
 ```
 
 ## Step 4.5 (optional): customise worktree sync dirs
@@ -142,6 +130,54 @@ field → built-in default. Only edit when defaults don't cover the
 project's working files (e.g. additional cache or local-config dirs
 that must follow the executor into the worktree).
 
+## Step 4.7 (optional but recommended): declare project QA commands
+
+`implementation`-phase verifiers run an independent QA gate over the
+executor's diff and need a project-wide baseline of check-only
+lint / format / typecheck / test commands. okstra does NOT auto-detect
+tooling from manifest files — declare the commands explicitly in
+`project.json` under `qaCommands`. Skipping this declaration is
+allowed but the verifier will then only run the plan's per-task
+`validation` set, with `qa-command not configured: <category>`
+recorded per missing category in the final report.
+
+Each category is an array of `{ "label", "cmd", "language"? }`
+objects. `language` is optional; when present the verifier MAY skip
+commands whose language is not represented in this run's diff.
+
+```json
+{
+  "projectId": "...",
+  "projectRoot": "...",
+  "qaCommands": {
+    "lint":      [{ "label": "cargo clippy", "cmd": "cargo clippy --all-targets -- -D warnings", "language": "rust" }],
+    "format":    [{ "label": "cargo fmt",    "cmd": "cargo fmt --check",                          "language": "rust" }],
+    "typecheck": [{ "label": "tsc",          "cmd": "pnpm exec tsc --noEmit",                     "language": "ts"   }],
+    "test":      [{ "label": "cargo test",   "cmd": "cargo test --workspace --locked",            "language": "rust" }]
+  }
+}
+```
+
+**`cmd` deny-list (mutation guard):** the verifier rejects any `cmd`
+containing tokens that imply mutation — declare commands in their
+check-only form only. Denied tokens include:
+
+- `--fix` (eslint, ruff), `--write` (prettier), ` -w` (gofmt),
+- ` -u` / `--updateSnapshot` / `--snapshot-update` / `--update-goldens`,
+- `INSTA_UPDATE=` with any value other than `no`,
+- `cargo insta accept`,
+- `npm install` (use `npm ci`), `cargo update`, `pip install -U`,
+- `pnpm add`, `bun add`, `cargo add`.
+
+Encountering a denied token aborts the verifier with status
+`contract-violated`; re-declare the command in check-only form to
+recover (e.g. swap `prettier --write` → `prettier --check`).
+
+The field is preserved across the runtime's auto-upserts of
+`project.json` — only `projectId`, `projectRoot`, `createdAt`,
+`updatedAt` are runtime-owned, so manual edits to `qaCommands`
+survive every subsequent `okstra setup` / `okstra run` invocation.
+
 ## Step 4.6 (automatic): project-local Claude settings symlink
 
 `okstra setup` (and `okstra run` on its first invocation per project)

package/runtime/templates/reports/settings.template.json

@@ -59,6 +59,7 @@
       "Bash(false)",
       "Bash(codex:*)",
       "Bash(codex exec:*)",
+      "Bash(okstra:*)",
       "Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)",
       "Bash(gemini:*)",
       "Bash($HOME/.okstra/bin/okstra-gemini-exec.sh:*)",

package/src/_python-helper.mjs

@@ -0,0 +1,42 @@
+import { spawn } from "node:child_process";
+import { resolvePaths } from "./paths.mjs";
+
+export async function runPythonSnippet({ script, args = [], extraEnv = {} }) {
+  const paths = await resolvePaths();
+  return new Promise((resolve) => {
+    const child = spawn("python3", ["-c", script, ...args], {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, PYTHONPATH: paths.pythonpath, ...extraEnv },
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (b) => (stdout += b.toString()));
+    child.stderr.on("data", (b) => (stderr += b.toString()));
+    child.on("error", (err) => resolve({ code: -1, stdout, stderr: err.message }));
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+export async function runPythonModule({ module, args = [], extraEnv = {}, stdio = "inherit-stdout" }) {
+  const paths = await resolvePaths();
+  return new Promise((resolve) => {
+    const child = spawn("python3", ["-m", module, ...args], {
+      stdio: stdio === "capture" ? ["ignore", "pipe", "pipe"] : ["ignore", "inherit", "inherit"],
+      env: { ...process.env, PYTHONPATH: paths.pythonpath, ...extraEnv },
+    });
+    let stdout = "";
+    let stderr = "";
+    if (stdio === "capture") {
+      child.stdout.on("data", (b) => (stdout += b.toString()));
+      child.stderr.on("data", (b) => (stderr += b.toString()));
+    }
+    child.on("error", (err) => resolve({ code: -1, stdout, stderr: err.message }));
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+export function emitJsonError({ stage, reason, extra = {} }) {
+  process.stdout.write(
+    JSON.stringify({ ok: false, stage, reason, ...extra }, null, 2) + "\n",
+  );
+}

package/src/plan-validate.mjs

@@ -0,0 +1,68 @@
+import { runPythonSnippet, emitJsonError } from "./_python-helper.mjs";
+
+const USAGE = `okstra plan-validate — verify an approved-plan file has a recognised approval marker
+
+Usage:
+  okstra plan-validate <plan-path>
+
+Output: JSON { ok: true, planPath } on success.
+On failure: { ok: false, reason } with non-zero exit code.
+
+Replaces the \`from okstra_ctl.run import _validate_approved_plan\` heredoc
+pattern. Use this in flows that need to confirm a plan was approved
+without invoking the full prepare_task_bundle pipeline.
+`;
+
+function parseArgs(args) {
+  const positional = args.filter((a) => !a.startsWith("--"));
+  const unknown = args.filter((a) => a.startsWith("--"));
+  if (unknown.length) throw new Error(`unknown argument '${unknown[0]}'`);
+  if (positional.length !== 1) {
+    throw new Error("expected exactly one positional argument: <plan-path>");
+  }
+  return { planPath: positional[0] };
+}
+
+const SCRIPT = `
+import json, sys
+from okstra_ctl.run import _validate_approved_plan, PrepareError
+
+path = sys.argv[1]
+try:
+    _validate_approved_plan(path)
+except PrepareError as e:
+    print(json.dumps({"ok": False, "stage": "validation", "reason": str(e), "planPath": path}))
+    sys.exit(1)
+
+print(json.dumps({"ok": True, "planPath": path}))
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  let opts;
+  try {
+    opts = parseArgs(args);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
+    return 2;
+  }
+
+  const result = await runPythonSnippet({
+    script: SCRIPT,
+    args: [opts.planPath],
+  });
+
+  if (result.code !== 0 && !result.stdout.trim()) {
+    emitJsonError({
+      stage: "python",
+      reason: `python invocation failed: ${result.stderr.trim() || "no output"}`,
+    });
+    return 1;
+  }
+
+  process.stdout.write(result.stdout);
+  return result.code === 0 ? 0 : result.code;
+}

package/src/render-bundle.mjs

@@ -0,0 +1,60 @@
+import { runPythonModule } from "./_python-helper.mjs";
+import { resolvePaths } from "./paths.mjs";
+
+const USAGE = `okstra render-bundle — preview the task bundle without launching claude
+
+This is a thin shim over \`python3 -m okstra_ctl.run\` that forces
+\`--render-only\`. Use it to preview where prepare_task_bundle() would
+materialize files (INSTRUCTION_SET_DIR, RUN_DIR, lead prompt path,
+final report template path, etc.) for a given task/phase, without
+actually creating the run-state or spawning the launcher.
+
+Usage:
+  okstra render-bundle --project-root <dir> --project-id <id> \\
+    --task-group <tg> --task-id <tid> --task-type <type> \\
+    --task-brief <path-or-rel> [--executor <name>] \\
+    [--approved-plan <path>] [--workers <list>] [--directive <text>] \\
+    [--lead-model <m>] [--claude-model <m>] [--codex-model <m>] \\
+    [--gemini-model <m>] [--report-writer-model <m>] \\
+    [--related-tasks <list>] [--base-ref <ref>] \\
+    [--clarification-response <path>] [--work-category <cat>]
+
+All flags pass through unchanged to \`python3 -m okstra_ctl.run\`. The
+shim auto-supplies \`--workspace-root\` (from \`okstra paths --field workspace\`)
+and \`--render-only\`, so callers do not need to set those.
+
+Replaces the long \`from okstra_ctl.run import PrepareInputs,
+prepare_task_bundle\` heredoc pattern.
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const paths = await resolvePaths();
+
+  // Callers should not pass these; we own them.
+  const forbidden = ["--workspace-root", "--render-only"];
+  for (const f of forbidden) {
+    if (args.includes(f)) {
+      process.stderr.write(
+        `error: ${f} is set by 'okstra render-bundle' itself — remove it from your args\n`,
+      );
+      return 2;
+    }
+  }
+
+  const finalArgs = [
+    "--workspace-root", paths.workspace,
+    "--render-only",
+    ...args,
+  ];
+
+  const result = await runPythonModule({
+    module: "okstra_ctl.run",
+    args: finalArgs,
+    stdio: "inherit-stdout",
+  });
+  return result.code ?? 0;
+}

package/src/task-list.mjs

@@ -0,0 +1,86 @@
+import { runPythonSnippet, emitJsonError } from "./_python-helper.mjs";
+
+const USAGE = `okstra task-list — list okstra tasks registered in this project
+
+Usage:
+  okstra task-list                   Resolve PROJECT_ROOT from cwd, list tasks
+  okstra task-list --cwd <dir>       Start resolution from <dir> instead of cwd
+  okstra task-list --project <dir>   Use <dir> directly as PROJECT_ROOT
+
+Output: JSON { ok, projectRoot, tasks: [...], latest: {...}|null }.
+
+Replaces the common pattern of loading okstra_project and calling
+list_project_tasks + read_latest_task from a python heredoc.
+`;
+
+function parseArgs(args) {
+  const opts = { cwd: process.cwd(), projectRoot: "" };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--cwd") {
+      opts.cwd = args[++i];
+      if (!opts.cwd) throw new Error("--cwd requires a path");
+    } else if (a === "--project") {
+      opts.projectRoot = args[++i];
+      if (!opts.projectRoot) throw new Error("--project requires a path");
+    } else {
+      throw new Error(`unknown argument '${a}'`);
+    }
+  }
+  return opts;
+}
+
+const SCRIPT = `
+import json, sys
+from pathlib import Path
+from okstra_project import (
+    list_project_tasks, read_latest_task,
+    resolve_project_root, ResolverError,
+)
+
+explicit = sys.argv[1]
+cwd = sys.argv[2]
+try:
+    pr = resolve_project_root(explicit_root=explicit, cwd=cwd)
+except ResolverError as e:
+    print(json.dumps({"ok": False, "stage": "resolve", "reason": str(e)}))
+    sys.exit(2)
+
+pr_path = Path(pr)
+print(json.dumps({
+    "ok": True,
+    "projectRoot": str(pr_path),
+    "tasks": list_project_tasks(pr_path),
+    "latest": read_latest_task(pr_path),
+}, default=str))
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  let opts;
+  try {
+    opts = parseArgs(args);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
+    return 2;
+  }
+
+  const result = await runPythonSnippet({
+    script: SCRIPT,
+    args: [opts.projectRoot, opts.cwd],
+  });
+
+  if (result.code !== 0 && !result.stdout.trim()) {
+    emitJsonError({
+      stage: "python",
+      reason: `python invocation failed: ${result.stderr.trim() || "no output"}`,
+    });
+    return 1;
+  }
+
+  process.stdout.write(result.stdout);
+  return result.code === 0 ? 0 : result.code;
+}

package/src/task-show.mjs

@@ -0,0 +1,120 @@
+import { runPythonSnippet, emitJsonError } from "./_python-helper.mjs";
+
+const USAGE = `okstra task-show — summarize a task's manifest and workflow state
+
+Usage:
+  okstra task-show <task-key>                  task-key is project-id:task-group:task-id
+  okstra task-show <task-key> --cwd <dir>      Resolve PROJECT_ROOT from <dir>
+  okstra task-show <task-key> --project <dir>  Use <dir> directly as PROJECT_ROOT
+
+Output: JSON with taskKey, taskType, taskRoot, brief path, workflow phases,
+artifacts, modelAssignments, latestRunPath. Replaces the
+\`cat task-manifest.json | python3 -c ...\` summarization pattern.
+`;
+
+function parseArgs(args) {
+  const opts = { cwd: process.cwd(), projectRoot: "", taskKey: "" };
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--cwd") {
+      opts.cwd = args[++i];
+      if (!opts.cwd) throw new Error("--cwd requires a path");
+    } else if (a === "--project") {
+      opts.projectRoot = args[++i];
+      if (!opts.projectRoot) throw new Error("--project requires a path");
+    } else if (a.startsWith("--")) {
+      throw new Error(`unknown argument '${a}'`);
+    } else {
+      positional.push(a);
+    }
+  }
+  if (positional.length !== 1) {
+    throw new Error("expected exactly one positional argument: <task-key>");
+  }
+  opts.taskKey = positional[0];
+  return opts;
+}
+
+const SCRIPT = `
+import json, sys
+from pathlib import Path
+from okstra_project import (
+    resolve_project_root, find_task_root, read_task_manifest,
+    ResolverError,
+)
+
+explicit = sys.argv[1]
+cwd = sys.argv[2]
+task_key = sys.argv[3]
+
+try:
+    pr = resolve_project_root(explicit_root=explicit, cwd=cwd)
+except ResolverError as e:
+    print(json.dumps({"ok": False, "stage": "resolve", "reason": str(e)}))
+    sys.exit(2)
+
+pr_path = Path(pr)
+task_root = find_task_root(pr_path, task_key)
+if task_root is None:
+    print(json.dumps({"ok": False, "stage": "task_root_missing", "reason": f"no task root for {task_key}"}))
+    sys.exit(1)
+
+manifest = read_task_manifest(task_root)
+if manifest is None:
+    print(json.dumps({"ok": False, "stage": "manifest_missing", "reason": f"task-manifest.json missing in {task_root}"}))
+    sys.exit(1)
+
+wf = manifest.get("workflow", {}) or {}
+out = {
+    "ok": True,
+    "projectRoot": str(pr_path),
+    "taskKey": manifest.get("taskKey"),
+    "taskType": manifest.get("taskType"),
+    "taskRoot": str(task_root),
+    "taskBriefPath": manifest.get("taskBriefPath"),
+    "workflow": {
+        "currentPhase": wf.get("currentPhase"),
+        "currentPhaseState": wf.get("currentPhaseState"),
+        "lastCompletedPhase": wf.get("lastCompletedPhase"),
+        "nextRecommendedPhase": wf.get("nextRecommendedPhase"),
+        "routingStatus": wf.get("routingStatus"),
+        "phaseStates": wf.get("phaseStates"),
+    },
+    "resultContract": manifest.get("resultContract"),
+    "artifacts": manifest.get("artifacts"),
+    "modelAssignments": manifest.get("modelAssignments"),
+    "latestRunPath": manifest.get("latestRunPath"),
+}
+print(json.dumps(out, ensure_ascii=False, default=str, indent=2))
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  let opts;
+  try {
+    opts = parseArgs(args);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
+    return 2;
+  }
+
+  const result = await runPythonSnippet({
+    script: SCRIPT,
+    args: [opts.projectRoot, opts.cwd, opts.taskKey],
+  });
+
+  if (result.code !== 0 && !result.stdout.trim()) {
+    emitJsonError({
+      stage: "python",
+      reason: `python invocation failed: ${result.stderr.trim() || "no output"}`,
+    });
+    return 1;
+  }
+
+  process.stdout.write(result.stdout);
+  return result.code === 0 ? 0 : result.code;
+}

package/src/worktree-lookup.mjs

@@ -0,0 +1,91 @@
+import { runPythonSnippet, emitJsonError } from "./_python-helper.mjs";
+
+const USAGE = `okstra worktree-lookup — look up registered worktree for a task-key
+
+Usage:
+  okstra worktree-lookup <project-id> <task-group> <task-id>
+
+The three identifiers are slugified by the runtime before lookup, so
+case/whitespace variants are tolerated.
+
+Output: JSON with the registry entry (worktreePath, branch, baseRef,
+status, lastPhase, createdAt). Emits {"ok": true, "entry": null} when
+the task-key has no active worktree.
+
+Replaces the okstra_ctl.worktree_registry.lookup() heredoc pattern.
+`;
+
+function parseArgs(args) {
+  const positional = args.filter((a) => !a.startsWith("--"));
+  const unknown = args.filter((a) => a.startsWith("--"));
+  if (unknown.length) throw new Error(`unknown argument '${unknown[0]}'`);
+  if (positional.length !== 3) {
+    throw new Error("expected exactly three positional arguments: <project-id> <task-group> <task-id>");
+  }
+  return { projectId: positional[0], taskGroup: positional[1], taskId: positional[2] };
+}
+
+const SCRIPT = `
+import json, sys
+from dataclasses import asdict
+from okstra_ctl import worktree_registry
+from okstra_ctl.ids import _safe_fs_segment
+
+pid, tg, tid = sys.argv[1], sys.argv[2], sys.argv[3]
+entry = worktree_registry.lookup(
+    _safe_fs_segment(pid),
+    _safe_fs_segment(tg),
+    _safe_fs_segment(tid),
+)
+if entry is None:
+    print(json.dumps({"ok": True, "entry": None}))
+else:
+    d = asdict(entry)
+    # rename for camelCase API symmetry
+    out = {
+        "ok": True,
+        "entry": {
+            "taskKey": d.get("task_key"),
+            "projectId": d.get("project_id"),
+            "taskGroup": d.get("task_group"),
+            "taskId": d.get("task_id"),
+            "worktreePath": d.get("worktree_path"),
+            "branch": d.get("branch"),
+            "baseRef": d.get("base_ref"),
+            "createdAt": d.get("created_at"),
+            "lastPhase": d.get("last_phase"),
+            "status": d.get("status"),
+        },
+    }
+    print(json.dumps(out, ensure_ascii=False, default=str, indent=2))
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  let opts;
+  try {
+    opts = parseArgs(args);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
+    return 2;
+  }
+
+  const result = await runPythonSnippet({
+    script: SCRIPT,
+    args: [opts.projectId, opts.taskGroup, opts.taskId],
+  });
+
+  if (result.code !== 0 && !result.stdout.trim()) {
+    emitJsonError({
+      stage: "python",
+      reason: `python invocation failed: ${result.stderr.trim() || "no output"}`,
+    });
+    return 1;
+  }
+
+  process.stdout.write(result.stdout);
+  return result.code === 0 ? 0 : result.code;
+}