okstra 0.96.1 → 0.97.1

package/docs/superpowers/plans/2026-06-20-stage-auto-integrate-teardown.md

@@ -0,0 +1,819 @@
+# stage 자동 통합(머지) + worktree teardown 구현 계획
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** whole-task final-verification 진입 시(및 단독 명령으로) stage done commit 을 task 브랜치에 자동 머지하고, 역할이 끝난 stage worktree·registry 키·stage 브랜치를 정리해 merged·dirty 게이트를 자연 통과시킨다.
+
+**Architecture:** 신규 코어 모듈 `stage_integrate.py` 의 `integrate_stages` 하나가 SSOT. Phase A(위상순 `--no-ff` 머지, 충돌 시 해당 머지만 abort+중단) + Phase B(worktree remove + registry release + `branch -d`, dirty stage skip)로 2-분리. `run.py` 의 whole-task final-verification prepare 경로가 자동 호출하고, 동일 코어를 `okstra integrate-stages` 단독 명령으로도 노출.
+
+**Tech Stack:** Python 3 (`scripts/okstra_ctl/`), git CLI(subprocess), pytest. Bash 얇은 래퍼(`okstra.sh`/`cli.sh`), Node CLI(`src/`).
+
+## Global Constraints
+
+- Python 4-space indent, snake_case 모듈. 새/대폭 수정 함수는 **유효 50줄 이하**(CLAUDE.md 4.5) — 넘으면 분리.
+- `runtime/`·개인 `.claude/` 직접 수정 금지. seed source(`scripts/`, `prompts/`, `src/`)만 수정. `runtime/` 은 `npm run build` 산출물.
+- pre-1.0 — compat shim 없음. 기존 API 변경 시 호출처 모두 갱신.
+- 단일 참조점: 같은 로직을 두 진입점에 복제 금지 — `integrate_stages` 코어로 수렴.
+- 문서/주석/CHANGES prose 는 한국어, 코드 식별자·경로·CLI 인자는 영어.
+- 테스트는 `python3 -m pytest tests/` 전체 통과. git 통합 테스트는 `tests/run/test_okstra_run_stage_base.py` 의 `_init_repo_with_commits` / `g(*args)` 픽스처 패턴을 따른다.
+- 커밋은 Conventional Commits. AI 트레일러/생성 푸터 금지. 동시 세션 환경 — amend 금지, 항상 새 커밋.
+
+---
+
+## File Structure
+
+| 파일 | 책임 |
+|---|---|
+| `scripts/okstra_ctl/stage_integrate.py` (신규) | `integrate_stages` 코어 + `_merge_stage` + `_teardown_stage` + `IntegrateResult`/`IntegrateError` + `main(argv)` 단독 명령 |
+| `scripts/okstra_ctl/worktree.py` (수정) | `is_ancestor` / `is_dirty_excluding_okstra` public 헬퍼 추출(현재 run.py 사설) |
+| `scripts/okstra_ctl/run.py` (수정) | final-verification whole-task 경로에서 `integrate_stages` 자동 호출; 사설 헬퍼를 worktree.py 위임으로 교체 |
+| `scripts/okstra.sh` · `scripts/lib/okstra/cli.sh` · `src/cli-registry.mjs` (수정) | `okstra integrate-stages` 라우팅 |
+| `prompts/profiles/final-verification.md` (수정) | whole-task 가 mutating(통합 머지+teardown)임을 명시 |
+| `docs/superpowers/specs/2026-06-06-stage-worktree-isolation-design.md` (수정) | §2/§9-#2 가 본 작업으로 전환·해소됨을 상호 참조 |
+| `CHANGES.md` (수정) | `사용자 영향:` 항목 |
+
+---
+
+## Task 1: git 헬퍼 공유화 (worktree.py 추출)
+
+`integrate_stages` 와 `run.py` 가 둘 다 ancestor 판정·okstra-제외 dirty 판정을 쓴다. 두 번째 호출자가 생기므로 `run.py` 사설 함수를 `worktree.py` public 헬퍼로 올린다.
+
+**Files:**
+- Modify: `scripts/okstra_ctl/worktree.py` (`okstra_clean_gate_excludes` 인근, 411 줄 이후)
+- Modify: `scripts/okstra_ctl/run.py:1445-1458` (`_is_ancestor`, `_is_dirty_excluding_okstra`)
+- Test: `tests/run/test_worktree_git_helpers.py` (신규)
+
+**Interfaces:**
+- Produces:
+  - `worktree.is_ancestor(cwd: str | Path, commit: str, head: str) -> bool` — commit/head 빈 문자열이면 False.
+  - `worktree.is_dirty_excluding_okstra(cwd: str | Path) -> bool` — `git status --short -- . :(exclude)<okstra 소유 경로>` 출력이 비어있지 않으면 True.
+
+- [ ] **Step 1: 실패 테스트 작성**
+
+`tests/run/test_worktree_git_helpers.py`:
+
+```python
+import subprocess
+import sys
+from pathlib import Path
+from _paths import REPO_ROOT
+
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+from okstra_ctl import worktree
+
+
+def _init(repo: Path):
+    subprocess.run(["git", "init", "-q", str(repo)], check=True)
+    subprocess.run(["git", "-C", str(repo), "config", "user.email", "t@e"], check=True)
+    subprocess.run(["git", "-C", str(repo), "config", "user.name", "t"], check=True)
+    (repo / "a").write_text("1\n")
+    subprocess.run(["git", "-C", str(repo), "add", "."], check=True)
+    subprocess.run(["git", "-C", str(repo), "commit", "-q", "-m", "c0"], check=True)
+    return subprocess.run(["git", "-C", str(repo), "rev-parse", "HEAD"],
+                          capture_output=True, text=True, check=True).stdout.strip()
+
+
+def test_is_ancestor_true_for_head_itself(tmp_path):
+    repo = tmp_path / "r"
+    head = _init(repo)
+    assert worktree.is_ancestor(repo, head, head) is True
+
+
+def test_is_ancestor_false_for_empty(tmp_path):
+    repo = tmp_path / "r"
+    _init(repo)
+    assert worktree.is_ancestor(repo, "", "abc") is False
+
+
+def test_dirty_false_when_clean(tmp_path):
+    repo = tmp_path / "r"
+    _init(repo)
+    assert worktree.is_dirty_excluding_okstra(repo) is False
+
+
+def test_dirty_true_with_untracked_source(tmp_path):
+    repo = tmp_path / "r"
+    _init(repo)
+    (repo / "newsrc").write_text("x\n")
+    assert worktree.is_dirty_excluding_okstra(repo) is True
+
+
+def test_dirty_ignores_dot_okstra(tmp_path):
+    repo = tmp_path / "r"
+    _init(repo)
+    (repo / ".okstra").mkdir()
+    (repo / ".okstra" / "junk").write_text("x\n")
+    assert worktree.is_dirty_excluding_okstra(repo) is False
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/run/test_worktree_git_helpers.py -v`
+Expected: FAIL — `AttributeError: module 'okstra_ctl.worktree' has no attribute 'is_ancestor'`
+
+- [ ] **Step 3: worktree.py 에 헬퍼 추가**
+
+`scripts/okstra_ctl/worktree.py` 의 `okstra_clean_gate_excludes` 정의 바로 뒤에 추가(파일 상단에 `import subprocess` 가 없으면 추가):
+
+```python
+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
+    r = subprocess.run(
+        ["git", "-C", str(cwd), "merge-base", "--is-ancestor", commit, head],
+        capture_output=True, text=True,
+    )
+    return r.returncode == 0
+
+
+def is_dirty_excluding_okstra(cwd) -> bool:
+    """True iff the worktree has changes outside okstra-owned paths."""
+    excludes = [f":(exclude){p}" for p in okstra_clean_gate_excludes(Path(cwd))]
+    r = subprocess.run(
+        ["git", "-C", str(cwd), "status", "--short", "--", ".", *excludes],
+        capture_output=True, text=True,
+    )
+    return bool(r.stdout.strip())
+```
+
+- [ ] **Step 4: run.py 사설 함수를 위임으로 교체**
+
+`scripts/okstra_ctl/run.py:1445-1458` 의 `_is_ancestor`/`_is_dirty_excluding_okstra` 본문을 worktree 위임으로 교체(호출처 `run.py:1500,1515,1520` 는 이름 유지로 그대로 동작):
+
+```python
+def _is_ancestor(cwd, commit, head) -> bool:
+    from .worktree import is_ancestor
+    return is_ancestor(cwd, commit, head)
+
+
+def _is_dirty_excluding_okstra(cwd) -> bool:
+    from .worktree import is_dirty_excluding_okstra
+    return is_dirty_excluding_okstra(cwd)
+```
+
+- [ ] **Step 5: 테스트 통과 + 회귀 확인**
+
+Run: `python3 -m pytest tests/run/test_worktree_git_helpers.py tests/run/test_okstra_run_stage_base.py -v`
+Expected: PASS (신규 5개 + 기존 stage_base 회귀)
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add scripts/okstra_ctl/worktree.py scripts/okstra_ctl/run.py tests/run/test_worktree_git_helpers.py
+git commit -m "refactor(worktree): ancestor/dirty 게이트 헬퍼를 worktree 공유 레이어로 추출"
+```
+
+---
+
+## Task 2: integrate_stages 코어 (Phase A 머지 + Phase B teardown)
+
+**Files:**
+- Create: `scripts/okstra_ctl/stage_integrate.py`
+- Test: `tests/run/test_stage_integrate.py` (신규)
+
+**Interfaces:**
+- Consumes: `worktree.is_ancestor`, `worktree.is_dirty_excluding_okstra` (Task 1); `worktree_registry.get_stage_row(project_id, task_group, task_id, stage) -> dict|None` (반환 `branch`/`worktree_path`/`base_ref`); `worktree_registry.release(project_id, task_group, task_id, stage_number=N)`; `consumers.latest_done_by_stage(rows) -> {stage: row}`.
+- Produces:
+  - `IntegrateError(Exception)`
+  - `@dataclass IntegrateResult: merged: list[int]; already_merged: list[int]; torn_down: list[int]; teardown_skipped: list[tuple[int, str]]; warnings: list[str]`
+  - `integrate_stages(*, project_id: str, task_group: str, task_id: str, task_worktree_path: str, stage_map: list[dict], done_rows: list[dict]) -> IntegrateResult`
+
+- [ ] **Step 1: 실패 테스트 작성 (Phase A: 머지 + already-merged + 충돌 abort)**
+
+`tests/run/test_stage_integrate.py`:
+
+```python
+import subprocess
+import sys
+from pathlib import Path
+from _paths import REPO_ROOT
+
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+import pytest
+
+from okstra_ctl.stage_integrate import (
+    integrate_stages, IntegrateError, IntegrateResult,
+)
+from okstra_ctl import worktree_registry
+
+
+def g(repo, *args):
+    return subprocess.run(["git", "-C", str(repo), *args],
+                          capture_output=True, text=True, check=True).stdout.strip()
+
+
+def _task_repo(tmp_path):
+    """task worktree(부모) 단일 repo. main=task 브랜치 역할."""
+    repo = tmp_path / "task"
+    repo.mkdir()
+    g(repo, "init", "-q", "-b", "task-T")
+    g(repo, "config", "user.email", "t@e")
+    g(repo, "config", "user.name", "t")
+    (repo / "base.txt").write_text("base\n")
+    g(repo, "add", ".")
+    g(repo, "commit", "-q", "-m", "base")
+    return repo
+
+
+def _stage_branch(repo, name, fname, content):
+    """task 브랜치에서 분기해 stage 브랜치에 1커밋. done commit sha 반환."""
+    g(repo, "checkout", "-q", "-b", name)
+    (repo / fname).write_text(content)
+    g(repo, "add", ".")
+    g(repo, "commit", "-q", "-m", name)
+    sha = g(repo, "rev-parse", "HEAD")
+    g(repo, "checkout", "-q", "task-T")
+    return sha
+
+
+def _stage_map(*pairs):
+    return [{"stage_number": n, "depends_on": d} for n, d in pairs]
+
+
+def test_merges_unmerged_stages_in_order(tmp_path, monkeypatch):
+    repo = _task_repo(tmp_path)
+    s1 = _stage_branch(repo, "task-T-s1", "a.txt", "a\n")
+    s2 = _stage_branch(repo, "task-T-s2", "b.txt", "b\n")
+    monkeypatch.setattr(
+        worktree_registry, "get_stage_row",
+        lambda p, gp, t, stage: {"branch": f"task-T-s{stage}",
+                                 "worktree_path": ""},
+    )
+    monkeypatch.setattr(worktree_registry, "release", lambda *a, **k: None)
+    rows = [
+        {"stage": 1, "status": "done", "head_commit": s1},
+        {"stage": 2, "status": "done", "head_commit": s2},
+    ]
+    res = integrate_stages(
+        project_id="p", task_group="g", task_id="T",
+        task_worktree_path=str(repo),
+        stage_map=_stage_map((1, []), (2, [1])),
+        done_rows=rows,
+    )
+    assert res.merged == [1, 2]
+    assert res.already_merged == []
+    # 두 stage 커밋이 task HEAD 에서 reachable
+    head = g(repo, "rev-parse", "HEAD")
+    for sha in (s1, s2):
+        assert subprocess.run(
+            ["git", "-C", str(repo), "merge-base", "--is-ancestor", sha, head]
+        ).returncode == 0
+
+
+def test_already_merged_stage_is_skipped(tmp_path, monkeypatch):
+    repo = _task_repo(tmp_path)
+    s1 = _stage_branch(repo, "task-T-s1", "a.txt", "a\n")
+    g(repo, "merge", "--no-ff", "--no-edit", "task-T-s1")  # 사용자가 먼저 머지
+    monkeypatch.setattr(
+        worktree_registry, "get_stage_row",
+        lambda p, gp, t, stage: {"branch": f"task-T-s{stage}", "worktree_path": ""},
+    )
+    monkeypatch.setattr(worktree_registry, "release", lambda *a, **k: None)
+    rows = [{"stage": 1, "status": "done", "head_commit": s1}]
+    res = integrate_stages(
+        project_id="p", task_group="g", task_id="T",
+        task_worktree_path=str(repo),
+        stage_map=_stage_map((1, [])),
+        done_rows=rows,
+    )
+    assert res.already_merged == [1]
+    assert res.merged == []
+
+
+def test_conflict_aborts_and_raises(tmp_path, monkeypatch):
+    repo = _task_repo(tmp_path)
+    # 두 stage 가 같은 파일을 다르게 수정 → 머지 충돌
+    s1 = _stage_branch(repo, "task-T-s1", "clash.txt", "from-s1\n")
+    s2 = _stage_branch(repo, "task-T-s2", "clash.txt", "from-s2\n")
+    monkeypatch.setattr(
+        worktree_registry, "get_stage_row",
+        lambda p, gp, t, stage: {"branch": f"task-T-s{stage}", "worktree_path": ""},
+    )
+    monkeypatch.setattr(worktree_registry, "release", lambda *a, **k: None)
+    rows = [
+        {"stage": 1, "status": "done", "head_commit": s1},
+        {"stage": 2, "status": "done", "head_commit": s2},
+    ]
+    with pytest.raises(IntegrateError, match="clash.txt"):
+        integrate_stages(
+            project_id="p", task_group="g", task_id="T",
+            task_worktree_path=str(repo),
+            stage_map=_stage_map((1, []), (2, [1])),
+            done_rows=rows,
+        )
+    # abort 로 task worktree 가 머지중 상태가 아니어야 함
+    assert not (repo / ".git" / "MERGE_HEAD").exists()
+    # stage 1 은 충돌 전 머지 성공으로 유지(재시도 시 already_merged)
+    s1_head = g(repo, "rev-parse", "task-T-s1")
+    assert subprocess.run(
+        ["git", "-C", str(repo), "merge-base", "--is-ancestor", s1_head,
+         g(repo, "rev-parse", "HEAD")]
+    ).returncode == 0
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/run/test_stage_integrate.py -v`
+Expected: FAIL — `ModuleNotFoundError: No module named 'okstra_ctl.stage_integrate'`
+
+- [ ] **Step 3: stage_integrate.py 작성 (코어 + Phase A)**
+
+`scripts/okstra_ctl/stage_integrate.py`:
+
+```python
+"""whole-task stage 통합(머지) + worktree teardown 코어.
+
+Phase A: stage done commit 을 task 브랜치에 위상순 --no-ff 머지(이미 머지면
+skip, 충돌이면 해당 머지만 abort 후 IntegrateError). Phase B: 머지/skip 된
+stage 의 worktree·registry 키·stage 브랜치를 정리(dirty 면 skip).
+설계: docs/superpowers/specs/2026-06-20-stage-auto-integrate-teardown-design.md
+"""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+class IntegrateError(Exception):
+    """stage 머지 충돌 등으로 통합을 중단해야 함."""
+
+
+@dataclass
+class IntegrateResult:
+    merged: list[int] = field(default_factory=list)
+    already_merged: list[int] = field(default_factory=list)
+    torn_down: list[int] = field(default_factory=list)
+    teardown_skipped: list[tuple[int, str]] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+def _git(cwd, *args) -> subprocess.CompletedProcess:
+    return subprocess.run(["git", "-C", str(cwd), *args],
+                          capture_output=True, text=True)
+
+
+def _merge_stage(task_wt: str, stage_n: int, branch: str, done_commit: str) -> str:
+    """한 stage 를 task 브랜치에 머지. 'merged'|'already_merged'.
+    충돌 시 abort 후 IntegrateError."""
+    from .worktree import is_ancestor
+
+    head = _git(task_wt, "rev-parse", "HEAD").stdout.strip()
+    if is_ancestor(task_wt, done_commit, head):
+        return "already_merged"
+    r = _git(task_wt, "merge", "--no-ff", "--no-edit", branch)
+    if r.returncode != 0:
+        conflicts = _git(task_wt, "diff", "--name-only", "--diff-filter=U").stdout.strip()
+        _git(task_wt, "merge", "--abort")
+        raise IntegrateError(
+            f"stage {stage_n} ({branch}) 머지 충돌 — abort 함. "
+            f"충돌 파일: {conflicts or '(unknown)'}. 수동 머지로 해소 후 재시도."
+        )
+    return "merged"
+
+
+def integrate_stages(
+    *, project_id: str, task_group: str, task_id: str,
+    task_worktree_path: str, stage_map: list[dict[str, Any]],
+    done_rows: list[dict[str, Any]],
+) -> IntegrateResult:
+    """whole-task 통합: Phase A 머지 → Phase B teardown."""
+    from .consumers import latest_done_by_stage
+
+    res = IntegrateResult()
+    if not task_worktree_path or not Path(task_worktree_path).exists():
+        return res  # non-git / degraded — no-op
+    done = latest_done_by_stage(done_rows)
+    ordered = sorted((s["stage_number"] for s in stage_map))
+
+    for n in ordered:
+        row = done.get(n)
+        if not row or not row.get("head_commit"):
+            continue  # 미완 stage 는 merged 게이트가 별도로 잡음
+        branch = _stage_branch_name(project_id, task_group, task_id, n)
+        if branch is None:
+            res.warnings.append(f"stage {n}: registry 에 stage-key 없음 — 머지 skip")
+            continue
+        outcome = _merge_stage(task_worktree_path, n, branch,
+                               row["head_commit"])
+        (res.merged if outcome == "merged" else res.already_merged).append(n)
+
+    _teardown_all(project_id, task_group, task_id, res)
+    return res
+
+
+def _stage_branch_name(project_id, task_group, task_id, stage_n) -> str | None:
+    from . import worktree_registry
+    row = worktree_registry.get_stage_row(project_id, task_group, task_id, stage_n)
+    if not row:
+        return None
+    return row.get("branch") or None
+```
+
+(Phase B `_teardown_all` / `_teardown_stage` 는 Step 5 에서 추가 — 우선 Phase A 검증.)
+
+`integrate_stages` 가 아직 `_teardown_all` 미정의이므로, Step 3 에서는 `_teardown_all` 호출 줄을 임시로 `pass` 대신 빈 함수 stub 로 둔다:
+
+```python
+def _teardown_all(project_id, task_group, task_id, res: IntegrateResult) -> None:
+    """Step 5 에서 구현."""
+    return
+```
+
+- [ ] **Step 4: Phase A 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/run/test_stage_integrate.py -v`
+Expected: PASS (머지/already/충돌 3개. teardown stub 이라 merged/already 만 검증하는 현재 테스트는 통과)
+
+- [ ] **Step 5: Phase B (teardown) 테스트 추가**
+
+`tests/run/test_stage_integrate.py` 에 추가. stage worktree 를 실제 `git worktree add` 로 만들어 teardown 검증:
+
+```python
+def _add_stage_worktree(repo, branch, path):
+    g(repo, "worktree", "add", "-q", str(path), branch)
+
+
+def test_teardown_removes_clean_stage_worktree_and_branch(tmp_path, monkeypatch):
+    repo = _task_repo(tmp_path)
+    s1 = _stage_branch(repo, "task-T-s1", "a.txt", "a\n")
+    wt1 = tmp_path / "stage-1"
+    _add_stage_worktree(repo, "task-T-s1", wt1)
+    rows = [{"stage": 1, "status": "done", "head_commit": s1}]
+
+    def fake_get_stage_row(p, gp, t, stage):
+        return {"branch": "task-T-s1", "worktree_path": str(wt1)}
+    released = []
+    monkeypatch.setattr(worktree_registry, "get_stage_row", fake_get_stage_row)
+    monkeypatch.setattr(worktree_registry, "release",
+                        lambda p, gp, t, stage_number=None: released.append(stage_number))
+
+    res = integrate_stages(
+        project_id="p", task_group="g", task_id="T",
+        task_worktree_path=str(repo),
+        stage_map=_stage_map((1, [])), done_rows=rows,
+    )
+    assert res.torn_down == [1]
+    assert not wt1.exists()                       # worktree dir 제거됨
+    assert released == [1]                        # registry release 호출됨
+    branches = g(repo, "branch", "--list", "task-T-s1")
+    assert branches == ""                         # branch -d 됨
+
+
+def test_teardown_skips_dirty_stage_worktree(tmp_path, monkeypatch):
+    repo = _task_repo(tmp_path)
+    s1 = _stage_branch(repo, "task-T-s1", "a.txt", "a\n")
+    wt1 = tmp_path / "stage-1"
+    _add_stage_worktree(repo, "task-T-s1", wt1)
+    (wt1 / "dirty.txt").write_text("uncommitted\n")   # dirty
+    rows = [{"stage": 1, "status": "done", "head_commit": s1}]
+    monkeypatch.setattr(worktree_registry, "get_stage_row",
+                        lambda p, gp, t, stage: {"branch": "task-T-s1",
+                                                 "worktree_path": str(wt1)})
+    monkeypatch.setattr(worktree_registry, "release", lambda *a, **k: None)
+
+    res = integrate_stages(
+        project_id="p", task_group="g", task_id="T",
+        task_worktree_path=str(repo),
+        stage_map=_stage_map((1, [])), done_rows=rows,
+    )
+    assert res.torn_down == []
+    assert res.teardown_skipped and res.teardown_skipped[0][0] == 1
+    assert wt1.exists()                           # 보존됨
+    assert g(repo, "branch", "--list", "task-T-s1") != ""  # 브랜치 보존
+```
+
+- [ ] **Step 6: Phase B 구현 (`_teardown_all` 교체)**
+
+`stage_integrate.py` 의 stub `_teardown_all` 을 교체하고 `_teardown_stage` 추가:
+
+```python
+def _teardown_all(project_id, task_group, task_id, res: IntegrateResult) -> None:
+    from . import worktree_registry
+
+    for n in [*res.merged, *res.already_merged]:
+        row = worktree_registry.get_stage_row(project_id, task_group, task_id, n)
+        outcome, detail = _teardown_stage(project_id, task_group, task_id, n, row)
+        if outcome == "torn_down":
+            res.torn_down.append(n)
+        elif outcome == "skipped":
+            res.teardown_skipped.append((n, detail))
+        if outcome == "warn":
+            res.warnings.append(detail)
+
+
+def _teardown_stage(project_id, task_group, task_id, stage_n, row):
+    """clean stage worktree 를 제거 + registry release + branch -d.
+    반환 ('torn_down'|'skipped'|'warn', detail)."""
+    from . import worktree_registry
+    from .worktree import is_dirty_excluding_okstra
+
+    wt = (row or {}).get("worktree_path") or ""
+    branch = (row or {}).get("branch") or ""
+    if wt and Path(wt).exists():
+        if is_dirty_excluding_okstra(wt):
+            return ("skipped", "dirty — 미커밋 변경 보존")
+        rm = subprocess.run(["git", "worktree", "remove", str(wt)],
+                            capture_output=True, text=True)
+        if rm.returncode != 0:
+            return ("warn", f"stage {stage_n} worktree remove 실패: {rm.stderr.strip()}")
+    worktree_registry.release(project_id, task_group, task_id, stage_number=stage_n)
+    if branch:
+        bd = subprocess.run(["git", "branch", "-d", branch],
+                            capture_output=True, text=True)
+        if bd.returncode != 0:
+            return ("warn", f"stage {stage_n} branch -d {branch} 실패(미머지?): "
+                            f"{bd.stderr.strip()}")
+    return ("torn_down", "")
+```
+
+참고: `git worktree remove <path>` 는 부모 repo 컨텍스트가 필요하므로 `-C` 없이 절대경로로 호출한다. `_teardown_stage` 가 50줄을 넘으면 dirty-skip 판정과 remove 를 보조 함수로 더 쪼갠다.
+
+- [ ] **Step 7: 전체 코어 테스트 통과**
+
+Run: `python3 -m pytest tests/run/test_stage_integrate.py -v`
+Expected: PASS (머지/already/충돌/teardown/dirty-skip 5개)
+
+- [ ] **Step 8: 커밋**
+
+```bash
+git add scripts/okstra_ctl/stage_integrate.py tests/run/test_stage_integrate.py
+git commit -m "feat(integrate): stage 자동 머지+teardown 코어 integrate_stages 추가"
+```
+
+---
+
+## Task 3: run.py whole-task final-verification 자동 호출 배선
+
+**Files:**
+- Modify: `scripts/okstra_ctl/run.py:1509-1521` (`_reserve_final_verification_target` 의 `else` whole-task 분기)
+- Test: `tests/run/test_final_verification_integrate_call.py` (신규)
+
+**Interfaces:**
+- Consumes: `stage_integrate.integrate_stages` (Task 2).
+- whole-task 분기에서 `merged`/`task_dirty` 계산 **전에** `integrate_stages` 를 호출해 통합·정리한 뒤, 그 결과를 ctx 의 통합 리포트 키에 주입한다.
+
+- [ ] **Step 1: 실패 테스트 작성**
+
+`integrate_stages` 가 whole-task 경로에서 정확한 인자로 호출되는지 monkeypatch 로 검증:
+
+```python
+import sys
+from pathlib import Path
+from _paths import REPO_ROOT
+
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+from okstra_ctl import run as run_mod
+from okstra_ctl import stage_integrate
+
+
+def test_whole_task_calls_integrate_before_target(monkeypatch, tmp_path):
+    calls = {}
+
+    def fake_integrate(**kw):
+        calls.update(kw)
+        return stage_integrate.IntegrateResult(merged=[1], torn_down=[1])
+
+    monkeypatch.setattr(run_mod._stage_integrate, "integrate_stages", fake_integrate)
+    # whole-task 경로가 integrate_stages 를 호출하는지: 최소 인자 키 확인
+    # (전체 prepare 통합은 e2e 가 담당 — 여기선 호출 계약만 박제)
+    assert hasattr(run_mod, "_stage_integrate")
+```
+
+> 구현 메모: `run.py` 상단 import 를 `from . import stage_integrate as _stage_integrate` 로 추가해 테스트가 모듈 핸들을 monkeypatch 할 수 있게 한다.
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/run/test_final_verification_integrate_call.py -v`
+Expected: FAIL — `AttributeError: module 'okstra_ctl.run' has no attribute '_stage_integrate'`
+
+- [ ] **Step 3: run.py 배선**
+
+`scripts/okstra_ctl/run.py` 상단 import 블록에 추가:
+
+```python
+from . import stage_integrate as _stage_integrate
+```
+
+`run.py:1509` 의 `else:` whole-task 분기에서 `head = _git_out(...)` 직후, `merged = {...}` 계산 **직전**에 통합 호출을 삽입:
+
+```python
+    else:
+        wt_path = ctx["EXECUTOR_WORKTREE_PATH"]
+        anchor = _reg.get_implementation_base(
+            inp.project_id, inp.task_group, inp.task_id) or ""
+        integ = _stage_integrate.integrate_stages(
+            project_id=inp.project_id, task_group=inp.task_group,
+            task_id=inp.task_id, task_worktree_path=wt_path,
+            stage_map=ctx_stage_map, done_rows=done_rows,
+        )
+        ctx["STAGE_INTEGRATION"] = _format_integration(integ)
+        head = _git_out(wt_path, "rev-parse", "HEAD")
+        from .consumers import latest_done_by_stage
+        merged = {s: _is_ancestor(wt_path, r.get("head_commit", ""), head)
+                  for s, r in latest_done_by_stage(done_rows).items()}
+        target = _resolve_whole_task_target(...)   # 기존 인자 유지
+```
+
+`IntegrateError` 는 `prepare_task_bundle` 의 기존 `PrepareError` 처리와 동일하게 surface 되도록, `integrate_stages` 호출을 try/except 로 감싸 `raise PrepareError(str(exc)) from exc` 로 변환(충돌 시 사용자에게 충돌 경로 노출). `_format_integration(integ) -> str` 헬퍼는 merged/already/torn_down/skipped/warnings 를 사람이 읽을 마크다운 블록으로 만든다(20줄 이하).
+
+- [ ] **Step 4: 테스트 통과**
+
+Run: `python3 -m pytest tests/run/test_final_verification_integrate_call.py -v`
+Expected: PASS
+
+- [ ] **Step 5: 회귀 — final-verification 관련 기존 테스트**
+
+Run: `python3 -m pytest tests/run/ -k "final or target or stage" -v`
+Expected: PASS (기존 whole-task target 테스트 무회귀)
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add scripts/okstra_ctl/run.py tests/run/test_final_verification_integrate_call.py
+git commit -m "feat(final-verification): whole-task 진입 시 stage 자동 통합+teardown 호출"
+```
+
+---
+
+## Task 4: 단독 명령 `okstra integrate-stages`
+
+**Files:**
+- Modify: `scripts/okstra_ctl/stage_integrate.py` (`main(argv)` 추가)
+- Modify: `scripts/okstra.sh` · `scripts/lib/okstra/cli.sh` · `src/cli-registry.mjs`
+- Test: `tests/run/test_stage_integrate_cli.py` (신규)
+
+**Interfaces:**
+- Consumes: `integrate_stages` (Task 2), `task_target.resolve_task_root`(기존 단독 명령들이 task 좌표를 푸는 방식), `consumers.read_consumers`.
+- Produces: `stage_integrate.main(argv: list[str] | None) -> int`.
+
+- [ ] **Step 1: 라우팅 패턴 확인 (코드 읽기)**
+
+Read: `scripts/okstra_ctl/handoff.py:302-340`(argparse subparser + main 패턴), `src/cli-registry.mjs`(명령 등록), `scripts/lib/okstra/cli.sh`(sub-command 디스패치). `okstra handoff <cmd>` 가 python `-m okstra_ctl.handoff` 로 가는 경로를 그대로 모사한다.
+
+- [ ] **Step 2: 실패 테스트 작성**
+
+```python
+import sys
+from pathlib import Path
+from _paths import REPO_ROOT
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+from okstra_ctl import stage_integrate
+
+
+def test_main_returns_zero_on_noop(tmp_path, capsys):
+    # stage worktree 미발급(non-git task path) → no-op, exit 0
+    rc = stage_integrate.main([
+        "--project-root", str(tmp_path),
+        "--project-id", "p", "--task-group", "g", "--task-id", "T",
+        "--plan-run-root", str(tmp_path),
+        "--task-worktree-path", str(tmp_path),
+    ])
+    assert rc == 0
+```
+
+- [ ] **Step 3: 실패 확인**
+
+Run: `python3 -m pytest tests/run/test_stage_integrate_cli.py -v`
+Expected: FAIL — `AttributeError: module ... has no attribute 'main'`
+
+- [ ] **Step 4: `main(argv)` 구현**
+
+`stage_integrate.py` 끝에 추가:
+
+```python
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+    import json
+    from .consumers import read_consumers
+
+    p = argparse.ArgumentParser(prog="okstra integrate-stages")
+    p.add_argument("--project-root", required=True)
+    p.add_argument("--project-id", required=True)
+    p.add_argument("--task-group", required=True)
+    p.add_argument("--task-id", required=True)
+    p.add_argument("--plan-run-root", required=True)
+    p.add_argument("--task-worktree-path", required=True)
+    p.add_argument("--stage-map-json", default="[]",
+                   help="[{stage_number, depends_on}] JSON")
+    a = p.parse_args(argv)
+    done_rows = [r for r in read_consumers(Path(a.plan_run_root))
+                 if r.get("status") == "done"]
+    try:
+        res = integrate_stages(
+            project_id=a.project_id, task_group=a.task_group,
+            task_id=a.task_id, task_worktree_path=a.task_worktree_path,
+            stage_map=json.loads(a.stage_map_json), done_rows=done_rows,
+        )
+    except IntegrateError as exc:
+        print(f"integrate-stages: {exc}", file=__import__("sys").stderr)
+        return 2
+    print(f"merged={res.merged} already={res.already_merged} "
+          f"torn_down={res.torn_down} skipped={res.teardown_skipped}")
+    for w in res.warnings:
+        print(f"warning: {w}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+```
+
+- [ ] **Step 5: Bash/Node 라우팅 추가**
+
+Step 1 에서 확인한 패턴대로:
+- `scripts/lib/okstra/cli.sh`: `integrate-stages` sub-command → `okstra_py -m okstra_ctl.stage_integrate "$@"`.
+- `src/cli-registry.mjs`: `handoff` 등록 항목과 동일 형태로 `integrate-stages` 항목 추가(설명: "stage 들을 task 브랜치에 통합 머지하고 stage worktree 를 정리").
+
+- [ ] **Step 6: 테스트 통과 + CLI 스모크**
+
+Run: `python3 -m pytest tests/run/test_stage_integrate_cli.py -v`
+Run: `node bin/okstra --help` (integrate-stages 가 명령 목록에 노출되는지 육안 확인)
+Expected: PASS + 명령 노출
+
+- [ ] **Step 7: 커밋**
+
+```bash
+git add scripts/okstra_ctl/stage_integrate.py scripts/lib/okstra/cli.sh scripts/okstra.sh src/cli-registry.mjs tests/run/test_stage_integrate_cli.py
+git commit -m "feat(cli): okstra integrate-stages 단독 명령 추가"
+```
+
+---
+
+## Task 5: 문서 — 프로파일·spec 상호참조·CHANGES
+
+**Files:**
+- Modify: `prompts/profiles/final-verification.md`
+- Modify: `docs/superpowers/specs/2026-06-06-stage-worktree-isolation-design.md`
+- Modify: `CHANGES.md`
+
+- [ ] **Step 1: final-verification 프로파일에 mutating 명시**
+
+`prompts/profiles/final-verification.md` 의 whole-task 설명에 한 문단 추가: "whole-task 모드는 진입 시 미머지 stage 를 task 브랜치에 `--no-ff` 자동 머지하고, 정리 가능한 stage worktree·registry 키·stage 브랜치를 제거한다(머지 충돌 시 중단). 따라서 whole-task final-verification 은 read-only 가 아니라 통합 커밋을 생성하는 mutating phase 다."
+
+- [ ] **Step 2: 2026-06-06 spec 상호참조**
+
+`docs/superpowers/specs/2026-06-06-stage-worktree-isolation-design.md` 의 §2 자동 머지 비범위 줄과 §9-#2(자동 teardown) 항목에 각각 한 줄 추가: "(2026-06-20 갱신: whole-task 통합 경로에 한해 [2026-06-20-stage-auto-integrate-teardown-design.md] 가 자동 머지+teardown 으로 전환·해소.)"
+
+- [ ] **Step 3: CHANGES.md 항목**
+
+`CHANGES.md` 최상단에 추가:
+
+```markdown
+## stage 자동 통합 + worktree 정리
+
+- whole-task final-verification 진입 시(및 `okstra integrate-stages` 명령으로) 완료된 stage 들을 task 브랜치에 자동 머지하고, 정리 가능한 stage worktree·브랜치를 제거합니다.
+- 사용자 영향: 더 이상 stage 브랜치를 수동 머지하거나 `git worktree remove` 로 stage 폴더를 직접 정리하지 않아도 whole-task 검증이 통과합니다. 머지 충돌이 있으면 충돌 파일을 보여주고 중단하므로 수동 해소 후 재시도하면 됩니다. 미커밋 변경이 남은 stage worktree 는 보존됩니다.
+```
+
+- [ ] **Step 4: 커밋**
+
+```bash
+git add prompts/profiles/final-verification.md docs/superpowers/specs/2026-06-06-stage-worktree-isolation-design.md CHANGES.md
+git commit -m "docs(integrate): final-verification mutating 명시 + spec 상호참조 + CHANGES"
+```
+
+---
+
+## Task 6: 빌드·전체 회귀·정리
+
+- [ ] **Step 1: 전체 테스트**
+
+Run: `python3 -m pytest tests/`
+Expected: 전부 PASS
+
+- [ ] **Step 2: 빌드 동기화 확인**
+
+Run: `npm run build`
+Expected: `runtime/` 에 stage_integrate.py 및 수정 파일이 동기화됨(에러 없음)
+
+- [ ] **Step 3: 워크플로 검증기**
+
+Run: `bash validators/validate-workflow.sh`
+Expected: PASS
+
+- [ ] **Step 4: spawn 된 clean-gate 안전망 task 정리 판단**
+
+이 plan 의 Task 2~3 이 머지+teardown 으로 nested 디렉터리를 제거하므로, 앞서 띄운 "clean gate 가 nested stage 디렉터리 제외" task(`task_74a5cabc`)는 dirty-skip 으로 worktree 가 남는 경우의 **fallback** 으로 여전히 유효하다. 중복이 아니므로 유지(별도 진행). 본 plan 범위에서는 손대지 않는다.
+
+- [ ] **Step 5: 최종 커밋(필요 시)**
+
+빌드 산출물(`runtime/`)이 gitignore 면 커밋 불필요. 추적 대상이면:
+
+```bash
+git add -A && git commit -m "chore: stage 통합 기능 빌드 동기화"
+```
+
+---
+
+## Self-Review 결과 (작성자 점검)
+
+- **Spec 커버리지**: §3 Phase A/B → Task 2; §2.3 진입 2개 → Task 3(자동)·Task 4(단독); §4 에러표(충돌 abort/dirty skip/branch -d 거부) → Task 2 테스트 I3·dirty·warn; §6 enforcement(merge --abort, branch -d safe, dirty 검사) → Task 2 구현; §7 시나리오 I1~I8 → Task 2/3 테스트 + Task 6 e2e 회귀. I7(코어 동일성)·I8(재진입 통과)은 Task 3·4 가 동일 `integrate_stages` 를 호출함으로 충족.
+- **Placeholder 스캔**: 코드 스텝은 실제 코드 포함. Task 4 Step 1 은 의도된 "코드 읽기" 스텝(라우팅 패턴 확인)으로 placeholder 아님.
+- **타입 일관성**: `integrate_stages` 시그니처·`IntegrateResult` 필드·`get_stage_row`/`release` 인자가 Task 2~4 에서 동일하게 사용됨. `_stage_integrate` 모듈 핸들 이름이 Task 3 전반에서 일관.