okstra 0.102.1 → 0.102.3

package/docs/superpowers/specs/2026-05-21-improvement-discovery-task-type-design.md

@@ -1,335 +0,0 @@
-# improvement-discovery task-type — 설계 spec
-
-- Date: 2026-05-21
-- Status: Draft (사용자 검토 대기)
-- Owner: Claude lead (현재 세션)
-- Related: `prompts/profiles/`, `scripts/okstra_ctl/workflow.py`, `scripts/okstra_ctl/wizard.py`, `templates/reports/final-report.template.md`, `validators/validate-run.py`, `skills/okstra-brief/SKILL.md`, `agents/workers/*.md`
-
-## 1. 문제
-
-okstra 의 현재 라이프사이클은 *외부 요청(brief) → 분류 → 라우팅* 모델을 가정한다. `requirements-discovery` 가 work-category 분류에 `improvement` 을 포함하긴 하지만, 이는 "사용자가 *개선 brief* 를 가져왔을 때" 의 분류일 뿐이다. **사용자가 개선처를 모르고 okstra 가 코드베이스에서 찾아주길 원하는 시나리오** 는 현재 라이프사이클의 어떤 phase 도 처리하지 못한다.
-
-단일 에이전트용 `improve-codebase-architecture` 스킬이 이미 존재한다는 점은 수요 검증 신호다. 그러나 그 스킬은 okstra 의 핵심 가치인 multi-worker cross-verification 이 빠져 있어, 모델별 발견 다양성 + Phase 5.5 합의도 분류라는 okstra 만의 강점을 활용하지 못한다.
-
-## 2. 목표와 비목표
-
-### 목표
-
-- 코드베이스 범위 + 우선순위 lens 만 입력으로 받아, lens 화이트리스트 안에서 개선 후보 N개 (기본 top-8, 절대 cap 12) 를 도출하는 새 task-type `improvement-discovery` 도입.
-- okstra 의 다른 phase 와 동일한 contract 패턴: brief → render-bundle → phase 실행 → final-report → 사용자 선택 라우팅.
-- 사용자 의도와 AI 이해도의 정합을 위한 **양방향 grilling 메커니즘**:
-  - **지점 ①**: `okstra-brief` Step 4 sharpening 강화 (brief 작성 시점)
-  - **지점 ②**: profile 의 Phase 1.5 reflect-back grilling (worker dispatch 직전)
-- lens 화이트리스트와 후보 cap 을 validator 가 강제. declaration 과 enforcement 가 일치.
-- final-report 의 후보 표가 *Source workers* 컬럼으로 worker:item 단위 추적성 유지 (글로벌 cross-worker traceability contract 와 일관).
-
-### 비목표
-
-- 후보별 자동 spin-off (`AskUserQuestion` 으로 K개 선택 → 자동 새 task-id 생성) 는 도입하지 않음. 사용자가 final-report 의 후보 목록을 보고 직접 후속 task 를 시작.
-- `PHASE_SEQUENCE` 의 정식 멤버로 편입하지 않음. sidetrack entry-point 로만 작동.
-- 후보의 구체적 구현 plan / 비용 추정 / 실제 코드 수정. 그건 다음 phase (requirements-discovery / implementation-planning / error-analysis) 의 책임.
-- `improve-codebase-architecture` 스킬 폐기 / 통합. 두 도구는 공존 — 단일 에이전트 빠른 분석은 그쪽, multi-worker 합의 기반 분석은 이쪽.
-
-## 3. 라이프사이클 위치
-
-```
-[brief: scope=codebase + priority-lenses + scan-scope]
-        ↓ okstra-run (--task-type improvement-discovery)
-[improvement-discovery]
-        ↓ final-report (Verdict Token: candidates-ready | no-candidates | blocked)
-        ↓ ## 4. Improvement Candidates 표 (top-N 후보, 각 후보별 권장 next-phase)
-        ↓ (사용자가 후보 K개 선택)
-[okstra-brief] (후보별로 새 brief 작성)
-        ↓ okstra-run (--task-type {requirements-discovery | implementation-planning | error-analysis})
-[기존 라이프사이클]
-```
-
-`workflow.py` 등록:
-
-- `PHASE_SEQUENCE` 에 **추가하지 않음** (단방향 흐름 유지).
-- `DEFAULT_NEXT_PHASE["improvement-discovery"] = "pending-routing-decision"` (`requirements-discovery` 와 동일 패턴).
-- `PHASE_RULES["improvement-discovery"]` 추가 — §5 에서 정의.
-
-## 4. brief contract
-
-### 4.1 variant 식별
-
-기존 brief 와 같은 파일 형식이지만 frontmatter 의 `scope: codebase` 마커로 구분한다.
-
-### 4.2 frontmatter 신규 필드
-
-```yaml
-scope: codebase                              # variant 마커 (필수)
-priority-lenses: [performance, security]     # lens enum 부분집합, 1–4개
-scan-scope: [src/foo/, src/bar/baz.ts]       # 스캔 대상 경로, 1개 이상
-out-of-scope: [src/vendor/, "**/generated/"] # 제외 경로 (선택)
-candidate-cap: 8                             # 후보 상한 (1–12, 기본 8, 선택)
-```
-
-`priority-lenses` cap 이 4 인 이유: 5개 이상은 발산이라 phase 가치가 떨어진다. 5개 이상 필요하면 brief 를 둘로 나누는 것이 옳다.
-
-`candidate-cap` 절대 상한이 12 인 이유: 그 이상은 사용자가 의사결정하지 못한다. 12 초과는 validator 가 거부.
-
-### 4.3 Required sections (기존 brief 와의 차이)
-
-| 섹션 | reporter-input | codebase-scan |
-|---|---|---|
-| Source Material | reporter 발화 verbatim | _(생략)_ |
-| Context | 배경 | 왜 이 범위를 지금 스캔하는가 |
-| Problem / Symptom | 증상 | _(생략)_ |
-| Desired Outcome | 성공 모양 | 어떤 종류의 개선을 보고 싶은가 + 후보 개수 의도 |
-| Constraints | 제약 | 변경 불가 영역, 호환성, deadline |
-| Scan Scope (신규) | _(없음)_ | scan-scope 의 각 path 에 한 줄 설명 |
-| Priority Lenses (신규) | _(없음)_ | 각 lens 가 *왜* 우선인지 한 줄 |
-| Open Questions | 동일 | 동일 |
-| Augmentation | 동일 | 동일 |
-
-### 4.4 `okstra-brief` Step 1 변경
-
-첫 질문을 2-level pick 으로 분리:
-
-- L1 `brief variant`: `Reporter input` / `Codebase scan`
-- L1 = Reporter input → 기존 4-source 흐름 (변경 없음).
-- L1 = Codebase scan → 새 sub-flow:
-  1. Scan Scope 경로 입력 (free-text, 여러 줄 가능)
-  2. Priority Lenses pick (lens enum 의 multi-select, 1–4)
-  3. Context / Desired Outcome / Constraints / Out-of-scope / candidate-cap 짧은 free-text
-  4. Step 4 sharpening 진입
-
-### 4.5 Step 4 sharpening 강화 (Grilling 지점 ①)
-
-기존 budget 6 → codebase-scan variant 에선 **budget 8** + improvement 전용 rules 5개:
-
-1. `scan-scope` 의 각 path 가 실제 존재하는지 codebase-first 검증. 없으면 한 질문으로 정정.
-2. 모호한 path (예: "백엔드", "결제 모듈") 를 구체 경로 1개 이상으로 narrowing.
-3. `priority-lenses` 의 lens 가 enum 안인지 검증. out-of-enum 이면 enum 내 가장 가까운 값 추천 후 한 질문.
-4. `out-of-scope` 가 `scan-scope` 와 모순되지 않는지 검증 (out-of-scope path 가 scan-scope path 안에 포함되어야 의미 있음).
-5. lens 우선순위 근거가 thin 하면 1 질문: "이 범위에서 어떤 lens 가 가장 큰 risk 인가?" + Recommended (codebase 1차 훑은 결과 기반).
-
-stop conditions (OR):
-
-- 기존: budget 소진 / 모든 required section 채워짐 / 사용자가 stop
-- 신규: `scan-scope` 의 모든 path 가 codebase 에 존재 + `priority-lenses` 가 valid enum 부분집합 (1–4개)
-
-### 4.6 Step 6 recommendation 헤리스틱
-
-codebase-scan brief 는 자동으로 `Recommended next phase: improvement-discovery` 라벨링.
-
-## 5. profile + Phase 1.5 reflect-back grilling
-
-### 5.1 profile 파일
-
-- `prompts/profiles/improvement-discovery.md` (영문)
-- `prompts/profiles/kr/improvement-discovery.md` (한글 페어)
-
-구조는 다른 profile 과 동일: Purpose / Required workers / Optional workers / `{{INCLUDE:_common-contract.md}}` / Brief consumption / Primary focus areas / Phase 1.5 reflect-back grilling / Expected output emphasis / Clarification request policy / Non-goals.
-
-### 5.2 Required workers
-
-`claude` / `codex` / `gemini` / `report-writer` 4개 모두 Required. gemini 가 optional 인 다른 phase 와 다른 이유는 §2 목표에 따른 다양성 우선 정책.
-
-### 5.3 lens enum 화이트리스트 (SSOT)
-
-`scripts/okstra_ctl/improvement_lenses.py` 의 상수 1개로 통일.
-
-```python
-LENSES = (
-    "performance",     # 처리 속도, 메모리, 대기 시간, N+1, 핫스팟
-    "security",        # 권한 우회, 입력 검증, 시크릿 노출, OWASP top 10
-    "readability",     # 명명, 구조, 이해 비용, 죽은 코드
-    "architecture",    # 의존성 결합, SRP, 테스트 가능성, 레이어 침범
-    "test-coverage",   # 누락된 경로, 엣지 케이스, 통합 테스트 결손
-    "dx",              # 개발자 경험, 빌드/스크립트, 디버깅 도구
-    "observability",   # 로깅, 모니터링, 에러 추적
-    "accessibility",   # a11y (프론트엔드 한정)
-)
-
-DEFAULT_CANDIDATE_CAP = 8
-ABSOLUTE_CANDIDATE_CAP = 12
-MIN_PRIORITY_LENSES = 1
-MAX_PRIORITY_LENSES = 4
-SOURCE_WORKERS = ("claude", "codex", "gemini")  # report-writer 는 author 이므로 source 에 등장 불가
-```
-
-profile / brief skill / validator / wizard 가 모두 이 모듈을 import 한다. 다른 곳에서 enum 을 재정의하면 위반 — 글로벌 단일 reference point 규칙.
-
-### 5.4 Phase 1.5 — Lead reflect-back grilling (Grilling 지점 ②)
-
-Phase 1 (context loading) 직후, Phase 4 (worker dispatch) 직전, lead 가 단독으로 실행:
-
-1. brief frontmatter (`scope`, `priority-lenses`, `scan-scope`, `out-of-scope`, `candidate-cap`) 와 Desired Outcome 을 읽음.
-2. `scan-scope` 의 각 path 를 `ls` / `Grep` / `Read` 로 1차 확인 — 실제 트리, 엔트리포인트, 의존 관계, 대략 LOC, 최근 commit 패턴 파악.
-3. lead 가 한 메시지로 **reflect-back 출력**:
-   - "내가 이해한 scope" — 경로별 한 줄 요약 (몇 모듈 / 몇 파일 / 주요 책임)
-   - "내가 이해한 priority lens 의 의미" — 각 lens 가 이 scope 에서 구체적으로 무엇을 의미하는지
-   - "내가 이해한 out-of-scope 의 근거" — 왜 그 경로가 제외되는지
-   - "발견한 의문점 N개" — 우선순위순
-4. 의문점마다 `AskUserQuestion` 한 개 + Recommended 답 (lead 의 1차 판단 + 근거 1줄, codebase-first).
-5. **budget 12 questions** (Grilling 지점 ① 의 8 과 합쳐 한 task 당 최대 20 grilling questions).
-6. **stop conditions** (OR):
-   - 모든 의문점 resolved
-   - budget 소진
-   - 사용자가 "충분해 / proceed / 워커 dispatch 해" 명시
-7. 결과를 `runs/improvement-discovery/<seq>/state/phase-1.5-grilling.md` 에 audit 로그로 기록 — 질문, 추천답, 사용자답, resolved scope/lenses 요약.
-
-worker prompt 는 이 grilling 결과를 **정답** 으로 받는다. worker 는 brief 의 원본 scope/lens 를 다시 해석하지 않고 phase-1.5-grilling.md 의 resolved 값만 사용.
-
-### 5.5 Phase rules — allowed / forbidden
-
-`workflow.py` 의 `PHASE_RULES["improvement-discovery"]`:
-
-**Allowed**:
-
-- lens enum 안에서 후보 도출
-- top-N 랭킹 (기본 8, brief `candidate-cap` 으로 1–12 사이 override 가능)
-- 후보별 `Lens` / `Scope` / `Severity` / `Effort` / `Consensus` / `Source workers` / `Recommended next-phase` / `Evidence` (file:line) 컬럼
-- Phase 1.5 reflect-back grilling log
-- Phase 5.5 convergence — full-consensus / partial-consensus / contested / worker-unique 분류
-
-**Forbidden**:
-
-- 소스 편집, 빌드, 마이그레이션, 배포
-- implementation-planning / implementation / error-analysis 로 자체 진입
-- lens enum 밖 후보 생성
-- top-N 12개 초과
-- codebase 외부 데이터 자유 조회 (brief 의 Source Material 또는 Phase 1.5 답변에 명시된 경우에만)
-- "다음 단계 진행해" 류 사용자 발화를 다음 phase 진입 권한으로 해석 (anti-escalation rule 일관 적용)
-
-## 6. 출력 contract + validator
-
-### 6.1 final-report 의 phase-specific 섹션
-
-기존 `final-report.template.md` 의 `## 4.` 슬롯에 `## 4. Improvement Candidates` 표 추가. 다른 섹션 (1, 2, 3, 5, 6) 은 모든 phase 공통 그대로.
-
-### 6.2 후보 표 schema (10 column)
-
-| 컬럼 | 값 | 비고 |
-|---|---|---|
-| `Cand ID` | `I-NNN` (3-digit, 유일) | |
-| `Lens` | enum 1개 (필요 시 ≤2개 csv) | lens enum 강제 |
-| `Title` | 한 줄 (≤80 char) | |
-| `Scope` | path csv | `scan-scope` 부분집합 |
-| `Severity` | `high / medium / low` | |
-| `Effort` | `S / M / L` | T-shirt 추정 |
-| `Consensus` | `full / partial / contested / worker-unique` | Phase 5.5 산출 |
-| `Source workers` | `claude:F-001, codex:1.2, gemini:F-3` | 글로벌 traceability |
-| `Recommended next-phase` | `requirements-discovery / implementation-planning / error-analysis` | |
-| `Evidence` | `path:line` csv | `## 3. Primary Evidence` 와 cross-link |
-
-### 6.3 Verdict Card / `## 2. Final Verdict` 토큰 enum (phase 전용)
-
-- `candidates-ready` — 후보 ≥1개, 라우팅 추천 정상
-- `no-candidates` — lens·scope 안에서 의미있는 개선처 없음 (깨끗한 codebase 신호)
-- `blocked` — scope/lens 가 너무 모호하여 후보 신뢰도 낮음 (`## 5. Clarification Items` 필요)
-
-Direction = `routing` 고정. Next Step = "사용자에게 후보 K개 선택 의뢰 (## 4. 표 참조)".
-
-### 6.4 `## 6. Recommended Next Steps` 매핑
-
-첫 entry 가 후보 라우팅 요약 — 각 후보가 어떤 next-phase 로 가야 하는지 한 줄 요약. 후보별 새 task-key 작명 가이드 (예: `<task-group>/imp-<Cand-ID>`).
-
-### 6.5 validator — `validators/validate-improvement-report.py`
-
-강제 항목:
-
-1. `## 4. Improvement Candidates` 섹션 존재 + 정확히 10 column schema (컬럼 순서/이름 byte-match).
-2. 각 행의 `Cand ID` 가 `I-NNN` 패턴 + run 내 유일.
-3. 각 행의 `Lens` 값이 lens enum 안 (out-of-enum 1건이라도 실패).
-4. 각 행의 `Scope` path 가 brief frontmatter 의 `scan-scope` 부분집합. `out-of-scope` 와 충돌 없음.
-5. 행 개수 ≤ brief 의 `candidate-cap` (1–12). brief 에 필드 누락 시 SSOT 의 `DEFAULT_CANDIDATE_CAP` (8) fallback. 절대 cap = 12.
-6. 각 행의 `Source workers` 가 비어 있지 않고 `<worker>:<item-id>` 패턴 일치. worker 이름은 SSOT 의 `SOURCE_WORKERS` 집합 (`claude` / `codex` / `gemini`) 안 — `report-writer` 가 source 에 등장하면 실패. single-worker 후보도 허용되지만 그 경우 `Consensus=worker-unique` 가 강제 (worker 1개인데 `Consensus=full` 인 행은 실패).
-7. `Recommended next-phase` 가 `requirements-discovery / implementation-planning / error-analysis` 중 하나.
-8. `## 2. Final Verdict` 의 Verdict Token 이 phase enum (`candidates-ready / no-candidates / blocked`) 안.
-9. Verdict Card 의 Verdict Token / Direction / Next Step 가 `## 2.` 와 byte-match (공통 rule).
-10. `runs/improvement-discovery/<seq>/state/phase-1.5-grilling.md` 존재 + resolved `scope` / `lenses` 블록 포함.
-11. lens enum SSOT (`scripts/okstra_ctl/improvement_lenses.py`) 와 byte-match — profile / brief / validator 가 같은 enum 을 본다는 보장.
-
-### 6.6 validator 통합 지점
-
-`validators/validate-run.py` 가 `task_type == "improvement-discovery"` 일 때 `validate-improvement-report.py` 를 추가 호출. 실패 시 run status = `contract-violated` (다른 phase 와 동일).
-
-### 6.7 report-writer 책임 (추가)
-
-기존 책임 (final-report 작성, single owner) 그대로 + `## 4.` 섹션을 위 10-column schema 정확히 채움. lens enum / Cand ID 패턴 / Source workers 형식은 report-writer 가 작성 시 자체 검증 (validator 는 최종 방어선).
-
-## 7. 등록 지점
-
-### 7.1 코드
-
-| 파일 | 변경 |
-|---|---|
-| `scripts/okstra_ctl/workflow.py` | `PHASE_RULES["improvement-discovery"]` 추가. `PHASE_SEQUENCE` 변경 없음. `DEFAULT_NEXT_PHASE["improvement-discovery"] = "pending-routing-decision"`. |
-| `scripts/okstra_ctl/wizard.py` | `TASK_TYPES` 에 1행 추가 (`("improvement-discovery", "Find improvement candidates in a codebase scope")`). |
-| `scripts/okstra_ctl/improvement_lenses.py` (신규) | lens enum SSOT + cap 상수. |
-| `scripts/okstra_ctl/run.py` | Phase 1.5 grilling log 파일 경로 등록. `prepare_task_bundle()` 의 task_type-agnostic 흐름은 그대로. |
-
-### 7.2 프롬프트 / 스킬 / 템플릿
-
-| 파일 | 변경 |
-|---|---|
-| `prompts/profiles/improvement-discovery.md` (신규) | §5 의 영문 profile. |
-| `prompts/profiles/kr/improvement-discovery.md` (신규) | 한글 페어. |
-| `templates/reports/improvement-discovery-input.template.md` (신규) | input 템플릿. `## 4. Improvement Candidates` 빈 표 + Phase 1.5 grilling 안내. |
-| `templates/reports/final-report.template.md` | `## 4.` 슬롯 phase-specific 분기 안내에 improvement-discovery 케이스 추가. |
-| `skills/okstra-brief/SKILL.md` | §4.4 / §4.5 / §4.6 의 모든 변경. |
-| `agents/workers/{claude,codex,gemini,report-writer}-worker.md` | improvement-discovery 진입 시 worker 가 Phase 1.5 grilling log 를 정답으로 받는 규칙 1줄 추가. |
-
-### 7.3 Validator
-
-| 파일 | 변경 |
-|---|---|
-| `validators/validate-improvement-report.py` (신규) | §6.5 의 11개 강제 항목. |
-| `validators/validate-run.py` | `task_type == "improvement-discovery"` 분기. |
-
-### 7.4 테스트
-
-| 파일 | 변경 |
-|---|---|
-| `tests/test_okstra_improvement_lenses.py` (신규) | SSOT import 일관성. profile / validator / brief skill 가 같은 enum 을 본다는 검증. |
-| `tests/test_validate_improvement_report.py` (신규) | validator 의 11개 항목 각각 happy + sad path. |
-| `tests/test_okstra_ctl_wizard.py` | `TASK_TYPES` 가 7개로 늘었음을 반영. |
-| `tests/test_workflow_phase_sequence.py` | `PHASE_RULES` 에 improvement-discovery 가 있고 `PHASE_SEQUENCE` 에는 없음을 검증. |
-| `tests-e2e/scenario-08-improvement-discovery-render-only.sh` (신규) | render-only 흐름 — brief variant 작성 → render-bundle → instruction-set 생성 → validator stub 통과. |
-
-### 7.5 문서
-
-| 파일 | 변경 |
-|---|---|
-| `README.md`, `README.kr.md` | task-type 라인업 표에 improvement-discovery 행 추가. |
-| `docs/kr/cli.md` | `--task-type improvement-discovery` 절 신규 + brief variant 흐름. |
-| `docs/kr/architecture.md` | 라이프사이클 흐름도 (§3) + sidetrack entry-point 설명. |
-| `docs/project-structure-overview.md` | `improvement_lenses.py` / `validate-improvement-report.py` 항목. |
-| `CHANGES.md` | 한국어 entry + `사용자 영향:` 한 줄. |
-| `CLAUDE.md` | Where-to-find-things 표 / Worker/agent contract 절 / Gotchas — 각각 한 줄씩. |
-
-## 8. PR 분리 권장
-
-- **PR 1 — phase 기반**: `improvement_lenses.py` SSOT + profile (en+kr) + `workflow.py` / `wizard.py` enum + input 템플릿 + worker agents 1줄 추가. validator 는 stub (항상 통과). brief skill 변경 없음. *목적*: phase 자체가 render-only 로 동작 가능한 상태.
-- **PR 2 — validator + 문서**: validator 본체 + `validate-run.py` 통합 + tests + e2e + `README` / `docs/kr` / `CHANGES.md`. *목적*: enforcement 완비.
-- **PR 3 — brief skill**: `okstra-brief` 의 2-level pick + Step 4 강화 + Step 6 헤리스틱. PR 2 가 끝난 뒤 별도. *이유*: brief skill 은 사용자 진입 UI 라 변경 영향이 크고, validator 가 먼저 ship 되어야 사용자가 잘못된 brief 를 만들었을 때 명확한 실패를 본다.
-
-## 9. Out-of-scope backlog
-
-- **후보별 자동 spin-off**: K개 선택 → 자동 새 task-id 생성 + 자동 brief 작성. 사용성 매력적이지만 새 메커니즘이 많이 필요. PR 4+ 로 별도 검토.
-- **lens 외 lens** (커스텀 lens, project-level 확장): 현재는 8개 enum 으로 강제. 프로젝트 단위 lens 추가 메커니즘은 별도 spec.
-- **무한 lens grilling 종료 휴리스틱**: 현재 budget 기반 (8 + 12 = 20). 더 정교한 confidence threshold 는 추후.
-- **improve-codebase-architecture 스킬과의 통합**: 두 도구가 정보 공유. 별도 spec.
-
-## 10. Open questions / risks
-
-- **brief 의 `scan-scope` 가 매우 커지면 (예: 모노레포 전체)** Phase 1.5 codebase 1차 훑기가 무거워진다. 1차 mitigation: brief sharpening 단계에서 LOC 추정값을 보여주고 사용자가 좁히도록 권유. 2차: phase 시작 시 lead 가 budget 초과 추정 시 사용자에게 narrowing 의뢰.
-- **worker 가 lens 화이트리스트를 무시하고 새 lens 를 만들어 낼 위험**: profile 의 Forbidden actions 와 validator 가 이중 방어선. report-writer 가 작성 시 자체 검증.
-- **Phase 1.5 grilling 이 사용자 피로도를 키울 위험**: budget 12 + Recommended 답 의무 + codebase-first 로 사용자에게 묻기 전 코드로 풀 수 있는 건 풀기. 그래도 부담이면 brief 의 sharpening 강화로 흡수 가능.
-- **release-handoff 직전 품질 게이트로 오용될 위험**: improvement-discovery 는 *코드베이스 범위 발견* 이지 *변경 게이트* 가 아님. final-verification 의 역할과 혼동 금지. profile 의 Purpose 와 Non-goals 에 명시.
-
-## 11. 수용 기준
-
-이 spec 의 구현이 완료되었다고 간주하려면 모두 충족:
-
-- `node bin/okstra` 의 wizard 에서 `improvement-discovery` task-type 이 선택 가능.
-- `okstra-brief` 가 codebase-scan variant 를 생성 가능 + 결과 brief 가 `scope: codebase` frontmatter 포함.
-- `npx okstra render-bundle --task-type improvement-discovery ...` 가 instruction-set 까지 생성.
-- `validators/validate-improvement-report.py` 가 §6.5 의 11개 항목 모두 검증 + happy/sad path 테스트 통과.
-- `tests-e2e/scenario-08-...` 가 render-only 흐름을 끝까지 통과.
-- 한글 docs (`README.kr.md`, `docs/kr/cli.md`, `docs/kr/architecture.md`) 가 improvement-discovery 를 설명.
-- `CHANGES.md` 에 사용자 영향 line 포함된 entry.

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

@@ -1,113 +0,0 @@
-# okstra-run 브랜치 결정 확인 단계 설계
-
-> 작성: 2026-06-02 · 상태: 설계 승인 대기
-
-## 1. 배경 / 문제
-
-`okstra-run` 은 모든 task-type 에서 task-key 마다 **새 git worktree + 브랜치**(base-ref 에서 분기)를
-생성한다 ([scripts/okstra_ctl/run.py:730](../../../scripts/okstra_ctl/run.py) — "every phase,
-every task-type"). 단 호출 시점에 이미 non-main worktree 안이면 그 worktree 를 재사용한다
-([worktree.py:509](../../../scripts/okstra_ctl/worktree.py)).
-
-문제: 이 "새 브랜치 vs 현재 worktree 재사용" 결정이 **암묵적으로 자동** 이루어진다. wizard 의
-최종 confirm 요약에도 "새 브랜치 `<name>` 을 새 worktree 에 만든다" 는 사실이 드러나지 않는다.
-Claude Code 를 auto mode 로 돌리면 base-ref(=`main` 추천)가 확인 없이 선택되고, 사용자가
-의도하지 않은 브랜치가 main 에서 생성될 수 있다.
-
-목표: wizard 중간에 **브랜치/worktree 결정을 명시적으로 보여주는 확인 단계**를 추가해, 무엇이
-어디서 만들어지는지(또는 재사용되는지)를 사용자가 확인하게 한다.
-
-## 2. 범위 / 결정 (brainstorming 합의)
-
-| 항목 | 결정 |
-|---|---|
-| 성격 | **확인 게이트만** — worktree 격리 동작은 변경 없음 |
-| 위치 | **전용 신설 step**, `base-ref` 직후 · 최종 `confirm` 직전 |
-| 형태 | 일반 `pick` picker (`Proceed` 추천 / `Edit`) — full-auto 에서 auto-pick 가능성은 감수(사용자 선택) |
-| 미리보기 정밀도 | **정확** — 계산된 브랜치명·base-ref·worktree 경로(또는 재사용 경로)를 명시 |
-
-**비목표**: 현재 브랜치에서 격리 없이 실행하는 opt-out(동작 변경) · auto-pick 을 강제로
-막는 하드스톱 · worker 로스터/ base-ref fail-closed (별도 가드레일, 이번 범위 아님).
-
-## 3. 설계
-
-### 3.1 부수효과 없는 미리보기 헬퍼 (single reference point)
-
-`worktree.py` 의 provisioning 로직에서 **결정만 계산하고 디스크를 건드리지 않는** 순수 함수를
-추출한다:
-
-```
-preview_worktree_decision(project_root, work_category, task_key_segments, base_ref)
-  -> { mode: "new" | "reuse", branch, worktree_path, base_ref }
-```
-
-- `mode` 는 provisioning 의 **두 재사용 경로를 모두 포섭**한다: ① cwd 가 이미 non-main
-  worktree([worktree.py:509](../../../scripts/okstra_ctl/worktree.py)), ② registry 에 이 task-key
-  의 active worktree 존재([worktree.py:519](../../../scripts/okstra_ctl/worktree.py)). 둘 중 하나면
-  `reuse`, 아니면 `new`.
-- `branch` / `worktree_path` 는 기존 `compute_branch_name` / `compute_worktree_path` 재사용.
-- `provision_task_worktree` 는 이 헬퍼를 호출해 결정을 얻도록 리팩터한다 → **wizard 미리보기와
-  실제 provisioning 이 같은 결정 로직을 공유** (미리보기/실제 불일치 불가).
-- wizard 에는 이미 `state.reuse_worktree`(registry 기반, 위 ②만 감지 — [wizard.py:575,888](../../../scripts/okstra_ctl/wizard.py))
-  가 있다. 이 헬퍼가 ①+② 를 모두 포섭하므로, `branch_confirm` 의 mode 는 기존 플래그가 아니라
-  **헬퍼 결과**를 권위 소스로 쓴다(기존 `reuse_worktree` 는 헬퍼로 대체하거나 헬퍼에서 파생).
-
-### 3.2 wizard state `branch_confirm`
-
-위치: `base_ref`(_pick/_text) 통과 직후 → `confirm` 직전.
-
-- emit: `kind: "pick"`, `multi: false`. 결정 텍스트는 step 의 `label` 에 담는다(별도 summary-fetch
-  서브커맨드 불필요).
-  - **mode=new**: 옵션 `Proceed`(추천) / `Edit`. label:
-    "새 브랜치 `<branch>` 를 base-ref `<X>` 에서 새 worktree(`<worktree_path>`)에 생성 — 진행?"
-  - **mode=reuse**: 옵션 `Proceed` 만. label:
-    "현재 worktree `<worktree_path>` (브랜치 `<branch>`) 재사용 — 진행?"
-- 전이:
-  - `Proceed` → `confirm`
-  - `Edit`(mode=new 만) → `base_ref` 로 복귀(base-ref 재선택 시 branch_confirm 재계산)
-- 데이터 의존: 헬퍼는 `work_category` + task-key 세그먼트가 필요. wizard state 가 이를 직접
-  보유하지 않으면 끌어오는 작업을 구현에 포함(없으면 base-ref 만으로 "새 worktree 생성" 수준
-  문구로 graceful degrade — 단 정확성 목표상 threading 우선).
-
-### 3.3 재사용 케이스 + base-ref 스킵 정합
-
-헬퍼의 `mode == reuse` 면 base-ref 는 무의미하다. wizard 의 기존 base-ref 게이팅(현재
-`state.reuse_worktree` 로 registry-reuse 케이스를 다룸)이 cwd-in-worktree 케이스도 함께 커버하도록
-헬퍼 mode 기준으로 정렬한다. `branch_confirm` 은 mode 만 보고 옵션/문구를 구성한다(reuse →
-Proceed-only + 재사용 문구, new → Proceed/Edit + 생성 문구). base-ref step 의 정확한 스킵 조건은
-구현 시 `state.reuse_worktree`/헬퍼 mode 기준으로 확인·정렬.
-
-### 3.4 okstra-run skill
-
-`branch_confirm` 은 일반 `pick` step 이라 okstra-run 의 기존 generic pick 렌더(AskUserQuestion)가
-그대로 처리한다. 결정 텍스트가 `label` 에 들어오므로 **스킬 변경은 없음(있어도 안내 1줄)**.
-
-## 4. enforcement
-
-validator 계약이 아니라 **state machine 구조**가 강제한다 — `confirm` 에 도달하려면
-`branch_confirm` 을 반드시 통과해야 한다(state 전이로 보장). 별도 validator 불필요.
-
-## 5. 변경 표면
-
-| 영역 | 파일 | 변경 |
-|---|---|---|
-| 미리보기 헬퍼 | `scripts/okstra_ctl/worktree.py` | `preview_worktree_decision` 추출 + `provision_task_worktree` 가 이를 호출하도록 리팩터 |
-| wizard state | `scripts/okstra_ctl/wizard.py` | `branch_confirm` state + 빌드/제출 핸들러 + `base_ref → branch_confirm → confirm` 전이, `Edit→base_ref` |
-| skill | `skills/okstra-run/SKILL.md` | (선택) generic pick 이 새 step 을 처리함을 1줄 명시 |
-| 테스트 | 기존 wizard 테스트 모듈 + worktree 테스트 | 아래 §6 |
-| 문서 | `docs/kr/architecture.md`, `CHANGES.md` | 새 단계 / 사용자 영향 |
-
-## 6. 테스트 전략
-
-- **미리보기 헬퍼 순수 단위테스트**: 메인 cwd → `mode=new` + 올바른 branch/base, non-main
-  worktree cwd → `mode=reuse`.
-- **공유 회귀**: `provision_task_worktree` 가 헬퍼와 동일 결정을 내는지(미리보기=실제).
-- **wizard 전이**: `base_ref → branch_confirm → confirm`; mode=new 프롬프트에 계산된 branch+base
-  노출; mode=reuse 프롬프트에 worktree path 노출 + Proceed-only; `Proceed→confirm` /
-  `Edit→base_ref`.
-
-## 7. 비목표 (이번 범위 아님)
-
-- 현재 브랜치 격리 opt-out(동작 변경).
-- auto-pick 하드스톱(추천 없는 강제 입력).
-- worker 로스터 핀(project.json `defaultWorkers`) · base-ref fail-closed — 별도 가드레일 작업.

package/docs/superpowers/specs/2026-06-02-okstra-run-phase-pane-cleanup-design.md

@@ -1,173 +0,0 @@
-# okstra-run phase 전환 시 tmux pane 정리 — 설계
-
-## Index
-
-- [배경 / 문제](#배경--문제)
-- [현재 메커니즘 (검증된 사실)](#현재-메커니즘-검증된-사실)
-- [목표 / 비목표](#목표--비목표)
-- [설계 결정](#설계-결정)
-- [구현 범위](#구현-범위)
-- [닫을 대상 — title allowlist](#닫을-대상--title-allowlist)
-- [스크립트 변경 (`okstra-trace-cleanup.sh`)](#스크립트-변경-okstra-trace-cleanupsh)
-- [contract 변경 (`_common-contract.md`)](#contract-변경-_common-contractmd)
-- [테스트](#테스트)
-- [enforcement 정직성 / 알려진 한계](#enforcement-정직성--알려진-한계)
-- [영향 / 전파](#영향--전파)
-
-## 배경 / 문제
-
-okstra-run 진행 중 lead 가 내부 phase 마다 새로운 worker 를 dispatch 하면 tmux pane 이
-누적된다. 한 run 이 끝나도 이전 phase 의 worker pane 들이 좀비로 남아 화면을 채운다.
-실제 지난 run 에서 `claude-worker ×3`, `codex-worker ×3`, `report-writer-worker ×1`
-= 7개 pane(`%133`~`%139`)이 run 종료 후에도 남아 사용자가 수동으로 `tmux kill-pane`
-해야 했다.
-
-현재 contract 는 **trace pane 만**, 그것도 **run 맨 끝 1회**만 정리하고, worker-agent
-pane 은 전혀 관리하지 않는다.
-
-## 현재 메커니즘 (검증된 사실)
-
-okstra dispatch 1회당 **두 종류**의 pane 이 생긴다:
-
-1. **worker-agent pane** — lead 가 `claude-worker` / `codex-worker` / `gemini-worker` /
-   `report-writer-worker` 를 Agent(서브에이전트)로 dispatch 하면, Claude Code 하네스의
-   서브에이전트 실행이 각 백그라운드 에이전트마다 pane 을 부여한다. title 은 에이전트
-   이름(하네스가 ✳/💬 glyph prefix 를 붙임). **okstra 코드가 만들지 않고 registry 에도
-   없으며 run 종료 후에도 잔존**한다. 누적의 주범.
-2. **trace pane** — codex/gemini wrapper(`okstra-codex-exec.sh` /
-   `okstra-gemini-exec.sh`)가 worker-agent pane **안에서** `tmux split-window` 로 만드는
-   `tail -F <log>` panel. title `<cli>-<role>-<pid>-trace`. okstra 소유이고 caller
-   `$TMUX_PANE` 으로 키된 registry(`${TMPDIR:-/tmp}/okstra-trace-panes/<caller>.list`)에
-   등록되며 `okstra-trace-cleanup.sh` 가 정리한다. `SessionEnd` 훅이 `/exit` 시 호출
-   ([settings.template.json:156](../../../templates/reports/settings.template.json)).
-
-사용자가 기억한 "codex/gemini = 새 panel 에 로그 tail" 설계는 **(2) trace pane 으로
-실재**한다([architecture.md Live-log mirror 절](../../kr/architecture.md)). 문제는 그
-위에 얹힌 **(1) worker-agent pane** 이 정리되지 않는 것이다.
-
-## 목표 / 비목표
-
-### 목표
-- 새 phase 의 worker 를 dispatch 하기 직전, 이전 phase 의 okstra pane(에이전트 + trace)을
-  자동으로 모두 닫는다.
-- lead 자신의 pane 과 사용자의 무관한 pane 은 절대 건드리지 않는다.
-- pane 정리 구현을 단일 참조점(`okstra-trace-cleanup.sh`)으로 유지한다.
-
-### 비목표
-- codex/gemini 의 실행 구조 변경(에이전트 dispatch → wrapper 직접 실행)은 하지 **않는다**.
-  구조(에이전트 pane + tail panel)는 그대로 두고 정리만 한다. (사용자 결정: "phase 시작 시
-  전부 닫기만")
-- 새 lifecycle phase 자동 진행 등 anti-escalation 규칙 변경 없음.
-
-## 설계 결정
-
-| # | 결정 | 사용자 확인 |
-|---|------|-------------|
-| D1 | 정리 시점 = **내부 phase 시작 직전** (이전 phase pane 전부) | ✅ "phase 시작 시 전부 닫기" |
-| D2 | phase 경계 정리는 **자동(무콜)**, 한 줄 보고 | ✅ "자동 정리 (무콜)" |
-| D3 | run 최종 종료 시점만 기존 **이진 prompt** 유지 | ✅ "마지막만 기존 prompt 유지" |
-| D4 | 닫을 대상 = worker-agent pane + trace pane | ✅ (로그의 7개 pane) |
-| D5 | 구조 변경 없음(에이전트 pane 제거 안 함) | ✅ "phase 시작 시 전부 닫기만" |
-
-## 구현 범위
-
-1. `scripts/okstra-trace-cleanup.sh` — "okstra pane" 식별을 **registry trace pane ∪
-   title-allowlist worker-agent pane (lead pane 제외)** 로 통일.
-2. `prompts/profiles/_common-contract.md` — phase 시작 자동정리 규약 추가 + 최종 prompt
-   대상 통합.
-3. `tests/test_okstra_trace_cleanup.py` — title-allowlist kill / lead·비-okstra pane
-   보존 회귀 가드 추가.
-4. 문서: `docs/kr/architecture.md` Live-log mirror 절, `CHANGES.md` 갱신.
-
-## 닫을 대상 — title allowlist
-
-rule #7 (allowlist over denylist): **닫아도 되는 것만** 명시.
-
-- worker-agent pane: title 이 다음 중 하나를 **포함**:
-  `claude-worker`, `codex-worker`, `gemini-worker`, `report-writer-worker`
-  (하네스 glyph/공백 prefix 를 흡수하기 위해 부분일치).
-- trace pane: caller `$TMUX_PANE` registry 에 등록된 pane id (기존 메커니즘 그대로).
-
-**불변 안전장치**:
-- lead 자신의 pane(`$TMUX_PANE`)은 식별 결과에서 **항상 제외** — title 이 우연히 매칭돼도
-  제외.
-- 검색 범위는 lead pane 이 속한 **tmux 세션**으로 한정(`tmux list-panes -s -t
-  $TMUX_PANE`), 전체 세션(`-a`) 스캔 금지.
-- allowlist 에 없는 title 은 절대 kill 대상이 아니다.
-
-## 스크립트 변경 (`okstra-trace-cleanup.sh`)
-
-식별 함수를 도입해 두 소스를 합집합으로 모은다 (의사 흐름):
-
-```
-okstra_panes():
-    panes = registry 에 등록된 pane id 들          # 기존 trace 경로
-    for (pane_id, title) in (현재 세션의 모든 pane):  # tmux list-panes -s -t $TMUX_PANE
-        if pane_id == $TMUX_PANE: continue           # lead 제외 (불변)
-        if title 가 allowlist 키워드 포함: panes += pane_id
-    return dedupe(panes)
-```
-
-- `--list` → `okstra_panes()` 의 각 `<pane_id>\t<title>` 출력. (최종 wrap-up prompt 가
-  사용; 비어 있으면 빈 stdout.)
-- (무인자) kill → `okstra_panes()` 전부 `tmux kill-pane` + registry 파일 제거. (phase
-  시작 자동정리 / 최종 prompt 예-분기 / `SessionEnd` 훅 공용.)
-- 기존 동작 보존: `$TMUX_PANE` 미설정 → no-op(exit 0). 모든 tmux 실패는 silent degrade
-  (lead 종료를 막지 않음).
-- `--dry-run`(= `--list` alias), `-h/--help`, unknown-option exit 2 는 유지.
-
-trace registry 의 caller-scoping 격리(다른 Claude 인스턴스의 trace pane 미터치)는 그대로
-유지된다. worker-agent pane 은 registry 가 없어 title 로만 식별하므로 세션 범위로만 좁힌다
-([아래 한계](#enforcement-정직성--알려진-한계) 참고).
-
-## contract 변경 (`_common-contract.md`)
-
-기존 "Phase wrap-up — worker trace pane disposition" 섹션에 두 가지를 반영:
-
-1. **신규 — phase 시작 자동정리 (shared, BLOCKING, 모든 profile 의 내부 phase 공통)**:
-   lead 가 새 worker batch 를 dispatch 하기 **직전**(이미 PROGRESS 마커를 찍는 전환점):
-   - 각 `PROGRESS: phase-5.5-convergence round=<N>` 직전
-   - `PROGRESS: phase-6-synthesis dispatching report-writer-worker` 직전
-   `$TMUX_PANE` 가 셋이면 `okstra-trace-cleanup.sh`(무인자)를 **prompt 없이** 실행하고
-   `이전 phase okstra pane N개 정리` 한 줄만 보고. `$TMUX_PANE` 미설정이면 silent-skip,
-   합성 pane 목록 날조 금지(기존 규칙과 동일).
-2. **최종 prompt 대상 통합**: 기존 run-종료 이진 prompt 의 `--list`/kill 이 trace pane
-   뿐 아니라 worker-agent pane(예: 마지막 phase 의 report-writer)까지 포함하도록 확장.
-   prompt 문구·이진 선택(모두 닫기/그대로)·empty-skip 규칙은 그대로.
-
-`_common-contract.md` 헤더의 "phase-specific 규칙 금지"와 충돌하지 않는다 — Phase 4/5,
-5.5, 6 은 이미 같은 파일의 "Worker interaction model" 절이 공유 lifecycle 로 다루는
-대상이다.
-
-## 테스트
-
-`tests/test_okstra_trace_cleanup.py` 에 실 tmux 서버 기반 케이스 추가(기존 픽스처 재사용):
-
-- `test_kills_worker_agent_panes_by_title`: caller(lead) pane + `claude-worker` /
-  `codex-worker` / `report-writer-worker` title pane 생성 → kill 모드 실행 → 에이전트
-  pane 은 죽고 **caller pane 은 보존**.
-- `test_preserves_non_okstra_panes`: allowlist 외 title(예: `가격 계산 기능 개발`,
-  `vim`) pane 은 보존.
-- `test_excludes_lead_pane_even_if_title_matches`: caller pane title 을
-  `claude-worker` 로 강제해도 `$TMUX_PANE` 이므로 보존.
-- `test_list_includes_agent_and_trace`: `--list` 가 registry trace pane + title-match
-  agent pane 을 합쳐 출력.
-- 기존 케이스(미설정 no-op, registry 미존재 no-op, caller-scope 격리, unknown-option)는
-  회귀 없이 통과.
-
-## enforcement 정직성 / 알려진 한계
-
-- **선언적 동작**: phase 시작 자동정리는 lead 가 contract 를 따르는 선언이며 런타임 강제
-  훅이 없다(내부 phase 경계는 lead 만 안다). 기존 최종정리와 동일한 강제 수준이고,
-  `SessionEnd` 훅만 `/exit` 시점을 강제한다. 이 한계를 과장하지 않는다.
-- **동시-run trade-off**: worker-agent pane 은 registry 가 없어 title 로만 식별한다.
-  같은 tmux 세션에서 **다른 okstra run 이 동시 실행** 중이면 그쪽 에이전트 pane 도
-  매칭될 수 있다(trace pane 의 caller-scoping 같은 격리 불가). 세션 범위로 좁혀 완화하되
-  완전 격리는 불가능 — 동일 세션 동시 okstra run 은 드문 케이스로 수용한다.
-
-## 영향 / 전파
-
-- 변경은 seed/source 파일(`scripts/`, `prompts/`, `templates/`)에 land → `npm run build`
-  → `runtime/` → `okstra install` 로 최종 사용자 전파. 개인 `.claude/` 직접 수정 아님.
-- 사용자 영향(CHANGES.md): "okstra-run 진행 중 새 phase 가 시작되면 이전 phase 의
-  worker/trace pane 이 자동으로 닫혀 화면에 좀비 pane 이 쌓이지 않는다."