okstra 0.68.0 → 0.69.0

package/bin/okstra

@@ -41,6 +41,19 @@ const COMMANDS = new Map([
     () => import("../src/render-bundle.mjs").then((m) => m.run),
   ],
   ["render-views", () => import("../src/render-views.mjs").then((m) => m.run)],
+  [
+    "render-final-report",
+    () => import("../src/render-final-report.mjs").then((m) => m.run),
+  ],
+  [
+    "inject-report-index",
+    () => import("../src/inject-report-index.mjs").then((m) => m.run),
+  ],
+  [
+    "spawn-followups",
+    () => import("../src/spawn-followups.mjs").then((m) => m.run),
+  ],
+  ["error-log", () => import("../src/error-log.mjs").then((m) => m.run)],
   ["wizard", () => import("../src/wizard.mjs").then((m) => m.run)],
   ["token-usage", () => import("../src/token-usage.mjs").then((m) => m.run)],
   ["memory", () => import("../src/memory.mjs").then((m) => m.run)],
@@ -89,6 +102,11 @@ Introspection commands (JSON output, used by skills to avoid python heredocs):
   token-usage            Collect token usage for a run (wraps the installed
                          okstra-token-usage.py so skills avoid emitting
                          python3 "$HOME/..." invocations).
+  render-views           Render slim AI + self-contained HTML views of a final report
+  render-final-report    Render the markdown sibling of a final-report data.json
+  inject-report-index    Add the top-of-report Index + scroll anchors to a report
+  spawn-followups        Create follow-up task bundles from a final report
+  error-log              Append run error events to the run error log
   memory                 Store and find user-home conversation memory under
                          ~/.okstra/memory-book.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.68.0",
+  "version": "0.69.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.68.0",
-  "builtAt": "2026-06-10T14:01:48.019Z",
+  "package": "0.69.0",
+  "builtAt": "2026-06-10T15:26:59.219Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -246,13 +246,13 @@ After each worker terminates, BEFORE classifying its terminal status, verify the
 After each worker terminates (any terminal status), if its errors sidecar exists, dump it to the run error log using the same resolved paths from the launch prompt:
 
 ```bash
-python3 scripts/okstra-error-log.py append-from-worker \
+okstra error-log append-from-worker \
   --sidecar <absolute-sidecar-path-from-launch-prompt> \
   --out <absolute-errors-log-path-from-launch-prompt> \
   --task-key <taskKey> --agent <agent> --agent-role <role> --model <model>
 ```
 
-For Codex/Gemini wrappers: if the CLI returns non-zero, times out, or hits a rate limit, immediately call `okstra-error-log.py append-observed --error-type cli-failure ...` with the captured exit code, duration, message, and stderr excerpt. The wrapper subagent does this from inside its own Bash tool — Lead does NOT need to re-record. Token usage is NOT available from Agent tool results in real time; it is collected post-hoc at the start of Phase 7.
+For Codex/Gemini wrappers: if the CLI returns non-zero, times out, or hits a rate limit, immediately call `okstra error-log append-observed --error-type cli-failure ...` with the captured exit code, duration, message, and stderr excerpt. The wrapper subagent does this from inside its own Bash tool — Lead does NOT need to re-record. Token usage is NOT available from Agent tool results in real time; it is collected post-hoc at the start of Phase 7.
 
 ## Phase 5.5: Convergence loop
 
@@ -271,7 +271,7 @@ When `task-manifest.json` does not set `convergence.maxRounds`, lead MUST resolv
 
 **Confirmed findings are pruned from the queue.** Findings classified as `full-consensus`, `partial-consensus`, or `worker-unique` MUST NOT appear in any subsequent round's reverify prompt for any worker. `contested` is a final classification assigned only when the last executed round completes and the queue is still non-empty — it is NEVER an intermediate queue label.
 
-If any re-verification batch yields a `verification-error` terminal status, or a worker result fails the contract, Lead MUST record one event per violation via `python3 scripts/okstra-error-log.py append-observed --error-type contract-violation --agent <offending-agent> ...`. Use `agent: "claude-lead"` only when the violation is detected internally without a specific worker.
+If any re-verification batch yields a `verification-error` terminal status, or a worker result fails the contract, Lead MUST record one event per violation via `okstra error-log append-observed --error-type contract-violation --agent <offending-agent> ...`. Use `agent: "claude-lead"` only when the violation is detected internally without a specific worker.
 
 If convergence is disabled, proceed directly to Phase 6 with the raw worker results.
 

package/runtime/agents/workers/claude-worker.md

@@ -104,7 +104,7 @@ If you find yourself thinking "let me double-check section 3" or "I should read
 
 ## Error reporting
 
-This agent is responsible for recording its own tool failures via `scripts/okstra-error-log.py`:
+This agent is responsible for recording its own tool failures via `okstra error-log`:
 
 **Path extraction (BLOCKING).** Before recording anything, extract the absolute sidecar path from the lead's dispatch prompt body:
 

package/runtime/agents/workers/codex-worker.md

@@ -103,7 +103,7 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
 
    c. **Result-file existence check (exit 0 only).** If `exit_code == 0` BUT no file exists at the extracted Result Path, the Codex CLI returned 0 without producing the analysis artifact. Observed failure mode: the CLI streams analysis prose on stdout, hits its token budget or a sandbox EPERM mid-`Write`, and exits 0 with the artifact never persisted. Forwarding the partial stdout silently degrades lead synthesis (the case that motivated this rule), so this path is required.
       1. Capture the final ~10 lines of the wrapper's live log for diagnostics — single Bash call: `tail -n 10 "${prompt_path%.md}.log"` (substitute the literal absolute prompt-history path; the wrapper writes the log next to it per the §"trace pane" comment in `okstra-codex-exec.sh`). Write the captured lines to a temp file (e.g. `<errors-sidecar-dir>/codex-result-missing-tail.txt`) so `--stderr-excerpt-file` can reference it.
-      2. Record a `cli-failure` event directly to the run-level error log via the exact `okstra-error-log.py append-observed` template in §"Error reporting" — substitute `--exit-code 0`, `--duration-ms <observed-ms>`, `--message "okstra-codex-exec.sh exited 0 but no result file at <abs-path>"`, and `--stderr-excerpt-file <temp-tail-path>`.
+      2. Record a `cli-failure` event directly to the run-level error log via the exact `okstra error-log append-observed` template in §"Error reporting" — substitute `--exit-code 0`, `--duration-ms <observed-ms>`, `--message "okstra-codex-exec.sh exited 0 but no result file at <abs-path>"`, and `--stderr-excerpt-file <temp-tail-path>`.
       3. Return `CODEX_RESULT_MISSING: codex exited 0 but result file absent at <abs-path>` instead of the raw stdout. The lead is responsible for deciding redispatch per `okstra-team-contract` "Lead Redispatch Policy on Result-Missing".
 
    d. **Normal return.** Otherwise (`exit_code == 0` AND result file exists), return the wrapper's accumulated stdout from `BashOutput`, prefixed by exactly one model-identity line copied verbatim from the `**Model:** Codex worker, <execution-value>` line in the lead prompt (per Worker Preamble → "Return message to the lead"):
@@ -175,7 +175,7 @@ This contract mirrors the `okstra-team-contract` skill's Worker Output Contract
 ## Error reporting
 
 The wrapper agent (this Codex worker subagent) is responsible for recording
-two kinds of errors via `scripts/okstra-error-log.py`:
+two kinds of errors via `okstra error-log`:
 
 **Path extraction (BLOCKING).** Before recording anything, extract the
 following two absolute paths verbatim from the lead's dispatch prompt body:
@@ -207,7 +207,7 @@ and the run-level error log staying empty.
    the dispatched `bash_id`:
 
    ```bash
-   python3 scripts/okstra-error-log.py append-observed \
+   okstra error-log append-observed \
      --out "<absolute-errors-log-path-from-lead-prompt>" \
      --task-key "<task-key>" \
      --phase "<phase>" \

package/runtime/agents/workers/gemini-worker.md

@@ -103,7 +103,7 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
 
    c. **Result-file existence check (exit 0 only).** If `exit_code == 0` BUT no file exists at the extracted Result Path, the Gemini CLI returned 0 without producing the analysis artifact. Observed failure mode: the CLI streams analysis prose on stdout, hits its token budget or a sandbox EPERM mid-`Write`, and exits 0 with the artifact never persisted. Forwarding the partial stdout silently degrades lead synthesis (the case that motivated this rule), so this path is required.
       1. Capture the final ~10 lines of the wrapper's live log for diagnostics — single Bash call: `tail -n 10 "${prompt_path%.md}.log"` (substitute the literal absolute prompt-history path; the wrapper writes the log next to it per the §"trace pane" comment in `okstra-gemini-exec.sh`). Write the captured lines to a temp file (e.g. `<errors-sidecar-dir>/gemini-result-missing-tail.txt`) so `--stderr-excerpt-file` can reference it.
-      2. Record a `cli-failure` event directly to the run-level error log via the exact `okstra-error-log.py append-observed` template in §"Error reporting" — substitute `--exit-code 0`, `--duration-ms <observed-ms>`, `--message "okstra-gemini-exec.sh exited 0 but no result file at <abs-path>"`, and `--stderr-excerpt-file <temp-tail-path>`.
+      2. Record a `cli-failure` event directly to the run-level error log via the exact `okstra error-log append-observed` template in §"Error reporting" — substitute `--exit-code 0`, `--duration-ms <observed-ms>`, `--message "okstra-gemini-exec.sh exited 0 but no result file at <abs-path>"`, and `--stderr-excerpt-file <temp-tail-path>`.
       3. Return `GEMINI_RESULT_MISSING: gemini exited 0 but result file absent at <abs-path>` instead of the raw stdout. The lead is responsible for deciding redispatch per `okstra-team-contract` "Lead Redispatch Policy on Result-Missing".
 
    d. **Normal return.** Otherwise (`exit_code == 0` AND result file exists), return the wrapper's accumulated stdout from `BashOutput`, prefixed by exactly one model-identity line copied verbatim from the `**Model:** Gemini worker, <execution-value>` line in the lead prompt (per Worker Preamble → "Return message to the lead"):
@@ -175,7 +175,7 @@ This contract mirrors the `okstra-team-contract` skill's Worker Output Contract
 ## Error reporting
 
 The wrapper agent (this Gemini worker subagent) is responsible for recording
-two kinds of errors via `scripts/okstra-error-log.py`:
+two kinds of errors via `okstra error-log`:
 
 **Path extraction (BLOCKING).** Before recording anything, extract the
 following two absolute paths verbatim from the lead's dispatch prompt body:
@@ -207,7 +207,7 @@ and the run-level error log staying empty.
    the dispatched `bash_id`:
 
    ```bash
-   python3 scripts/okstra-error-log.py append-observed \
+   okstra error-log append-observed \
      --out "<absolute-errors-log-path-from-lead-prompt>" \
      --task-key "<task-key>" \
      --phase "<phase>" \

package/runtime/agents/workers/report-writer-worker.md

@@ -101,9 +101,9 @@ Rules (the schema enforces most of these — they are listed here so you know *w
 - Cite file paths and line numbers in every `evidence.primary[].source` / `consensus[].evidence` cell.
 - Preserve every analysis worker's ticket tagging — every row's `ticketId` field carries the ticket key or the task-fallback. For single-ticket runs, set `ticketCoverage` to `{"singleTicket": "<ticket>"}`. For runs that do not require ticket tagging (`release-handoff`, `final-verification`), set `ticketCoverage` to `{"omit": true}`.
 - For `implementation-planning`, populate `implementationPlanning.requirementCoverage` with one row per concrete requirement from the brief / packet, using IDs `R-001`, `R-002`, ... in source order. `coveredBy` MUST name the specific Option Candidate plus Stage/Step that satisfies the requirement. Use `status: "covered"` only when the report's plan actually covers it; otherwise use `gap` or `blocked C-NNN` and ensure the corresponding `Clarification Items` row blocks approval. Do not collapse this into `ticketCoverage`; ticket coverage is not requirement coverage.
-- When the `Task Type` is `improvement-discovery`, populate `## 5.9 Improvement Candidates` with the 10-column schema enforced by `validators/validate-improvement-report.py`. Source the row IDs (`I-NNN`), lens whitelist, and Source workers patterns from `scripts/okstra_ctl/improvement_lenses.py` — do NOT introduce new lens names or worker prefixes. `improvement-discovery` is NOT in the data.json schema enum, so author its markdown directly (not via `okstra-render-final-report.py`). Immediately after writing the markdown, run (`Bash`): `python3 scripts/okstra-inject-report-index.py <markdown path> --report-language <en|ko>`. That adds the top-of-report Index plus `I-NNN` / `C-NNN` scroll anchors; the run validator fails the report when the Index anchor is absent.
+- When the `Task Type` is `improvement-discovery`, populate `## 5.9 Improvement Candidates` with the 10-column schema enforced by `validators/validate-improvement-report.py`. Source the row IDs (`I-NNN`), lens whitelist, and Source workers patterns from `scripts/okstra_ctl/improvement_lenses.py` — do NOT introduce new lens names or worker prefixes. `improvement-discovery` is NOT in the data.json schema enum, so author its markdown directly (not via `okstra-render-final-report.py`). Immediately after writing the markdown, run (`Bash`): `okstra inject-report-index <markdown path> --report-language <en|ko>`. That adds the top-of-report Index plus `I-NNN` / `C-NNN` scroll anchors; the run validator fails the report when the Index anchor is absent.
 
-Write the data.json with your `Write` tool against the absolute `Result Path`. Then invoke the renderer (`Bash`): `python3 scripts/okstra-render-final-report.py <data.json path>`. Confirm both files exist and respond with a short status line prefixed by your model identity, copied verbatim from the `**Model:** Report writer worker, <modelExecutionValue>` line in your dispatch prompt (per Worker Preamble → "Return message to the lead"):
+Write the data.json (and the audit sidecar `.md`) with your `Write` tool — that is the canonical authoring path, and okstra ships no hook that blocks `.md` writes (its only settings hook is the `SessionEnd` trace-cleanup; the coding-preflight hook emits reminders but never blocks). A Bash heredoc is acceptable ONLY when a specific `Write` call is genuinely rejected by the host environment, and it MUST produce byte-identical content — do not reach for it pre-emptively. Then invoke the renderer (`Bash`): `okstra render-final-report <data.json path>`. Confirm both files exist and respond with a short status line prefixed by your model identity, copied verbatim from the `**Model:** Report writer worker, <modelExecutionValue>` line in your dispatch prompt (per Worker Preamble → "Return message to the lead"):
 
 ```
 **Model:** Report writer worker, <modelExecutionValue>

package/runtime/prompts/launch.template.md

@@ -67,8 +67,8 @@ Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at
 - When dispatching any worker you MUST inject **two header lines** into the dispatch prompt body so the worker subagent can record errors without guessing paths:
   - `**Errors log path:** <absolute run-level errors log path>`
   - `**Errors sidecar path:** <absolute per-worker sidecar path matching the dispatched worker>`
-- These lines are the canonical contract — worker subagents extract them verbatim and pass them to `okstra-error-log.py append-observed --out ...` (run-level cli-failure / contract-violation events) and to their internal sidecar writes (worker-reported tool-failure events) respectively.
-- After each worker terminates, dump its sidecar into the run-level errors log via `python3 scripts/okstra-error-log.py append-from-worker --sidecar <sidecar-path> --out <run-errors-log-path> --task-key {{TASK_KEY}} --agent <worker-id> --agent-role worker --model <assigned-model-execution-value>` (per `okstra-team-contract` Worker Output Contract).
+- These lines are the canonical contract — worker subagents extract them verbatim and pass them to `okstra error-log append-observed --out ...` (run-level cli-failure / contract-violation events) and to their internal sidecar writes (worker-reported tool-failure events) respectively.
+- After each worker terminates, dump its sidecar into the run-level errors log via `okstra error-log append-from-worker --sidecar <sidecar-path> --out <run-errors-log-path> --task-key {{TASK_KEY}} --agent <worker-id> --agent-role worker --model <assigned-model-execution-value>` (per `okstra-team-contract` Worker Output Contract).
 
 ## Executor Worktree
 

package/runtime/prompts/profiles/_implementation-deliverable.md

@@ -44,6 +44,7 @@ are collected and convergence finished. Phase 1-5 do not need it.
    git diff <base>..HEAD | grep -E '^\+[^+].*\b(TBD|TODO|FIXME|XXX|implement later|handle edge cases|similar to|placeholder)\b' || echo 'clean'
    ```
    Only newly-added lines (those starting with `+` and not part of the `+++` header) are inspected. If output is anything other than `clean`, the run MUST either remove the placeholders before finalising or record an explicit justification per occurrence in the final report.
+7. **Stage-foreign literal scrub** — when the report-writer modelled this stage's `data.json` on another stage's report (a common shortcut for structural consistency), stage-specific literals get copied verbatim and silently misattribute this run. Confirm every branch name, commit SHA, stageKey, and stage number in the report resolves to **this** run's stage `<N>` — its worktree branch is `<prefix>-<task-id>-s<N>`, its stageKey `<task-id>-stage-<N>`. Sweep the report for any `-s<M>` / `stage-<M>` / `Stage <M>` where `M ≠ N` and for SHAs not in this run's `Commit list`; each hit is a copy-from-other-stage defect to correct before finalising.
 
 ## Lead post-stage persistence (BLOCKING — runs after the Executor emits `### Stage Carry Evidence`)
 

package/runtime/prompts/profiles/_implementation-executor.md

@@ -24,12 +24,13 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
   - **Language-agnostic principles that ALWAYS bind (the TDD loop below MUST satisfy them):** (1) no self-mocking of the SUT — stub/spy only injected collaborators, never the subject's own methods; (2) behavioral assertions on outcomes (return value, state, persisted rows, events, boundary calls) — never `toHaveBeenCalled*` on an internal helper as the only/primary assertion; (3) truthful names — a `get*` / `find*` that writes/inserts, or a name encoding the caller's use-case (`*ForInit`) or hiding a domain rule (`findValid*`), is a defect; (4) single-purpose functions ≤50 effective lines, plain-English readability.
   - **Graceful degradation (codex / gemini executor runtimes, or any runtime where the `~/.claude/skills/okstra-coding-preflight/` files are absent or unreadable):** do NOT skip the gate — apply the agnostic principles above plus the project's own `CLAUDE.md` / `CONTRIBUTING` / formatter+lint config, and record `coding-conventions: skill-unavailable → applied <project rules + agnostic principles>` in the final report. Never claim a skill read that did not happen.
   - **CLI executor transcription (BLOCKING when the executor provider is `codex` or `gemini`):** the executor CLI process does NOT share the lead's context — a gate that stays in lead memory never reaches it. The lead MUST copy this entire "Coding-conventions preflight" bullet tree (file-read instructions, project review rule packs, agnostic principles, graceful degradation) verbatim into the dispatched executor prompt body. Enforcement: the CLI wrapper agents refuse an implementation-Executor dispatch whose persisted prompt lacks the literal heading `Coding-conventions preflight`, returning `<SENTINEL_PREFIX>_PREFLIGHT_MISSING` (see `agents/workers/_cli-wrapper-template.md` → Prompt Composition).
+- **Non-interactive auto-execution (BLOCKING when the executor provider is `codex` or `gemini`).** A CLI executor runs head-less (`codex exec` / gemini equivalent) — there is no human at the keyboard. Skills loaded during the run (tdd, coding-preflight, and others) contain "get user approval", "state your plan to the user and wait", or "ask before proceeding" gates written for interactive sessions; in this run those gates are **already satisfied** by the upstream `implementation-planning` approval (the plan this stage executes was human-approved). The executor MUST NOT stop to request approval, MUST NOT end its turn after only producing a plan, and MUST carry the stage through end-to-end — RED → GREEN → refactor → per-step commits → `### Stage Carry Evidence`. The ONLY skill step to skip is the interactive user-approval prompt itself; every other skill rule (TDD discipline, conventions, real-IO isolation) still binds. The lead MUST transcribe this bullet verbatim into the dispatched CLI executor prompt (same reason as the preflight transcription rule above — the CLI process does not share lead context). Stopping early for approval in a head-less run is the observed empty-exit failure (exit 0, no diff): treat it as `contract-violated`.
 - **Mandatory TDD loop**: BEFORE the first `Edit` or `Write` call, the executor MUST apply a red-green-refactor loop for every code change in this run. This is required; skipping it is a `contract-violated` outcome. This governs HOW each step is executed (failing test first → minimal implementation → refactor); it does not override the approved plan's WHAT/file scope.
   - Order of operations per plan step: (1) write/extend the test that captures the step's acceptance criterion and confirm it fails for the right reason, (2) commit the failing test (`test(<scope>): ...`), (3) implement the minimum change to make it pass, (4) commit the implementation (`feat|fix(<scope>): ...`), (5) refactor without changing behaviour and commit separately if any cleanup is made (`refactor(<scope>): ...`). The failing-then-passing transition between steps (2) and (4) is the `TDD evidence` required by the final report.
   - Doc-only / config-only / pure-rename steps that have no observable runtime behaviour are exempt from the failing-test requirement, but the executor MUST cite the exemption per step in the final report (`TDD exemption: <reason>`).
   - When the touched area has no existing test harness, the executor MUST stand up the minimum harness needed to host one regression test for this run rather than skipping TDD entirely. Record the harness-bootstrap step as an `Out-of-plan edit` if it is not in the plan.
 - **DB / IO / SQL changes require real execution — mock-only is NOT validation evidence:** when this run's diff touches DB/IO/SQL (ORM / query-builder code — sequelize / typeorm / prisma / knex / raw SQL — `*.repository.*`, model/entity files, `migrations/**`, `*.sql`, or any changed query string), a mocked unit test cannot observe the SQL the query builder actually emits — a mocked suite once passed while `count({ col: 'FontFamily.fontFamily' })` threw `Unknown column` on the real DB. The executor MUST run the change against a real (or faithful-replica) datastore — the `db-test` validation step (plan `validation` db step, else `project.json.qaCommands.db-test`), targeting a **local / replica** DB — and cite its exact command + exit code in the final report's `Validation evidence`. If no real DB / `db-test` command is reachable, do NOT claim the change verified: label the DB portion `정적 분석상 …, 미검증(실행 안 함)` in the report, surface it in the routing recommendation, and never downplay the real run as "too heavy". `git push` stays forbidden (universal list); the unverified DB state is carried forward so `final-verification` cannot accept it and `release-handoff` cannot push.
-- **Real-IO test isolation (BLOCKING).** A test that exercises a **real** datastore, HTTP endpoint, external service, message queue, or filesystem — a live DB connection / DSN, a real `fetch` / `axios` / `http` request, an actual S3 / queue client, anything the project's normal CI test suite cannot run because that backend is absent — MUST be written under the task's qa directory `<task_root>/qa/` (the `TASK_QA_PATH` token; same directory that holds the Tier 3 conformance manifest). It MUST NOT be written into the project source test tree — `src/**`, `test/**`, `tests/**`, `**/__test__/**`, `**/__tests__/**`, `*.spec.*`, `*.test.*`, or anywhere the project's lint/test globs collect. Two reasons: (a) the project's CI / normal suite has no real DB or network, so a real-IO test placed in source silently breaks the pipeline; (b) it is an okstra verification artifact, and the artifact-home rule confines okstra outputs to `.okstra/`. **The dividing line is the IO, not the intent:** a unit test that stubs/spies only *injected collaborators* (mock — no real socket, no real DB handle) is a TDD red-green artifact and stays in source; the moment a test opens a real connection or makes a real network call it belongs in qa. A stage's real-IO requirement check is a Tier 3 conformance script under `<task_root>/qa/` (declared via the implementation-planning conformance entry) — never smuggle real IO into a `*.spec.*` in source to make it run "as a unit test". The `db-test` real-execution gate above is satisfied by the conformance/db-test path against the replica, NOT by adding a live-DB `*.spec.*` to the project suite.
+- **Real-IO test isolation (BLOCKING).** A test that exercises a **real** datastore, HTTP endpoint, external service, message queue, or filesystem — a live DB connection / DSN, a real `fetch` / `axios` / `http` request, an actual S3 / queue client, anything the project's normal CI test suite cannot run because that backend is absent — MUST be written under the task's qa directory `<task_root>/qa/` (the `TASK_QA_PATH` token; same directory that holds the Tier 3 conformance manifest). It MUST NOT be written into the project source test tree — `src/**`, `test/**`, `tests/**`, `**/__test__/**`, `**/__tests__/**`, `*.spec.*`, `*.test.*`, or anywhere the project's lint/test globs collect. Two reasons: (a) the project's CI / normal suite has no real DB or network, so a real-IO test placed in source silently breaks the pipeline; (b) it is an okstra verification artifact, and the artifact-home rule confines okstra outputs to `.okstra/`. **The dividing line is the IO, not the intent:** a unit test that stubs/spies only *injected collaborators* (mock — no real socket, no real DB handle) is a TDD red-green artifact and stays in source; the moment a test opens a real connection or makes a real network call it belongs in qa. A stage's real-IO requirement check is a Tier 3 conformance script under `<task_root>/qa/` (declared via the implementation-planning conformance entry) — never smuggle real IO into a `*.spec.*` in source to make it run "as a unit test". The `db-test` real-execution gate above is satisfied by the conformance/db-test path against the replica, NOT by adding a live-DB `*.spec.*` to the project suite. **These qa artifacts stay untracked — never commit them.** `.okstra/**` is gitignored (the artifact-home rule); conformance scripts and their results are *executed* and recorded in the carry sidecar / verifier result, never written into git history. A committed `.okstra/qa` file is a stage-branch defect that leaks okstra internals into the eventual PR (see the `git add` rules below).
 - re-read the approved plan end-to-end and parse the `## 5.5 Stage Map`. Read the **Stage** injected in the launch prompt (`Stage for this implementation run`): the single stage number this run owns. The runtime already selected and reserved this stage (one run = one stage) — do NOT recompute the start stage from `consumers.jsonl`.
   - load every `runs/<plan-key>/carry/stage-<i>.json` for `i ∈ depends-on(this stage)` and inject them into the executor's working context as "runtime carry-in". For a `depends-on (none)` stage, no sidecar load — task-brief only.
   - this stage's `depends-on` are all already `status:done`. Its file list, step order, Stage Validation commands, Stage Exit Contract, and rollback path are the authoritative scope.
@@ -58,6 +59,7 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
 - read-only inspection commands: `git status`, `git diff`, `git log`, `grep`, `rg`, `find`, `cat`, `ls`, file Read tools
 - build, lint, type-check, and test commands (`npm test`, `pytest`, `go build`, `cargo test`, `bash -n`, etc.)
 - **local git operations only**: `git add`, `git commit`. Prefer small commits keyed to plan steps.
+- **No okstra artifacts in commits (BLOCKING).** Never use `git add -f`. Before every `git commit`, run `git diff --cached --name-only` and confirm it contains zero `.okstra/` paths (and zero `.project-docs/` paths when the legacy symlink is present). `.okstra/**` is gitignored; force-staging it onto the stage branch is the one way these verification artifacts reach the upstream PR. Conformance/qa evidence belongs in the carry sidecar and verifier result — committing it is never correct, even when a step's instructions seem to ask for it.
 - **Commit message format (mandatory)**: every commit message MUST follow Conventional Commits — `<type>(<scope>): <subject>` for the first line, optional body separated by a blank line, optional footer. Constraints:
   - `<type>` MUST be one of: `feat` / `fix` / `perf` / `revert` / `deps` / `docs` / `refactor` / `build` / `ci` / `chore` / `test`. When the repo is `release-please`-managed, this aligns the commit with a configured changelog section.
   - `<scope>` SHOULD be the plan step identifier or the primary module touched (e.g. `feat(report-writer): ...`). Omit the parentheses only when no meaningful scope applies.

package/runtime/prompts/profiles/_implementation-verifier.md

@@ -96,6 +96,7 @@ Re-running commands proves the diff *builds and passes*; it does NOT prove the d
   - **Tautological delegation assertion:** a test asserts the SUT result equals a direct call to the same pure helper/collaborator that the SUT delegates to, instead of asserting an independent literal value or observable state.
   - **Untruthful name:** a read-named function (`get*` / `find*` / `load*`) that writes/inserts/mutates; an adapter or repository name encoding the caller's use-case (`*ForInit`) or hiding a domain rule (`findValid*` / `findActive*`).
   - **Hexagonal (only when the overlay is loaded):** business logic inside a port body; an adapter method that is not pure I/O (post-fetch JS filtering on domain state, domain-rule evaluation); a domain object declared outside the `domain/` boundary.
+  - **okstra artifact committed to the branch:** any path in the `git diff --name-only <base>...HEAD` enumeration that lives under `.okstra/` (or `.project-docs/` when the legacy symlink is present). `.okstra/**` is gitignored, so a committed okstra file means the executor force-staged it (`git add -f`) — leaking verification artifacts (qa scripts, conformance results) into the eventual PR. Cite the path; recommend `git rm --cached <path>` to untrack it while keeping the file on disk. Conformance/qa evidence belongs in the carry sidecar / verifier result, never in git history.
   - **Real-IO test in source tree:** a changed/added test under the project source test tree — `src/**`, `test/**`, `tests/**`, `**/__test__/**`, `**/__tests__/**`, `*.spec.*`, `*.test.*` — that opens a **real** DB connection / DSN, makes a real `fetch` / `axios` / `http` request, or otherwise hits real external IO without mocking the injected collaborator (a live handle, not a stub/spy). Real-IO tests MUST live under `<task_root>/qa/` per the executor's *Real-IO test isolation* rule — a live-IO test in source silently breaks the project's CI suite and violates the artifact-home rule. Cite the test file + the real-IO line; recommend moving it to `<task_root>/qa/` (or declaring it as a Tier 3 conformance script). Mock-only unit tests in source are NOT a hit.
 - **Advisory findings (recorded as recommendations; verdict MAY still PASS):** function >50 effective lines, a single body mixing read+write stages, weak readability, a missing-but-non-critical outcome assertion, newly orphaned private/public code that is safe to remove but not on a critical path, or weak-but-not-misleading names. These land in the verifier result as `should-fix` / `nit` recommendations, not as a `FAIL`.
 - **Output.** Every finding — blocking or advisory — is a structured item in the verifier's worker result (`path:line`, rule, severity, suggested fix) so it carries into Phase 5.5 convergence and the final report. A blocking hit sets the verifier verdict to `FAIL` with the rule cited, using the same verdict machinery as the Discrepancy rule above. `Claude lead` MUST NOT silently downgrade a cited blocking finding to advisory during synthesis; an override requires a concrete cited reason, exactly as for the Discrepancy rule.

package/runtime/prompts/profiles/improvement-discovery.md

@@ -33,7 +33,7 @@
   - `Consensus` cells in `## 5.9 Improvement Candidates` use the table enum exactly: `full`, `partial`, `contested`, `worker-unique`. Map convergence's `full-consensus` / `partial-consensus` labels to `full` / `partial` before writing the table.
   - `## 7. Final Verdict` Verdict Token ∈ {`candidates-ready`, `no-candidates`, `blocked`}; Direction `routing`; Next Step "사용자에게 후보 K개 선택 의뢰 (## 5.9 표 참조)"
   - `## 3. Recommended Next Steps` first entry summarises per-candidate routing and proposes new task-key names of the form `<task-group>/imp-<Cand-ID>`
-  - this report is authored free-form (improvement-discovery is not in the data.json schema enum); after the markdown is written, the report-writer runs `scripts/okstra-inject-report-index.py <report.md> --report-language <en|ko>` to add the top-of-report Index + `I-NNN`/`C-NNN` scroll anchors. The run validator fails the report when the Index anchor is missing.
+  - this report is authored free-form (improvement-discovery is not in the data.json schema enum); after the markdown is written, the report-writer runs `okstra inject-report-index <report.md> --report-language <en|ko>` to add the top-of-report Index + `I-NNN`/`C-NNN` scroll anchors. The run validator fails the report when the Index anchor is missing.
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
   - if scan-scope or priority-lenses cannot be made concrete during Phase 1.5, end the run with Verdict Token `blocked`, populate `## 1. Clarification Items` with `Blocks=next-phase` rows, and do not run worker dispatch
   - every clarification row carries a recommended answer + one-line rationale inside the `Expected form` cell

package/runtime/prompts/wizard/prompts.ko.json

@@ -168,7 +168,7 @@
       "echo_template": "approved-plan: {value}"
     },
     "approve_plan_confirm": {
-      "label": "이 플랜으로 implementation 을 진행할까요?\n  {path}\n· 예 — 진행합니다. 플랜이 아직 승인 전이면 지금 data.json(정본) + 리포트를 함께 approved 로 처리한 뒤 진행합니다. (markdown 만 손으로 고치면 일관성 검증에서 거부되므로 이 경로로 승인하세요.)\n· 아니오 — 진행하지 않습니다.",
+      "label": "이 플랜으로 진행할까요?\n  {path}\n· 예 — 진행합니다. 플랜이 아직 승인 전이면 지금 data.json(정본) + 리포트를 함께 approved 로 처리한 뒤 진행합니다. (markdown 만 손으로 고치면 일관성 검증에서 거부되므로 이 경로로 승인하세요.)\n· 아니오 — 진행하지 않습니다.",
       "echo_template": "approve-plan: {value}",
       "options": {
         "yes": "예 — 승인하고 진행",
@@ -179,16 +179,16 @@
         "approved": "approved-plan: {path} (승인·진행 확인됨)"
       },
       "errors": {
-        "declined": "진행을 선택하지 않으면 implementation 을 시작할 수 없습니다. 진행(예)하거나 위저드를 종료하세요.",
+        "declined": "진행을 선택하지 않으면 다음 단계로 넘어갈 수 없습니다. 진행(예)하거나 위저드를 종료하세요.",
         "still_unapproved": "approve-plan: 승인 처리 후에도 승인 상태가 아닙니다 (data.json/markdown 불일치): {path}"
       }
     },
     "stage_pick": {
       "label": "stage 범위를 선택하세요. auto 는 전체 task(모든 stage)를, 특정 번호는 해당 stage 만 대상으로 합니다.",
+      "label_final_verification": "검증할 implementation stage 를 선택하세요.",
       "echo_template": "stage: {value}",
       "options": {
-        "auto": "auto (다음 미완료 stage)",
-        "auto_final_verification": "auto (전체 task — 모든 stage 머지 후 한 번)"
+        "auto": "auto (다음 미완료 stage)"
       }
     },
     "directive_pick": {

package/runtime/python/okstra_ctl/conformance.py

@@ -258,6 +258,23 @@ def apply_qa_waiver(manifest: object, stage_key: str, reason: str, *, at: str,
     return False
 
 
+def clear_qa_waiver(manifest: object, stage_key: str) -> bool:
+    """stage_key entry 의 `waiver` 를 제거한다(in place). 제거했으면 True.
+
+    한 stage 의 새 run 이 시작될 때, 그 stage entry 에 남아 있던 이전 run 의
+    waiver(예: all-gate run 이 미래 stage 를 미리 waive 한 것)는 stale 다 —
+    그대로 두면 verifier 가 conformance 를 skip 해 마스킹된다. 이 run 이 실제로
+    검증하도록 제거한다. 사용자가 이번 run 에 같은 stage 를 명시 waive 한
+    경우(--qa-waiver)는 호출 측에서 걸러 보존한다."""
+    entries = manifest.get("entries") if isinstance(manifest, dict) else None
+    if not isinstance(entries, list):
+        return False
+    for entry in entries:
+        if isinstance(entry, dict) and entry.get("stageKey") == stage_key:
+            return entry.pop("waiver", None) is not None
+    return False
+
+
 def manifest_required_surfaces(manifest: object) -> set[str]:
     """매니페스트 전 entry 의 `requires` 합집합 — 선언된 surface 집합."""
     entries = manifest.get("entries") if isinstance(manifest, dict) else None

package/runtime/python/okstra_ctl/run.py

@@ -81,7 +81,11 @@ from .workers import (
 )
 from .workflow import compute_workflow_state
 from .locks import worktree_provision_mutex
-from .worktree import provision_task_worktree
+from .worktree import (
+    WorktreeProvision,
+    okstra_clean_gate_excludes,
+    provision_task_worktree,
+)
 
 # Frontmatter approval-flag matcher.
 #
@@ -1151,6 +1155,46 @@ def _apply_qa_waiver_if_requested(inp: "PrepareInputs", project_root: Path) -> N
     manifest_path.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n")
 
 
+def _clear_stale_stage_waiver(inp: "PrepareInputs", project_root: Path, stage: int) -> None:
+    """A fresh `implementation` run of stage N must not inherit a waiver left on
+    its conformance entry by an earlier run (e.g. an all-gate run that pre-waived
+    future stages, or an abandoned attempt). A stale waiver makes the verifier
+    skip Tier 3 conformance and silently mask this stage, so clear it — UNLESS
+    the user re-waived this exact stage for this run via `--qa-waiver` (already
+    applied upstream in `_apply_qa_waiver_if_requested`)."""
+    from .conformance import clear_qa_waiver, parse_qa_waiver_arg
+    from .paths import task_dir
+    manifest_path = (
+        task_dir(project_root, inp.task_group, inp.task_id)
+        / "qa" / "conformance-manifest.json"
+    )
+    if not manifest_path.is_file():
+        return
+    manifest = json.loads(manifest_path.read_text())
+    entries = manifest.get("entries") if isinstance(manifest, dict) else None
+    if not isinstance(entries, list):
+        return
+    # The manifest stageKey is `<task-id>-stage-<N>` authored by planning; match
+    # on the `-stage-<N>` suffix so we do not assume the task-id's exact form.
+    suffix = f"-stage-{stage}"
+    stage_key = next(
+        (e["stageKey"] for e in entries
+         if isinstance(e, dict) and isinstance(e.get("stageKey"), str)
+         and e["stageKey"].endswith(suffix)),
+        None,
+    )
+    if stage_key is None:
+        return
+    if inp.qa_waiver:
+        parsed = parse_qa_waiver_arg(inp.qa_waiver)
+        if parsed is not None and parsed[0] == stage_key:
+            return  # user intentionally waived this stage for this run
+    if clear_qa_waiver(manifest, stage_key):
+        manifest_path.write_text(
+            json.dumps(manifest, indent=2, ensure_ascii=False) + "\n"
+        )
+
+
 def _register_and_check_project(project_root: Path, inp: PrepareInputs) -> None:
     """project.json self-registration + (implementation 한정) qaCommands gate 검증."""
     from okstra_project import ResolverError
@@ -1493,10 +1537,22 @@ def _is_ancestor(cwd, commit, head) -> bool:
 
 
 def _is_dirty_excluding_okstra(cwd) -> bool:
-    out = _git_out(cwd, "status", "--short", "--", ".", ":(exclude).okstra")
+    excludes = [f":(exclude){p}" for p in okstra_clean_gate_excludes(Path(cwd))]
+    out = _git_out(cwd, "status", "--short", "--", ".", *excludes)
     return bool(out.strip())
 
 
+def _single_stage_final_verification_worktree(inp: "PrepareInputs") -> WorktreeProvision:
+    """Placeholder until the selected stage registry row is resolved."""
+    return WorktreeProvision(
+        status="deferred-final-verification",
+        note=(
+            "final-verification single-stage uses the selected implementation "
+            "stage worktree from the registry"
+        ),
+    )
+
+
 def _reserve_final_verification_target(
     inp: "PrepareInputs", ctx: dict, ctx_stage_map: list,
 ) -> None:
@@ -1519,6 +1575,7 @@ def _reserve_final_verification_target(
         row = _reg.get_stage_row(inp.project_id, inp.task_group, inp.task_id, n)
         wt_path = (row or {}).get("worktree_path", "")
         stage_base = (row or {}).get("base_ref", "")
+        stage_branch = (row or {}).get("branch", "")
         head = _git_out(wt_path, "rev-parse", "HEAD") if wt_path else ""
         target = _resolve_single_stage_target(
             requested_stage=inp.stage, done_rows=done_rows,
@@ -1527,6 +1584,12 @@ def _reserve_final_verification_target(
             stage_dirty=_is_dirty_excluding_okstra(wt_path) if wt_path else False,
         )
         ctx["EXECUTOR_WORKTREE_PATH"] = wt_path
+        ctx["EXECUTOR_WORKTREE_BRANCH"] = stage_branch
+        ctx["EXECUTOR_WORKTREE_BASE_REF"] = stage_base
+        ctx["EXECUTOR_WORKTREE_STATUS"] = "reused-stage"
+        ctx["EXECUTOR_WORKTREE_NOTE"] = (
+            f"final-verification uses implementation stage {n} worktree"
+        )
     else:
         wt_path = ctx["EXECUTOR_WORKTREE_PATH"]
         anchor = _reg.get_implementation_base(
@@ -1803,21 +1866,24 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     with worktree_provision_mutex(
         okstra_home(), inp.project_id, task_group_segment, task_id_segment,
     ):
-        try:
-            worktree = provision_task_worktree(
-                task_type=inp.task_type,
-                project_root=project_root,
-                project_id=inp.project_id,
-                task_group_segment=task_group_segment,
-                task_id_segment=task_id_segment,
-                work_category=inp.work_category,
-                base_ref=inp.base_ref,
-                require_base_ref=True,
-            )
-        except RuntimeError as exc:
-            raise PrepareError(
-                f"task worktree provisioning failed: {exc}"
-            ) from exc
+        if inp.task_type == "final-verification" and inp.stage and inp.stage != "auto":
+            worktree = _single_stage_final_verification_worktree(inp)
+        else:
+            try:
+                worktree = provision_task_worktree(
+                    task_type=inp.task_type,
+                    project_root=project_root,
+                    project_id=inp.project_id,
+                    task_group_segment=task_group_segment,
+                    task_id_segment=task_id_segment,
+                    work_category=inp.work_category,
+                    base_ref=inp.base_ref,
+                    require_base_ref=True,
+                )
+            except RuntimeError as exc:
+                raise PrepareError(
+                    f"task worktree provisioning failed: {exc}"
+                ) from exc
 
         # ---- implementation stage selection (path-independent) ----
         # Resolve + provision the stage BEFORE run-path compute so RUN_DIR
@@ -1832,6 +1898,10 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
                 task_key, worktree.status,
             )
             stage_arg = impl_stage_selection.stage
+            # Drop any stale waiver on this stage so the run actually verifies
+            # conformance (kept inside the per-task-key mutex so concurrent
+            # same-task runs don't race the manifest write).
+            _clear_stale_stage_waiver(inp, project_root, impl_stage_selection.stage)
         else:
             impl_stage_selection = None
             stage_arg = None

package/runtime/python/okstra_ctl/wizard.py

@@ -763,6 +763,22 @@ def _resolve_reuse_worktree(state: WizardState) -> bool:
     return bool(entry and entry.status == "active")
 
 
+def _base_ref_required(state: WizardState) -> bool:
+    return state.task_type != "final-verification" and state.reuse_worktree is False
+
+
+def _base_ref_ready(state: WizardState) -> bool:
+    return not _base_ref_required(state) or S_BASE_REF_PICK in state.answered
+
+
+def _branch_confirm_required(state: WizardState) -> bool:
+    return state.task_type != "final-verification"
+
+
+def _stage_auto_allowed(state: WizardState) -> bool:
+    return state.task_type == "implementation"
+
+
 def _existing_task_brief(project_root: Path, task_key: str) -> str:
     """Read taskBriefPath from manifest for an existing task. Empty if none."""
     root = find_task_root(project_root, task_key)
@@ -1495,12 +1511,14 @@ def _build_stage_pick(state: WizardState) -> Prompt:
         stages, _errs = mod._parse_stage_map(plan_text)
     finally:
         _sys.modules.pop("_ip_stage_v_wizard", None)
-    auto_label = (
-        t["options"].get("auto_final_verification", t["options"]["auto"])
+    label = (
+        t.get("label_final_verification", t["label"])
         if state.task_type == "final-verification"
-        else t["options"]["auto"]
+        else t["label"]
     )
-    options = [_opt("auto", auto_label)]
+    options = []
+    if _stage_auto_allowed(state):
+        options.append(_opt("auto", t["options"]["auto"]))
     for s in stages:
         depends = ",".join(map(str, s.depends_on)) or "(none)"
         options.append(_opt(
@@ -1509,7 +1527,7 @@ def _build_stage_pick(state: WizardState) -> Prompt:
         ))
     return Prompt(
         step=S_STAGE_PICK, kind="pick",
-        label=t["label"],
+        label=label,
         options=options,
         echo_template=t["echo_template"],
     )
@@ -1518,7 +1536,12 @@ def _build_stage_pick(state: WizardState) -> Prompt:
 def _submit_stage_pick(state: WizardState, answer: str) -> Optional[str]:
     if not answer:
         raise WizardError("value required")
-    if answer != "auto":
+    if answer == "auto":
+        if not _stage_auto_allowed(state):
+            raise WizardError(
+                "final-verification requires an explicit stage number"
+            )
+    else:
         try:
             int(answer)
         except ValueError:
@@ -2352,7 +2375,7 @@ STEPS: list[Step] = [
          owns=("keep_existing_brief",)),
     Step(S_BASE_REF_PICK,
          applies=lambda s: (S_TASK_TYPE in s.answered
-                            and s.reuse_worktree is False
+                            and _base_ref_required(s)
                             and S_BASE_REF_PICK not in s.answered
                             and bool(s.brief_path)),
          build=_build_base_ref_pick, submit=_submit_base_ref_pick,
@@ -2367,8 +2390,7 @@ STEPS: list[Step] = [
                             and not s.approved_plan_pending_text
                             and S_APPROVED_PLAN_PICK not in s.answered
                             and bool(s.brief_path)
-                            and (s.reuse_worktree is True
-                                 or S_BASE_REF_PICK in s.answered)
+                            and _base_ref_ready(s)
                             and not s.base_ref_pending_text
                             and _latest_implementation_planning_report(s) is not None),
          build=_build_approved_plan_pick, submit=_submit_approved_plan_pick,
@@ -2377,8 +2399,7 @@ STEPS: list[Step] = [
          applies=lambda s: (s.task_type in _STAGE_SCOPED_TASK_TYPES
                             and not s.approved_plan_path
                             and bool(s.brief_path)
-                            and (s.reuse_worktree is True
-                                 or S_BASE_REF_PICK in s.answered)
+                            and _base_ref_ready(s)
                             and not s.base_ref_pending_text
                             and (s.approved_plan_pending_text
                                  or _latest_implementation_planning_report(s) is None)),
@@ -2548,11 +2569,16 @@ STEPS: list[Step] = [
          build=_build_pr_template_scope, submit=_submit_pr_template_scope,
          owns=("pr_template_scope",)),
     Step(S_BRANCH_CONFIRM,
-         applies=lambda s: _ready_for_confirm(s) and s.branch_confirmed is None,
+         applies=lambda s: (_ready_for_confirm(s)
+                            and _branch_confirm_required(s)
+                            and s.branch_confirmed is None),
          build=_build_branch_confirm, submit=_submit_branch_confirm,
          owns=("branch_confirmed",)),
     Step(S_CONFIRM,
-         applies=lambda s: _ready_for_confirm(s) and s.branch_confirmed is True and s.confirmed is None,
+         applies=lambda s: (_ready_for_confirm(s)
+                            and (not _branch_confirm_required(s)
+                                 or s.branch_confirmed is True)
+                            and s.confirmed is None),
          build=_build_confirm, submit=_submit_confirm,
          owns=("confirmed", "edit_target")),
     Step(S_EDIT_TARGET,
@@ -2570,7 +2596,7 @@ def _identity_ready(s: WizardState) -> bool:
         return False
     if not s.brief_path:
         return False
-    if s.reuse_worktree is False and S_BASE_REF_PICK not in s.answered:
+    if _base_ref_required(s) and S_BASE_REF_PICK not in s.answered:
         return False
     if s.base_ref_pending_text:
         return False
@@ -2763,7 +2789,21 @@ def render_args(state: WizardState) -> dict[str, str]:
     workers = state.workers_override.strip()
     if state.task_type == "implementation":
         workers = ""  # profile-default roster is mandatory for impl
-    base_ref = "" if state.reuse_worktree else state.base_ref
+    base_ref = (
+        ""
+        if state.reuse_worktree or state.task_type == "final-verification"
+        else state.base_ref
+    )
+    if state.task_type == "implementation":
+        stage = state.selected_stage or "auto"
+    elif state.task_type == "final-verification":
+        if not state.selected_stage or state.selected_stage == "auto":
+            raise WizardError(
+                "final-verification requires an explicit stage number"
+            )
+        stage = state.selected_stage
+    else:
+        stage = ""
     pr_template = (
         state.pr_template_path
         if state.task_type == "release-handoff"
@@ -2779,7 +2819,7 @@ def render_args(state: WizardState) -> dict[str, str]:
         "executor": state.executor,
         "critic": state.critic,
         "approved-plan": state.approved_plan_path,
-        "stage": (state.selected_stage or "auto") if state.task_type in _STAGE_SCOPED_TASK_TYPES else "",
+        "stage": stage,
         "base-ref": base_ref,
         "workers": workers,
         "directive": state.directive,
@@ -2801,7 +2841,9 @@ def confirmation_block(state: WizardState) -> str:
     lines.append(f"  task-type     : {state.task_type}")
     lines.append(f"  task-key      : {state.task_group}/{state.task_id}")
     lines.append(f"  brief         : {state.brief_path or '(none)'}")
-    if state.reuse_worktree:
+    if state.task_type == "final-verification":
+        lines.append("  base-ref      : (selected stage worktree)")
+    elif state.reuse_worktree:
         lines.append("  base-ref      : (reusing existing worktree)")
     else:
         lines.append(f"  base-ref      : {state.base_ref}")
@@ -2829,7 +2871,11 @@ def confirmation_block(state: WizardState) -> str:
         lines.append(f"  critic        : {state.critic or '(off)'}")
     if state.task_type in _STAGE_SCOPED_TASK_TYPES:
         lines.append(f"  approved-plan : {state.approved_plan_path}")
-        lines.append(f"  stage         : {state.selected_stage or 'auto'}")
+        stage = (
+            state.selected_stage
+            or ("auto" if state.task_type == "implementation" else "(not selected)")
+        )
+        lines.append(f"  stage         : {stage}")
     if state.clarification_response_path:
         lines.append(f"  clarification : {state.clarification_response_path}")
     if state.task_type == "release-handoff" and state.pr_template_path:

package/runtime/python/okstra_ctl/worktree.py

@@ -373,6 +373,24 @@ def _resolve_snapshot_files(project_root: Optional[Path] = None) -> tuple[str, .
     )
 
 
+def okstra_clean_gate_excludes(project_root: Optional[Path] = None) -> tuple[str, ...]:
+    """Project-relative paths okstra owns and source clean gates should ignore."""
+    out: list[str] = []
+    seen: set[str] = set()
+    for rel in (
+        ".okstra",
+        *_resolve_sync_dirs(project_root),
+        *_resolve_sync_files(project_root),
+        *_resolve_snapshot_files(project_root),
+    ):
+        cleaned = rel.strip().removeprefix("./").rstrip("/")
+        if not cleaned or cleaned == "." or cleaned in seen:
+            continue
+        seen.add(cleaned)
+        out.append(cleaned)
+    return tuple(out)
+
+
 def _link_sync_dirs(source_root: Path, worktree_path: Path) -> list[str]:
     """Symlink each configured dir from `source_root` (the MAIN
     worktree) into the new worktree.

package/runtime/python/okstra_token_usage/collect.py

@@ -183,6 +183,7 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
     # silently (observed in dev-9692 error-analysis: claude/codex workers
     # dispatched without `name` → both unavailable, report-writer named → fine).
     unattributed_sessions: list[str] = []
+    unattributed_totals: list[dict] = []
     for sid, path in claude_sessions.items():
         if sid == lead_sid:
             lead_path = path
@@ -194,6 +195,7 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
             by_agent.setdefault(agent, []).append((sid, path, totals))
         else:
             unattributed_sessions.append(sid)
+            unattributed_totals.append(totals)
 
     # Lead.
     if lead_path is not None:
@@ -273,6 +275,26 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
                     block["cliNote"] = f"{agent} CLI session found but no usage recorded (likely errored before completion)"
         worker["usage"] = block
 
+    # Fold team-tagged worker sessions that carry no agentName into the worker
+    # pool. They cannot be mapped to a specific workerId (so each named worker
+    # row above stays `unavailable`), but the tokens are real team-worker spend —
+    # most often an in-process teammate whose work is commingled in a team-tagged
+    # session the harness never tagged with `name`. Without this, the run-level
+    # Worker total reads 0 and the report validator hard-fails a legitimate run.
+    # Attribution is aggregate, not per-worker; usageSummary records it openly.
+    unattributed_usage = None
+    if unattributed_totals:
+        unattributed_usage = usage_block(
+            _aggregate_totals(unattributed_totals), source="claude-jsonl"
+        )
+        unattributed_usage["sessionIds"] = unattributed_sessions
+        unattributed_usage["note"] = (
+            "Team-tagged worker session(s) with no agentName (dispatched without "
+            "the Agent `name` arg, or an in-process teammate commingled with the "
+            "lead). Folded into the worker pool as an aggregate because they "
+            "cannot be mapped to a specific workerId."
+        )
+
     # Aggregate summary.
     lead = state.get("leadUsage") or {}
     workers = state.get("workers", [])
@@ -283,6 +305,10 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
     worker_billable = sum((w.get("usage") or {}).get("billableEquivalentTokens", 0) or 0 for w in workers)
     worker_cost = sum((w.get("usage") or {}).get("estimatedCostUsd", 0) or 0 for w in workers)
     cli_cost = sum((w.get("usage") or {}).get("cliEstimatedCostUsd", 0) or 0 for w in workers)
+    if unattributed_usage is not None:
+        worker_total += unattributed_usage.get("totalTokens", 0) or 0
+        worker_billable += unattributed_usage.get("billableEquivalentTokens", 0) or 0
+        worker_cost += unattributed_usage.get("estimatedCostUsd", 0) or 0
 
     # Surface models whose pricing lookup failed so the silent-zero case is visible.
     unmatched_models: list[str] = []
@@ -312,6 +338,7 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
         "sessionsFound": len(claude_sessions),
         "unmatchedModels": sorted(set(unmatched_models)),
         "unattributedTeamSessions": unattributed_sessions,
+        "unattributedWorkerUsage": unattributed_usage,
         "definitions": {
             "totalTokens": "Sum of input + output + cache_creation + cache_read tokens (raw processed volume; matches Anthropic API breakdown). Cache reads are 95%+ in long sessions.",
             "billableEquivalentTokens": "Tokens normalized to base-input-price units (cache_creation_5m x1.25, cache_creation_1h x2.0, cache_read x0.1, output x5). 5m vs 1h is split from usage.cache_creation when the API breakdown is present; otherwise all cache_creation falls into 5m.",

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

@@ -169,7 +169,7 @@ A reverify dispatch that returns a **terminal non-result** (`timeout`, `error`,
 Rules:
 
 1. For each affected finding, append a `votes[W].verdict = "verification-error"` entry instead of `disagree`, plus the wrapper's captured exit reason in `votes[W].explanation`.
-2. Record one event per failed dispatch via `python3 scripts/okstra-error-log.py append-observed --error-type cli-failure --agent <worker> ...` (the worker wrapper does this for Codex/Gemini; for Claude worker timeouts the lead does it).
+2. Record one event per failed dispatch via `okstra error-log append-observed --error-type cli-failure --agent <worker> ...` (the worker wrapper does this for Codex/Gemini; for Claude worker timeouts the lead does it).
 3. Add an entry to the round's `skippedWorkers[]` with `{worker: <W>, reason: "dispatch-non-result", terminalStatus: <timeout|error|not-run>}`.
 4. If at least one dispatch was issued AND all reverify dispatches in a round terminate as non-result (mirroring the pseudocode's `len(dispatches) > 0` guard), the round is treated as gate-closed: write `round2SkippedReason: "all-reverify-non-result"` (even if the round in question is round 1 — i.e. round 2 never runs because round 1 produced no usable votes), record one `contract-violation` event per non-result dispatch, and exit the WHILE loop.
 5. Section 6 (Specialization Lens) of a worker output is OUT of convergence scope per "Convergence scope" above — its absence is NEVER a `verification-error`.
@@ -293,7 +293,7 @@ Assigned worker prompt history path: <Project Root>/<Prompt History Path>
 2. `team-state-<task-type>-<seq>.json` → `workers[].usage.cliModel` for that role (initial run's actual execution value)
 3. The `**Model:**` line of the initial Phase 4 prompt for that role (read from its persisted prompt-history file)
 
-If none of the three is available, **abort the reverify dispatch for that role** and record a `contract-violation` event via `okstra-error-log.py append-observed`. Do NOT guess, do NOT fall back to training-data defaults — for codex this would silently produce `o4-mini` instead of the assigned `gpt-5.5`-class model, which is a real bug class observed in production.
+If none of the three is available, **abort the reverify dispatch for that role** and record a `contract-violation` event via `okstra error-log append-observed`. Do NOT guess, do NOT fall back to training-data defaults — for codex this would silently produce `o4-mini` instead of the assigned `gpt-5.5`-class model, which is a real bug class observed in production.
 
 For Codex/Gemini wrapper subagents, the `**Model:** <role>, <modelExecutionValue>` line is what their wrapper extracts to pass into the underlying CLI's `--model` flag. Omitting it forces the wrapper to fall back to its own training-data knowledge of the CLI's historical default.
 

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

@@ -60,7 +60,7 @@ The prompt MUST include, in this order at the top:
     before the dispatch is constructed. The worker copies this verbatim
     into `data.json.meta.reportLanguage`.
 11. For implementation-planning runs: a literal block listing the 8 required English section headings the validator scans for (`Option Candidates`, `Trade-off`, `Recommended Option`, `Stepwise Execution Order`, `Dependency`, `Validation Checklist`, `Rollback`, `User Approval Request`). The writer must use these exact substrings as section headings (Korean translation in parentheses is allowed).
-12. An explicit instruction: `You are the author of TWO files: (a) the final-report data.json at <Result Path>, (b) the worker-results audit file at <Worker Result Path>. After writing the data.json, invoke "python3 scripts/okstra-render-final-report.py <Result Path>" via Bash so the markdown sibling is rendered before you return. Do not return the report inline. The validator fails the run when (a)'s schema validation fails, when the rendered markdown is absent, or when (b) is missing.`
+12. An explicit instruction: `You are the author of TWO files: (a) the final-report data.json at <Result Path>, (b) the worker-results audit file at <Worker Result Path>. After writing the data.json, invoke "okstra render-final-report <Result Path>" via Bash so the markdown sibling is rendered before you return. Do not return the report inline. The validator fails the run when (a)'s schema validation fails, when the rendered markdown is absent, or when (b) is missing.`
 
 **Completion detection after dispatch (BLOCKING).** The `Agent(... team_name ...)` call returns `Spawned successfully` immediately; that ack is NOT completion. After dispatching the report-writer (async), Lead MUST detect its completion via the self-scheduled polling protocol in [okstra-team-contract](../okstra-team-contract/SKILL.md) "Worker-completion detection (self-scheduled polling)", polling for the appearance of the data.json (Result Path) and the worker-results file (Worker Result Path) — do NOT restate the algorithm here. Report-writer is a single worker, so the pending set has one entry; the SSOT protocol handles that naturally. Lead MUST NOT treat the `Spawned successfully` ack as completion and MUST NOT end its turn with a prose "waiting for the report" statement; that path stalls the run until the user manually nudges it.
 
@@ -78,7 +78,7 @@ Except for `release-handoff` (which is single-lead by design and never dispatche
 
 1. A Report writer worker dispatch was actually attempted (Agent call was issued).
 2. The attempt recorded a terminal status of `error`, `timeout`, or `not-run` with a concrete reason (tool error message, timeout duration, or external blocker).
-3. The reason is logged via `okstra-error-log.py append-observed --error-type cli-failure ...` (or `tool-failure` if the failure was internal).
+3. The reason is logged via `okstra error-log append-observed --error-type cli-failure ...` (or `tool-failure` if the failure was internal).
 
 Speculative reasons such as "session resume constraint", "team object no longer exists", or "lead can do it faster" are NOT valid.
 
@@ -90,7 +90,7 @@ The four steps below MUST execute in this exact order. Reordering them is the re
 2. **Phase 7 step 1 — Token-usage collector with `--substitute-data`** (BLOCKING). One invocation aggregates `leadUsage` / `workers[].usage` / `usageSummary` into team-state AND populates `tokenUsage` + `executionStatus[].totalTokens` etc. in the data.json AND re-invokes the renderer so the sibling markdown carries the real numbers. Skipping the flag ships a markdown full of `--` cells.
 
    ```bash
-   python3 scripts/okstra-token-usage.py \
+   okstra token-usage \
      <runDirectoryPath>/state/team-state-<task-type>-<seq>.json \
      --write --summary \
      --substitute-data <runDirectoryPath>/reports/final-report-<task-type>-<seq>.data.json
@@ -100,7 +100,7 @@ The four steps below MUST execute in this exact order. Reordering them is the re
 3. **Phase 7 step 1.5 — Render report views** (BLOCKING, conditional output). Always invoke the renderer; it decides whether an html sibling is warranted:
 
    ```bash
-   python3 scripts/okstra-render-report-views.py \
+   okstra render-views \
      <runDirectoryPath>/reports/final-report-<task-type>-<seq>.md
    ```
 
@@ -112,7 +112,7 @@ The four steps below MUST execute in this exact order. Reordering them is the re
 4. **Phase 7 step 2 — Follow-up task spawner** (BLOCKING when Section 4 is non-empty). Turns the report's `## 4. Follow-up Tasks (후속 작업)` rows into `tasks/<task-group>/<new-task-id>/` stubs.
 
    ```bash
-   python3 scripts/okstra-spawn-followups.py \
+   okstra spawn-followups \
      <runDirectoryPath>/reports/final-report-<task-type>-<seq>.data.json \
      --project-root <project_root> \
      --task-group <task-group> \
@@ -323,7 +323,7 @@ Persistence steps that must be performed in Phase 7:
 - [ ] 5. **Update task-index.md**: Refresh human-readable summary
 - [ ] 6. **Generate final status file**: `runs/<task-type>/status/final-<task-type>-<seq>.status` (if necessary)
 - [ ] 7. **Save convergence state**: `runs/<task-type>/state/convergence-<task-type>-<seq>.json` (when convergence is enabled)
-- [ ] 8. **Spawn follow-up task stubs**: run `scripts/okstra-spawn-followups.py` against the final-report per the canonical spawn rule defined in "Phase 7 follow-up task spawner" above. Do not restate the trigger condition here — that section is the single source of truth. The script is idempotent across reruns.
+- [ ] 8. **Spawn follow-up task stubs**: run `okstra spawn-followups` against the final-report per the canonical spawn rule defined in "Phase 7 follow-up task spawner" above. Do not restate the trigger condition here — that section is the single source of truth. The script is idempotent across reruns.
 - [ ] 9. **Human HTML report** (conditional): `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` — produced by Phase 7 step 1.5 **only when the report has ≥1 §5 `C-*` clarification row** (self-contained, embeds `Export user response` button). Clarification-free reports legitimately have no html sibling; do not treat its absence as a missing artifact.
 
 ### Response after Persistence

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -303,7 +303,7 @@ Schema:
 Workers MUST omit `source` / `recordedAt` / `agent` / `agentRole` / `model` /
 `taskKey`. Claude lead fills those in when dumping the sidecar to the
 run-level errors log (`runs/<task-type>/logs/errors-<task-type>-<seq>.jsonl`)
-via `scripts/okstra-error-log.py append-from-worker`.
+via `okstra error-log append-from-worker`.
 
 Workers MUST use only `errorType: "tool-failure"` in the **sidecar file**.
 
@@ -312,7 +312,7 @@ run-level errors log path or their sidecar path from the
 `runs/<task-type>/...` template syntax. Both absolute paths are delivered
 by Lead via two dispatch-prompt header lines:
 
-- `**Errors log path:** <absolute path>` — run-level JSONL (`okstra-error-log.py append-observed --out ...`)
+- `**Errors log path:** <absolute path>` — run-level JSONL (`okstra error-log append-observed --out ...`)
 - `**Errors sidecar path:** <absolute path>` — per-worker JSON (`{ "schemaVersion": 1, "errors": [...] }`)
 
 Lead obtains both paths from the launch prompt's `## Run Logs (error-log
@@ -322,7 +322,7 @@ without proceeding — this is the contractual replacement for the previous
 "derive from template placeholders" behavior, which silently produced
 empty run-level error logs in production.
 
-- `cli-failure` events are recorded by the wrapper subagent itself (Codex / Gemini), but **directly to the run-level error log** via `okstra-error-log.py append-observed --error-type cli-failure ...` — NOT via the sidecar. The sidecar is an in-process tool-failure channel only.
+- `cli-failure` events are recorded by the wrapper subagent itself (Codex / Gemini), but **directly to the run-level error log** via `okstra error-log append-observed --error-type cli-failure ...` — NOT via the sidecar. The sidecar is an in-process tool-failure channel only.
 - **Wrapper invocation arity.** Both `okstra-codex-exec.sh` and `okstra-gemini-exec.sh` accept four required positional arguments plus an optional fifth `<role>`: `<project-root> <model> <prompt-path> <worktree-path> [<role>]`. The fourth (worktree) argument is **mandatory for implementation phase** and optional otherwise. For codex it becomes `--add-dir <worktree>` (sandbox write access); for gemini it is appended to `--include-directories`. Omitting it during implementation causes the codex sandbox to reject every Edit/Write targeting the worktree with EPERM. Workers extract the path from the `**Worktree:**` / `EXECUTOR_WORKTREE_PATH` / `cwd for every mutating command:` line in the lead prompt. The optional fifth `<role>` is folded into both the caller (worker) pane title `<cli>-<role>-<pid>` and the sibling trace-pane title `<cli>-<role>-<pid>-trace[from=<caller-pane-id>]` (e.g. `codex-worker-93421` ↔ `codex-worker-93421-trace[from=%5]`). `<pid>` is the wrapper's own PID and disambiguates concurrent dispatches of the same role; the embedded caller pane id keeps the trace ↔ worker correlation visible even when the worker pane's title is overwritten by the parent process (Claude Code's TUI emits OSC 2 title escape sequences on its own pane). Always pass the literal string `worker` so the dispatch is self-describing (the wrapper defaults to `worker` if omitted).
 - **Background dispatch + polling contract (Codex / Gemini wrappers).** Both wrapper subagents MUST dispatch `okstra-codex-exec.sh` / `okstra-gemini-exec.sh` via `Bash(run_in_background: true)` and poll with `BashOutput(bash_id)` until the shell reports `status == "completed"`, capped at 30 minutes (1800s) of wall-clock elapsed time. `BashOutput` itself is the wait primitive — call it back-to-back; do NOT insert a standalone `sleep` between polls. The Claude Code harness blocks `sleep` calls of 5 seconds or longer as a circumvention vector and explicitly forbids chaining shorter sleeps inside until-loops to work around the block. Workers that hit the contract bug must NOT self-recover with `until ...; do sleep 2; done` wrappers — that path violates the harness anti-circumvention rule, even though it superficially "works". The legacy "single foreground `Bash` with 120000ms timeout" rule, and the subsequent "60-second cadence with `sleep 60` between polls" rule, are both retired. The current rule applies in **every phase** (analysis runs typically complete in 1–2 `BashOutput` calls, so there is no regression for short jobs). Recording responsibilities:
   - Successful completion: return the wrapper's accumulated stdout from the final `BashOutput`. No log entry.
@@ -330,8 +330,8 @@ empty run-level error logs in production.
   - Polling cap reached: before `KillShell`, perform a one-shot **mtime-grace check** on the wrapper's live log (`<prompt>.log`). If the log was written within the last 90 seconds AND grace has not yet been applied this loop, extend the cap from 1800s → 2100s (one-shot +5min) and continue polling. Otherwise (log stale, OR grace already applied), call `KillShell(shell_id)`, record `cli-failure` with `--exit-code 124 --duration-ms <observed_ms> --message "<wrapper> exceeded polling cap (grace=<applied|not-applied>, last_mtime_age=<n>s)"`, then return the language-specific `*_CLI_TIMEOUT` sentinel. The grace exists to absorb token-budget spikes where the CLI is genuinely still producing output past the 30-minute mark; it is a one-shot soft extension, NOT a loop.
   - Token-usage matching is unaffected: the wrapper subagent stays alive throughout polling, so the wrapper's jsonl timestamp window continues to cover the underlying CLI rollout's full duration (see §"Token-usage accounting" below).
 - **No external timeout on wrapper subagents.** The codex/gemini wrapper subagent's polling loop (with optional mtime grace) is the SINGLE timeout authority for its dispatch. Lead MUST NOT impose a separate `Agent()` call timeout, an outer `Bash` wall-clock deadline, or any other mechanism that terminates the subagent before its own polling cap is reached. Doing so reproduces the historical failure mode that motivated this rule: Lead aborts the subagent at e.g. 18 minutes, the subagent returns nothing, and Lead classifies the role as "no response" while the underlying CLI was actively working. The wrapper's polling cap (30min + optional 5min grace) is calibrated so that, combined with Lead's redispatch policy (see "Lead Redispatch Policy on Result-Missing"), a recoverable single-run failure costs at most ~70 minutes of wall-clock — predictable enough to plan around. If a specific run requires a tighter cap, lower it in the wrapper subagent's polling contract (single source of truth), NOT by layering Lead-side timeouts.
-- `contract-violation` events (C) are recorded by Lead via `okstra-error-log.py append-observed --error-type contract-violation ...` after inspecting worker outputs.
-- Lead's responsibility regarding the sidecar is to dump it to the run-level error log via `okstra-error-log.py append-from-worker` after each worker terminates; Lead does not write into the sidecar.
+- `contract-violation` events (C) are recorded by Lead via `okstra error-log append-observed --error-type contract-violation ...` after inspecting worker outputs.
+- Lead's responsibility regarding the sidecar is to dump it to the run-level error log via `okstra error-log append-from-worker` after each worker terminates; Lead does not write into the sidecar.
 
 ## Convergence Phase Rules
 

package/runtime/validators/validate-run.py

@@ -621,7 +621,7 @@ def _scan_token_usage_summary(content: str, failures: list[str]) -> None:
                     failures.append(
                         f"Token Usage Summary row `{label_cell or '<unlabeled>'}` has "
                         f"a zero value `{stripped}` — no okstra run consumes zero "
-                        "tokens. Re-run `python3 scripts/okstra-token-usage.py "
+                        "tokens. Re-run `okstra token-usage "
                         "<team-state> --write --summary --substitute-data "
                         "<report-path>` to repopulate from session jsonls. The "
                         "Codex/Gemini CLI row is the only place `$0.00` is "
@@ -1024,7 +1024,7 @@ def validate_team_state_usage(team_state: dict, failures: list[str]) -> None:
     if not summary or not summary.get("collectedAt"):
         failures.append(
             "team-state.usageSummary is empty — Phase 7 token-usage collection was skipped. "
-            "Run `python3 scripts/okstra-token-usage.py <team-state> --write --summary "
+            "Run `okstra token-usage <team-state> --write --summary "
             "--substitute-data <final-report>`."
         )
         return

package/src/_python-helper.mjs

@@ -1,6 +1,58 @@
 import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
 import { buildPythonpath, resolvePaths } from "./paths.mjs";
 
+function resolveInstalledScript(paths, scriptName) {
+  // Prefer the installed copy under ~/.okstra/bin (what production users run);
+  // fall back to the in-repo source when invoked from a checkout that has not
+  // been installed (dev / CI).
+  const installed = join(paths.bin, scriptName);
+  if (existsSync(installed)) return installed;
+  const repoRoot = fileURLToPath(new URL("..", import.meta.url));
+  const dev = resolvePath(repoRoot, "scripts", scriptName);
+  return existsSync(dev) ? dev : null;
+}
+
+// Thin spawn shim shared by every `okstra <cmd>` subcommand that fronts a
+// `scripts/okstra-*.py` entry point. Centralizing it keeps PYTHONPATH wiring
+// and installed/dev resolution in one place so skills call `okstra <cmd>`
+// instead of emitting `python3 "$HOME/..."` (which breaks `Bash(okstra:*)`
+// permission matching and prompts on every call).
+export async function runInstalledScript({ scriptName, args, usage, emptyArgsCode = 2 }) {
+  if (args.length === 0) {
+    process.stdout.write(usage);
+    return emptyArgsCode;
+  }
+  // Only a bare `--help` / `-h` prints the wrapper usage. A `--help` that
+  // follows a subcommand (e.g. `error-log append-observed --help`) must reach
+  // the python helper so its own per-subcommand help shows through.
+  if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) {
+    process.stdout.write(usage);
+    return 0;
+  }
+  const paths = await resolvePaths();
+  const entry = resolveInstalledScript(paths, scriptName);
+  if (!entry) {
+    process.stderr.write(
+      `error: ${scriptName} not found — run 'okstra install' (or 'okstra ensure-installed') first\n`,
+    );
+    return 1;
+  }
+  return await new Promise((resolve) => {
+    const child = spawn("python3", [entry, ...args], {
+      stdio: "inherit",
+      env: { ...process.env, PYTHONPATH: buildPythonpath(paths) },
+    });
+    child.on("error", (err) => {
+      process.stderr.write(`error: failed to spawn python3: ${err.message}\n`);
+      resolve(1);
+    });
+    child.on("close", (code) => resolve(typeof code === "number" ? code : 1));
+  });
+}
+
 export async function runPythonSnippet({ script, args = [], extraEnv = {} }) {
   const paths = await resolvePaths();
   return new Promise((resolve) => {

package/src/error-log.mjs

@@ -0,0 +1,19 @@
+import { runInstalledScript } from "./_python-helper.mjs";
+
+const USAGE = `okstra error-log — append okstra run error events to the run error log
+
+Wraps the python helper (\`okstra-error-log.py\`) installed under
+\`~/.okstra/bin/\` so skills and worker wrappers call \`okstra error-log\`
+instead of emitting a \`python3 "$HOME/..."\` invocation (which breaks
+\`Bash(okstra:*)\` permission matching and prompts on every call).
+
+Usage:
+  okstra error-log <subcommand> [...]      # e.g. append-observed / append-from-worker
+
+All arguments are forwarded verbatim to the python helper. See
+\`okstra error-log append-observed --help\` for the full option list.
+`;
+
+export async function run(args) {
+  return runInstalledScript({ scriptName: "okstra-error-log.py", args, usage: USAGE });
+}

package/src/inject-report-index.mjs

@@ -0,0 +1,22 @@
+import { runInstalledScript } from "./_python-helper.mjs";
+
+const USAGE = `okstra inject-report-index — add the top-of-report Index + scroll anchors to a report
+
+Wraps the python helper (\`okstra-inject-report-index.py\`) installed under
+\`~/.okstra/bin/\` so skills call \`okstra inject-report-index\` instead of
+emitting a \`python3 "$HOME/..."\` invocation (which breaks \`Bash(okstra:*)\`
+permission matching and prompts on every call).
+
+Usage:
+  okstra inject-report-index <markdown-path> [--report-language <en|ko>]
+
+All arguments are forwarded verbatim to the python helper.
+`;
+
+export async function run(args) {
+  return runInstalledScript({
+    scriptName: "okstra-inject-report-index.py",
+    args,
+    usage: USAGE,
+  });
+}

package/src/render-final-report.mjs

@@ -0,0 +1,22 @@
+import { runInstalledScript } from "./_python-helper.mjs";
+
+const USAGE = `okstra render-final-report — render the markdown sibling of a final-report data.json
+
+Wraps the python helper (\`okstra-render-final-report.py\`) installed under
+\`~/.okstra/bin/\` so skills call \`okstra render-final-report\` instead of
+emitting a \`python3 "$HOME/..."\` invocation (which breaks \`Bash(okstra:*)\`
+permission matching and prompts on every call).
+
+Usage:
+  okstra render-final-report <path-to-final-report.data.json>
+
+The argument is forwarded verbatim to the python helper.
+`;
+
+export async function run(args) {
+  return runInstalledScript({
+    scriptName: "okstra-render-final-report.py",
+    args,
+    usage: USAGE,
+  });
+}

package/src/render-views.mjs

@@ -1,18 +1,14 @@
-import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { resolve as resolvePath } from "node:path";
-import { fileURLToPath } from "node:url";
-import { resolvePaths } from "./paths.mjs";
+import { runInstalledScript } from "./_python-helper.mjs";
 
-const USAGE = `okstra render-views — render slim AI + self-contained HTML views of a final-report
+const USAGE = `okstra render-views — render the self-contained HTML view of a final-report
 
 A thin spawn shim over \`scripts/okstra-render-report-views.py\` (installed
 at \`$HOME/.okstra/bin/okstra-render-report-views.py\`). Reads the final-
-report MD and writes two siblings:
+report MD and writes a single sibling:
 
-  <stem>.slim.md   — token-saving AI consumption copy
   <stem>.html       — single-file self-contained human view with form
-                       controls on §5 clarification rows
+                       controls on §5 clarification rows (skipped when the
+                       report has no §5 C-* clarification rows)
 
 Usage:
   okstra render-views <path-to-final-report.md>
@@ -23,45 +19,10 @@ When the optional flags are omitted the script infers from the report
 path and its '- Task Type:' / '- Task Key:' lines.
 `;
 
-function resolveEntrypoint(paths) {
-  // Prefer the installed copy under ~/.okstra/bin (what production users
-  // see); fall back to the in-repo dev source when running from a
-  // checkout that hasn't been installed.
-  const installed = resolvePath(paths.home, "bin", "okstra-render-report-views.py");
-  if (existsSync(installed)) return installed;
-  const here = fileURLToPath(new URL("..", import.meta.url));
-  const dev = resolvePath(here, "scripts", "okstra-render-report-views.py");
-  if (existsSync(dev)) return dev;
-  return null;
-}
-
 export async function run(args) {
-  if (args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(USAGE);
-    return 0;
-  }
-  if (args.length === 0) {
-    process.stderr.write("error: missing <path-to-final-report.md>\n");
-    process.stderr.write(USAGE);
-    return 2;
-  }
-  const paths = await resolvePaths();
-  const entry = resolveEntrypoint(paths);
-  if (!entry) {
-    process.stderr.write(
-      "error: okstra-render-report-views.py not found. " +
-      "Run `okstra install` to install the runtime.\n",
-    );
-    return 1;
-  }
-  return await new Promise((res) => {
-    const child = spawn("python3", [entry, ...args], {
-      stdio: ["ignore", "inherit", "inherit"],
-    });
-    child.on("error", (err) => {
-      process.stderr.write(`error: ${err.message}\n`);
-      res(1);
-    });
-    child.on("close", (code) => res(code ?? 0));
+  return runInstalledScript({
+    scriptName: "okstra-render-report-views.py",
+    args,
+    usage: USAGE,
   });
 }

package/src/spawn-followups.mjs

@@ -0,0 +1,23 @@
+import { runInstalledScript } from "./_python-helper.mjs";
+
+const USAGE = `okstra spawn-followups — create follow-up task bundles from a final report
+
+Wraps the python helper (\`okstra-spawn-followups.py\`) installed under
+\`~/.okstra/bin/\` so skills call \`okstra spawn-followups\` instead of
+emitting a \`python3 "$HOME/..."\` invocation (which breaks \`Bash(okstra:*)\`
+permission matching and prompts on every call).
+
+Usage:
+  okstra spawn-followups <args...>
+
+All arguments are forwarded verbatim to the python helper. See
+\`okstra spawn-followups --help\` for the full option list.
+`;
+
+export async function run(args) {
+  return runInstalledScript({
+    scriptName: "okstra-spawn-followups.py",
+    args,
+    usage: USAGE,
+  });
+}

package/src/token-usage.mjs

@@ -1,7 +1,4 @@
-import { spawn } from "node:child_process";
-import { join } from "node:path";
-import { promises as fs } from "node:fs";
-import { resolvePaths } from "./paths.mjs";
+import { runInstalledScript } from "./_python-helper.mjs";
 
 const USAGE = `okstra token-usage — collect token usage for a run
 
@@ -15,37 +12,9 @@ Usage:
   okstra token-usage <state-file> [--write] [--summary] [...]
 
 Arguments and flags after the state-file path are forwarded verbatim to
-the python helper. See \`python3 ~/.okstra/bin/okstra-token-usage.py --help\`
-for the full option list.
+the python helper. See \`okstra token-usage --help\` for the full option list.
 `;
 
 export async function run(args) {
-  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(USAGE);
-    return args.length === 0 ? 2 : 0;
-  }
-
-  const paths = await resolvePaths();
-  const script = join(paths.bin, "okstra-token-usage.py");
-
-  try {
-    await fs.access(script);
-  } catch {
-    process.stderr.write(
-      `error: ${script} not found — run 'okstra install' (or 'okstra ensure-installed') first\n`,
-    );
-    return 1;
-  }
-
-  return await new Promise((resolve) => {
-    const child = spawn("python3", [script, ...args], {
-      stdio: "inherit",
-      env: { ...process.env, PYTHONPATH: paths.pythonpath },
-    });
-    child.on("error", (err) => {
-      process.stderr.write(`error: failed to spawn python3: ${err.message}\n`);
-      resolve(1);
-    });
-    child.on("close", (code) => resolve(typeof code === "number" ? code : 1));
-  });
+  return runInstalledScript({ scriptName: "okstra-token-usage.py", args, usage: USAGE });
 }