okstra 0.102.1 → 0.102.3

package/docs/superpowers/plans/2026-06-11-wizard-whole-task-final-verification.md

@@ -1,526 +0,0 @@
-# wizard whole-task final-verification 노출 Implementation Plan
-
-> **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 위저드의 final-verification stage picker 에서 "전체 task 검증" 을 명시 항목으로 선택할 수 있게 한다(prepare 계약 무변경, `auto` 토큰 미사용).
-
-**Architecture:** 위저드 레이어만 수정한다. picker 가 `consumers.jsonl` 의 done 행을 읽어 stage 별 done 마킹을 붙이고, 전 stage done 일 때만 "전체 task" 항목(내부 sentinel `__whole_task__`)을 노출한다. `render_args` 가 sentinel 을 빈 stage(`""`)로 변환해 prepare 의 기존 whole-task 경로를 탄다. 머지/clean/active 전제는 prepare 의 PrepareError 게이트에 위임한다.
-
-**Tech Stack:** Python 3 (`scripts/okstra_ctl/wizard.py`), JSON 프롬프트(`prompts/wizard/prompts.ko.json`), pytest.
-
-**Spec:** [2026-06-11-wizard-whole-task-final-verification-design.md](../specs/2026-06-11-wizard-whole-task-final-verification-design.md)
-
----
-
-## File Structure
-
-- `scripts/okstra_ctl/wizard.py` — sentinel 상수, done/Stage-Map 헬퍼, picker·submit·render_args·confirmation 수정.
-- `prompts/wizard/prompts.ko.json` — `steps.stage_pick.options` 에 whole-task·done 마킹 라벨 추가.
-- `tests/test_wizard_stage_pick.py` — picker·submit·render_args 회귀 + 신규 케이스.
-- `tests/test_wizard_whole_task_fv.py` — done 헬퍼 + whole-task 노출 게이트 신규 테스트.
-
-기존 단독-stage UX(`54b9482`)·prepare·CLI 계약은 건드리지 않는다.
-
----
-
-## Task 1: sentinel 상수 + done/Stage-Map 헬퍼
-
-**Files:**
-- Modify: `scripts/okstra_ctl/wizard.py` (토큰 블록 1354-1360 근처, 헬퍼는 `_stage_auto_allowed` 1778 부근)
-- Test: `tests/test_wizard_whole_task_fv.py` (create)
-
-- [ ] **Step 1: 실패 테스트 작성**
-
-`tests/test_wizard_whole_task_fv.py`:
-
-```python
-import importlib
-import json
-import sys
-from pathlib import Path
-
-REPO = Path(__file__).resolve().parents[1]
-
-
-def _load_wizard():
-    if "okstra_ctl.wizard" in sys.modules:
-        return sys.modules["okstra_ctl.wizard"]
-    if str(REPO / "scripts") not in sys.path:
-        sys.path.insert(0, str(REPO / "scripts"))
-    return importlib.import_module("okstra_ctl.wizard")
-
-
-def _plan_run(tmp_path: Path, done_stages: list[int]) -> Path:
-    """plan_run_root/reports/plan.md + plan_run_root/consumers.jsonl 를 만들고
-    approved plan 경로를 돌려준다. plan_run_root == plan.resolve().parents[1]."""
-    run = tmp_path / "run"
-    (run / "reports").mkdir(parents=True)
-    plan = run / "reports" / "plan.md"
-    fixture = (REPO / "tests" / "fixtures" / "plans"
-               / "valid_three_stage_parallel.md").read_text(encoding="utf-8")
-    plan.write_text(fixture + "\n- [x] Approved\n", encoding="utf-8")
-    rows = [json.dumps({"status": "done", "stage": n,
-                        "impl_task_key": "k", "head_commit": f"sha{n}"})
-            for n in done_stages]
-    (run / "consumers.jsonl").write_text(
-        ("\n".join(rows) + "\n") if rows else "", encoding="utf-8")
-    return plan
-
-
-def test_done_stage_numbers_reads_consumers(tmp_path):
-    wizard = _load_wizard()
-    plan = _plan_run(tmp_path, [1, 3])
-    state = wizard.WizardState(
-        workspace_root=str(REPO), project_root=str(tmp_path),
-        project_id="demo", task_type="final-verification",
-        approved_plan_path=str(plan))
-    assert wizard._done_stage_numbers(state) == {1, 3}
-
-
-def test_whole_task_allowed_true_when_all_done(tmp_path):
-    wizard = _load_wizard()
-    plan = _plan_run(tmp_path, [1, 2, 3])
-    state = wizard.WizardState(
-        workspace_root=str(REPO), project_root=str(tmp_path),
-        project_id="demo", task_type="final-verification",
-        approved_plan_path=str(plan))
-    assert wizard._whole_task_allowed(state) is True
-
-
-def test_whole_task_allowed_false_when_partial(tmp_path):
-    wizard = _load_wizard()
-    plan = _plan_run(tmp_path, [1, 2])
-    state = wizard.WizardState(
-        workspace_root=str(REPO), project_root=str(tmp_path),
-        project_id="demo", task_type="final-verification",
-        approved_plan_path=str(plan))
-    assert wizard._whole_task_allowed(state) is False
-
-
-def test_whole_task_allowed_false_for_implementation(tmp_path):
-    wizard = _load_wizard()
-    plan = _plan_run(tmp_path, [1, 2, 3])
-    state = wizard.WizardState(
-        workspace_root=str(REPO), project_root=str(tmp_path),
-        project_id="demo", task_type="implementation",
-        approved_plan_path=str(plan))
-    assert wizard._whole_task_allowed(state) is False
-```
-
-- [ ] **Step 2: 테스트 실패 확인**
-
-Run: `python3 -m pytest tests/test_wizard_whole_task_fv.py -v`
-Expected: FAIL — `AttributeError: module ... has no attribute '_done_stage_numbers'`
-
-- [ ] **Step 3: 최소 구현**
-
-`scripts/okstra_ctl/wizard.py` 의 토큰 블록(`_REUSE_LAST_TOKEN = "__reuse_last__"` 등이 있는 1354-1360 근처)에 sentinel 추가:
-
-```python
-WHOLE_TASK_STAGE = "__whole_task__"
-```
-
-`_stage_auto_allowed` 정의(1778 근처) 바로 아래에 헬퍼 3개 추가:
-
-```python
-def _parse_stage_objects(state: WizardState) -> list:
-    """승인 plan 의 Stage Map stage 객체 목록. validator 의 _parse_stage_map 재사용.
-    `_build_stage_pick` 과 `_whole_task_allowed` 가 공유한다."""
-    import importlib.util as _ilu
-    import sys as _sys
-    plan_text = Path(state.approved_plan_path).read_text(encoding="utf-8")
-    validator_path = (Path(state.workspace_root) / "validators"
-                      / "validate-implementation-plan-stages.py")
-    spec = _ilu.spec_from_file_location("_ip_stage_v_wizard", str(validator_path))
-    if spec is None or spec.loader is None:
-        raise WizardError(f"cannot load stage validator at {validator_path}")
-    mod = _ilu.module_from_spec(spec)
-    _sys.modules["_ip_stage_v_wizard"] = mod
-    try:
-        spec.loader.exec_module(mod)
-        stages, _errs = mod._parse_stage_map(plan_text)
-    finally:
-        _sys.modules.pop("_ip_stage_v_wizard", None)
-    return stages
-
-
-def _done_stage_numbers(state: WizardState) -> set:
-    """approved plan 을 소비한 implementation run 들의 consumers.jsonl 에서
-    done 처리된 stage 번호 집합. git 호출 없음 — 파일 읽기만(prepare 와 동일 SSOT)."""
-    if not state.approved_plan_path:
-        return set()
-    from .consumers import (read_consumers, backfill_done_from_carry,
-                            latest_done_by_stage)
-    plan_run_root = Path(state.approved_plan_path).resolve().parents[1]
-    backfill_done_from_carry(plan_run_root)
-    rows = read_consumers(plan_run_root)
-    return set(latest_done_by_stage(rows).keys())
-
-
-def _whole_task_allowed(state: WizardState) -> bool:
-    """final-verification 이고 Stage Map 의 모든 stage 가 done 일 때만 True.
-    위저드는 done 만 본다 — 머지/clean/active 는 prepare 게이트가 강제한다."""
-    if state.task_type != "final-verification":
-        return False
-    if not state.approved_plan_path:
-        return False
-    stages = _parse_stage_objects(state)
-    if not stages:
-        return False
-    done = _done_stage_numbers(state)
-    return all(s.stage_number in done for s in stages)
-```
-
-- [ ] **Step 4: 테스트 통과 확인**
-
-Run: `python3 -m pytest tests/test_wizard_whole_task_fv.py -v`
-Expected: 4 PASS
-
-- [ ] **Step 5: 커밋**
-
-```bash
-git add scripts/okstra_ctl/wizard.py tests/test_wizard_whole_task_fv.py
-git commit -m "feat(wizard): final-verification done/whole-task 헬퍼 추가"
-```
-
----
-
-## Task 2: stage picker 에 done 마킹 + 전체 task 항목
-
-**Files:**
-- Modify: `scripts/okstra_ctl/wizard.py:1494-1533` (`_build_stage_pick`)
-- Modify: `prompts/wizard/prompts.ko.json` (`steps.stage_pick.options`)
-- Test: `tests/test_wizard_whole_task_fv.py`
-
-- [ ] **Step 1: 실패 테스트 추가**
-
-`tests/test_wizard_whole_task_fv.py` 끝에 추가(`_plan_run` 헬퍼 재사용):
-
-```python
-def test_picker_shows_whole_task_when_all_done(tmp_path):
-    wizard = _load_wizard()
-    plan = _plan_run(tmp_path, [1, 2, 3])
-    state = wizard.WizardState(
-        workspace_root=str(REPO), project_root=str(tmp_path),
-        project_id="demo", task_type="final-verification",
-        approved_plan_path=str(plan))
-    prompt = wizard._build_stage_pick(state)
-    values = [o.value for o in prompt.options]
-    assert wizard.WHOLE_TASK_STAGE in values
-    assert "auto" not in values
-    assert values == [wizard.WHOLE_TASK_STAGE, "1", "2", "3"]
-
-
-def test_picker_hides_whole_task_when_partial(tmp_path):
-    wizard = _load_wizard()
-    plan = _plan_run(tmp_path, [1, 2])
-    state = wizard.WizardState(
-        workspace_root=str(REPO), project_root=str(tmp_path),
-        project_id="demo", task_type="final-verification",
-        approved_plan_path=str(plan))
-    prompt = wizard._build_stage_pick(state)
-    values = [o.value for o in prompt.options]
-    assert wizard.WHOLE_TASK_STAGE not in values
-    # stage 3 미완 마킹이 라벨에 보인다
-    label_3 = next(o.label for o in prompt.options if o.value == "3")
-    assert "미완" in label_3
-    label_1 = next(o.label for o in prompt.options if o.value == "1")
-    assert "done" in label_1
-```
-
-- [ ] **Step 2: 테스트 실패 확인**
-
-Run: `python3 -m pytest tests/test_wizard_whole_task_fv.py -k picker -v`
-Expected: FAIL — whole-task 항목이 없고 done 마킹이 없음
-
-- [ ] **Step 3: 구현**
-
-`prompts/wizard/prompts.ko.json` 의 `steps.stage_pick.options` 를 다음으로 교체:
-
-```json
-    "options": {
-      "auto": "auto (다음 미완료 stage)",
-      "whole_task": "전체 task 검증 (모든 stage)",
-      "done_mark": "[done]",
-      "undone_mark": "[미완]"
-    }
-```
-
-`scripts/okstra_ctl/wizard.py` 의 `_build_stage_pick` 본문을 교체(파싱은 `_parse_stage_objects` 로 위임):
-
-```python
-def _build_stage_pick(state: WizardState) -> Prompt:
-    """Parse the Stage Map from the approved plan and build the stage picker."""
-    t = _p(state.workspace_root, "stage_pick")
-    stages = _parse_stage_objects(state)
-    is_fv = state.task_type == "final-verification"
-    label = (
-        t.get("label_final_verification", t["label"])
-        if is_fv else t["label"]
-    )
-    done = _done_stage_numbers(state) if is_fv else set()
-    options = []
-    if _stage_auto_allowed(state):
-        options.append(_opt("auto", t["options"]["auto"]))
-    if is_fv and stages and all(s.stage_number in done for s in stages):
-        options.append(_opt(
-            WHOLE_TASK_STAGE,
-            t["options"].get("whole_task", "전체 task 검증 (모든 stage)"),
-        ))
-    for s in stages:
-        depends = ",".join(map(str, s.depends_on)) or "(none)"
-        suffix = ""
-        if is_fv:
-            mark = (t["options"].get("done_mark", "[done]")
-                    if s.stage_number in done
-                    else t["options"].get("undone_mark", "[미완]"))
-            suffix = f"  {mark}"
-        options.append(_opt(
-            str(s.stage_number),
-            f"{s.stage_number}: {s.title}  "
-            f"[depends-on: {depends} | steps: {s.step_count}]{suffix}",
-        ))
-    return Prompt(
-        step=S_STAGE_PICK, kind="pick",
-        label=label,
-        options=options,
-        echo_template=t["echo_template"],
-    )
-```
-
-- [ ] **Step 4: 테스트 통과 + 기존 picker 회귀 확인**
-
-Run: `python3 -m pytest tests/test_wizard_whole_task_fv.py tests/test_wizard_stage_pick.py -v`
-Expected: 신규 picker 2 PASS + `test_final_verification_stage_pick_excludes_auto`(이제 stage 별 라벨에 `[미완]` 가 붙지만 value 는 `["1","2","3"]` 유지) 포함 기존 전부 PASS
-
-> 주의: `test_final_verification_stage_pick_excludes_auto` 는 done 행이 없는 plan 을 쓰므로 whole-task 항목이 안 뜨고 `values == ["1","2","3"]` 가 유지된다. 라벨 문자열은 검사하지 않으므로 마킹 추가와 무관하다.
-
-- [ ] **Step 5: 커밋**
-
-```bash
-git add scripts/okstra_ctl/wizard.py prompts/wizard/prompts.ko.json tests/test_wizard_whole_task_fv.py
-git commit -m "feat(wizard): final-verification picker 에 done 마킹 + 전체 task 항목"
-```
-
----
-
-## Task 3: submit 이 전체 task sentinel 수용
-
-**Files:**
-- Modify: `scripts/okstra_ctl/wizard.py:1536-1552` (`_submit_stage_pick`)
-- Test: `tests/test_wizard_whole_task_fv.py`
-
-- [ ] **Step 1: 실패 테스트 추가**
-
-```python
-def test_submit_accepts_whole_task_for_fv(tmp_path):
-    wizard = _load_wizard()
-    state = wizard.WizardState(
-        workspace_root=str(REPO), project_root=str(tmp_path),
-        project_id="demo", task_type="final-verification")
-    result = wizard._submit_stage_pick(state, wizard.WHOLE_TASK_STAGE)
-    assert state.selected_stage == wizard.WHOLE_TASK_STAGE
-    assert result == f"stage: {wizard.WHOLE_TASK_STAGE}"
-
-
-def test_submit_rejects_whole_task_for_implementation(tmp_path):
-    wizard = _load_wizard()
-    state = wizard.WizardState(
-        workspace_root=str(REPO), project_root=str(tmp_path),
-        project_id="demo", task_type="implementation")
-    try:
-        wizard._submit_stage_pick(state, wizard.WHOLE_TASK_STAGE)
-        assert False, "expected WizardError"
-    except wizard.WizardError as exc:
-        assert "final-verification" in str(exc)
-```
-
-- [ ] **Step 2: 테스트 실패 확인**
-
-Run: `python3 -m pytest tests/test_wizard_whole_task_fv.py -k submit -v`
-Expected: FAIL — sentinel 이 `int()` 분기로 빠져 "stage number" 에러
-
-- [ ] **Step 3: 구현**
-
-`_submit_stage_pick` 을 교체:
-
-```python
-def _submit_stage_pick(state: WizardState, answer: str) -> Optional[str]:
-    if not answer:
-        raise WizardError("value required")
-    if answer == "auto":
-        if not _stage_auto_allowed(state):
-            raise WizardError(
-                "final-verification requires an explicit stage number"
-            )
-    elif answer == WHOLE_TASK_STAGE:
-        if state.task_type != "final-verification":
-            raise WizardError(
-                "whole-task verification is only valid for final-verification"
-            )
-    else:
-        try:
-            int(answer)
-        except ValueError:
-            raise WizardError(
-                f"answer must be 'auto', whole-task, or a stage number, "
-                f"got {answer!r}"
-            )
-    state.selected_stage = answer
-    return f"stage: {answer}"
-```
-
-- [ ] **Step 4: 테스트 통과 + 기존 submit 회귀 확인**
-
-Run: `python3 -m pytest tests/test_wizard_whole_task_fv.py tests/test_wizard_stage_pick.py -k submit -v`
-Expected: 신규 2 + 기존 submit 케이스 전부 PASS
-
-- [ ] **Step 5: 커밋**
-
-```bash
-git add scripts/okstra_ctl/wizard.py tests/test_wizard_whole_task_fv.py
-git commit -m "feat(wizard): _submit_stage_pick 이 전체 task sentinel 수용"
-```
-
----
-
-## Task 4: render_args 빈 stage 변환 + confirmation 라벨
-
-**Files:**
-- Modify: `scripts/okstra_ctl/wizard.py:2792-2806` (`render_args` stage 결정부)
-- Modify: `scripts/okstra_ctl/wizard.py:2872-2878` (`confirmation_block` stage 표기부)
-- Test: `tests/test_wizard_whole_task_fv.py`
-
-- [ ] **Step 1: 실패 테스트 추가**
-
-```python
-def test_render_args_whole_task_emits_empty_stage(tmp_path):
-    wizard = _load_wizard()
-    plan = _plan_run(tmp_path, [1, 2, 3])
-    state = wizard.WizardState(
-        workspace_root=str(REPO), project_root=str(tmp_path),
-        project_id="demo", task_type="final-verification",
-        approved_plan_path=str(plan),
-        selected_stage=wizard.WHOLE_TASK_STAGE)
-    args = wizard.render_args(state)
-    assert args["stage"] == ""
-    assert args["base-ref"] == ""  # final-verification 은 base 자동 해소
-
-
-def test_render_args_single_stage_fv_keeps_number(tmp_path):
-    wizard = _load_wizard()
-    plan = _plan_run(tmp_path, [2])
-    state = wizard.WizardState(
-        workspace_root=str(REPO), project_root=str(tmp_path),
-        project_id="demo", task_type="final-verification",
-        approved_plan_path=str(plan), selected_stage="2")
-    args = wizard.render_args(state)
-    assert args["stage"] == "2"
-
-
-def test_confirmation_block_labels_whole_task(tmp_path):
-    wizard = _load_wizard()
-    plan = _plan_run(tmp_path, [1, 2, 3])
-    state = wizard.WizardState(
-        workspace_root=str(REPO), project_root=str(tmp_path),
-        project_id="demo", task_group="g", task_id="t",
-        task_type="final-verification", approved_plan_path=str(plan),
-        selected_stage=wizard.WHOLE_TASK_STAGE)
-    block = wizard.confirmation_block(state)
-    assert "전체 task" in block
-```
-
-- [ ] **Step 2: 테스트 실패 확인**
-
-Run: `python3 -m pytest tests/test_wizard_whole_task_fv.py -k "render_args or confirmation" -v`
-Expected: FAIL — sentinel 이 그대로 stage 로 새거나 `WizardError`("requires an explicit stage number")
-
-- [ ] **Step 3: 구현**
-
-`render_args` 의 stage 결정 블록(현재 `elif state.task_type == "final-verification":` 분기, 2799-2804)을 교체:
-
-```python
-    if state.task_type == "implementation":
-        stage = state.selected_stage or "auto"
-    elif state.task_type == "final-verification":
-        if state.selected_stage == WHOLE_TASK_STAGE:
-            stage = ""  # prepare 가 빈 stage 를 whole-task 로 해석
-        elif not state.selected_stage or state.selected_stage == "auto":
-            raise WizardError(
-                "final-verification requires an explicit stage number"
-            )
-        else:
-            stage = state.selected_stage
-    else:
-        stage = ""
-```
-
-`confirmation_block` 의 stage 표기 블록(2874-2878)을 교체:
-
-```python
-        stage = (
-            "전체 task"
-            if state.selected_stage == WHOLE_TASK_STAGE
-            else (state.selected_stage
-                  or ("auto" if state.task_type == "implementation"
-                      else "(not selected)"))
-        )
-```
-
-- [ ] **Step 4: 테스트 통과 + render_args 회귀 확인**
-
-Run: `python3 -m pytest tests/test_wizard_whole_task_fv.py tests/test_wizard_stage_pick.py -k "render_args or confirmation" -v`
-Expected: 신규 3 + 기존 render_args 케이스(`test_render_args_includes_stage_for_implementation` 등) 전부 PASS
-
-- [ ] **Step 5: 커밋**
-
-```bash
-git add scripts/okstra_ctl/wizard.py tests/test_wizard_whole_task_fv.py
-git commit -m "feat(wizard): render_args 가 전체 task sentinel 을 빈 stage 로 변환"
-```
-
----
-
-## Task 5: 통합 검증 + CHANGES 기록
-
-**Files:**
-- Modify: `CHANGES.md`
-- Test: 전체 위저드 스위트
-
-- [ ] **Step 1: 전체 위저드 테스트**
-
-Run: `python3 -m pytest tests/test_wizard_whole_task_fv.py tests/test_wizard_stage_pick.py tests/test_wizard_final_verification_stage.py tests/test_okstra_ctl_wizard.py -v`
-Expected: 전부 PASS (whole-task 경로에서도 base-ref/branch-confirm 생략이 유지되는지 `test_okstra_ctl_wizard.py` 가 커버)
-
-- [ ] **Step 2: build 후 runtime sync 확인**
-
-Run: `npm run build && node bin/okstra --version`
-Expected: 빌드 성공, 버전 출력. `runtime/` 에 prompts.ko.json·wizard.py 변경분이 반영됨(직접 편집 금지, 빌드로만).
-
-- [ ] **Step 3: CHANGES.md 항목 추가**
-
-`CHANGES.md` 의 최상단 날짜 섹션(`## 2026-06-11`, 없으면 생성)에 추가:
-
-```markdown
-### feat(wizard): final-verification 위저드에서 전체 task 검증 선택 지원
-
-- **배경**: `54b9482` 이후 okstra-run 위저드의 `final-verification` 은 명시 stage 만 선택 가능해, 모든 stage 를 머지한 뒤 한 번 도는 전체-task 검증을 CLI `--stage auto` 로만 할 수 있었다.
-- **해결**: stage picker 에 stage 별 done 마킹을 표시하고, 모든 stage 가 done 이면 "전체 task 검증" 항목을 노출한다. 선택 시 prepare 에 빈 stage 를 넘겨 기존 전체-task 경로를 탄다(`auto` 토큰 미사용, prepare 계약 무변경). 머지/clean 미충족은 prepare 의 기존 PrepareError 가 안내한다.
-- 사용자 영향: 다음 release + `npx -y okstra@latest install` 후, 모든 stage 가 done 이면 위저드에서 "전체 task 검증" 을 골라 task 전체를 한 번에 검증할 수 있다.
-```
-
-- [ ] **Step 4: 커밋**
-
-```bash
-git add CHANGES.md runtime/
-git commit -m "docs(changes): wizard 전체 task final-verification 지원 기록 + runtime 빌드"
-```
-
----
-
-## Self-Review 결과
-
-- **Spec coverage**: §3 노출(Task 2) · §4 done 데이터원(Task 1) · §5 빈 stage emit(Task 4) · §6 게이트 함수(Task 2~4) · §7 프롬프트(Task 2) · §8 테스트(Task 1~5) — 전부 매핑됨.
-- **Placeholder**: 모든 코드 스텝에 실제 본문 포함, TODO 없음.
-- **Type/이름 일관성**: `WHOLE_TASK_STAGE` sentinel 이 Task 1 정의 → 2·3·4 에서 동일 이름 사용. `_parse_stage_objects`/`_done_stage_numbers`/`_whole_task_allowed` 시그니처 일관.
-- **회귀**: 각 Task Step 4 가 기존 `test_wizard_stage_pick.py` 를 함께 돌려 단독-stage UX 불변을 확인.