okstra 0.11.0 → 0.13.0

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/python/okstra_project/resolver.py

@@ -117,12 +117,15 @@ def upsert_project_json(project_root: Path, project_id: str, *,
                 f"or manually delete {target} if you intend to re-register this directory "
                 f"under a different id. "
                 f"(projectId 불일치: 한 PROJECT_ROOT 에는 하나의 projectId 만 허용됩니다.)")
-        result = {
-            "projectId": project_id,
-            "projectRoot": abs_root,
-            "createdAt": str(data.get("createdAt") or when),
-            "updatedAt": when,
-        }
+        # Preserve any user-managed fields (e.g. `worktreeSyncDirs`,
+        # `mcpServers`) so manual edits to project.json are not wiped
+        # by the per-run self-registration upsert. Only the canonical
+        # identity/timestamp fields below are owned by this function.
+        result = dict(data) if isinstance(data, dict) else {}
+        result["projectId"] = project_id
+        result["projectRoot"] = abs_root
+        result["createdAt"] = str(data.get("createdAt") or when)
+        result["updatedAt"] = when
     else:
         result = {
             "projectId": project_id,

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.
 

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

@@ -148,15 +148,59 @@ If `implementation` chosen, ask two more `AskUserQuestion` in order:
 
 ## Step 6 (optional): Directive / workers / models / related / clarification
 
-Single `AskUserQuestion` first: `"Use default workers and models, or customize?"`
+Single `AskUserQuestion` first: `"기본 워커/모델로 진행할까요, 아니면 커스터마이즈할까요?"` (options: `Use defaults`, `Customize`).
 
 - `Use defaults` → all overrides remain empty.
-- `Customize` → ask each in turn (free text, blank = use default):
-  - workers CSV (subset of `claude,codex,gemini,report-writer`)
-  - `lead-model`, `claude-model`, `codex-model`, `gemini-model`, `report-writer-model`
-  - `directive`
-  - `related-tasks` CSV
-  - `clarification-response` path (relevant for follow-up `requirements-discovery` / `error-analysis` runs)
+- `Customize` → the prompts you ask depend on the `task_type` chosen in Step 4. Blank answer always means "use default". Never call the prompt label "worker CSV" — use plain Korean labels as shown below.
+
+### 6a. `implementation` phase (executor-driven)
+
+In this phase the roster is fixed by the profile (executor + two verifiers + report-writer). The Step 4 `executor` answer already determines who mutates code; verifier models use phase-specific defaults (`Claude verifier`=sonnet, `Codex verifier`=gpt-5.5, `Gemini verifier`=auto). So ask **only three model prompts**, plus directive/related/clarification:
+
+1. `"리더(Claude lead) 모델? (빈 칸 = 기본값)"` → `lead_model`
+2. `"실행자({executor-provider}) 모델? (빈 칸 = 기본값)"` → maps to `claude_model` / `codex_model` / `gemini_model` based on the Step 4 executor choice. The other two provider model fields stay empty (verifiers use defaults).
+3. `"리포트 작성자(report-writer) 모델? (빈 칸 = 기본값)"` → `report_writer_model`
+4. `"추가 directive (선택, 빈 칸 가능)"` → `directive`
+5. `"관련 task id 목록, 쉼표 구분 (선택, 빈 칸 가능)"` → `related_tasks_raw`
+
+Do NOT ask for `workers_override` in implementation — the profile's required roster must be preserved (verifier slots are mandatory). Leave `workers_override=""`.
+
+### 6b. Other phases (`requirements-discovery`, `error-analysis`, `implementation-planning`, `final-verification`, `release-handoff`)
+
+Ask each in turn (free text, blank = default):
+
+1. `"참여 워커 목록 (쉼표 구분, 빈 칸 = 프로필 기본값). 선택지: claude, codex, gemini, report-writer"` → `workers_override`
+2. `"리더(Claude lead) 모델? (빈 칸 = 기본값)"` → `lead_model`
+3. `"claude 워커 모델? (빈 칸 = 기본값)"` → `claude_model`
+4. `"codex 워커 모델? (빈 칸 = 기본값)"` → `codex_model`
+5. `"gemini 워커 모델? (빈 칸 = 기본값)"` → `gemini_model`
+6. `"리포트 작성자 모델? (빈 칸 = 기본값)"` → `report_writer_model`
+7. `"추가 directive (선택, 빈 칸 가능)"` → `directive`
+8. `"관련 task id 목록, 쉼표 구분 (선택, 빈 칸 가능)"` → `related_tasks_raw`
+9. `"clarification-response 파일 경로 (follow-up 시에만, 빈 칸 가능)"` → `clarification_response_path`
+
+For prompts whose target worker is NOT in the resolved workers list (after override), skip the prompt and present a single line such as `gemini-model 생략 (workers에 gemini 없음)`.
+
+## Step 6.5: Confirm selections before rendering
+
+Before calling `prepare_task_bundle`, echo the resolved selections back to the user in a compact block so they can verify what will be passed. Show the **effective** values, not the raw input — i.e. when the user left a field blank, display `default` (and where known, the actual default such as `opus` / `sonnet`). Example for an `implementation` run:
+
+```
+선택 확인:
+  task-type     : implementation
+  task-key      : <group>/<id>
+  executor      : codex
+  workers       : (프로필 기본 — executor + verifier 2 + report-writer)
+  lead-model    : default (opus)
+  codex-model   : gpt-5.5-high           ← executor model
+  claude-model  : default (sonnet)       ← verifier
+  gemini-model  : default (auto)         ← verifier
+  report-writer : default (opus)
+  directive     : (none)
+  approved-plan : <abs path>
+```
+
+Then `AskUserQuestion`: `"이대로 진행할까요?"` with options `Proceed` / `Edit`. On `Edit`, return to the relevant Step 6 sub-prompt.
 
 ## Step 7: Call `prepare_task_bundle` directly
 
@@ -182,7 +226,7 @@ out = prepare_task_bundle(PrepareInputs(
     task_type="<task-type>",
     brief_path=brief_abs,
     directive="<directive or empty>",
-    workers_override="<workers csv or empty>",
+    workers_override="<comma-separated worker list, or empty for profile default; MUST be empty for implementation>",
     lead_model="...", claude_model="...", codex_model="...",
     gemini_model="...", report_writer_model="...",
     related_tasks_raw="...",

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

@@ -116,6 +116,32 @@ print(result)
 PY
 ```
 
+## Step 4.5 (optional): customise worktree sync dirs
+
+Each okstra run provisions a task-scoped git worktree under
+`~/.okstra/worktrees/.../`. A small set of project-root-relative
+directories is symlinked from the main checkout into that worktree so
+every task sees the shared state. The built-in default is
+`.project-docs`, `.scratch`, `graphify-out`, `.claude`.
+
+To override per-project, add a `worktreeSyncDirs` array to
+`project.json`. Empty array disables the feature; the field is
+preserved across the runtime's auto-upserts (only `projectId`,
+`projectRoot`, `createdAt`, `updatedAt` are runtime-owned).
+
+```json
+{
+  "projectId": "...",
+  "projectRoot": "...",
+  "worktreeSyncDirs": [".project-docs", ".scratch", ".claude", "my-custom-dir"]
+}
+```
+
+Resolution precedence: `OKSTRA_WORKTREE_SYNC_DIRS` env var → this
+field → built-in default. Only edit when defaults don't cover the
+project's working files (e.g. additional cache or local-config dirs
+that must follow the executor into the worktree).
+
 ## Step 5: Verify
 
 ```bash