okstra 0.67.0 → 0.69.0

package/runtime/python/okstra_ctl/wizard.py

@@ -261,6 +261,7 @@ S_BRANCH_CONFIRM = "branch_confirm"
 S_CONFIRM = "confirm"
 S_EDIT_TARGET = "edit_target"
 S_DONE = "done"
+S_ABORTED = "aborted"
 
 # ---- 멀티탭 배치 프롬프트 그룹 (방출 계층 전용) ----
 # 그룹 id 는 S_* 가 아니므로 prompts JSON SOT / step-id 동기화 검사 대상이 아니다.
@@ -362,6 +363,8 @@ class WizardState:
     branch_confirmed: Optional[bool] = None
     confirmed: Optional[bool] = None
     edit_target: str = ""
+    # terminal: user picked 중단 — no further prompt ever applies
+    aborted: bool = False
 
     # bookkeeping
     answered: list[str] = field(default_factory=list)
@@ -384,7 +387,7 @@ class Option:
 @dataclass
 class Prompt:
     step: str
-    kind: str  # "pick" | "text" | "done"
+    kind: str  # "pick" | "text" | "pick_group" | "done" | "aborted"
     label: str = ""
     options: list[Option] = field(default_factory=list)
     help: str = ""
@@ -760,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)
@@ -1492,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(
@@ -1506,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"],
     )
@@ -1515,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:
@@ -2201,6 +2227,7 @@ def _build_branch_confirm(state: WizardState) -> Prompt:
     options = [_opt("proceed", opts["proceed"])]
     if decision.status == "new":
         options.append(_opt("edit", opts["edit"]))
+    options.append(_opt("abort", opts["abort"]))
     return Prompt(step=S_BRANCH_CONFIRM, kind="pick", label=label,
                   options=options, echo_template=t["echo_template"])
 
@@ -2210,8 +2237,13 @@ def _submit_branch_confirm(state: WizardState, value: str) -> Optional[str]:
         _reset_from(state, S_BASE_REF_PICK)
         state.branch_confirmed = None
         return "branch-confirm: edit"
+    if value == "abort":
+        state.aborted = True
+        return "branch-confirm: abort"
     if value != "proceed":
-        raise WizardError(f"expected 'proceed' or 'edit', got: {value!r}")
+        raise WizardError(
+            f"expected 'proceed' / 'edit' / 'abort', got: {value!r}"
+        )
     state.branch_confirmed = True
     return "branch-confirm: proceed"
 
@@ -2343,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,
@@ -2358,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,
@@ -2368,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)),
@@ -2539,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,
@@ -2561,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
@@ -2685,6 +2720,8 @@ def _build_group_prompt(state: WizardState, group_id: str) -> Prompt:
 
 
 def next_prompt(state: WizardState) -> Prompt:
+    if state.aborted:
+        return Prompt(step=S_ABORTED, kind="aborted")
     if state.confirmed:
         return Prompt(step=S_DONE, kind="done")
     for step in STEPS:
@@ -2731,7 +2768,7 @@ def submit(state: WizardState, value: str) -> dict[str, Any]:
     validation failure (caller may re-prompt).
     """
     prompt = next_prompt(state)
-    if prompt.kind == "done":
+    if prompt.kind in ("done", "aborted"):
         return {"echo": "", "next": prompt.to_json()}
     if prompt.kind == "pick_group":
         return _submit_group(state, prompt, value)
@@ -2745,10 +2782,28 @@ def submit(state: WizardState, value: str) -> dict[str, Any]:
 
 def render_args(state: WizardState) -> dict[str, str]:
     """Convert finalized state into ``okstra render-bundle`` argument map."""
+    if state.aborted:
+        raise WizardError(
+            "wizard was aborted by the user — render-args is unavailable"
+        )
     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"
@@ -2764,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,
@@ -2786,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}")
@@ -2814,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:
@@ -2928,7 +2989,13 @@ def _cli(argv: list[str]) -> int:
 
     if args.cmd == "render-args":
         state = load_state_file(state_path)
-        print(json.dumps({"ok": True, "args": render_args(state)},
+        try:
+            rendered = render_args(state)
+        except WizardError as exc:
+            print(json.dumps({"ok": False, "error": str(exc)},
+                             ensure_ascii=False, indent=2))
+            return 0
+        print(json.dumps({"ok": True, "args": rendered},
                          ensure_ascii=False, indent=2))
         return 0
 

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.
@@ -492,11 +510,14 @@ def compute_worktree_path(
     task_group_segment: str,
     task_id_segment: str,
     stage_number: Optional[int] = None,
+    group_id: Optional[str] = None,
 ) -> Path:
     """Pure path computation. One worktree dir per task-key, or per
     `<task-key>/stage-<N>` when stage_number is given (implementation
     stage isolation). Uses `OKSTRA_HOME` when set (test hook), else
     `~/.okstra`."""
+    if stage_number is not None and group_id is not None:
+        raise ValueError("stage_number and group_id are mutually exclusive")
     okstra_home = os.environ.get("OKSTRA_HOME", "").strip()
     base = Path(okstra_home) if okstra_home else (Path.home() / ".okstra")
     path = (
@@ -507,6 +528,8 @@ def compute_worktree_path(
     )
     if stage_number is not None:
         path = path / f"stage-{stage_number}"
+    if group_id is not None:
+        path = path / f"group-{group_id}"
     return path
 
 
@@ -515,12 +538,17 @@ def compute_branch_name(
     work_category: str,
     task_id_segment: str,
     stage_number: Optional[int] = None,
+    group_id: Optional[str] = None,
 ) -> str:
     """One branch per task-key, or `<prefix>-<task-id>-s<N>` for an
     implementation stage worktree."""
+    if stage_number is not None and group_id is not None:
+        raise ValueError("stage_number and group_id are mutually exclusive")
     name = f"{_work_category_prefix(work_category)}-{_safe_segment(task_id_segment)}"
     if stage_number is not None:
         name = f"{name}-s{stage_number}"
+    if group_id is not None:
+        name = f"{name}-{group_id}"
     return name
 
 

package/runtime/python/okstra_ctl/worktree_registry.py

@@ -46,13 +46,17 @@ def _okstra_worktrees_dir() -> Path:
 def task_key(
     project_id: str, task_group: str, task_id: str,
     stage_number: Optional[int] = None,
+    group_id: Optional[str] = None,
 ) -> str:
-    """Canonical task-key. With stage_number, returns the stage-scoped
-    key `<proj>/<group>/<task>#stage-<N>` used to reserve a per-stage
-    worktree independently of the task-key entry."""
+    """Canonical task-key. stage_number → `#stage-<N>` (per-stage worktree),
+    group_id → `#group-<id>` (stage-group collector worktree). 둘은 상호배타."""
+    if stage_number is not None and group_id is not None:
+        raise ValueError("stage_number and group_id are mutually exclusive")
     base = f"{project_id}/{task_group}/{task_id}"
     if stage_number is not None:
         return f"{base}#stage-{stage_number}"
+    if group_id is not None:
+        return f"{base}#group-{group_id}"
     return base
 
 
@@ -70,6 +74,7 @@ class WorktreeEntry:
     status: str = "active"  # "active" | "released"
     stage: Optional[int] = None
     implementation_base_commit: str = ""
+    stages: Optional[list] = None
 
 
 @contextlib.contextmanager
@@ -119,8 +124,9 @@ def _save(data: dict) -> None:
 def lookup(
     project_id: str, task_group: str, task_id: str,
     stage_number: Optional[int] = None,
+    group_id: Optional[str] = None,
 ) -> Optional[WorktreeEntry]:
-    key = task_key(project_id, task_group, task_id, stage_number)
+    key = task_key(project_id, task_group, task_id, stage_number, group_id)
     with _registry_lock():
         data = _load()
         row = data["tasks"].get(key)
@@ -139,18 +145,20 @@ def reserve(
     base_ref: str,
     phase: str = "",
     stage_number: Optional[int] = None,
+    group_id: Optional[str] = None,
+    stages: Optional[list] = None,
 ) -> WorktreeEntry:
     """Atomically insert a new entry. Raises RuntimeError if the
     task-key already exists or the branch is already owned by a
     different task-key. Callers should `lookup()` first when re-entry
     is expected.
     """
-    key = task_key(project_id, task_group, task_id, stage_number)
+    key = task_key(project_id, task_group, task_id, stage_number, group_id)
     now = time.strftime("%Y-%m-%dT%H:%M:%S%z") or time.strftime("%Y-%m-%dT%H:%M:%S")
     with _registry_lock():
         data = _load()
-        if key in data["tasks"]:
-            existing = data["tasks"][key]
+        existing = data["tasks"].get(key)
+        if existing and existing.get("status") != "released":
             raise RuntimeError(
                 f"task-key already has a worktree registered: {key} → "
                 f"{existing['worktree_path']} (branch {existing['branch']}). "
@@ -174,6 +182,7 @@ def reserve(
             "last_phase": phase,
             "status": "active",
             "stage": stage_number,
+            "stages": stages,
         }
         data["tasks"][key] = row
         data["branches"][branch] = key
@@ -218,6 +227,24 @@ def set_implementation_base(
         return commit
 
 
+def reset_implementation_base(
+    project_id: str, task_group: str, task_id: str, commit: str,
+) -> str:
+    """anchor 를 의식적으로 재고정한다. 유일한 호출자는 git-reconcile 의
+    `--reset-anchor` — prepare 경로는 절대 anchor 를 움직이지 않는다."""
+    key = task_key(project_id, task_group, task_id)
+    with _registry_lock():
+        data = _load()
+        row = data["tasks"].get(key)
+        if row is None:
+            raise RuntimeError(
+                f"no task-key entry to reset implementation base: {key}"
+            )
+        row["implementation_base_commit"] = commit
+        _save(data)
+        return commit
+
+
 def get_implementation_base(
     project_id: str, task_group: str, task_id: str,
 ) -> Optional[str]:
@@ -262,13 +289,17 @@ def list_active_stage_numbers(
         return out
 
 
-def release(project_id: str, task_group: str, task_id: str) -> Optional[WorktreeEntry]:
+def release(
+    project_id: str, task_group: str, task_id: str,
+    stage_number: Optional[int] = None,
+    group_id: Optional[str] = None,
+) -> Optional[WorktreeEntry]:
     """Mark the entry as `released` (worktree dir intact — preservation
     is the project's policy). The branch index is freed so future
     reservations of the same branch name are not blocked.
     Returns the prior entry, or None when not found.
     """
-    key = task_key(project_id, task_group, task_id)
+    key = task_key(project_id, task_group, task_id, stage_number, group_id)
     with _registry_lock():
         data = _load()
         row = data["tasks"].get(key)

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-context-loader/SKILL.md

@@ -155,6 +155,6 @@ Information to be obtained after executing this skill:
 - Reference list of config files/deployment manifests and task-level expected values
 - Current run status and presence of existing worker results
 - Current run prompt history contract for attempted workers
-- Candidate `teamName` for Phase 3 hand-off: `okstra-<task-key>` (with task-key slugified per Step 1's slug rule)
+- Candidate `teamName` for Phase 3 hand-off: `okstra-<task-key>` (with task-key slugified per Step 1's slug rule); implementation stage runs append `-s<N>` — the launch prompt's Team Creation Gate block carries the final name verbatim
 - Current Claude `lead.sessionId` (the in-flight Claude Code session) — required by `okstra-team-contract` when registering the lead in `team-state.json`
 - Resume command path: from `task-manifest.json` → `latestResumeCommandPath` (fallback: latest `runs/<task-type>/sessions/claude-resume-*.sh` by mtime). Never reconstruct the filename — the `<seq>` counter is category-local and may diverge from `manifests/`.

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`.
@@ -264,7 +264,7 @@ Agent(
   prompt: "<re-verification prompt with findings batch>",
   name: "<role-slug>-reverify-r<N>",
   subagent_type: "<same as initial execution>",
-  team_name: "okstra-<task-key>",
+  team_name: "<teamName recorded in team-state>",
   model: "<same as initial execution>",
   mode: "auto"
 )
@@ -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

@@ -34,7 +34,7 @@ Agent(
   prompt: "<report-writer prompt: see this skill + Required reading clause + Available MCP Servers section>",
   name: "report-writer",
   subagent_type: "report-writer-worker",
-  team_name: "okstra-<task-key>",   # omit if team is not alive — see Resume-safe dispatch
+  team_name: "<teamName recorded in team-state>",   # omit if team is not alive — see Resume-safe dispatch
   model: "<family token of Report writer worker's modelExecutionValue>",   # opus/sonnet/haiku — NOT hardcoded; see below
   mode: "auto"
 )
@@ -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.
 
@@ -68,7 +68,7 @@ The prompt MUST include, in this order at the top:
 
 A resumed lead session can ALWAYS dispatch a fresh Report writer worker. The Agent tool does not require a previously created Team to be alive:
 
-- If `TeamCreate` for `okstra-<task-key>` still succeeds (or the team is still listed), include `team_name` in the dispatch.
+- If `TeamCreate` for the team-state `teamName` still succeeds (or the team is still listed), include `team_name` in the dispatch.
 - If `TeamCreate` reports the name is taken or the team is gone, omit `team_name` from the dispatch — the worker still runs as a background subagent and its session is still recoverable by `agentName: "report-writer"` in `okstra-token-usage.py`.
 - Do NOT skip dispatch because of any team-related error. Record the team status in team-state and proceed without `team_name`.
 
@@ -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