okstra 0.39.0 → 0.40.0

package/docs/superpowers/plans/2026-06-02-okstra-run-branch-confirm-step.md

@@ -0,0 +1,337 @@
+# okstra-run 브랜치 결정 확인 단계 구현 계획
+
+> **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:** okstra-run wizard 의 최종 confirm 직전에 "새 worktree+브랜치 생성 vs 현재 worktree 재사용" 을 명시 확인하는 전용 `branch_confirm` 단계를 추가한다(동작 변경 없음, 확인 게이트만).
+
+**Architecture:** `worktree.py` 의 provisioning 결정 로직을 부수효과 없는 `preview_worktree_decision()` 으로 추출하고 `provision_task_worktree` 가 이를 호출하게 리팩터한다(미리보기=실제 보장). wizard 에 predicate-driven `branch_confirm` Step 을 추가해 그 헬퍼로 결정을 미리보고 picker 로 확인받는다. 강제는 state 전이 구조(`confirm` 도달 전 `branch_confirm` 필수).
+
+**Tech Stack:** Python 3 (pytest), wizard prompts JSON(`prompts/wizard/prompts.ko.json`).
+
+설계 근거: [docs/superpowers/specs/2026-06-02-okstra-run-branch-confirm-step-design.md](../specs/2026-06-02-okstra-run-branch-confirm-step-design.md)
+
+핵심 사실(검증됨):
+- okstra-run 스킬은 `--work-category` 를 넘기지 않으므로 wizard 경로의 work_category 는 `""` → 실제 브랜치는 `task-<task-id>` (`_work_category_prefix("")=="task"`). 미리보기도 `work_category=""` 로 동일 계산.
+- wizard 는 predicate-driven: 각 `Step.applies(state)` 가 참인 첫 미답 Step 이 다음 단계. prompt 텍스트는 `prompts/wizard/prompts.ko.json` 의 `steps.<id>`.
+- provision 결정 4갈래: not-git(`skipped-not-git`) / in-worktree(`skipped-in-worktree`) / registry active(`reused`) / 신규(`created`).
+
+---
+
+## File Structure
+
+- `scripts/okstra_ctl/worktree.py` — `WorktreeDecision` dataclass + `preview_worktree_decision()` 추출, `provision_task_worktree` 가 이를 사용하도록 리팩터.
+- `scripts/okstra_ctl/wizard.py` — `S_BRANCH_CONFIRM` 상수, `WizardState.branch_confirmed`, `_build_branch_confirm`/`_submit_branch_confirm`, STEPS 항목, `_ready_for_confirm` 갱신.
+- `prompts/wizard/prompts.ko.json` — `steps.branch_confirm` 텍스트.
+- `docs/kr/architecture.md`, `CHANGES.md` — 새 단계 / 사용자 영향.
+- tests: `tests/test_okstra_worktree.py`, `tests/test_okstra_ctl_wizard.py`, `tests/test_wizard_prompts.py`.
+
+---
+
+## Task 1: preview_worktree_decision 추출 + provision 리팩터
+
+**Files:**
+- Modify: `scripts/okstra_ctl/worktree.py`
+- Test: `tests/test_okstra_worktree.py`
+
+- [ ] **Step 1: 실패 테스트 작성** (`tests/test_okstra_worktree.py` 에 추가)
+
+```python
+def test_preview_decision_new_when_main_repo(tmp_path, monkeypatch):
+    import subprocess
+    from okstra_ctl.worktree import preview_worktree_decision
+    repo = tmp_path / "repo"; repo.mkdir()
+    subprocess.run(["git", "init", "-q"], cwd=repo, check=True)
+    monkeypatch.setenv("OKSTRA_HOME", str(tmp_path / "home"))
+    d = preview_worktree_decision(
+        project_root=repo, project_id="proj", task_group_segment="grp",
+        task_id_segment="dev-1", work_category="", base_ref="main",
+    )
+    assert d.status == "new"
+    assert d.branch == "task-dev-1"
+    assert d.base_ref == "main"
+    assert d.worktree_path.endswith("/proj/grp/dev-1")
+
+
+def test_preview_decision_not_git(tmp_path):
+    from okstra_ctl.worktree import preview_worktree_decision
+    d = preview_worktree_decision(
+        project_root=tmp_path, project_id="proj", task_group_segment="grp",
+        task_id_segment="dev-1", work_category="", base_ref="main",
+    )
+    assert d.status == "skipped-not-git"
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_okstra_worktree.py -k preview -q`
+Expected: FAIL — `ImportError: cannot import name 'preview_worktree_decision'`
+
+- [ ] **Step 3: WorktreeDecision + preview_worktree_decision 구현**
+
+`worktree.py` 에 추가 (기존 `WorktreeProvision` dataclass 근처). decision 은 provision 의 4갈래를 부수효과 없이 계산한다. registry 재사용/in-worktree/not-git 분기는 기존 `provision_task_worktree` 의 가드(`_is_git_repo`, `_is_inside_non_main_worktree`, `worktree_registry.lookup`)를 그대로 호출(모두 read-only).
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class WorktreeDecision:
+    status: str            # "new" | "reused" | "skipped-in-worktree" | "skipped-not-git"
+    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, task_group_segment, task_id_segment,
+    work_category, base_ref="",
+) -> "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_repo(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,
+    )
+```
+
+- [ ] **Step 4: provision_task_worktree 가 헬퍼를 쓰도록 리팩터**
+
+`provision_task_worktree` 의 결정 분기(현재 not-git / in-worktree / registry-lookup 구간, 약 line 494-532)를 `decision = preview_worktree_decision(...)` 한 줄 호출로 교체하고, `decision.status` 로 분기:
+- `skipped-not-git` → 기존 note 로 `WorktreeProvision(status="skipped-not-git", ...)` 반환.
+- `skipped-in-worktree` → 기존 note 로 반환.
+- `reused` → `worktree_registry.touch_phase(...)` + `_seed_worktree_settings_symlink(Path(decision.path))` 후 기존 reused note 로 반환.
+- `new` → `decision.branch` / `decision.path` 를 사용해 기존 생성 로직(`git worktree add` + `worktree_registry.reserve` + seed) 그대로 수행, `status="created"` 반환.
+
+핵심: 결정(분기 판정 + branch/path 계산)은 헬퍼가 단일 소스. provision 은 실행만.
+
+- [ ] **Step 5: 통과 + 회귀 확인**
+
+Run: `python3 -m pytest tests/test_okstra_worktree.py -q`
+Expected: 신규 preview 테스트 통과 + 기존 worktree 테스트 전부 통과(회귀 0).
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add scripts/okstra_ctl/worktree.py tests/test_okstra_worktree.py
+git commit -m "refactor(worktree): preview_worktree_decision 추출 + provision 공유"
+```
+
+---
+
+## Task 2: wizard branch_confirm 단계
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py`
+- Modify: `prompts/wizard/prompts.ko.json`
+- Test: `tests/test_okstra_ctl_wizard.py`, `tests/test_wizard_prompts.py`
+
+- [ ] **Step 1: 프롬프트 텍스트 추가** (`prompts/wizard/prompts.ko.json` 의 `steps` 객체에)
+
+```json
+"branch_confirm": {
+  "label": "{summary}",
+  "labels": {
+    "new": "새 브랜치 `{branch}` 를 base-ref `{base_ref}` 에서 새 worktree(`{path}`)에 생성합니다 — 진행할까요?",
+    "reuse": "현재 worktree(`{path}`, 브랜치 `{branch}`)를 재사용합니다 — 진행할까요?",
+    "in_worktree": "현재 worktree(`{path}`)에서 그대로 진행합니다(이미 non-main worktree) — 진행할까요?",
+    "not_git": "git 저장소가 아니므로 `{path}` 에서 직접 진행합니다 — 진행할까요?"
+  },
+  "options": { "proceed": "진행", "edit": "base-ref 다시 고르기" },
+  "echo_template": "branch-confirm: {value}"
+}
+```
+
+- [ ] **Step 2: 실패 테스트 작성** — 핸들러 직접 테스트 (전체 wizard 구동 없이; 기존 파일의 `WizardState(...)` 직접 구성 + 핸들러 직접 호출 패턴을 따름. `_seed_wizard_prompts` 헬퍼는 파일 상단에 이미 있음)
+
+```python
+def test_build_branch_confirm_new_worktree(tmp_path, monkeypatch):
+    import subprocess
+    from okstra_ctl.wizard import WizardState, _build_branch_confirm, S_BRANCH_CONFIRM
+    repo = tmp_path / "repo"; repo.mkdir()
+    subprocess.run(["git", "init", "-q"], cwd=repo, check=True)
+    _seed_wizard_prompts(repo)
+    monkeypatch.setenv("OKSTRA_HOME", str(tmp_path / "home"))
+    state = WizardState(
+        workspace_root=str(repo), project_root=str(repo),
+        project_id="proj", task_group="grp", task_id="dev-1", base_ref="main",
+    )
+    p = _build_branch_confirm(state)
+    assert p.step == S_BRANCH_CONFIRM and p.kind == "pick"
+    assert "task-dev-1" in p.label and "main" in p.label
+    vals = [o.value for o in p.options]
+    assert "proceed" in vals and "edit" in vals   # new 모드 → edit 제공
+
+
+def test_submit_branch_confirm_proceed_and_edit(tmp_path):
+    from okstra_ctl.wizard import WizardState, _submit_branch_confirm
+    state = WizardState(
+        workspace_root=str(tmp_path), project_root=str(tmp_path),
+        project_id="proj", task_group="grp", task_id="dev-1", base_ref="main",
+    )
+    assert _submit_branch_confirm(state, "proceed") is not None
+    assert state.branch_confirmed is True
+    state.branch_confirmed = True
+    _submit_branch_confirm(state, "edit")
+    assert state.branch_confirmed is None   # edit → 재확인 위해 리셋
+```
+
+(전이 자체 — `branch_confirm → confirm` 순서 — 는 기존 confirm-도달 테스트를 갱신해 검증한다. Step 5 참조.)
+
+- [ ] **Step 3: 실패 확인**
+
+Run: `python3 -m pytest tests/test_okstra_ctl_wizard.py -k branch_confirm -q`
+Expected: FAIL (S_BRANCH_CONFIRM 미정의 / 전이 없음).
+
+- [ ] **Step 4: wizard 구현** (`scripts/okstra_ctl/wizard.py`)
+
+1) 상수: `S_CONFIRM` 정의 부근에 `S_BRANCH_CONFIRM = "branch_confirm"`.
+2) `WizardState` 에 필드 추가: `branch_confirmed: Optional[bool] = None`.
+3) build/submit 핸들러 추가:
+
+```python
+def _build_branch_confirm(state: WizardState) -> Prompt:
+    from okstra_ctl.worktree import preview_worktree_decision
+    decision = preview_worktree_decision(
+        project_root=Path(state.project_root),
+        project_id=state.project_id,
+        task_group_segment=state.task_group,
+        task_id_segment=state.task_id,
+        work_category="",            # okstra-run 경로는 --work-category 를 안 넘김
+        base_ref=state.base_ref,
+    )
+    key = {
+        "new": "new", "reused": "reuse",
+        "skipped-in-worktree": "in_worktree", "skipped-not-git": "not_git",
+    }[decision.status]
+    t = _p(state.workspace_root, "branch_confirm")
+    label = t["labels"][key].format(
+        branch=decision.branch or "(none)",
+        base_ref=decision.base_ref or "(HEAD)",
+        path=decision.path,
+    )
+    # new 모드에서만 Edit 제공; 그 외에는 Proceed 만.
+    opts = t["options"]
+    options = [_opt("proceed", opts["proceed"])]
+    if decision.status == "new":
+        options.append(_opt("edit", opts["edit"]))
+    return Prompt(step=S_BRANCH_CONFIRM, kind="pick", label=label,
+                  options=options, echo_template=t["echo_template"])
+
+
+def _submit_branch_confirm(state: WizardState, value: str) -> Optional[str]:
+    if value == "edit":
+        _reset_from(state, S_BASE_REF_PICK)   # base-ref 재질문
+        state.branch_confirmed = None
+        return "branch-confirm: edit"
+    if value != "proceed":
+        raise WizardError(f"expected 'proceed' or 'edit', got: {value!r}")
+    state.branch_confirmed = True
+    return "branch-confirm: proceed"
+```
+
+4) STEPS 리스트에서 `Step(S_CONFIRM, ...)` **바로 앞**에 삽입:
+
+```python
+    Step(S_BRANCH_CONFIRM,
+         applies=lambda s: _ready_for_confirm(s) and s.branch_confirmed is None,
+         build=_build_branch_confirm, submit=_submit_branch_confirm,
+         owns=("branch_confirmed",)),
+```
+
+5) `_ready_for_confirm` 가 confirm 전에 branch_confirm 을 강제하도록, `S_CONFIRM` 의 `applies` 를 `_ready_for_confirm(s) and s.branch_confirmed is True and s.confirmed is None` 로 변경.
+
+> 주의: `applies` 술어가 `_ready_for_confirm(s)` 를 공유하므로, STEPS 리스트에서 `S_BRANCH_CONFIRM` 이 `S_CONFIRM` 보다 **앞에** 와야 branch_confirm 이 먼저 매칭된다(첫 매칭 우선). `_reset_from` 가 `branch_confirmed` 도 리셋 범위에 포함하는지 확인 — base-ref edit 시 branch_confirmed 가 다시 None 이어야 재계산된다(위 submit 에서 명시적으로 None 처리했으니 OK).
+
+- [ ] **Step 5: 기존 confirm-도달 테스트 갱신 (필수 — 안 하면 회귀)**
+
+`tests/test_okstra_ctl_wizard.py` 에서 `next_prompt(state).step == S_CONFIRM` 를 단언하는 기존 테스트들(현재 약 line 478, 519, 664, 685, 899 — `grep -n "== S_CONFIRM" tests/test_okstra_ctl_wizard.py` 로 전수 확인)은 이제 confirm **직전에 `S_BRANCH_CONFIRM` 이 먼저 나온다.** 각 지점을 다음 패턴으로 갱신:
+
+```python
+    p = next_prompt(state)
+    assert p.step == S_BRANCH_CONFIRM      # 새 게이트가 먼저
+    submit(state, "proceed")
+    assert next_prompt(state).step == S_CONFIRM
+```
+
+`S_BRANCH_CONFIRM` 을 테스트 상단 import 에 추가. 누락하면 해당 테스트들이 `S_BRANCH_CONFIRM != S_CONFIRM` 로 실패한다 — 전수 갱신할 것.
+
+- [ ] **Step 6: 통과 + 회귀**
+
+Run: `python3 -m pytest tests/test_okstra_ctl_wizard.py tests/test_wizard_prompts.py -q`
+Expected: 신규 + 갱신된 기존 전부 통과. 이어서 `python3 -m pytest tests/ -q` 전체 회귀 0.
+
+- [ ] **Step 7: 커밋**
+
+```bash
+git add scripts/okstra_ctl/wizard.py prompts/wizard/prompts.ko.json tests/test_okstra_ctl_wizard.py tests/test_wizard_prompts.py
+git commit -m "feat(wizard): branch_confirm 단계 — 브랜치/worktree 결정 명시 확인"
+```
+
+---
+
+## Task 3: okstra-run 스킬 안내 + 문서
+
+**Files:**
+- Modify: `skills/okstra-run/SKILL.md`
+- Modify: `docs/kr/architecture.md`, `CHANGES.md`
+
+- [ ] **Step 1: 스킬 1줄 안내** — `skills/okstra-run/SKILL.md` 의 pick 처리 설명 부근에, `branch_confirm` 도 일반 pick step 으로 그대로 렌더된다는 1줄 추가(별도 처리 불필요 명시). 기존 step 설명 형식을 따른다.
+
+- [ ] **Step 2: architecture.md** — requirements-discovery fan-out 절 부근(또는 wizard/worktree 설명부)에 추가:
+
+```markdown
+#### branch_confirm (worktree 결정 확인)
+
+okstra-run wizard 는 최종 confirm 직전에 `branch_confirm` 단계로 "새 브랜치/worktree 생성 vs
+현재 worktree 재사용"을 명시 확인한다. 결정은 `worktree.preview_worktree_decision()`(부수효과 없음)
+으로 미리보고, 같은 헬퍼를 `provision_task_worktree` 가 실행에 쓰므로 미리보기와 실제가 일치한다.
+worktree 격리 동작 자체는 변경 없음(확인 게이트만).
+```
+
+- [ ] **Step 3: CHANGES.md** — `## 2026-06-02` 섹션에 추가:
+
+```markdown
+### feat(wizard): okstra-run 에 브랜치/worktree 결정 확인 단계 추가
+
+- okstra-run wizard 가 최종 confirm 직전에 `branch_confirm` 단계를 띄워, 새 브랜치를 base-ref 에서
+  새 worktree 에 만드는지(또는 현재 worktree 재사용)를 명시 확인하게 함. auto mode 에서 base-ref 가
+  조용히 선택되어 의도치 않은 브랜치가 생기던 문제의 가시성을 높임. worktree 격리 동작은 변경 없음.
+- 사용자 영향: 다음 release + `npx -y okstra@latest install` 후 적용. okstra-run 진행 시 브랜치 생성
+  여부를 확인하는 단계가 한 번 더 추가된다(full-auto 가 아닌 경우 실제로 멈춰 확인).
+```
+
+- [ ] **Step 4: 커밋**
+
+```bash
+git add skills/okstra-run/SKILL.md docs/kr/architecture.md CHANGES.md
+git commit -m "docs(branch-confirm): 스킬 안내 + architecture + CHANGES"
+```
+
+---
+
+## Task 4: 전체 회귀 + 빌드
+
+- [ ] **Step 1:** `python3 -m pytest tests/ -q` → 전부 통과(회귀 0).
+- [ ] **Step 2:** `npm run build` → 성공(runtime 동기화).
+- [ ] **Step 3:** `node bin/okstra --version` → 버전 출력.
+- [ ] **Step 4:** `git status --short` → clean 확인.