okstra 0.102.1 → 0.102.3

package/docs/superpowers/plans/2026-06-02-final-verification-protocol-hardening.md

@@ -1,326 +0,0 @@
-# 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:** final-verification 을 "리뷰 의견 수집"에서 **target 일치성 → 요구사항 커버리지 → read-only validation → 구조화된 verdict** 로 이어지는 검증 프로토콜로 강화한다.
-
-**Architecture:** lead 의 강한 entry gate 와 동일한 기준을 (1) 워커 dispatch contract, (2) 입력 템플릿, (3) report schema/template, (4) validator 에 구조화해 전달·강제한다. 변경은 저위험 prose/contract(PR1)와 고위험 schema/validator(PR2) 둘로 나눈다.
-
-**Tech Stack:** Markdown 프로파일/템플릿, JSON Schema, Python(validate-run.py + pytest), Jinja2 렌더 + i18n(en/ko json), okstra 빌드(`npm run build`).
-
-근거: 본 계획은 두 출처를 병합한다 — (A) 검증 초점 분석(이 세션), (B) 다른 에이전트의 final-verification contract 분석. 아래 모든 항목은 소스 직접 확인으로 검증됨.
-
----
-
-## 범위 결정 (먼저 확인)
-
-- **PR1 (저위험, schema 무변경):** 프로파일 prose 정정 + 검증 초점 재설계 + 워커 dispatch target snapshot + 입력 템플릿. 단독으로 가치 있음.
-- **PR2 (고위험, breaking — pre-1.0 라 compat 불필요):** report schema/template/i18n + validator 강제 + golden fixture. PR1 위에 쌓는다.
-- **범위 밖 (별도):** `analysis-material` 이 brief 전체를 복사하는 중복([material.py](../../../scripts/okstra_ctl/material.py)). **모든 task-type 에 영향을 주는 cross-cutting** 이라 이 PR 들에 섞지 않고 별도 후속 작업으로 분리.
-
-브랜치: PR1/PR2 각각 `main` 기준 새 브랜치 (pane-cleanup PR 과 무관).
-
----
-
-## File Structure
-
-**PR1**
-- Modify: `prompts/profiles/final-verification.md` — 검증 초점 재설계, no-mutation audit 범위 축소, routing vocab, section-name 호환, conditional-accept 참조, deliverable target-snapshot.
-- Modify: `templates/worker-prompt-preamble.md` — `implementation` 전용 Worktree 블록을 `final-verification` 까지 확장(+ base ref / head SHA / diff stat anchor).
-- Modify: `templates/reports/final-verification-input.template.md` — `## Requirement Coverage Source` 섹션 + target/requirement 질문.
-
-**PR2**
-- Modify: `schemas/final-report-v1.0.schema.json` — `sourceImplementationReport`(diffSummaryQuote/implementationBaseRef/gitDiffStat), `finalVerdict`(conditionalAcceptanceConditions), `ReadonlyCommandRow`(status/nullable exitCode/rejectionReason).
-- Modify: `templates/reports/final-report.template.md` — §4.8.1 새 필드 렌더, §4.8.x Conditional Acceptance Conditions, Read-only Command Log status 렌더.
-- Modify: `templates/reports/i18n/en.json` + `ko.json` — 신규 `evidenceMeta`/라벨 키.
-- Modify: `validators/validate-run.py` — verdict↔blocker/condition/routing 일관성 강제 + 섹션 목록.
-- Modify: `tests/test_validate_run.py`(또는 해당 파일) — 강제 로직 회귀 테스트.
-- Modify: `tests/fixtures/reports/golden-final-verification.md`, `tests/fixtures/final-report-data/final-verification-001.data.json` — 새 필드 반영.
-- Modify: `CHANGES.md` — 사용자 영향 엔트리(PR2 에서, 또는 양쪽).
-
-`runtime/` 는 gitignored build output — 커밋에 포함 안 함. profile/template/preamble/schema/i18n 변경 후 `npm run build` 로 동기화.
-
----
-
-# PR1 — 저위험 prose / contract
-
-## Task 1: 검증 초점 재설계 + Expected output emphasis 제거
-
-**Files:** Modify `prompts/profiles/final-verification.md:11-21`
-
-- [ ] **Step 1:** `Primary focus areas` + `Expected output emphasis` 블록(11-21행)을 아래로 교체.
-
-```markdown
-- Primary focus areas (each maps to a deliverable section below):
-  - Acceptance-gating — a failure here pushes the verdict toward `blocked` / `conditional-accept`:
-    - requirement & acceptance coverage — every must-pass point in the brief's `## Acceptance Criteria` (and the approved plan's requirements) is covered with a cited artifact or raised as an Acceptance Blocker; no silent omissions
-    - delivered artifacts match recorded expected values in `reference-expectations` (config files, deployment manifests, other recorded expected states); when reference-expectations are absent, record it as missing information rather than assuming a match
-    - test & validation suite pass status — independently re-run the read-only two-tier command set (Tier 1 = brief/approved-plan `validation`, Tier 2 = `project.json` `qaCommands`) and confirm each passes on the verified head, citing exact command + exit code
-    - test correctness — delivered tests actually assert the intended behaviour: no gutted/weakened assertions, no tautological or always-passing tests, no tests exercising only mocks; new behaviour has matching coverage
-    - no new defects introduced — the diff does not break previously-working behaviour and adds no new bug (logic/off-by-one, null/empty handling, resource leaks, broken error paths)
-    - scope conformance — the delivered diff stays within the approved plan's scope; flag out-of-scope edits, unrelated file changes, leftover debug/commented-out code, and unintended deletions
-  - Residual-tracked — note as Residual Risk unless severe enough to block:
-    - unresolved edge cases
-    - regression risk in adjacent code paths not directly changed
-    - documentation or rollout gaps
-    - production-specific failure modes not caught by tests (env/config drift across stages, secrets & permission/auth changes, migration ordering & rollback executability, observability gaps)
-```
-
-- [ ] **Step 2:** `grep -n "Expected output emphasis" prompts/profiles/final-verification.md` → 0건(제거 확인). `grep -rn "Expected output emphasis" tests/ validators/` → 0건(참조 없음, 이미 확인됨).
-- [ ] **Step 3:** `npm run build && bash validators/validate-workflow.sh` → OK.
-- [ ] **Step 4:** commit `feat(profiles/final-verification): 검증 초점 재설계 — gating/residual 2계층 + 테스트정확성·범위·신규버그 추가`.
-
-## Task 2: no-mutation audit 범위 축소 (자기모순 제거)
-
-**Files:** Modify `prompts/profiles/final-verification.md:43`
-
-- [ ] **Step 1:** self-review 5번 항목을 교체.
-
-old:
-```
-  5. **No-mutation audit** — scan the run's session transcripts for any Edit / Write / mutating Bash command. Any occurrence means the run has crossed into implementation and MUST be re-routed; do NOT silently strip the evidence.
-```
-new:
-```
-  5. **No source-mutation audit** — scan the run's session transcripts for Edit / Write or state-mutating Bash commands that touch paths OUTSIDE `<PROJECT_ROOT>/.okstra/**` and outside the assigned run-artifact paths. Writes to worker prompts, audit sidecars, team-state, the final-report `data.json`, and rendered reports under the run directory are allowed okstra artifacts. Any source/schema/deployment mutation means the run has crossed into implementation and MUST be re-routed; do NOT silently strip the evidence.
-```
-
-- [ ] **Step 2:** `npm run build` → OK. commit `fix(profiles/final-verification): no-mutation audit 를 source-mutation 으로 한정 (.okstra artifact 허용)`.
-
-## Task 3: routing vocabulary + section-name 호환 + conditional-accept 참조
-
-**Files:** Modify `prompts/profiles/final-verification.md` (23, 29, 35행)
-
-- [ ] **Step 1 (routing, 35행):** `Routing recommendation` deliverable 줄 교체.
-
-old:
-```
-  - **Routing recommendation**: brief note on the next safe phase (`done`, `error-analysis`, `implementation-planning`) tied to the verdict and blocker list.
-```
-new:
-```
-  - **Routing recommendation**: the next safe phase — one of `release-handoff`, `done`, `error-analysis`, `implementation-planning` — tied to the verdict and blocker list. `release-handoff` is allowed ONLY when the Verdict Token is `accepted`.
-```
-
-- [ ] **Step 2 (section-name 호환, 23행):** entry-gate 줄에서 implementation report 필수 섹션 인용을 양쪽 표기 허용으로.
-
-old fragment: ``includes `Plan link & approval evidence`, `Commit list`, ``
-new fragment: ``includes the approved-plan reference (heading `Approved Plan Reference` or `Plan link & approval evidence`), `Commit list`, ``
-
-- [ ] **Step 3 (conditional-accept 참조, 29행):** `conditional-accept` 설명에 구조화 deliverable 참조 추가(현 문장 끝에 append).
-
-append: ` Each condition MUST be recorded as a row in the **Conditional Acceptance Conditions** deliverable (id, condition, evidence required, blocks-release-handoff).`
-
-> 주의: 이 줄은 PR2 의 §4.8 Conditional Acceptance Conditions 섹션·schema 와 짝이다. PR1 만 단독 머지할 경우 이 Step 3 는 PR2 와 함께 가도록 보류 가능 — 실행 시점에 결정.
-
-- [ ] **Step 4:** `npm run build && bash validators/validate-workflow.sh` → OK. commit `fix(profiles/final-verification): routing 에 release-handoff 추가 + approved-plan 섹션명 호환`.
-
-## Task 4: 워커 dispatch 에 verification target snapshot 전달
-
-**Files:** Modify `templates/worker-prompt-preamble.md:84-88`, `prompts/profiles/final-verification.md`(deliverable)
-
-- [ ] **Step 1 (preamble):** `For the implementation phase specifically...` 블록(84-88)을 implementation + final-verification 둘 다 커버하도록 교체.
-
-old:
-```
-For the **implementation phase** specifically, the dispatched prompt MUST also include:
-
-- `**Worktree:** <absolute-path>` — the task worktree path.
-- `cwd for every mutating command: <absolute-path>` — same as Worktree path; used by codex / gemini wrappers as `--add-dir` / `--include-directories`.
-```
-new:
-```
-For the **implementation phase** specifically, the dispatched prompt MUST also include:
-
-- `**Worktree:** <absolute-path>` — the task worktree path.
-- `cwd for every mutating command: <absolute-path>` — same as Worktree path; used by codex / gemini wrappers as `--add-dir` / `--include-directories`.
-
-For the **final-verification phase** specifically, the dispatched prompt MUST also include the verification target snapshot so every analyser verifies the SAME target the lead captured at the entry gate:
-
-- `**Worktree:** <absolute-path>` — the checkout under verification (read-only).
-- `**Verification base ref:** <base-ref>` — the implementation base for the diff.
-- `**Verification head SHA:** <sha>` — head SHA captured at run start.
-- `**Verification diff stat:** <git diff --stat output>` — the captured diff-stat that bounds the verification scope.
-```
-
-- [ ] **Step 2 (profile deliverable, final-verification.md "Source Implementation Report" deliverable 28행 근처):** 워커가 이 snapshot 을 기준으로 검증하고 보고서가 cite 하도록, deliverable 의 Source Implementation Report 항목에 한 줄 추가:
-
-append: ` The lead injects this same target snapshot into every analyser prompt (`**Worktree:** / **Verification base ref:** / **Verification head SHA:** / **Verification diff stat:**`); a worker that cannot confirm its analysis ran against that exact head MUST record a `tool-failure` rather than verify an ambiguous target.`
-
-- [ ] **Step 3:** `npm run build && bash validators/validate-workflow.sh` → OK. commit `feat(worker-preamble,final-verification): 워커 dispatch 에 verification target snapshot 전달`.
-
-## Task 5: 입력 템플릿에 Requirement Coverage Source 추가
-
-**Files:** Modify `templates/reports/final-verification-input.template.md` (`## Source Implementation Report` 다음)
-
-- [ ] **Step 1:** `## Source Implementation Report` 블록 종료(40행 인용구) 다음에 신규 섹션 삽입.
-
-```markdown
-
-## Requirement Coverage Source
-
-- Approved implementation-planning report path:
-- Requirement source used for coverage (plan section / brief Acceptance Criteria):
-- Requirement IDs / acceptance IDs to verify:
-- Requirements intentionally excluded from this verification:
-
-> final-verification 은 위 source 의 각 requirement / acceptance id 마다 Validation Evidence 에 artifact 를 cite 해야 한다. source 가 비면 brief 의 `## Acceptance Criteria` 를 기본 source 로 사용한다.
-```
-
-- [ ] **Step 2:** 입력 템플릿의 analyser 질문 목록(85행 근처) 맨 앞에 target-integrity 질문 2개 추가:
-
-```markdown
-1. Does the verification target (head SHA / diff stat) match the implementation report's commit list and diff summary?
-2. For each requirement / acceptance criterion, what exact artifact (commit SHA, test output, log line, config value) proves coverage?
-```
-(기존 번호 질문들은 뒤로 밀린다.)
-
-- [ ] **Step 3:** `npm run build`. 렌더 검증: `python3 -m pytest tests/test_template_full_render_both_langs.py -q` → PASS. commit `feat(final-verification-input): Requirement Coverage Source + target-integrity 질문`.
-
-## Task 6: PR1 검증 + PR
-
-- [ ] **Step 1:** `python3 -m pytest tests/ -q` → 전부 PASS(또는 tmux skip). `bash validators/validate-workflow.sh` → OK. `node bin/okstra --version`.
-- [ ] **Step 2:** diff critique — 새 토큰 grep(`grep -rn "Verification base ref\|Requirement Coverage Source\|No source-mutation audit" prompts/ templates/`), runtime parity.
-- [ ] **Step 3:** push + `gh pr create --base main` (제목 `feat(final-verification): 검증 프로토콜 강화 — 초점/target snapshot/입력 (PR1)`).
-
----
-
-# PR2 — report contract (schema / template / i18n / validator)
-
-> PR1 머지 후 `main` 기준 새 브랜치에서 진행. breaking schema 변경(pre-1.0, compat 불필요).
-
-## Task 7: schema — sourceImplementationReport diff-stat 분리
-
-**Files:** Modify `schemas/final-report-v1.0.schema.json` (`sourceImplementationReport`, 현 ~547행)
-
-- [ ] **Step 1 (test first):** schema 검증 테스트 추가 — diff-stat/diffSummaryQuote 누락 시 invalid. (해당 schema 검증 테스트 파일은 `tests/test_validate_run*.py` 또는 schema 단위 테스트; 실행 시 위치 확인 후 케이스 추가.)
-- [ ] **Step 2:** `sourceImplementationReport` 를 교체:
-
-```json
-"sourceImplementationReport": {
-  "type": "object",
-  "required": ["path", "commitListQuote", "diffSummaryQuote", "worktreePath", "implementationBaseRef", "capturedHeadSha", "gitStatusShort", "gitDiffStat"],
-  "additionalProperties": false,
-  "properties": {
-    "path": { "type": "string" },
-    "commitListQuote": { "type": "string" },
-    "diffSummaryQuote": { "type": "string" },
-    "worktreePath": { "type": "string" },
-    "implementationBaseRef": { "type": "string" },
-    "capturedHeadSha": { "type": "string" },
-    "gitStatusShort": { "type": "string" },
-    "gitDiffStat": { "type": "string" }
-  }
-}
-```
-(주의: 기존 `baseHeadSha` → `implementationBaseRef` + `capturedHeadSha` 분리. template/i18n/fixture 동반 수정 필요 — Task 10/11.)
-
-- [ ] **Step 3:** schema 테스트 PASS. commit.
-
-## Task 8: schema — conditionalAcceptanceConditions
-
-**Files:** Modify `schemas/final-report-v1.0.schema.json` (`finalVerdict` + `$defs`)
-
-- [ ] **Step 1 (test first):** verdict=`conditional-accept` 인데 conditions 비면 invalid 케이스.
-- [ ] **Step 2:** `finalVerdict.properties` 에 추가 + `$defs` 에 row 정의:
-
-```json
-"conditionalAcceptanceConditions": {
-  "type": "array",
-  "items": { "$ref": "#/$defs/ConditionalAcceptanceConditionRow" }
-}
-```
-```json
-"ConditionalAcceptanceConditionRow": {
-  "type": "object",
-  "required": ["id", "condition", "evidenceRequired", "blocksReleaseHandoff"],
-  "additionalProperties": false,
-  "properties": {
-    "id": { "type": "string", "pattern": "^CA-\\d{3,}$" },
-    "condition": { "type": "string", "minLength": 1 },
-    "evidenceRequired": { "type": "string", "minLength": 1 },
-    "blocksReleaseHandoff": { "type": "boolean" }
-  }
-}
-```
-(`finalVerdict.required` 에는 넣지 않음 — accepted/blocked 에선 빈 배열 허용; 강제는 validator 에서 verdict 조건부로.)
-
-- [ ] **Step 3:** 테스트 PASS. commit.
-
-## Task 9: schema — ReadonlyCommandRow status / nullable exitCode
-
-**Files:** Modify `schemas/final-report-v1.0.schema.json` (`ReadonlyCommandRow`, 현 ~1306행)
-
-- [ ] **Step 1 (test first):** status=`rejected`, exitCode=null 인 row 가 valid 케이스 + status=`executed` 인데 exitCode=null 이면 invalid(아래 Step 2 의 조건).
-- [ ] **Step 2:** `ReadonlyCommandRow` 교체:
-
-```json
-"ReadonlyCommandRow": {
-  "type": "object",
-  "required": ["number", "tier", "command", "status", "exitCode", "outputTail"],
-  "additionalProperties": false,
-  "properties": {
-    "number": { "type": "integer", "minimum": 1 },
-    "tier": { "enum": [1, 2] },
-    "command": { "type": "string", "minLength": 1 },
-    "status": { "enum": ["executed", "rejected", "not-configured"] },
-    "exitCode": { "type": ["integer", "null"] },
-    "rejectionReason": { "type": ["string", "null"] },
-    "outputTail": { "type": "string" }
-  },
-  "allOf": [
-    { "if": { "properties": { "status": { "const": "executed" } } },
-      "then": { "properties": { "exitCode": { "type": "integer" } } } },
-    { "if": { "properties": { "status": { "const": "rejected" } } },
-      "then": { "required": ["rejectionReason"] } }
-  ]
-}
-```
-
-- [ ] **Step 3:** 테스트 PASS. commit.
-
-## Task 10: template §4.8 — 새 필드 렌더
-
-**Files:** Modify `templates/reports/final-report.template.md` (§4.8.1, + 신규 conditions 섹션, Read-only Command Log)
-
-- [ ] **Step 1:** §4.8.1 Source Implementation Report 렌더에 diffSummaryQuote / implementationBaseRef / gitDiffStat 추가, baseHeadSha → capturedHeadSha 로 변경 (i18n 키는 Task 11).
-- [ ] **Step 2:** §4.8.x `Conditional Acceptance Conditions` 섹션 추가 — verdict=`conditional-accept` 일 때 행 렌더, 아니면 `- Not applicable (verdict is not conditional-accept).`.
-- [ ] **Step 3:** Read-only Command Log 렌더에 `status` 열 + rejected 행의 `rejectionReason`, exitCode null 처리.
-- [ ] **Step 4:** `npm run build`. `python3 -m pytest tests/test_template_full_render_both_langs.py tests/test_render_phase_blocks.py -q` → PASS(또는 fixture 갱신 후). commit.
-
-## Task 11: i18n 키 + golden fixture
-
-**Files:** Modify `templates/reports/i18n/en.json`, `ko.json`, `tests/fixtures/reports/golden-final-verification.md`, `tests/fixtures/final-report-data/final-verification-001.data.json`
-
-- [ ] **Step 1:** `en.json` + `ko.json` 의 `evidenceMeta` 에 키 추가: `diffSummaryAtRunStart`, `implementationBaseRef`, `gitDiffStatAtRunStart` (+ conditions/command-status 라벨). 기존 `capturedHeadBaseSha` → `capturedHeadSha` 의미로 정리.
-- [ ] **Step 2:** golden data.json 에 새 필드 채우고, golden md 를 새 렌더 결과로 갱신 (`npm run build` 후 렌더러로 재생성하거나 수동 갱신).
-- [ ] **Step 3:** `python3 -m pytest tests/test_template_full_render_both_langs.py tests/test_report_views.py -q` → PASS. commit.
-
-## Task 12: validator — verdict↔blocker/condition/routing 일관성 강제
-
-**Files:** Modify `validators/validate-run.py` (final-verification 블록 ~1172), `tests/test_validate_run*.py`
-
-- [ ] **Step 1 (test first):** 4개 회귀 테스트 추가:
-  - verdict=`accepted` + acceptanceBlockers 비어있지 않음 → fail
-  - verdict=`blocked` + acceptanceBlockers 0개 → fail
-  - verdict=`conditional-accept` + conditions 0개 → fail
-  - routingRecommendation 이 `release-handoff` 인데 verdict ≠ `accepted` → fail
-- [ ] **Step 2:** `if task_type == "final-verification":` 블록(1172)에 위 4개 검사 추가. 신규 §4.8 섹션 추가했으면 `FINAL_VERIFICATION_REQUIRED_SECTIONS`(876)에 `"Conditional Acceptance Conditions"` 등 반영.
-- [ ] **Step 3:** `python3 -m pytest tests/test_validate_run.py -q` → PASS. commit.
-
-## Task 13: PR2 검증 + docs + PR
-
-- [ ] **Step 1:** `python3 -m pytest tests/ -q`, `bash validators/validate-workflow.sh`, golden 렌더 테스트 전부 PASS.
-- [ ] **Step 2:** `CHANGES.md` 에 사용자 영향 엔트리(verdict 일관성 강제 + diff-stat/conditions/command-status 구조화).
-- [ ] **Step 3:** diff critique(rule #5) — schema↔template↔i18n↔fixture↔validator 5자 정합, 새 식별자 grep.
-- [ ] **Step 4:** push + `gh pr create --base main` (`feat(final-verification): report contract 구조화 — diff-stat/conditions/command-status + verdict 강제 (PR2)`).
-
----
-
-## Self-Review (작성자 체크)
-
-- **Spec coverage:** 다른 에이전트 8개 항목 매핑 — #1 target snapshot=Task4, #2 diff-stat=Task7/10/11, #3 requirement source=Task5, #4 no-mutation=Task2, #5 conditions=Task3/8/10/12, #6 command status=Task9/10/12, #7 routing=Task3, #8 section-name=Task3. + 검증 초점 재설계=Task1.
-- **범위 밖 명시:** material.py 중복(cross-cutting)은 별도 — spawn 권장.
-- **Placeholder:** schema/profile/preamble/input 은 완전한 텍스트 포함. template/i18n/fixture(Task10/11)는 정확한 위치·키를 지정하되, 렌더 결과 golden md 는 빌드로 재생성하는 절차로 둠(수작업 전체 전사 비현실적).
-- **enforcement 정직성:** 검증 초점(Task1)·no-mutation(Task2)·target snapshot(Task4)은 선언 레벨(런타임 강제 없음). verdict↔blocker/condition/routing(Task12)·schema 필드(Task7-9)는 validator/schema 가 런타임 강제.
-- **의존성:** Task3 Step3(conditional 참조)는 PR2 의 conditions 와 짝 — PR1 단독이면 보류.

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

@@ -1,337 +0,0 @@
-# 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 확인.