okstra 0.10.0 → 0.12.0

package/runtime/python/okstra_ctl/worktree.py

@@ -1,19 +1,34 @@
-"""Implementation-phase git worktree provisioning.
+"""Per-task git worktree provisioning.
 
-Implementation runs operate on an isolated git worktree rooted under
-`~/.okstra/worktrees/<project_id>/<task_group_segment>/<task_id_segment>-<run_seq>`.
-The executor mutates files there; verifiers read from the same path.
-The worktree is always kept after the run for inspection, manual PR
-authoring, and rollback verification.
+Every okstra task — regardless of task-type/phase — runs inside an
+isolated git worktree rooted at
+`~/.okstra/worktrees/<project_id>/<task_group>/<task_id>/`. The same
+worktree is reused across all phases of one task-key (requirements-
+discovery → error-analysis → implementation-planning → implementation),
+so phase N picks up exactly the working-tree state phase N-1 left
+behind.
 
-Pre-conditions handled here:
-  - Skip non-`implementation` task-types entirely.
-  - Skip when `project_root` itself already sits inside a non-main git
-    worktree (the run reuses the caller's working tree).
-  - Refuse to clobber an existing path or branch — raise PrepareError.
+A global registry (`worktree_registry.py`) maps task-keys to the
+on-disk path + branch and serialises reservations, so two concurrent
+okstra runs cannot collide on the same path or branch name.
 
-Side effects: `git worktree add -b <branch> <path> <base_ref>` is invoked
-in `project_root`. The function does NOT chdir.
+Pre-conditions handled here:
+  - Skip when `project_root` is not a git repo (degrade gracefully).
+  - Skip when `project_root` itself is already a non-main worktree
+    (caller's tree is already an isolated workspace; reuse it).
+  - Re-entry of the same task-key returns the existing worktree.
+  - Branch / path collisions across task-keys raise PrepareError-like
+    RuntimeError.
+
+Side effects:
+  - `git worktree add -b <branch> <path> <base_ref>` invoked in the
+    main worktree of `project_root` (NOT `project_root` itself when it
+    is also a worktree — base must be the main checkout).
+  - Per-task sync dirs (.project-docs, .scratch, graphify-out by
+    default) symlinked from the **main worktree** into the new
+    worktree so every task sees the same shared state, irrespective of
+    which worktree the caller invoked okstra from.
+  - The function does NOT chdir.
 """
 from __future__ import annotations
 
@@ -23,17 +38,20 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Optional
 
+from .ids import _safe_fs_segment
+from . import worktree_registry
+
 
 OKSTRA_WORKTREES_RELATIVE = Path(".okstra/worktrees")
 
 
 # Project-root directories that hold okstra task state, ignored by git, or
 # otherwise required for the executor to operate but NOT carried across by
-# `git worktree add`. Each is symlinked from project_root into the new
-# worktree at provision time. Symlinks (not copies) so the executor sees
-# the live state and disk/CPU cost stays near zero; the trade-off is that
-# any write through the link reaches the original project_root, which is
-# acceptable because the executor only writes inside its own task-scoped
+# `git worktree add`. Each is symlinked from the MAIN worktree into the new
+# worktree at provision time. Symlinks (not copies) so every task sees the
+# live shared state and disk/CPU cost stays near zero; the trade-off is
+# that any write through the link reaches the main worktree, which is
+# acceptable because okstra only writes inside its own task-scoped
 # subdirectory (e.g. `.project-docs/okstra/tasks/<task-id>/runs/...`).
 #
 # Override via the `OKSTRA_WORKTREE_SYNC_DIRS` env var: a colon-separated
@@ -62,32 +80,45 @@ _WORK_CATEGORY_PREFIX = {
 
 @dataclass
 class WorktreeProvision:
-    """Result of `provision_implementation_worktree`.
+    """Result of `provision_task_worktree`.
 
     status:
       - "created": fresh worktree at `path` on `branch`
-      - "skipped-non-implementation": task-type was not `implementation`
-      - "skipped-in-worktree": project_root is already inside a non-main
+      - "reused": registry already had this task-key; same path/branch
+        returned and no new `git worktree add` was executed
+      - "skipped-in-worktree": project_root is itself a non-main
         worktree; the run reuses `project_root` and no new worktree is
-        materialised
+        materialised (registry NOT updated — that caller is already
+        isolated by virtue of its own worktree)
       - "skipped-not-git": project_root has no `.git` (worktree path
         cannot be provisioned; degrade gracefully)
     """
     status: str
-    path: str = ""          # absolute path of the executor worktree (or project_root when reused)
+    path: str = ""          # absolute path of the task worktree (or project_root when reused)
     branch: str = ""        # branch checked out in the worktree (empty when reused / not-git)
     base_ref: str = ""      # commit SHA the worktree was branched from (empty when not created)
     note: str = ""          # human-readable explanation, surfaced in team-state / manifests
 
 
+def _safe_segment(value: str) -> str:
+    """Sanitise a single path/branch segment.
+
+    Forbidden chars (`/`, `:`, spaces, anything outside `[a-z0-9-]`)
+    are collapsed to `-`. Empty result becomes `_` so we never create
+    an empty path component. Delegates to the canonical slugifier in
+    `ids.py` to stay in lock-step with run-id / manifest segmentation.
+    """
+    return _safe_fs_segment(value)
+
+
 def _work_category_prefix(work_category: str) -> str:
     key = (work_category or "").strip().lower()
     return _WORK_CATEGORY_PREFIX.get(key, "task")
 
 
-def _git(project_root: Path, *args: str) -> subprocess.CompletedProcess:
+def _git(cwd: Path, *args: str) -> subprocess.CompletedProcess:
     return subprocess.run(
-        ["git", "-C", str(project_root), *args],
+        ["git", "-C", str(cwd), *args],
         capture_output=True, text=True, check=False,
     )
 
@@ -101,7 +132,6 @@ def _is_inside_non_main_worktree(project_root: Path) -> bool:
     per_tree = _git(project_root, "rev-parse", "--git-dir")
     if common.returncode != 0 or per_tree.returncode != 0:
         return False
-    # Both paths can be relative to project_root; resolve before compare.
     common_abs = (project_root / common.stdout.strip()).resolve()
     per_tree_abs = (project_root / per_tree.stdout.strip()).resolve()
     return common_abs != per_tree_abs
@@ -117,13 +147,31 @@ def _branch_exists(project_root: Path, branch: str) -> bool:
     return res.returncode == 0
 
 
-def _head_sha(project_root: Path) -> str:
-    res = _git(project_root, "rev-parse", "HEAD")
+def _head_sha(cwd: Path) -> str:
+    res = _git(cwd, "rev-parse", "HEAD")
     if res.returncode != 0:
         return ""
     return res.stdout.strip()
 
 
+def _main_worktree_path(project_root: Path) -> Path:
+    """Locate the repository's MAIN worktree (the original checkout).
+
+    `git worktree list --porcelain` lists worktrees in a stable order
+    where the first `worktree <path>` block is the main checkout.
+    Falls back to `project_root` if parsing fails — caller still gets
+    a working path, sync-dir links just point at the caller's tree
+    (the prior behaviour).
+    """
+    res = _git(project_root, "worktree", "list", "--porcelain")
+    if res.returncode != 0:
+        return project_root
+    for line in res.stdout.splitlines():
+        if line.startswith("worktree "):
+            return Path(line[len("worktree "):].strip())
+    return project_root
+
+
 def _resolve_sync_dirs() -> tuple[str, ...]:
     """Return the list of project-root-relative dirs to symlink into the
     new worktree. Reads `OKSTRA_WORKTREE_SYNC_DIRS` if set (colon-separated,
@@ -138,11 +186,12 @@ def _resolve_sync_dirs() -> tuple[str, ...]:
     return tuple(part for part in (p.strip() for p in raw.split(":")) if part)
 
 
-def _link_sync_dirs(project_root: Path, worktree_path: Path) -> list[str]:
-    """Symlink each configured project-root dir into the new worktree.
+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.
 
     Skip rules:
-      - Source missing in project_root → silently skipped.
+      - Source missing in `source_root` → silently skipped.
       - Target path already exists in worktree (e.g. tracked content
         checked out by `git worktree add`) → skipped to avoid clobbering
         version-controlled files.
@@ -153,7 +202,7 @@ def _link_sync_dirs(project_root: Path, worktree_path: Path) -> list[str]:
     """
     notes: list[str] = []
     for rel in _resolve_sync_dirs():
-        src = (project_root / rel).resolve()
+        src = (source_root / rel).resolve()
         if not src.exists():
             continue
         dst = worktree_path / rel
@@ -170,17 +219,20 @@ def compute_worktree_path(
     project_id: str,
     task_group_segment: str,
     task_id_segment: str,
-    run_seq: int,
 ) -> Path:
-    """Pure path computation. Mirrors `okstra_root` location convention.
+    """Pure path computation. One worktree dir per task-key.
 
-    Uses `OKSTRA_HOME` when set (test hook), else `~/.okstra`.
+    Uses `OKSTRA_HOME` when set (test hook), else `~/.okstra`. Note
+    there is NO run-seq segment — every phase of the same task-key
+    shares this dir.
     """
     okstra_home = os.environ.get("OKSTRA_HOME", "").strip()
     base = Path(okstra_home) if okstra_home else (Path.home() / ".okstra")
     return (
-        base / "worktrees" / project_id
-        / task_group_segment / f"{task_id_segment}-{int(run_seq):03d}"
+        base / "worktrees"
+        / _safe_segment(project_id)
+        / _safe_segment(task_group_segment)
+        / _safe_segment(task_id_segment)
     )
 
 
@@ -188,46 +240,40 @@ def compute_branch_name(
     *,
     work_category: str,
     task_id_segment: str,
-    run_seq: int,
 ) -> str:
-    return f"{_work_category_prefix(work_category)}-{task_id_segment}-{int(run_seq):03d}"
+    """One branch per task-key. No run-seq — phases share the branch."""
+    return f"{_work_category_prefix(work_category)}-{_safe_segment(task_id_segment)}"
 
 
-def provision_implementation_worktree(
+def provision_task_worktree(
     *,
     task_type: str,
     project_root: Path,
     project_id: str,
     task_group_segment: str,
     task_id_segment: str,
-    run_seq: int,
     work_category: str,
 ) -> WorktreeProvision:
-    """Materialise (or skip) the executor worktree for this run.
+    """Materialise (or reuse) the task worktree for this run.
 
-    The caller passes the same `run_seq` used by the reports/manifests
-    artefacts so the worktree directory is colocated by sequence number.
+    First phase of a task-key creates the worktree on a new branch.
+    Subsequent phases of the same task-key look up the registry and
+    return the existing path + branch unchanged.
 
     Raises:
-        PrepareError-like RuntimeError when worktree creation fails
-        (path clash, branch clash, `git worktree add` non-zero). The
-        caller (`run.py`) catches and re-raises as PrepareError to keep
-        a single error surface.
+        RuntimeError when worktree creation fails (path clash on disk
+        that the registry does not know about, branch clash with a
+        different task-key, `git worktree add` non-zero). The caller
+        (`run.py`) catches and re-raises as PrepareError to keep a
+        single error surface.
     """
-    if task_type != "implementation":
-        return WorktreeProvision(
-            status="skipped-non-implementation",
-            path=str(project_root),
-            note="worktree provisioning skipped: task-type is not 'implementation'",
-        )
-
     if not _is_git_repo(project_root):
         return WorktreeProvision(
             status="skipped-not-git",
             path=str(project_root),
             note=(
                 "worktree provisioning skipped: project_root is not inside a git "
-                "repository; executor will operate directly on project_root"
+                "repository; task will operate directly on project_root"
             ),
         )
 
@@ -237,44 +283,62 @@ def provision_implementation_worktree(
             path=str(project_root),
             note=(
                 "worktree provisioning skipped: project_root is already inside a "
-                "non-main git worktree; executor reuses the caller's worktree"
+                "non-main git worktree; task reuses the caller's worktree"
+            ),
+        )
+
+    safe_project = _safe_segment(project_id)
+    safe_group = _safe_segment(task_group_segment)
+    safe_task = _safe_segment(task_id_segment)
+
+    # Registry lookup first — same task-key across phases must reuse.
+    existing = worktree_registry.lookup(safe_project, safe_group, safe_task)
+    if existing is not None and existing.status == "active":
+        worktree_registry.touch_phase(safe_project, safe_group, safe_task, task_type)
+        return WorktreeProvision(
+            status="reused",
+            path=existing.worktree_path,
+            branch=existing.branch,
+            base_ref=existing.base_ref,
+            note=(
+                f"task worktree reused at {existing.worktree_path} on branch "
+                f"{existing.branch} (base {existing.base_ref[:12]}); phase {task_type}"
             ),
         )
 
     worktree_path = compute_worktree_path(
-        project_id=project_id,
-        task_group_segment=task_group_segment,
-        task_id_segment=task_id_segment,
-        run_seq=run_seq,
+        project_id=safe_project,
+        task_group_segment=safe_group,
+        task_id_segment=safe_task,
     )
     branch = compute_branch_name(
         work_category=work_category,
-        task_id_segment=task_id_segment,
-        run_seq=run_seq,
+        task_id_segment=safe_task,
     )
 
     if worktree_path.exists():
         raise RuntimeError(
-            f"executor worktree path already exists: {worktree_path}. "
-            "Remove it with `git worktree remove <path>` (or `rm -rf` if it is "
-            "not a registered worktree) before retrying this implementation run."
+            f"task worktree path already exists but is not in the registry: "
+            f"{worktree_path}. Remove it with `git worktree remove <path>` "
+            "(or `rm -rf` if it is not a registered worktree) before retrying."
         )
     if _branch_exists(project_root, branch):
         raise RuntimeError(
-            f"executor worktree branch already exists: {branch}. "
-            "Delete it (`git branch -D <branch>`) or bump OKSTRA_RUN_SEQ_OVERRIDE "
-            "before retrying."
+            f"task worktree branch already exists: {branch}. "
+            "Delete it (`git branch -D <branch>`) or choose a different "
+            "work-category before retrying."
         )
 
-    base_ref = _head_sha(project_root)
+    main_root = _main_worktree_path(project_root)
+    base_ref = _head_sha(main_root)
     if not base_ref:
         raise RuntimeError(
-            "could not resolve HEAD sha in project_root; cannot create worktree"
+            "could not resolve HEAD sha in main worktree; cannot create task worktree"
         )
 
     worktree_path.parent.mkdir(parents=True, exist_ok=True)
     res = _git(
-        project_root,
+        main_root,
         "worktree", "add", "-b", branch, str(worktree_path), base_ref,
     )
     if res.returncode != 0:
@@ -283,16 +347,35 @@ def provision_implementation_worktree(
             f"{(res.stderr or res.stdout).strip()}"
         )
 
-    linked = _link_sync_dirs(project_root, worktree_path)
+    # Sync dirs sourced from the MAIN worktree so every task sees the
+    # same shared state regardless of which checkout invoked okstra.
+    linked = _link_sync_dirs(main_root, worktree_path)
     linked_suffix = f"; linked {', '.join(linked)}" if linked else ""
 
+    try:
+        worktree_registry.reserve(
+            project_id=safe_project,
+            task_group=safe_group,
+            task_id=safe_task,
+            worktree_path=str(worktree_path),
+            branch=branch,
+            base_ref=base_ref,
+            phase=task_type,
+        )
+    except RuntimeError:
+        # Roll back the on-disk worktree so the next attempt is not
+        # blocked by the lingering directory / branch.
+        _git(main_root, "worktree", "remove", "--force", str(worktree_path))
+        _git(main_root, "branch", "-D", branch)
+        raise
+
     return WorktreeProvision(
         status="created",
         path=str(worktree_path),
         branch=branch,
         base_ref=base_ref,
         note=(
-            f"executor worktree created at {worktree_path} on branch {branch} "
-            f"(base {base_ref[:12]}){linked_suffix}"
+            f"task worktree created at {worktree_path} on branch {branch} "
+            f"(base {base_ref[:12]}; phase {task_type}){linked_suffix}"
         ),
     )

package/runtime/python/okstra_ctl/worktree_registry.py

@@ -0,0 +1,211 @@
+"""Global task-worktree registry.
+
+Tracks which `(project_id, task_group, task_id)` task-key owns which
+on-disk worktree path and branch, across concurrent okstra runs on the
+same machine. The registry lives under `OKSTRA_HOME` (default
+`~/.okstra`) and is guarded by an `fcntl` exclusive lock so that two
+processes cannot race to reserve the same path or branch.
+
+Why a global registry:
+  - A single task-key spans multiple phases (requirements-discovery →
+    error-analysis → implementation-planning → implementation). All
+    phases must land in the **same** worktree on the **same** branch.
+    Re-entry from any phase must look up the existing entry instead of
+    creating a duplicate.
+  - Two different task-keys must never collide on the same branch name.
+    A global branch index makes that detectable cheaply.
+  - Cleanup of stale entries (worktree dir removed manually) needs a
+    single source of truth.
+
+The registry is intentionally JSON-on-disk (no SQLite): the data set is
+tiny (one row per active task on this machine) and the human-readable
+file is useful for debugging.
+"""
+from __future__ import annotations
+
+import contextlib
+import fcntl
+import json
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+REGISTRY_FILENAME = "registry.json"
+LOCK_FILENAME = "registry.lock"
+
+
+def _okstra_worktrees_dir() -> Path:
+    home_env = os.environ.get("OKSTRA_HOME", "").strip()
+    base = Path(home_env) if home_env else (Path.home() / ".okstra")
+    return base / "worktrees"
+
+
+def task_key(project_id: str, task_group: str, task_id: str) -> str:
+    """Canonical task-key string used as the registry primary key.
+
+    Segments are NOT re-slugified here — callers must pass already
+    sanitised segments (see `worktree._safe_segment`). The key form
+    `<project>/<group>/<task>` is the same shape used for filesystem
+    paths so a key can be visually correlated with the worktree dir.
+    """
+    return f"{project_id}/{task_group}/{task_id}"
+
+
+@dataclass
+class WorktreeEntry:
+    task_key: str
+    project_id: str
+    task_group: str
+    task_id: str
+    worktree_path: str
+    branch: str
+    base_ref: str
+    created_at: str
+    last_phase: str = ""
+    status: str = "active"  # "active" | "released"
+
+
+@contextlib.contextmanager
+def _registry_lock():
+    """Exclusive flock on `<worktrees>/registry.lock`. Mirrors the
+    `central_lock` pattern from `locks.py` but scoped to the registry
+    so we do not serialise unrelated central operations.
+    """
+    root = _okstra_worktrees_dir()
+    root.mkdir(parents=True, exist_ok=True)
+    lockfile = root / LOCK_FILENAME
+    if not lockfile.exists():
+        lockfile.touch()
+    f = lockfile.open("r+")
+    try:
+        fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+        yield
+    finally:
+        f.close()
+
+
+def _registry_path() -> Path:
+    return _okstra_worktrees_dir() / REGISTRY_FILENAME
+
+
+def _load() -> dict:
+    p = _registry_path()
+    if not p.exists():
+        return {"tasks": {}, "branches": {}}
+    try:
+        data = json.loads(p.read_text())
+    except (OSError, json.JSONDecodeError):
+        return {"tasks": {}, "branches": {}}
+    data.setdefault("tasks", {})
+    data.setdefault("branches", {})
+    return data
+
+
+def _save(data: dict) -> None:
+    p = _registry_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    tmp = p.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+    os.replace(tmp, p)
+
+
+def lookup(project_id: str, task_group: str, task_id: str) -> Optional[WorktreeEntry]:
+    """Return the registered entry for this task-key, or None.
+
+    Does not validate that `worktree_path` still exists on disk — that
+    is the caller's responsibility (so reclaim logic can decide policy).
+    """
+    key = task_key(project_id, task_group, task_id)
+    with _registry_lock():
+        data = _load()
+        row = data["tasks"].get(key)
+        if not row:
+            return None
+        return WorktreeEntry(task_key=key, **row)
+
+
+def reserve(
+    *,
+    project_id: str,
+    task_group: str,
+    task_id: str,
+    worktree_path: str,
+    branch: str,
+    base_ref: str,
+    phase: str = "",
+) -> 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)
+    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]
+            raise RuntimeError(
+                f"task-key already has a worktree registered: {key} → "
+                f"{existing['worktree_path']} (branch {existing['branch']}). "
+                "Use `lookup` to reuse it, or release it before reserving anew."
+            )
+        owner = data["branches"].get(branch)
+        if owner and owner != key:
+            raise RuntimeError(
+                f"branch {branch!r} is already registered to a different "
+                f"task-key: {owner}. Choose a different work-category or "
+                "release the conflicting task first."
+            )
+        row = {
+            "project_id": project_id,
+            "task_group": task_group,
+            "task_id": task_id,
+            "worktree_path": worktree_path,
+            "branch": branch,
+            "base_ref": base_ref,
+            "created_at": now,
+            "last_phase": phase,
+            "status": "active",
+        }
+        data["tasks"][key] = row
+        data["branches"][branch] = key
+        _save(data)
+        return WorktreeEntry(task_key=key, **row)
+
+
+def touch_phase(project_id: str, task_group: str, task_id: str, phase: str) -> None:
+    """Record the most recent phase observed on this worktree.
+    Best-effort: silently no-ops if the task-key is not registered.
+    """
+    key = task_key(project_id, task_group, task_id)
+    with _registry_lock():
+        data = _load()
+        row = data["tasks"].get(key)
+        if not row:
+            return
+        row["last_phase"] = phase
+        _save(data)
+
+
+def release(project_id: str, task_group: str, task_id: str) -> 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)
+    with _registry_lock():
+        data = _load()
+        row = data["tasks"].get(key)
+        if not row:
+            return None
+        row["status"] = "released"
+        # Free the branch slot so reuse / new task can reclaim the name.
+        if data["branches"].get(row["branch"]) == key:
+            del data["branches"][row["branch"]]
+        _save(data)
+        return WorktreeEntry(task_key=key, **row)

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

@@ -14,13 +14,18 @@ description: Use when the user asks to list past okstra runs, check execution hi
 ## Step 0: Verify okstra runtime + project setup
 
 ```bash
-npx -y okstra@latest ensure-installed >/dev/null 2>&1 || {
+if command -v okstra >/dev/null 2>&1; then
+  OKSTRA_CMD="okstra"
+else
+  OKSTRA_CMD="npx -y okstra@latest"
+fi
+$OKSTRA_CMD ensure-installed >/dev/null 2>&1 || {
   echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
   exit 1
 }
-eval "$(npx -y okstra@latest paths --shell)"
+eval "$($OKSTRA_CMD paths --shell)"
 export PYTHONPATH="$OKSTRA_PYTHONPATH"
-OKSTRA_PROJECT_INFO="$(npx -y okstra@latest check-project --json)" || {
+OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
   echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
   echo "$OKSTRA_PROJECT_INFO" >&2
   exit 1

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

@@ -15,13 +15,18 @@ user-invocable: false
 ## Step 0: Verify okstra runtime + project setup
 
 ```bash
-npx -y okstra@latest ensure-installed >/dev/null 2>&1 || {
+if command -v okstra >/dev/null 2>&1; then
+  OKSTRA_CMD="okstra"
+else
+  OKSTRA_CMD="npx -y okstra@latest"
+fi
+$OKSTRA_CMD ensure-installed >/dev/null 2>&1 || {
   echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
   exit 1
 }
-eval "$(npx -y okstra@latest paths --shell)"
+eval "$($OKSTRA_CMD paths --shell)"
 export PYTHONPATH="$OKSTRA_PYTHONPATH"
-OKSTRA_PROJECT_INFO="$(npx -y okstra@latest check-project --json)" || {
+OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
   echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
   echo "$OKSTRA_PROJECT_INFO" >&2
   exit 1

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

@@ -199,7 +199,9 @@ The final-report template `okstra-final-report.template.md` Section 4.5 already
 
 ### Release-handoff section contract (release-handoff runs only)
 
-When the run's `task-type` is `release-handoff`, the final report MUST include Section `## 4.6 Release Handoff Deliverables` with all seven sub-sections (`4.6.1` Source Verification Report, `4.6.2` Feature Branch & Working-Tree State, `4.6.3` User Selections, `4.6.4` Executed Commands, `4.6.5` Commit List, `4.6.6` Pull Request Outcome, `4.6.7` Routing Recommendation). The drafter does **not** invent values for these sub-sections — every entry is dictated by the lead's recorded git/gh command log and the user's verbatim answers to the H1/H2/H3 menu prompts. If the user picked `skip` (H1) or `cancel` (H3), keep 4.6.3 populated but leave 4.6.4–4.6.6 explicitly empty per the template's empty-state lines.
+When the run's `task-type` is `release-handoff`, the final report MUST include Section `## 4.6 Release Handoff Deliverables` with all seven sub-sections (`4.6.1` Source Verification Report, `4.6.2` Feature Branch & Working-Tree State, `4.6.3` User Selections, `4.6.4` Executed Commands, `4.6.5` Commit List, `4.6.6` Pull Request Outcome, `4.6.7` Routing Recommendation). Every entry is dictated by the lead's recorded git/gh command log and the user's verbatim answers to the H1/H2/H3 menu prompts. If the user picked `skip` (H1) or `cancel` (H3), keep 4.6.3 populated but leave 4.6.4–4.6.6 explicitly empty per the template's empty-state lines.
+
+**Single-lead authorship (release-handoff only):** release-handoff has no worker roster (no `Report writer worker`, no `Claude worker` drafter). The Claude lead authors the final-report file directly — there is no `Report writer worker` dispatch to perform in Phase 6, no resume-safe dispatch concern, and no mandatory worker-results file for a report-writer role. The rest of this skill's dispatch / resume / fallback machinery applies ONLY when `Report writer worker` is in the roster (i.e. every task-type other than `release-handoff`).
 
 The final-report template `okstra-final-report.template.md` Section 4.6 already encodes this contract — copy that block verbatim and fill in. For non-`release-handoff` runs, omit Section 4.6 entirely.