okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/worktree/__init__.py

@@ -0,0 +1,92 @@
+"""Per-task git worktree provisioning.
+
+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-option-selection →
+implementation-planning → implementation), so phase N picks up exactly
+the working-tree state phase N-1 left behind.
+
+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.
+
+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.
+
+구현은 여섯 층으로 나뉜다. 바닥의 세 층 — `naming`(문자열 계산),
+`sync_config`(무엇을 옮길지), `git_ops`(git 사실) — 은 서로를 모른다. 그 위에
+`cleanliness`(무엇이 더러운가) · `linking`(실제로 링크 걸기) ·
+`decisions`(무엇이 일어날지 미리 답하기)가 있고, 부수 효과를 내는 것은
+`provision` 하나뿐이다. 이 파일은 밖으로 나가는 이름만 모아 둔다.
+"""
+from __future__ import annotations
+
+from .cleanliness import (
+    dirty_entries_excluding_okstra,
+    is_dirty_excluding_okstra,
+    nested_worktree_excludes,
+    okstra_clean_gate_excludes,
+)
+from .decisions import (
+    StageWorktreeDecision,
+    WorktreeDecision,
+    preview_worktree_decision,
+    resolve_stage_worktree_decision,
+)
+from .git_ops import (
+    MergeError,
+    _git,
+    _resolve_commit_sha,
+    is_ancestor,
+    is_git_work_tree,
+    main_worktree_path,
+    merge_branch,
+    remove_worktree_force,
+)
+from .naming import compute_branch_name, compute_worktree_path
+from .provision import (
+    WorktreeProvision,
+    provision_stage_worktree,
+    provision_task_worktree,
+)
+
+__all__ = [
+    "MergeError",
+    "StageWorktreeDecision",
+    "WorktreeDecision",
+    "WorktreeProvision",
+    "_git",
+    "_resolve_commit_sha",
+    "compute_branch_name",
+    "compute_worktree_path",
+    "dirty_entries_excluding_okstra",
+    "is_ancestor",
+    "is_dirty_excluding_okstra",
+    "is_git_work_tree",
+    "main_worktree_path",
+    "merge_branch",
+    "nested_worktree_excludes",
+    "okstra_clean_gate_excludes",
+    "preview_worktree_decision",
+    "provision_stage_worktree",
+    "provision_task_worktree",
+    "remove_worktree_force",
+    "resolve_stage_worktree_decision",
+]

package/runtime/python/okstra_ctl/worktree/cleanliness.py

@@ -0,0 +1,89 @@
+"""okstra 기준으로 worktree 가 깨끗한지 판정한다.
+
+`git status` 가 보는 더러움과 okstra 가 신경 쓰는 더러움은 다르다. okstra 는
+자기 산출물(`.okstra/`), 자기가 걸어 둔 sync 심링크, 자기가 만든 중첩 worktree
+를 제외하고 남는 변경만 사용자의 것으로 본다. 그 제외 목록을 만드는 곳이
+여기이고, 그래서 `sync_config`(무엇을 걸었나)와 `git_ops`(지금 무엇이 바뀌었나)
+양쪽을 쓴다.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from .git_ops import _git
+from .sync_config import (
+    _resolve_snapshot_files,
+    _resolve_sync_dirs,
+    _resolve_sync_files,
+)
+
+
+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 nested_worktree_excludes(worktree_path) -> tuple[str, ...]:
+    """Relative paths of git worktrees nested under `worktree_path`.
+
+    implementation stage worktrees live inside the task worktree
+    (`<task-id>/stage-<N>/`), so the parent's `git status --short` reports
+    each as an untracked `?? stage-N/`. They are git-registered worktrees,
+    not user source changes, so clean gates must ignore them. Derived from
+    `git worktree list` rather than a hardcoded pattern so it tracks exactly
+    what git registered.
+    """
+    root = Path(worktree_path).resolve()
+    r = _git(root, "worktree", "list", "--porcelain")
+    if r.returncode != 0:
+        return ()
+    out: list[str] = []
+    for line in r.stdout.splitlines():
+        if not line.startswith("worktree "):
+            continue
+        wt = Path(line[len("worktree "):].strip()).resolve()
+        if wt == root:
+            continue
+        try:
+            rel = wt.relative_to(root)
+        except ValueError:
+            continue
+        out.append(str(rel))
+    return tuple(out)
+
+
+def dirty_entries_excluding_okstra(cwd) -> list[str]:
+    """`git status --short` rows for changes outside okstra-owned paths.
+
+    okstra-owned = `okstra_clean_gate_excludes` (e.g. `.okstra`, synced dirs)
+    plus `nested_worktree_excludes` (stage worktrees nested under `cwd`).
+
+    This is the clean-worktree question every okstra gate asks, and the one a
+    plan step must ask through `okstra worktree-status` rather than through a
+    bare `git status --porcelain`: okstra provisions `.okstra` plus the synced
+    entries into every task worktree, so a bare status is never empty there and
+    an assertion built on it fails on okstra's own scaffolding.
+    """
+    owned = (*okstra_clean_gate_excludes(Path(cwd)), *nested_worktree_excludes(cwd))
+    excludes = [f":(exclude){p}" for p in owned]
+    out = _git(Path(cwd), "status", "--short", "--", ".", *excludes).stdout
+    return [line for line in out.splitlines() if line.strip()]
+
+
+def is_dirty_excluding_okstra(cwd) -> bool:
+    """True iff the worktree has changes outside okstra-owned paths."""
+    return bool(dirty_entries_excluding_okstra(cwd))

package/runtime/python/okstra_ctl/worktree/decisions.py

@@ -0,0 +1,127 @@
+"""provision 하기 전에 무엇이 일어날지 답한다.
+
+위저드는 사용자에게 경로와 브랜치를 보여 준 뒤 확인을 받는다. 그 시점에 이미
+worktree 를 만들어 버리면 안 되므로, 판단(재사용인가 신규인가, 어느 경로인가)만
+떼어 여기에 둔다. 레지스트리를 읽기는 하지만 예약하지는 않는다 — 예약은
+`provision` 의 몫이다.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .. import worktree_registry
+from .git_ops import _is_inside_non_main_worktree, is_git_work_tree
+from .naming import _safe_segment, compute_branch_name, compute_worktree_path
+
+
+@dataclass
+class WorktreeDecision:
+    """Side-effect-free preview of what `provision_task_worktree` would do.
+
+    status:
+      - "new": no active registry entry; a fresh worktree would be created
+      - "reused": registry already has this task-key; existing path/branch returned
+      - "skipped-in-worktree": project_root is itself a non-main worktree
+      - "skipped-not-git": project_root has no .git
+    """
+    status: str
+    path: str              # worktree path (new: prospective; reuse: existing; skip: project_root)
+    branch: str = ""       # new: prospective branch; reused: existing branch
+    base_ref: str = ""     # new: requested base_ref; reused: existing base
+
+
+def preview_worktree_decision(
+    *,
+    project_root,
+    project_id: str,
+    task_group_segment: str,
+    task_id_segment: str,
+    work_category: str,
+    base_ref: str = "",
+) -> "WorktreeDecision":
+    """Side-effect-free: what provision_task_worktree WOULD do, without touching disk.
+
+    Mirrors provision's decision branches exactly; reuses the same read-only
+    helpers so preview never diverges from the actual provisioning result.
+    """
+    project_root = Path(project_root)
+    if not is_git_work_tree(project_root):
+        return WorktreeDecision(status="skipped-not-git", path=str(project_root))
+    if _is_inside_non_main_worktree(project_root):
+        return WorktreeDecision(status="skipped-in-worktree", path=str(project_root))
+    safe_project = _safe_segment(project_id)
+    safe_group = _safe_segment(task_group_segment)
+    safe_task = _safe_segment(task_id_segment)
+    existing = worktree_registry.lookup(safe_project, safe_group, safe_task)
+    if existing is not None and existing.status == "active":
+        return WorktreeDecision(
+            status="reused", path=existing.worktree_path,
+            branch=existing.branch, base_ref=existing.base_ref,
+        )
+    return WorktreeDecision(
+        status="new",
+        path=str(compute_worktree_path(
+            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=safe_task),
+        base_ref=base_ref,
+    )
+
+
+@dataclass
+class StageWorktreeDecision:
+    """Side-effect-free decision for one concrete implementation stage."""
+
+    status: str
+    path: str
+    branch: str = ""
+    base_ref: str = ""
+
+
+def resolve_stage_worktree_decision(
+    *,
+    project_id: str,
+    task_group_segment: str,
+    task_id_segment: str,
+    work_category: str,
+    stage_number: int,
+) -> StageWorktreeDecision:
+    """Resolve whether one concrete stage worktree is new or reusable."""
+    safe_project = _safe_segment(project_id)
+    safe_group = _safe_segment(task_group_segment)
+    safe_task = _safe_segment(task_id_segment)
+    existing = worktree_registry.lookup(
+        safe_project, safe_group, safe_task, stage_number=stage_number)
+    if existing is not None and _stage_entry_is_reusable(existing):
+        return StageWorktreeDecision(
+            status="reused",
+            path=existing.worktree_path,
+            branch=existing.branch,
+            base_ref=existing.base_ref,
+        )
+    return StageWorktreeDecision(
+        status="new",
+        path=str(compute_worktree_path(
+            project_id=safe_project, task_group_segment=safe_group,
+            task_id_segment=safe_task, stage_number=stage_number)),
+        branch=compute_branch_name(
+            work_category=work_category, task_id_segment=safe_task,
+            stage_number=stage_number),
+    )
+
+
+def _stage_entry_is_reusable(entry: worktree_registry.WorktreeEntry) -> bool:
+    """Whether a registered stage worktree can be entered by this run.
+
+    `active` is the live-run case. `released` with the directory still on disk is
+    the fix-run case: a stage whose verifier returned FAIL records a `failed`
+    consumers row, which frees the occupancy but deliberately keeps the worktree
+    and its branch as the reviewable stack. Re-entry MUST reuse that tree —
+    provisioning anew refuses on the existing path and branch. After whole-task
+    final-verification removes the directory the entry stops being reusable, so
+    the stage provisions from scratch.
+    """
+    if entry.status == "active":
+        return True
+    return entry.status == "released" and Path(entry.worktree_path).is_dir()

package/runtime/python/okstra_ctl/worktree/git_ops.py

@@ -0,0 +1,165 @@
+"""worktree 가 쓰는 git 명령 한 겹.
+
+`_git` 은 `check=False` 라서 호출부가 returncode 를 보고 판단한다. 이 층은
+okstra 의 규칙을 하나도 모른다 — 브랜치가 존재하는지, HEAD 가 무엇인지,
+머지가 충돌했는지 같은 git 사실만 답한다. okstra 가 무엇을 무시하기로 했는지는
+`cleanliness` 가, 무엇을 옮기기로 했는지는 `sync_config` 가 안다.
+"""
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+def _git(cwd: Path, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", "-C", str(cwd), *args],
+        capture_output=True, text=True, check=False,
+    )
+
+
+def _is_inside_non_main_worktree(project_root: Path) -> bool:
+    """True iff project_root is inside a git worktree that is NOT the
+    repository's main checkout. Detection rule: `--git-dir` (per-worktree
+    .git pointer) differs from `--git-common-dir` (shared object store).
+    """
+    common = _git(project_root, "rev-parse", "--git-common-dir")
+    per_tree = _git(project_root, "rev-parse", "--git-dir")
+    if common.returncode != 0 or per_tree.returncode != 0:
+        return False
+    common_abs = (project_root / common.stdout.strip()).resolve()
+    per_tree_abs = (project_root / per_tree.stdout.strip()).resolve()
+    return common_abs != per_tree_abs
+
+
+def is_git_work_tree(project_root: Path) -> bool:
+    """project_root 가 git work tree 내부인지 판정하는 public git-introspection seam.
+
+    git 미설치(FileNotFoundError) 를 포함한 모든 실패는 False — 호출자(migrate
+    등)가 non-git 레이아웃으로 안전하게 폴백할 수 있도록 한다. 과거 migrate.py
+    가 같은 판정을 자체 구현(`--show-toplevel`)했는데 이 seam 으로 통합한다."""
+    try:
+        res = _git(project_root, "rev-parse", "--is-inside-work-tree")
+    except (OSError, FileNotFoundError):
+        return False
+    return res.returncode == 0 and res.stdout.strip() == "true"
+
+
+def _branch_exists(project_root: Path, branch: str) -> bool:
+    res = _git(project_root, "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}")
+    return res.returncode == 0
+
+
+def _branch_checkout_path(project_root: Path, branch: str) -> str:
+    """The worktree that currently has *branch* checked out, or "" when none does.
+
+    `git branch -D` refuses to delete a checked-out branch, so an existing-branch
+    error that only recommends `-D` is unfollowable whenever the branch is the
+    main checkout's HEAD. Callers use this to name the extra step instead.
+    """
+    res = _git(project_root, "worktree", "list", "--porcelain")
+    if res.returncode != 0:
+        return ""
+    current = ""
+    for line in res.stdout.splitlines():
+        if line.startswith("worktree "):
+            current = line[len("worktree "):].strip()
+        elif line.strip() == f"branch refs/heads/{branch}":
+            return current
+    return ""
+
+
+def _branch_exists_message(project_root: Path, branch: str, kind: str) -> str:
+    """Existing-branch error text whose remedy is actually runnable."""
+    checkout = _branch_checkout_path(project_root, branch)
+    if checkout:
+        return (
+            f"{kind} worktree branch already exists: {branch}, and it is checked "
+            f"out at {checkout}. `git branch -D {branch}` will refuse while it is "
+            f"checked out — switch that checkout to another branch first "
+            f"(`git -C {checkout} switch <other-branch>`), then delete it, or "
+            "choose a different work-category before retrying."
+        )
+    return (
+        f"{kind} worktree branch already exists: {branch}. "
+        f"Delete it (`git branch -D {branch}`) or choose a different "
+        "work-category before retrying."
+    )
+
+
+def _head_sha(cwd: Path) -> str:
+    res = _git(cwd, "rev-parse", "HEAD")
+    if res.returncode != 0:
+        return ""
+    return res.stdout.strip()
+
+
+def _resolve_commit_sha(cwd: Path, ref: str) -> str:
+    """Resolve a user-supplied ref (branch, tag, short/long SHA) to a full
+    commit SHA in `cwd`. Returns empty string when the ref is not resolvable
+    so the caller can raise a contextual error.
+    """
+    res = _git(cwd, "rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}")
+    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 is_ancestor(cwd, commit: str, head: str) -> bool:
+    """True iff `commit` is an ancestor of `head` (both non-empty)."""
+    if not commit or not head:
+        return False
+    return _git(Path(cwd), "merge-base", "--is-ancestor", commit, head).returncode == 0
+
+
+class MergeError(RuntimeError):
+    """`git merge` 가 내용 충돌이 아닌 사유로 실패했을 때(추적되지 않은 파일
+    덮어쓰기, 진행 중인 머지 잔존, 없는 브랜치 등) 던진다. 충돌 파일이 0개인
+    실패를 '충돌'로 둔갑시키지 않고 git stderr 를 그대로 노출해 호출자가 올바른
+    복구 경로로 안내하도록 한다."""
+
+
+def merge_branch(cwd, branch: str, *, no_ff: bool) -> list[str] | None:
+    """`branch` 를 cwd 의 현재 HEAD 에 머지한다. 성공이면 None, 내용 충돌이면
+    abort 후 충돌 파일 목록을 반환한다(최소 1개). 충돌이 아닌 머지 실패는
+    MergeError 로 던진다 — 충돌 0개를 충돌로 보고하지 않기 위함. 호출자가 충돌
+    목록을 HandoffConflict/IntegrateError 등 적절한 예외로 변환한다 — 머지·
+    충돌감지·abort 시퀀스의 단일 지점."""
+    args = ["merge", "--no-ff", "--no-edit", branch] if no_ff \
+        else ["merge", "--no-edit", branch]
+    res = _git(Path(cwd), *args)
+    if res.returncode == 0:
+        return None
+    conflicts = _git(Path(cwd), "diff", "--name-only",
+                     "--diff-filter=U").stdout.split()
+    _git(Path(cwd), "merge", "--abort")
+    if not conflicts:
+        raise MergeError((res.stderr or res.stdout).strip()
+                         or f"git merge {branch} failed (exit={res.returncode})")
+    return conflicts
+
+
+def remove_worktree_force(cwd, worktree_path) -> subprocess.CompletedProcess:
+    """워크트리를 강제 제거한다. provision_*_worktree 가 워크트리에 .okstra·
+    synced 디렉터리/파일 symlink(untracked) 를 깔기 때문에 plain remove 는 그
+    잔여물 때문에 git 이 거부한다 — dirty 게이트로 실사용자 변경을 막은 뒤
+    --force 로 okstra 잔여물만 정리하는 단일 지점."""
+    return _git(Path(cwd), "worktree", "remove", "--force", str(worktree_path))