okstra 0.68.0 → 0.70.0

package/runtime/python/okstra_ctl/wizard.py

@@ -763,6 +763,70 @@ 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 _parse_stage_objects(state: WizardState) -> list:
+    """승인 plan 의 Stage Map stage 객체 목록. validator 의 _parse_stage_map 재사용.
+    `_build_stage_pick` 과 `_whole_task_allowed` 가 공유한다."""
+    import importlib.util as _ilu
+    import sys as _sys
+    plan_text = Path(state.approved_plan_path).read_text(encoding="utf-8")
+    validator_path = (Path(state.workspace_root) / "validators"
+                      / "validate-implementation-plan-stages.py")
+    spec = _ilu.spec_from_file_location("_ip_stage_v_wizard", str(validator_path))
+    if spec is None or spec.loader is None:
+        raise WizardError(f"cannot load stage validator at {validator_path}")
+    mod = _ilu.module_from_spec(spec)
+    _sys.modules["_ip_stage_v_wizard"] = mod
+    try:
+        spec.loader.exec_module(mod)
+        stages, _errs = mod._parse_stage_map(plan_text)
+    finally:
+        _sys.modules.pop("_ip_stage_v_wizard", None)
+    return stages
+
+
+def _done_stage_numbers(state: WizardState) -> set:
+    """approved plan 을 소비한 implementation run 들의 consumers.jsonl 에서
+    done 처리된 stage 번호 집합. git 호출 없음 — 파일 읽기만(prepare 와 동일 SSOT)."""
+    if not state.approved_plan_path:
+        return set()
+    from .consumers import (read_consumers, backfill_done_from_carry,
+                            latest_done_by_stage)
+    plan_run_root = Path(state.approved_plan_path).resolve().parents[1]
+    backfill_done_from_carry(plan_run_root)
+    rows = read_consumers(plan_run_root)
+    return set(latest_done_by_stage(rows).keys())
+
+
+def _whole_task_allowed(state: WizardState) -> bool:
+    """final-verification 이고 Stage Map 의 모든 stage 가 done 일 때만 True.
+    위저드는 done 만 본다 — 머지/clean/active 는 prepare 게이트가 강제한다."""
+    if state.task_type != "final-verification":
+        return False
+    if not state.approved_plan_path:
+        return False
+    stages = _parse_stage_objects(state)
+    if not stages:
+        return False
+    done = _done_stage_numbers(state)
+    return all(s.stage_number in done for s in stages)
+
+
 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)
@@ -1342,6 +1406,7 @@ _REUSE_LAST_TOKEN = "__reuse_last__"
 _SIBLINGS_TOKEN = "__siblings__"
 _LATEST_REPORT_TOKEN = "__latest_report__"
 _PROJECT_DEFAULT_TOKEN = "__project_default__"
+WHOLE_TASK_STAGE = "__whole_task__"
 
 
 def _list_implementation_planning_reports(
@@ -1477,39 +1542,35 @@ def _submit_approve_plan_confirm(state: WizardState, value: str) -> Optional[str
 
 def _build_stage_pick(state: WizardState) -> Prompt:
     """Parse the Stage Map from the approved plan and build the stage picker."""
-    import importlib.util as _ilu
-    import sys as _sys
     t = _p(state.workspace_root, "stage_pick")
-    plan_text = Path(state.approved_plan_path).read_text(encoding="utf-8")
-    validator_path = (
-        Path(state.workspace_root) / "validators"
-        / "validate-implementation-plan-stages.py"
-    )
-    spec = _ilu.spec_from_file_location("_ip_stage_v_wizard", str(validator_path))
-    if spec is None or spec.loader is None:
-        raise WizardError(f"cannot load stage validator at {validator_path}")
-    mod = _ilu.module_from_spec(spec)
-    _sys.modules["_ip_stage_v_wizard"] = mod
-    try:
-        spec.loader.exec_module(mod)
-        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"])
-        if state.task_type == "final-verification"
-        else t["options"]["auto"]
+    stages = _parse_stage_objects(state)
+    is_fv = state.task_type == "final-verification"
+    label = (
+        t.get("label_final_verification", t["label"])
+        if is_fv else t["label"]
     )
-    options = [_opt("auto", auto_label)]
+    done = _done_stage_numbers(state) if is_fv else set()
+    options = []
+    if _stage_auto_allowed(state):
+        options.append(_opt("auto", t["options"]["auto"]))
+    if _whole_task_allowed(state):
+        options.append(_opt(WHOLE_TASK_STAGE, t["options"]["whole_task"]))
     for s in stages:
         depends = ",".join(map(str, s.depends_on)) or "(none)"
+        suffix = ""
+        if is_fv:
+            mark = (t["options"]["done_mark"]
+                    if s.stage_number in done
+                    else t["options"]["undone_mark"])
+            suffix = f"  {mark}"
         options.append(_opt(
             str(s.stage_number),
-            f"{s.stage_number}: {s.title}  [depends-on: {depends} | steps: {s.step_count}]",
+            f"{s.stage_number}: {s.title}  "
+            f"[depends-on: {depends} | steps: {s.step_count}]{suffix}",
         ))
     return Prompt(
         step=S_STAGE_PICK, kind="pick",
-        label=t["label"],
+        label=label,
         options=options,
         echo_template=t["echo_template"],
     )
@@ -1518,12 +1579,24 @@ 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"
+            )
+    elif answer == WHOLE_TASK_STAGE:
+        if not _whole_task_allowed(state):
+            raise WizardError(
+                "whole-task verification requires final-verification "
+                "with all stages done"
+            )
+    else:
         try:
             int(answer)
         except ValueError:
             raise WizardError(
-                f"answer must be 'auto' or a stage number, got {answer!r}"
+                f"answer must be 'auto', whole-task, or a stage number, "
+                f"got {answer!r}"
             )
     state.selected_stage = answer
     return f"stage: {answer}"
@@ -2352,7 +2425,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 +2440,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 +2449,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 +2619,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 +2646,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 +2839,24 @@ 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 state.selected_stage == WHOLE_TASK_STAGE:
+            stage = ""  # prepare 가 빈 stage 를 whole-task 로 해석
+        elif not state.selected_stage or state.selected_stage == "auto":
+            raise WizardError(
+                "final-verification requires an explicit stage number"
+            )
+        else:
+            stage = state.selected_stage
+    else:
+        stage = ""
     pr_template = (
         state.pr_template_path
         if state.task_type == "release-handoff"
@@ -2779,7 +2872,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 +2894,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 +2924,14 @@ 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 = (
+            _msg(state.workspace_root, "confirmation", "stage_whole_task")
+            if state.selected_stage == WHOLE_TASK_STAGE
+            else (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.
 
@@ -572,7 +572,7 @@ Promoted blockers enter `## 5.8 Acceptance Blockers`; since `accepted` requires
 
 ### State
 
-Critic output lives at `runs/final-verification/worker-results/<provider>-critic-final-verification-<seq>.md`. The convergence state `config.critic` summary (see §"Coverage critic pass") records `mode: "acceptance-devils-advocate"`, `candidatesProposed`, `confirmedBlockers`, `downgradedToResidual` (optional v1.2 fields; readers treat absence as null).
+Critic output lives in the run's `worker-results/` directory (`runs/final-verification/worker-results/` for whole-task verification, `runs/final-verification/stage-<N>/worker-results/` for single-stage), filename `<provider>-critic-final-verification-<seq>.md`. The convergence state `config.critic` summary (see §"Coverage critic pass") records `mode: "acceptance-devils-advocate"`, `candidatesProposed`, `confirmedBlockers`, `downgradedToResidual` (optional v1.2 fields; readers treat absence as null).
 
 ## Output
 

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

@@ -299,7 +299,7 @@ B. **`task-manifest.json` (direct):** if catalog missing, slugify task-group / t
 
 C. **`timeline.json` (specific run):** for a specific date or run, read `.okstra/tasks/<group-segment>/<id-segment>/history/timeline.json`, filter `runs[]` by `runTimestamp` / `status` / `taskType`, use `runs[].reportPath`.
 
-D. **Specific task-type (fallback):** `latestReportPath` is task-type-agnostic. For a specific task-type's latest report, look under `.okstra/tasks/<group-segment>/<id-segment>/runs/<task-type-segment>/reports/`, filename pattern `final-report-<task-type-segment>-<NNN>.md` per `scripts/okstra_ctl/sequence.py:31`. Highest seq is latest. Cross-verify with `timeline.json`'s `runs[].taskType` filter.
+D. **Specific task-type (fallback):** `latestReportPath` is task-type-agnostic. For a specific task-type's latest report, look under `.okstra/tasks/<group-segment>/<id-segment>/runs/<task-type-segment>/reports/`, filename pattern `final-report-<task-type-segment>-<NNN>.md` per `scripts/okstra_ctl/sequence.py:31`. Highest seq is latest. Stage-isolated runs (`implementation`, single-stage `final-verification`) keep their reports one level deeper at `runs/<task-type-segment>/stage-<N>/reports/` — scan those subdirectories too; seq is independent per stage. Cross-verify with `timeline.json`'s `runs[].taskType` filter.
 
 ### report.2 — Confirm existence
 

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,
+  });
+}