okstra 0.67.0 → 0.68.0

package/runtime/python/okstra_ctl/handoff.py

@@ -0,0 +1,348 @@
+"""release-handoff stage-group 모드의 강제 지점.
+
+자격 판정(eligible) · 수집 브랜치 생성+머지(assemble) · verified/pr 행 기록을
+단일 모듈로 강제한다. lead 는 `okstra handoff <sub>` 로 호출만 한다.
+설계: docs/superpowers/specs/2026-06-10-stage-group-handoff-design.md
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from . import consumers, worktree_registry
+from .worktree import compute_branch_name, compute_worktree_path
+
+
+class HandoffError(Exception):
+    """자격/전제 위반 — exit 1, actionable 메시지."""
+
+
+class HandoffConflict(Exception):
+    """stage 간 merge 충돌 — exit 2, 충돌 경로 동봉."""
+
+    def __init__(self, stage: int, paths: List[str]):
+        self.stage = stage
+        self.paths = paths
+        super().__init__(
+            f"merge conflict while merging stage {stage}: {', '.join(paths)}")
+
+
+def group_id_for(stages: List[int]) -> str:
+    return "g" + "-".join(str(n) for n in sorted(stages))
+
+
+def compute_eligibility(stage_map: List[Dict[str, Any]],
+                        rows: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """stage 별 PR 가능 여부와 차단 사유. 의존 폐포는 선택 집합의 속성이라
+    여기서는 판정하지 않는다 (assemble 의 check_dependency_closure 가 담당)."""
+    done = consumers.latest_done_by_stage(rows)
+    verified = consumers.verified_accepted_stages(rows)
+    in_pr = consumers.pr_covered_stages(rows)
+    out = []
+    for s in stage_map:
+        n = s["stage_number"]
+        reasons = []
+        if n in in_pr:
+            reasons.append("already-in-pr")
+        else:
+            if n not in done:
+                reasons.append("not-done")
+            if n not in verified:
+                reasons.append("not-verified-accepted")
+        out.append({
+            "stage": n,
+            "depends_on": list(s["depends_on"]),
+            "eligible": not reasons,
+            "reasons": reasons,
+            "head_commit": (done.get(n) or {}).get("head_commit", ""),
+        })
+    return out
+
+
+def check_dependency_closure(
+    selected: List[int],
+    stage_map: List[Dict[str, Any]],
+    done_by_stage: Dict[int, Dict[str, Any]],
+    is_merged_to_base: Callable[[str], bool],
+) -> List[Tuple[int, int]]:
+    """선택 집합의 의존 폐포 위반 목록 [(stage, 미충족 선행)].
+    선행이 같은 그룹에 선택됐거나 이미 base 에 머지된 경우만 허용."""
+    sel = set(selected)
+    by_n = {s["stage_number"]: s for s in stage_map}
+    violations = []
+    for n in sorted(selected):
+        for d in by_n[n]["depends_on"]:
+            if d in sel:
+                continue
+            head = (done_by_stage.get(d) or {}).get("head_commit", "")
+            if not head or not is_merged_to_base(head):
+                violations.append((n, d))
+    return violations
+
+
+def _run_git(args: List[str], cwd, check: bool = True) -> subprocess.CompletedProcess:
+    r = subprocess.run(["git", *args], cwd=str(cwd),
+                       capture_output=True, text=True)
+    if check and r.returncode != 0:
+        raise HandoffError(f"git {' '.join(args)} failed: {r.stderr.strip()}")
+    return r
+
+
+def _require_eligible(stage_map, rows, stages) -> Dict[int, Dict[str, Any]]:
+    elig = {e["stage"]: e for e in compute_eligibility(stage_map, rows)}
+    unknown = [n for n in stages if n not in elig]
+    if unknown:
+        raise HandoffError(f"stages not in Stage Map: {unknown}")
+    bad = {n: elig[n]["reasons"] for n in stages if elig[n]["reasons"]}
+    if bad:
+        raise HandoffError(f"stages not eligible: {bad}")
+    return elig
+
+
+def _require_closure(stages, stage_map, done, project_root, base_branch) -> None:
+    def merged(commit: str) -> bool:
+        return _run_git(["merge-base", "--is-ancestor", commit,
+                         f"origin/{base_branch}"], project_root,
+                        check=False).returncode == 0
+    violations = check_dependency_closure(stages, stage_map, done, merged)
+    if violations:
+        lines = [
+            f"stage {n} depends on stage {d} which is neither selected nor "
+            f"merged into origin/{base_branch} — include stage {d} in the "
+            "group or PR-merge it first"
+            for n, d in violations
+        ]
+        raise HandoffError("dependency closure violated:\n" + "\n".join(lines))
+
+
+def _reuse_existing(entry, stages, done, project_root) -> Dict[str, Any]:
+    head = _run_git(["rev-parse", entry.branch], project_root).stdout.strip()
+    for n in stages:
+        h = (done.get(n) or {}).get("head_commit", "")
+        if _run_git(["merge-base", "--is-ancestor", h, head], project_root,
+                    check=False).returncode != 0:
+            raise HandoffError(
+                f"collector branch {entry.branch} exists but stage {n} head "
+                f"{h} is not merged into it — remove the branch/worktree and "
+                "the registry group key, then retry")
+    return {"ok": True, "reused": True, "group_id": group_id_for(stages),
+            "branch": entry.branch, "worktree_path": entry.worktree_path,
+            "head": head, "stages": sorted(stages), "merge_commits": []}
+
+
+def _cleanup_group(project_root, wt_path, branch, project_id, task_group,
+                   task_id, gid) -> None:
+    _run_git(["worktree", "remove", "--force", str(wt_path)], project_root,
+             check=False)
+    _run_git(["branch", "-D", branch], project_root, check=False)
+    worktree_registry.release(project_id, task_group, task_id, group_id=gid)
+
+
+def _merge_stages(wt_path, stages, work_category, task_id, project_root,
+                  project_id, task_group, gid, branch) -> List[str]:
+    merge_commits = []
+    for n in sorted(stages):
+        stage_branch = compute_branch_name(
+            work_category=work_category, task_id_segment=task_id,
+            stage_number=n)
+        r = _run_git(["merge", "--no-edit", stage_branch], wt_path, check=False)
+        if r.returncode != 0:
+            paths = _run_git(["diff", "--name-only", "--diff-filter=U"],
+                             wt_path).stdout.split()
+            _run_git(["merge", "--abort"], wt_path, check=False)
+            _cleanup_group(project_root, wt_path, branch, project_id,
+                           task_group, task_id, gid)
+            raise HandoffConflict(stage=n, paths=paths)
+        merge_commits.append(
+            _run_git(["rev-parse", "HEAD"], wt_path).stdout.strip())
+    return merge_commits
+
+
+def assemble(*, project_root, plan_run_root, stage_map, stages, base_branch,
+             work_category, project_id, task_group, task_id) -> Dict[str, Any]:
+    """수집 브랜치를 만들고 선택 stage 브랜치들을 머지한다. 멱등."""
+    stages = sorted(set(stages))
+    rows = consumers.read_consumers(Path(plan_run_root))
+    _require_eligible(stage_map, rows, stages)
+    _run_git(["fetch", "origin", base_branch], project_root)
+    done = consumers.latest_done_by_stage(rows)
+    _require_closure(stages, stage_map, done, project_root, base_branch)
+
+    base_commit = worktree_registry.get_implementation_base(
+        project_id, task_group, task_id)
+    if not base_commit:
+        raise HandoffError(
+            "implementation_base_commit not recorded in worktree registry — "
+            "run at least one implementation stage first")
+
+    gid = group_id_for(stages)
+    existing = worktree_registry.lookup(
+        project_id, task_group, task_id, group_id=gid)
+    if existing and existing.status == "active":
+        return _reuse_existing(existing, stages, done, project_root)
+
+    branch = compute_branch_name(work_category=work_category,
+                                 task_id_segment=task_id, group_id=gid)
+    wt_path = compute_worktree_path(
+        project_id=project_id, task_group_segment=task_group,
+        task_id_segment=task_id, group_id=gid)
+    worktree_registry.reserve(
+        project_id=project_id, task_group=task_group, task_id=task_id,
+        worktree_path=str(wt_path), branch=branch, base_ref=base_commit,
+        phase="release-handoff", group_id=gid, stages=stages)
+    try:
+        _run_git(["worktree", "add", "-b", branch, str(wt_path), base_commit],
+                 project_root)
+        merge_commits = _merge_stages(wt_path, stages, work_category, task_id,
+                                      project_root, project_id, task_group, gid,
+                                      branch)
+    except HandoffConflict:
+        raise  # _merge_stages 가 이미 _cleanup_group 으로 예약·worktree 를 되돌림
+    except Exception:
+        # worktree add 실패 등 비-충돌 경로 — 예약이 orphan 으로 남지 않도록 역전
+        _cleanup_group(project_root, wt_path, branch, project_id, task_group,
+                       task_id, gid)
+        raise
+    head = merge_commits[-1] if merge_commits else base_commit
+    return {"ok": True, "reused": False, "group_id": gid, "branch": branch,
+            "worktree_path": str(wt_path), "head": head, "stages": stages,
+            "merge_commits": merge_commits}
+
+
+def _impl_task_key_for(rows: List[Dict[str, Any]], stage: int) -> str:
+    done = consumers.latest_done_by_stage(rows)
+    row = done.get(stage)
+    if not row:
+        raise HandoffError(
+            f"stage {stage} has no done row in consumers.jsonl — "
+            "finish the implementation stage first")
+    return row.get("impl_task_key", "")
+
+
+def record_verified(*, plan_run_root, stage: int, report_path: str,
+                    data_json) -> Dict[str, Any]:
+    """단독-stage accepted 만 기록. data.json 의 taskType/scope/verdict 를 검증해
+    lead 가 임의 보고서를 verified 로 올리는 것을 막는다."""
+    try:
+        data = json.loads(Path(data_json).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise HandoffError(f"cannot read final-report data.json: {exc}")
+    if (data.get("header") or {}).get("taskType") != "final-verification":
+        raise HandoffError("data.json is not a final-verification report")
+    scope = data.get("verificationScope")
+    if scope != "single-stage":
+        raise HandoffError(
+            f"record-verified requires verificationScope single-stage, "
+            f"got {scope!r}")
+    token = ((data.get("finalVerdict") or {}).get("verdictToken")
+             or "").strip().lower()
+    if token != "accepted":
+        raise HandoffError(f"verdict token must be `accepted`, got {token!r}")
+    rows = consumers.read_consumers(Path(plan_run_root))
+    key = _impl_task_key_for(rows, stage)
+    consumers.append_verified(Path(plan_run_root), impl_task_key=key,
+                              stage=stage, verdict="accepted",
+                              report_path=report_path)
+    return {"ok": True, "stage": stage, "report_path": report_path}
+
+
+def record_pr(*, plan_run_root, stages: List[int], branch: str,
+              url: str) -> Dict[str, Any]:
+    if not stages:
+        raise HandoffError("record-pr requires at least one stage")
+    rows = consumers.read_consumers(Path(plan_run_root))
+    key = _impl_task_key_for(rows, sorted(stages)[0])
+    consumers.append_pr(Path(plan_run_root), impl_task_key=key,
+                        stages=stages, branch=branch, url=url)
+    return {"ok": True, "stages": sorted(stages), "branch": branch, "url": url}
+
+
+def _parse_stages_csv(raw: str) -> List[int]:
+    try:
+        out = sorted({int(x) for x in raw.split(",") if x.strip()})
+    except ValueError:
+        raise HandoffError(f"--stages must be a comma-separated int list, got {raw!r}")
+    if not out:
+        raise HandoffError("--stages must select at least one stage")
+    return out
+
+
+def main(argv: Optional[list] = None) -> int:
+    import argparse
+
+    from .run import _parse_stage_map_into_ctx
+
+    p = argparse.ArgumentParser(prog="okstra handoff")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def common(sp, *, plan=True):
+        if plan:
+            sp.add_argument("--plan-run-root", required=True)
+
+    sp = sub.add_parser("eligible")
+    common(sp)
+    sp.add_argument("--approved-plan", required=True)
+
+    sp = sub.add_parser("assemble")
+    common(sp)
+    sp.add_argument("--approved-plan", required=True)
+    sp.add_argument("--project-root", default=".")
+    sp.add_argument("--project-id", required=True)
+    sp.add_argument("--task-group", required=True)
+    sp.add_argument("--task-id", required=True)
+    sp.add_argument("--work-category", required=True)
+    sp.add_argument("--stages", required=True)
+    sp.add_argument("--base", required=True)
+
+    sp = sub.add_parser("record-verified")
+    common(sp)
+    sp.add_argument("--stage", type=int, required=True)
+    sp.add_argument("--report-path", required=True)
+    sp.add_argument("--data-json", required=True)
+
+    sp = sub.add_parser("record-pr")
+    common(sp)
+    sp.add_argument("--stages", required=True)
+    sp.add_argument("--branch", required=True)
+    sp.add_argument("--url", required=True)
+
+    a = p.parse_args(argv)
+    try:
+        if a.cmd == "eligible":
+            stage_map = _parse_stage_map_into_ctx(a.approved_plan)
+            rows = consumers.read_consumers(Path(a.plan_run_root))
+            out = {"stages": compute_eligibility(stage_map, rows)}
+        elif a.cmd == "assemble":
+            out = assemble(
+                project_root=Path(a.project_root).resolve(),
+                plan_run_root=Path(a.plan_run_root),
+                stage_map=_parse_stage_map_into_ctx(a.approved_plan),
+                stages=_parse_stages_csv(a.stages), base_branch=a.base,
+                work_category=a.work_category, project_id=a.project_id,
+                task_group=a.task_group, task_id=a.task_id)
+        elif a.cmd == "record-verified":
+            out = record_verified(plan_run_root=Path(a.plan_run_root),
+                                  stage=a.stage, report_path=a.report_path,
+                                  data_json=a.data_json)
+        else:
+            out = record_pr(plan_run_root=Path(a.plan_run_root),
+                            stages=_parse_stages_csv(a.stages),
+                            branch=a.branch, url=a.url)
+    except HandoffConflict as exc:
+        print(json.dumps({"error": str(exc), "stage": exc.stage,
+                          "conflicts": exc.paths}, ensure_ascii=False))
+        return 2
+    except HandoffError as exc:
+        print(json.dumps({"error": str(exc)}, ensure_ascii=False))
+        return 1
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    import sys as _sys
+
+    _sys.exit(main())

package/runtime/python/okstra_ctl/render.py

@@ -1641,8 +1641,11 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
     # - release-handoff (and any other phase that renders with no workers
     #   selected) is single-lead and MUST NOT call `TeamCreate`. Emit a
     #   short notice instead of the BLOCKING gate.
+    # - concurrent implementation runs skip team creation to avoid racing the
+    #   shared `~/.claude/teams/` config.
     # - All other phases keep the full team-creation contract.
     task_type = ctx.get("TASK_TYPE", "")
+    concurrent_stages = str(ctx.get("CONCURRENT_RUN_STAGES", "") or "").strip()
     if task_type == "release-handoff" or not selected:
         team_creation_gate_block = (
             "## Single-Lead Phase (no team creation)\n"
@@ -1655,7 +1658,34 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
             "report). Do NOT call `TeamCreate` or dispatch any sub-agent\n"
             "from this run — that would be a contract violation."
         )
+    elif task_type == "implementation" and concurrent_stages:
+        team_creation_gate_block = (
+            "## Concurrent-run: no-team background (BLOCKING)\n"
+            "\n"
+            "A concurrent implementation run of the same task-key holds stage(s)\n"
+            f"`{concurrent_stages}` right now. Creating a team would race the shared\n"
+            "`~/.claude/teams/` config and can make another stage's `config.json`\n"
+            "unreadable. This run therefore does NOT create a team.\n"
+            "\n"
+            "Required actions, in order:\n"
+            "\n"
+            "1. Do NOT call `TeamCreate`, and do NOT dispatch any worker with\n"
+            "   `Agent(... team_name: ...)`.\n"
+            "2. Before any dispatch, record in team-state:\n"
+            '   `teamCreate: { attempted: false, status: "skipped",'
+            f' reason: "concurrent-run", concurrentStages: [{concurrent_stages}] }}`.\n'
+            "3. Dispatch every worker with `run_in_background: true` and NO\n"
+            "   `team_name` (the Phase 5 fallback). Worker completion is detected by\n"
+            "   result-file polling, so analysis output is equivalent — only the\n"
+            "   Teams split-pane view is lost."
+        )
     else:
+        team_name = f'okstra-{ctx.get("TASK_KEY", "")}'
+        stage = str(ctx.get("EFFECTIVE_STAGES", "") or "").strip()
+        if task_type == "implementation" and stage:
+            # stage 격리 run 은 stage 별 team — 같은 task 의 다른 stage 가 남긴
+            # team 과 이름이 충돌하지 않는다(worktree branch `-s<N>` 접미사와 동형).
+            team_name = f"{team_name}-s{stage}"
         team_creation_gate_block = (
             "## Team Creation Gate (BLOCKING)\n"
             "\n"
@@ -1671,14 +1701,26 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
             "\n"
             "1. Invoke the `okstra-team-contract` skill and verify the selected worker\n"
             "   roster against `task-manifest.json`'s `resultContract.requiredWorkerRoles`.\n"
-            f'2. Call `TeamCreate(team_name: "okstra-{ctx.get("TASK_KEY", "")}", description: ...)`.\n'
+            f'2. Call `TeamCreate(team_name: "{team_name}", description: ...)`.\n'
             "3. Record the outcome in team-state under\n"
             '   `teamCreate: { attempted: true, status: "ok" | "error", error?: <msg> }`\n'
-            "   BEFORE any `Agent(...)` worker dispatch.\n"
+            "   AND record the exact name as `teamName` BEFORE any `Agent(...)` worker\n"
+            "   dispatch.\n"
             "4. Only after `teamCreate` is persisted may you dispatch workers — with\n"
             "   `team_name` on success, or with `run_in_background: true` and no\n"
             '   `team_name` ONLY when `teamCreate.status == "error"` was recorded.\n'
             "\n"
+            'If `TeamCreate` fails with "team already exists" (stale leftover from an\n'
+            "earlier attempt): call `TeamList`; if the team is listed in this session,\n"
+            "`TeamDelete` it and retry step 2 once. If it is NOT listed, do NOT remove\n"
+            "`~/.claude/teams/...` / `~/.claude/tasks/...` on your own initiative —\n"
+            "shell deletion of harness-internal state is destructive and `rm -rf` is\n"
+            "commonly denied by user permission rules. Instead ask the user via\n"
+            "AskUserQuestion (recommended option: quarantine), and on approval move\n"
+            f"`~/.claude/teams/{team_name}` and `~/.claude/tasks/{team_name}` into\n"
+            "`~/.okstra/trash/<UTC-timestamp>/` with `mv` (reversible, no delete),\n"
+            "then retry step 2 once.\n"
+            "\n"
             'If the Agent tool rejects a dispatch with `"team must be created first"` /\n'
             '`"team을 먼저 생성하거나 team_name 없이 호출해야 합니다"`, the correct\n'
             "response is to go back to step 2 — NOT to strip `team_name` and retry."