okstra 0.11.0 → 0.13.0

package/runtime/python/okstra_ctl/worktree.py

@@ -1,48 +1,73 @@
-"""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
 
+import json
 import os
 import subprocess
 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
-# list of project-root-relative paths that REPLACES this default. Use an
-# empty string to disable the feature entirely.
+# Override precedence (most-specific first):
+#   1. `OKSTRA_WORKTREE_SYNC_DIRS` env var — colon-separated list, REPLACES
+#      defaults. Empty string disables the feature entirely. One-off
+#      operator override.
+#   2. `worktreeSyncDirs` array in `.project-docs/okstra/project.json` —
+#      project-level config, persists across runs. Same semantics: array
+#      REPLACES defaults, empty array disables.
+#   3. The built-in `DEFAULT_WORKTREE_SYNC_DIRS` below.
 DEFAULT_WORKTREE_SYNC_DIRS: tuple[str, ...] = (
     ".project-docs",
     ".scratch",
     "graphify-out",
+    ".claude",
 )
 
 
@@ -62,32 +87,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 +139,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,32 +154,83 @@ 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 _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,
-    empty string disables); otherwise returns the built-in default.
+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).
     """
-    raw = os.environ.get("OKSTRA_WORKTREE_SYNC_DIRS")
-    if raw is None:
-        return DEFAULT_WORKTREE_SYNC_DIRS
-    raw = raw.strip()
-    if not raw:
-        return ()
-    return tuple(part for part in (p.strip() for p in raw.split(":")) if part)
+    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 _read_project_json_sync_dirs(project_root: Path) -> Optional[tuple[str, ...]]:
+    """Read `worktreeSyncDirs` from `.project-docs/okstra/project.json`.
 
-def _link_sync_dirs(project_root: Path, worktree_path: Path) -> list[str]:
-    """Symlink each configured project-root dir into the new worktree.
+    Returns None if the field is absent or the file cannot be parsed (so
+    the caller falls back to defaults). Returns an empty tuple if the
+    field is explicitly an empty array (caller treats this as "disable").
+    A non-list value is treated as missing — we do not raise here because
+    sync-dir resolution must never block worktree provisioning.
+    """
+    target = project_root / ".project-docs" / "okstra" / "project.json"
+    if not target.is_file():
+        return None
+    try:
+        data = json.loads(target.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    value = data.get("worktreeSyncDirs")
+    if not isinstance(value, list):
+        return None
+    cleaned = tuple(
+        item.strip() for item in value
+        if isinstance(item, str) and item.strip()
+    )
+    return cleaned
+
+
+def _resolve_sync_dirs(project_root: Optional[Path] = None) -> tuple[str, ...]:
+    """Return the list of project-root-relative dirs to symlink into the
+    new worktree. Precedence: env var → project.json → built-in default.
+    See the comment above `DEFAULT_WORKTREE_SYNC_DIRS` for full semantics.
+    """
+    raw = os.environ.get("OKSTRA_WORKTREE_SYNC_DIRS")
+    if raw is not None:
+        raw = raw.strip()
+        if not raw:
+            return ()
+        return tuple(part for part in (p.strip() for p in raw.split(":")) if part)
+    if project_root is not None:
+        from_project = _read_project_json_sync_dirs(project_root)
+        if from_project is not None:
+            return from_project
+    return DEFAULT_WORKTREE_SYNC_DIRS
+
+
+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.
@@ -152,8 +240,8 @@ def _link_sync_dirs(project_root: Path, worktree_path: Path) -> list[str]:
     caller can include them in the provisioning note.
     """
     notes: list[str] = []
-    for rel in _resolve_sync_dirs():
-        src = (project_root / rel).resolve()
+    for rel in _resolve_sync_dirs(source_root):
+        src = (source_root / rel).resolve()
         if not src.exists():
             continue
         dst = worktree_path / rel
@@ -170,17 +258,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 +279,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 +322,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 +386,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}"
         ),
     )