okstra 0.102.2 → 0.102.4

package/docs/superpowers/plans/2026-06-21-release-handoff-local-checkout.md

@@ -1,348 +0,0 @@
-# release-handoff `local checkout` 액션 구현 계획
-
-> **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:** release-handoff 에 `local checkout` 액션을 추가해, 검증된 task 브랜치를 메인 워크트리로 가져와 로컬 테스트 가능 상태로 만든다.
-
-**Architecture:** Python 헬퍼 `okstra handoff local-checkout` 가 registry 의 task-key 행에서 okstra 워크트리·브랜치를 해소하고, 메인 워크트리 cwd 에서 `git worktree remove --force`(브랜치 보존) → `release_status`(branch 슬롯 유지) → `git checkout` 을 수행한다. release-handoff 프로필이 확인을 받고 이 명령 하나만 호출한다. base 브랜치는 절대 건드리지 않는다.
-
-**Tech Stack:** Python 3 (argparse, subprocess), 기존 `okstra_ctl.handoff` / `worktree` / `worktree_registry`, Node CLI shim, markdown 프로필.
-
-## Global Constraints
-
-- 설계 문서: [docs/superpowers/specs/2026-06-21-release-handoff-local-checkout-design.md](../specs/2026-06-21-release-handoff-local-checkout-design.md) — 충돌 시 spec 우선.
-- `runtime/` 직접 수정 금지(빌드 산출물). 소스는 `scripts/` `src/` `prompts/`; 변경 후 `npm run build`.
-- pre-1.0 — compat shim 불필요. `local only` 액션은 완전 제거.
-- 함수 본문 50줄 이하.
-- 동시 세션 환경 — git amend 금지, 항상 새 커밋. 내 작업 파일만 스테이징.
-- Conventional Commits, 메시지 한국어 prose, AI 트레일러 금지.
-- 사용자 영향 있는 변경은 [CHANGES.md](../../../CHANGES.md) 에 `사용자 영향:` 항목 추가(한국어).
-- `local checkout` 은 whole-task 모드 전용. base 브랜치 자동 머지는 비목표.
-
-## File Structure
-
-- `scripts/okstra_ctl/handoff.py` — `local_checkout()` 코어 + `local-checkout` 서브커맨드/디스패치 추가.
-- `src/commands/execute/handoff.mjs` — USAGE 에 `local-checkout` 노출(동작은 기존 shim 이 그대로 forward).
-- `tests/handoff/test_handoff_local_checkout.py` — 신규: 성공/메인 dirty 거부/registry 행 없음 + 브랜치 보존 실증.
-- `prompts/profiles/release-handoff.md` — 액션 선택 재편 + 핸들러 + `local only` 잔존 참조 정리 + 보고 deliverable.
-- `CHANGES.md` — 사용자 영향 항목.
-
----
-
-### Task 1: `local_checkout()` 코어 + CLI 서브커맨드
-
-**Files:**
-- Modify: `scripts/okstra_ctl/handoff.py` (import 확장 + `local_checkout()` 추가 + `main()` argparse/dispatch)
-- Modify: `src/commands/execute/handoff.mjs` (USAGE)
-- Test: `tests/handoff/test_handoff_local_checkout.py`
-
-**Interfaces:**
-- Consumes: `worktree_registry.lookup(project_id, task_group, task_id) -> Optional[WorktreeEntry]` (`.branch`, `.worktree_path`, `.status`); `worktree_registry.release_status(project_id, task_group, task_id)`; `worktree.main_worktree_path(Path) -> Path`; `worktree.is_dirty_excluding_okstra(cwd) -> bool`; `handoff._run_git(args, cwd, check=True)`.
-- Produces: `handoff.local_checkout(*, project_root, project_id, task_group, task_id) -> Dict[str, Any]` — 성공 시 `{"ok": True, "branch": str, "mainWorktreePath": str, "removedWorktree": str, "status": "checked-out"}`; 전제 위반 시 `HandoffError`(→ exit 1). CLI: `okstra handoff local-checkout --project-root <dir> --project-id <id> --task-group <g> --task-id <t>`.
-
-- [ ] **Step 1: 실패 테스트 작성**
-
-`tests/handoff/test_handoff_local_checkout.py` 생성:
-
-```python
-"""handoff.local_checkout — okstra 워크트리 제거 + 메인 checkout 의 git 실증."""
-import sys
-import subprocess
-from pathlib import Path
-from _paths import REPO_ROOT
-
-LIB_DIR = REPO_ROOT / "scripts"
-if str(LIB_DIR) not in sys.path:
-    sys.path.insert(0, str(LIB_DIR))
-
-import pytest
-
-from okstra_ctl import handoff, worktree_registry
-
-ARGS = dict(project_id="proj", task_group="grp", task_id="task")
-BRANCH = "feature-development-task"
-
-
-def _git(repo, *args):
-    r = subprocess.run(["git", *args], cwd=str(repo),
-                       capture_output=True, text=True)
-    assert r.returncode == 0, r.stderr
-    return r.stdout.strip()
-
-
-def _main_repo(tmp_path):
-    repo = tmp_path / "main"
-    repo.mkdir()
-    _git(repo, "init", "-q", "-b", "main")
-    _git(repo, "config", "user.email", "t@t")
-    _git(repo, "config", "user.name", "t")
-    (repo / "base.txt").write_text("base\n")
-    _git(repo, "add", ".")
-    _git(repo, "commit", "-q", "-m", "base")
-    return repo
-
-
-def _provision_okstra_worktree(repo, tmp_path):
-    """main repo 에서 task 브랜치를 든 okstra 워크트리를 만들고 registry 에 등록."""
-    okstra_wt = tmp_path / "okstra-wt"
-    _git(repo, "worktree", "add", "-b", BRANCH, str(okstra_wt), "main")
-    (okstra_wt / "work.txt").write_text("task work\n")
-    _git(okstra_wt, "add", ".")
-    _git(okstra_wt, "commit", "-q", "-m", "task work")
-    worktree_registry.reserve(**ARGS, worktree_path=str(okstra_wt),
-                              branch=BRANCH, base_ref="main")
-    return okstra_wt
-
-
-def test_local_checkout_removes_worktree_and_checks_out_in_main(tmp_path):
-    repo = _main_repo(tmp_path)
-    okstra_wt = _provision_okstra_worktree(repo, tmp_path)
-
-    out = handoff.local_checkout(project_root=repo, **ARGS)
-
-    assert out["status"] == "checked-out"
-    assert out["branch"] == BRANCH
-    assert not okstra_wt.exists()                       # okstra 워크트리 제거
-    assert _git(repo, "rev-parse", "--abbrev-ref", "HEAD") == BRANCH  # 메인이 task 브랜치
-    assert _git(repo, "rev-parse", "--verify", BRANCH)  # 브랜치 ref 보존
-    assert (repo / "work.txt").exists()                 # task 작업물이 메인에 보임
-    assert worktree_registry.lookup(**ARGS).status == "released"
-
-
-def test_local_checkout_aborts_when_main_dirty(tmp_path):
-    repo = _main_repo(tmp_path)
-    okstra_wt = _provision_okstra_worktree(repo, tmp_path)
-    (repo / "uncommitted.txt").write_text("dirty\n")    # 메인 dirty (.okstra 밖)
-
-    with pytest.raises(handoff.HandoffError, match="미커밋"):
-        handoff.local_checkout(project_root=repo, **ARGS)
-
-    assert okstra_wt.exists()                           # 보존
-    assert worktree_registry.lookup(**ARGS).status == "active"  # 미변경
-
-
-def test_local_checkout_errors_when_no_registry_entry(tmp_path):
-    repo = _main_repo(tmp_path)
-    with pytest.raises(handoff.HandoffError, match="registry"):
-        handoff.local_checkout(project_root=repo, **ARGS)
-```
-
-- [ ] **Step 2: 테스트 실패 확인**
-
-Run: `python3 -m pytest tests/handoff/test_handoff_local_checkout.py -v`
-Expected: FAIL — `AttributeError: module 'okstra_ctl.handoff' has no attribute 'local_checkout'`
-
-- [ ] **Step 3: import 확장**
-
-`scripts/okstra_ctl/handoff.py` 의 import 한 줄을 교체:
-
-```python
-from .worktree import compute_branch_name, compute_worktree_path
-```
-→
-```python
-from .worktree import (compute_branch_name, compute_worktree_path,
-                       main_worktree_path, is_dirty_excluding_okstra)
-```
-
-- [ ] **Step 4: `local_checkout()` 구현**
-
-`scripts/okstra_ctl/handoff.py` 에 `assemble(...)` 정의 바로 다음(즉 `record_verified` 앞)에 추가:
-
-```python
-def local_checkout(*, project_root, project_id, task_group, task_id) -> Dict[str, Any]:
-    """whole-task: okstra task-key 워크트리를 제거하고 task 브랜치를 메인
-    워크트리에 checkout 한다(브랜치 보존). 메인이 dirty 면 거부. base 브랜치는
-    건드리지 않는다."""
-    entry = worktree_registry.lookup(project_id, task_group, task_id)
-    if not entry or not entry.branch or not entry.worktree_path:
-        raise HandoffError(
-            "task-key worktree registry 엔트리가 없습니다 — local checkout 대상 없음")
-    main_wt = main_worktree_path(Path(project_root))
-    if is_dirty_excluding_okstra(main_wt):
-        raise HandoffError(
-            f"메인 워크트리에 미커밋 변경이 있습니다 ({main_wt}) — "
-            "커밋/스태시 후 다시 시도하세요")
-    _run_git(["worktree", "remove", "--force", entry.worktree_path], main_wt)
-    worktree_registry.release_status(project_id, task_group, task_id)
-    co = _run_git(["checkout", entry.branch], main_wt, check=False)
-    if co.returncode != 0:
-        raise HandoffError(
-            f"git checkout {entry.branch} 실패: {co.stderr.strip()} — 워크트리는 "
-            f"제거됨; 메인({main_wt})에서 수동 checkout 으로 복구하세요")
-    return {"ok": True, "branch": entry.branch, "mainWorktreePath": str(main_wt),
-            "removedWorktree": entry.worktree_path, "status": "checked-out"}
-```
-
-- [ ] **Step 5: argparse 서브커맨드 + 디스패치**
-
-`scripts/okstra_ctl/handoff.py` 의 `main()` 에서 `record-pr` 서브파서 등록 다음에 추가:
-
-```python
-    sp = sub.add_parser("local-checkout")
-    common(sp, plan=False)
-    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)
-```
-
-디스패치에서 `else:`(record-pr) 바로 앞에 elif 추가:
-
-```python
-        elif a.cmd == "local-checkout":
-            out = local_checkout(
-                project_root=Path(a.project_root).resolve(),
-                project_id=a.project_id, task_group=a.task_group,
-                task_id=a.task_id)
-```
-
-- [ ] **Step 6: 테스트 통과 확인**
-
-Run: `python3 -m pytest tests/handoff/test_handoff_local_checkout.py -v`
-Expected: PASS (3 passed)
-
-- [ ] **Step 7: handoff.mjs USAGE 갱신**
-
-`src/commands/execute/handoff.mjs` 의 USAGE 에서 `record-pr` 줄 다음에 추가:
-
-```
-  okstra handoff record-pr --plan-run-root <dir> --stages 2,3 \\
-    --branch <b> --url <u>
-  okstra handoff local-checkout --project-root <dir> --project-id <id> \\
-    --task-group <g> --task-id <t>
-```
-
-- [ ] **Step 8: CLI 스모크**
-
-Run: `node bin/okstra handoff --help`
-Expected: 출력에 `local-checkout` 줄이 보임.
-
-- [ ] **Step 9: 커밋**
-
-```bash
-git add scripts/okstra_ctl/handoff.py src/commands/execute/handoff.mjs tests/handoff/test_handoff_local_checkout.py
-git commit -m "feat(handoff): okstra handoff local-checkout 서브커맨드 추가"
-```
-
----
-
-### Task 2: release-handoff 프로필 — 액션 재편 + `local only` 정리
-
-**Files:**
-- Modify: `prompts/profiles/release-handoff.md`
-
-**Interfaces:**
-- Consumes: Task 1 의 CLI `okstra handoff local-checkout ...`.
-- Produces: 프로필 동작 — `local checkout`(첫째)/`push + PR`/`skip` 3지선다, whole-task 게이트, 확인 후 헬퍼 호출, 보고 deliverable.
-
-- [ ] **Step 1: 액션 선택 블록 교체**
-
-`prompts/profiles/release-handoff.md` 의 다음 블록(현재 22–26줄)을 교체:
-
-old:
-```
-  1. **Action selection** — present three choices and capture exactly one:
-     - `local only` — complete the handoff as a local delivery record: record the accepted, already-committed branch and end without push or PR.
-     - `push + PR` — push the feature branch, then open or reuse a pull request.
-     - `skip` — cancel delivery actions for now: record that release-handoff was intentionally skipped and end the run without any git command.
-     If the user picks `skip`, route directly to the final-report self-review pass.
-```
-new:
-```
-  1. **Action selection** — present three choices and capture exactly one:
-     - `local checkout` (whole-task mode only) — bring the verified task branch into the MAIN worktree for local testing (no push, no PR). See step 1c. When `HANDOFF_MODE` is `stage-group`, do NOT offer this option — tell the user "`local checkout` is whole-task mode only" and re-ask.
-     - `push + PR` — push the feature branch, then open or reuse a pull request.
-     - `skip` — cancel delivery actions for now: record that release-handoff was intentionally skipped and end the run without any git command.
-     If the user picks `skip`, route directly to the final-report self-review pass.
-  1c. **Local checkout execution** (only when the user picked `local checkout`) — confirm with the user that okstra will remove the okstra task worktree and `git checkout <feature branch>` in the MAIN worktree, and that the base branch is never modified. On confirmation run:
-      `okstra handoff local-checkout --project-root <project root> --project-id <id> --task-group <g> --task-id <t>`
-      Exit 1 means a precondition failed (MAIN worktree dirty, registry entry missing, or checkout failed): show the error verbatim and re-ask the action selection. On success the okstra task worktree no longer exists — the lead's cwd is gone, so EVERY subsequent step (final-report authoring included) MUST use absolute paths or run from the MAIN worktree. Then route to the final-report self-review pass.
-```
-
-- [ ] **Step 2: 잔존 `local only` 참조 정리**
-
-다음 세 줄을 각각 교체:
-
-68줄 old: `    - Q1 action: `local only` | `push + PR` | `skip`.`
-68줄 new: `    - Q1 action: `local checkout` | `push + PR` | `skip`.`
-
-75줄 old: `    - `- Not run (user picked local only or skip).``
-75줄 new: `    - `- Not run (user picked local checkout or skip).``
-
-79줄 old: `    - `- No PR action requested.` (user picked `local only` or `skip`)`
-79줄 new: `    - `- No PR action requested.` (user picked `local checkout` or `skip`)`
-
-- [ ] **Step 3: Local Checkout Outcome deliverable 추가**
-
-`Required deliverable shape` 의 **Pull Request Outcome** 블록(현재 78–82줄) 다음에 새 deliverable 추가:
-
-old:
-```
-    - `- PR creation skipped: <reason>` for any user-driven cancellation
-  - **Stage Group** (stage-group mode only): selected stages, each stage's single-stage verification report path + quoted `Verdict Token` row, collector branch name, merge commit SHAs from assemble, and the dependency-closure verdict (from the assemble output / error).
-```
-new:
-```
-    - `- PR creation skipped: <reason>` for any user-driven cancellation
-  - **Local Checkout Outcome**: one of
-    - `- Not run (user picked push + PR or skip).`
-    - `- Checked out <branch> into <main worktree path>; okstra task worktree <path> removed. Next: 로컬 테스트 후 PR 하려면 okstra-run 으로 release-handoff 재진입 → push + PR.`
-  - **Stage Group** (stage-group mode only): selected stages, each stage's single-stage verification report path + quoted `Verdict Token` row, collector branch name, merge commit SHAs from assemble, and the dependency-closure verdict (from the assemble output / error).
-```
-
-- [ ] **Step 4: 잔존 참조 일관성 확인**
-
-Run: `grep -n "local only" prompts/profiles/release-handoff.md`
-Expected: 출력 없음(모든 `local only` 제거됨).
-
-- [ ] **Step 5: 워크플로 validator**
-
-Run: `bash validators/validate-workflow.sh`
-Expected: PASS(또는 본 변경과 무관한 기존 상태 그대로 — 신규 실패 없음).
-
-- [ ] **Step 6: 커밋**
-
-```bash
-git add prompts/profiles/release-handoff.md
-git commit -m "feat(handoff): release-handoff 에 local checkout 액션 + local only 제거"
-```
-
----
-
-### Task 3: CHANGES.md + 빌드 + 최종 검증
-
-**Files:**
-- Modify: `CHANGES.md`
-
-- [ ] **Step 1: CHANGES.md 항목 추가**
-
-`CHANGES.md` 의 `## 2026-06-21` 섹션(없으면 최상단 날짜 섹션 위에 생성)에 추가:
-
-```markdown
-### feat(handoff): release-handoff 에 `local checkout` 액션 추가 — 검증된 브랜치를 메인 워크트리로
-
-- **배경**: okstra task 작업은 격리된 git worktree(`~/.okstra/worktrees/...`)에서 진행돼, 검증이 끝난 뒤 사용자가 결과를 로컬에서 테스트하려면 그 폴더로 직접 `cd` 해야 했다. task 브랜치를 메인 작업 디렉터리로 가져오는 한-스텝 경로가 없었다.
-- **해결**: release-handoff 액션 선택을 `local checkout`(신규, 첫째)/`push + PR`/`skip` 으로 재편하고(중복이던 `local only` 제거), 신규 `okstra handoff local-checkout` 헬퍼가 메인 워크트리 dirty 확인 후 okstra task 워크트리를 제거(브랜치 보존)하고 메인에서 `git checkout <task-branch>` 를 수행한다. base 브랜치는 건드리지 않는다(whole-task 모드 전용).
-- 사용자 영향: release-handoff 에서 `local checkout` 을 고르면, 검증된 task 브랜치가 메인 작업 디렉터리에 바로 체크아웃돼 별도 `cd` 없이 로컬 테스트할 수 있다. 메인에 미커밋 변경이 있으면 중단·안내한다. 기존 `local only` 액션은 `skip` 과 중복이라 제거됐다. (설치 환경은 `okstra install` 로 런타임 갱신 후 적용.)
-```
-
-- [ ] **Step 2: 런타임 빌드**
-
-Run: `npm run build`
-Expected: 성공(소스가 `runtime/` 으로 동기화됨).
-
-- [ ] **Step 3: 최종 검증 스윕**
-
-Run: `python3 -m pytest tests/handoff/test_handoff_local_checkout.py tests/handoff/test_handoff_assemble.py -q`
-Expected: PASS(신규 3 + 기존 회귀 무손상).
-
-Run: `node bin/okstra handoff --help`
-Expected: `local-checkout` 노출.
-
-- [ ] **Step 4: 커밋**
-
-```bash
-git add CHANGES.md
-git commit -m "docs(handoff): local checkout 액션 CHANGES 기록"
-```