okstra 0.34.1 → 0.36.1

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

@@ -0,0 +1,335 @@
+# 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/task-process/README.md

@@ -0,0 +1,74 @@
+# okstra-run task process
+
+## Index
+
+- [1. 읽는 순서](#1-읽는-순서)
+- [2. 전체 그림](#2-전체-그림)
+- [3. task-type 문서](#3-task-type-문서)
+- [4. 핵심 코드 위치](#4-핵심-코드-위치)
+- [5. 빠른 비교표](#5-빠른-비교표)
+
+## 1. 읽는 순서
+
+`okstra-run`은 Claude Code 세션 안에서 task를 시작하는 경로다. 이 폴더는 그 실행 흐름을 두 층으로 나눠 정리한다.
+
+1. 먼저 [common-flow.md](common-flow.md)를 읽는다. 모든 task-type이 공유하는 wizard, render-bundle, lead phase, artifact 흐름이다.
+2. 그 다음 실행하려는 task-type 문서를 읽는다.
+3. task-type별 차이는 "wizard에서 더 묻는 것", "`prepare_task_bundle()`이 runtime에서 막는 것", "lead profile이 phase 안에서 지키는 것" 세 군데로 나눠 확인한다.
+
+## 2. 전체 그림
+
+```mermaid
+flowchart TD
+    U[User in Claude Code] --> S[/okstra-run skill/]
+    S --> R[Step 1<br/>ensure-installed / paths / check-project]
+    R --> W[okstra wizard<br/>state machine]
+    W --> A[render-args]
+    A --> B[okstra render-bundle<br/>--render-only]
+    B --> P[prepare_task_bundle()]
+    P --> I[instruction-set<br/>claude-execution-prompt.md]
+    I --> L[Current Claude session<br/>takes over as Claude lead]
+    L --> F[Phase 1-7 lead workflow]
+    F --> O[final-report + manifests + status]
+```
+
+`okstra-run`은 `scripts/okstra.sh`를 호출하지 않는다. 대신 `okstra wizard`와 `okstra render-bundle`을 거쳐 같은 Python 단일 진입점인 `prepare_task_bundle()`로 수렴한다.
+
+## 3. task-type 문서
+
+| task-type | 문서 | 한 줄 목적 |
+|---|---|---|
+| `requirements-discovery` | [requirements-discovery.md](requirements-discovery.md) | 요청을 분류하고 다음 안전 phase를 고른다. |
+| `error-analysis` | [error-analysis.md](error-analysis.md) | 증상과 evidence로 원인 후보와 검증 경로를 찾는다. |
+| `implementation-planning` | [implementation-planning.md](implementation-planning.md) | 구현 옵션, 검증, rollback, approval gate가 있는 계획을 만든다. |
+| `implementation` | [implementation.md](implementation.md) | 승인된 계획을 executor가 구현하고 verifier가 독립 검증한다. |
+| `final-verification` | [final-verification.md](final-verification.md) | 구현 결과를 read-only로 acceptance 판단한다. |
+| `release-handoff` | [release-handoff.md](release-handoff.md) | accepted verdict 뒤 push/PR handoff를 lead-only로 수행한다. |
+
+## 4. 핵심 코드 위치
+
+| 관심사 | 정본 |
+|---|---|
+| okstra-run skill 절차 | [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md) |
+| wizard state machine | [`scripts/okstra_ctl/wizard.py`](../../scripts/okstra_ctl/wizard.py) |
+| wizard prompt text | [`prompts/wizard/prompts.ko.json`](../../prompts/wizard/prompts.ko.json) |
+| render-bundle Node shim | [`src/render-bundle.mjs`](../../src/render-bundle.mjs) |
+| bundle 생성 단일 진입점 | [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py) |
+| phase boundary | [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py) |
+| task worktree | [`scripts/okstra_ctl/worktree.py`](../../scripts/okstra_ctl/worktree.py) |
+| worker roster parser | [`scripts/okstra_ctl/workers.py`](../../scripts/okstra_ctl/workers.py) |
+| lead operating contract | [`agents/SKILL.md`](../../agents/SKILL.md) |
+| phase profiles | [`prompts/profiles/`](../../prompts/profiles/) |
+| final report shape | [`templates/reports/final-report.template.md`](../../templates/reports/final-report.template.md) |
+
+## 5. 빠른 비교표
+
+| task-type | wizard 특수 질문 | runtime prepare gate | lead/worker mode | 다음 phase 기본값 |
+|---|---|---|---|---|
+| `requirements-discovery` | 공통 질문만 | profile/brief/base-ref 존재 | multi-worker analysis, convergence 1 round default | `pending-routing-decision` |
+| `error-analysis` | 공통 질문만 | profile/brief/base-ref 존재 | multi-worker analysis, convergence 2 rounds default | `implementation-planning` |
+| `implementation-planning` | 공통 질문만 | profile/brief/base-ref 존재 | multi-worker analysis + Phase 6 plan-body verification | `implementation` |
+| `implementation` | approved plan, stage, executor | approved marker, stage map, QA command deny-list | executor writes, verifiers read-only | `final-verification` |
+| `final-verification` | 공통 질문만 | profile/brief/base-ref 존재 | multi-worker read-only verification | `pending-release-handoff` |
+| `release-handoff` | PR template override/scope | PR template resolution, empty worker roster | single-lead, no TeamCreate, no workers | `done-or-follow-up` |
+

package/docs/task-process/common-flow.md

@@ -0,0 +1,166 @@
+# okstra-run common flow
+
+## Index
+
+- [1. 한 줄 요약](#1-한-줄-요약)
+- [2. 두 entrypoint가 만나는 지점](#2-두-entrypoint가-만나는-지점)
+- [3. wizard 입력 수집 흐름](#3-wizard-입력-수집-흐름)
+- [4. render-bundle과 prepare_task_bundle](#4-render-bundle과-prepare_task_bundle)
+- [5. Claude lead phase 1-7](#5-claude-lead-phase-1-7)
+- [6. artifact layout](#6-artifact-layout)
+- [7. 공통 분기 규칙](#7-공통-분기-규칙)
+- [8. 주의할 불일치 지점](#8-주의할-불일치-지점)
+
+## 1. 한 줄 요약
+
+`okstra-run`은 "질문을 직접 판단하는 skill"이 아니라 `okstra wizard` JSON state machine을 사용자에게 relay하는 얇은 loop다. 입력 수집이 끝나면 `okstra render-bundle`을 호출하고, 이 명령이 `python3 -m okstra_ctl.run --render-only`를 통해 task bundle을 만든다. 그 뒤 현재 Claude Code 세션이 `Claude lead`로 전환된다.
+
+## 2. 두 entrypoint가 만나는 지점
+
+```mermaid
+flowchart LR
+    subgraph InSession["Claude Code in-session"]
+        A[/okstra-run skill/] --> B[okstra wizard]
+        B --> C[okstra render-bundle<br/>forces --render-only]
+    end
+
+    subgraph Terminal["terminal path"]
+        D[scripts/okstra.sh] --> E[CLI parse / prompt / confirm]
+    end
+
+    C --> P[prepare_task_bundle()]
+    E --> P
+    P --> G[task bundle artifacts]
+    G --> H{launch mode}
+    H -->|render-only| I[current Claude reads lead prompt]
+    H -->|non-render-only| J[exec claude --session-id ...]
+```
+
+공통 원칙은 `prepare_task_bundle()`가 task bundle 생성의 단일 권위라는 점이다. wizard나 shell wrapper가 path 계산, manifest 생성, worktree 생성 로직을 복제하지 않는다.
+
+## 3. wizard 입력 수집 흐름
+
+```mermaid
+stateDiagram-v2
+    [*] --> VerifyRuntime: okstra ensure-installed / paths / check-project
+    VerifyRuntime --> NewState: okstra wizard new-state-file
+    NewState --> TaskPick: wizard init
+    TaskPick --> BriefPath: brand-new task
+    TaskPick --> TaskType: existing task
+    BriefPath --> TaskGroup: new task, brief accepted
+    TaskGroup --> TaskId
+    TaskId --> TaskType
+    TaskType --> BriefKeep: existing task with existing brief
+    BriefKeep --> BriefPath: change
+    BriefKeep --> BaseRef: keep
+    TaskType --> BaseRef: no active worktree
+    TaskType --> ImplementationExtras: implementation only
+    BaseRef --> ImplementationExtras: implementation only
+    BaseRef --> DefaultsOrCustom: non-implementation
+    ImplementationExtras --> DefaultsOrCustom
+    DefaultsOrCustom --> WorkersOverride: non-implementation analyser roster
+    WorkersOverride --> Confirm: defaults
+    DefaultsOrCustom --> ModelAndOptionalInputs: customize
+    ModelAndOptionalInputs --> Confirm
+    Confirm --> EditTarget: Edit
+    EditTarget --> TaskType: rewind selected step
+    Confirm --> Done: Proceed
+```
+
+새 task는 brief를 먼저 받는다. brief frontmatter에 `task-group:`과 `brief-id:`가 있으면 wizard가 task group/id를 추천값 pick으로 보여준다. 기존 task는 manifest의 `workflow.nextRecommendedPhase`를 task-type 추천값으로 보여주고, 기존 brief path가 있으면 유지/변경을 묻는다.
+
+## 4. render-bundle과 prepare_task_bundle
+
+```mermaid
+sequenceDiagram
+    participant Skill as okstra-run skill
+    participant Node as okstra CLI
+    participant Py as okstra_ctl.run
+    participant FS as .project-docs/okstra
+    participant Home as ~/.okstra
+
+    Skill->>Node: okstra wizard render-args
+    Node-->>Skill: { args: ... }
+    Skill->>Node: okstra render-bundle --... --render-only
+    Node->>Py: python3 -m okstra_ctl.run --render-only --...
+    Py->>Py: validate profile, brief, task-type gates
+    Py->>Home: reserve/reuse task worktree registry
+    Py->>FS: write run-context and instruction-set
+    Py->>FS: write task/run manifests, team-state, timeline, discovery
+    Py->>Home: record_start status=prepared
+    Py-->>Node: task root, instruction-set, rendered lead prompt
+    Node-->>Skill: stdout
+    Skill->>FS: read claude-execution-prompt.md
+```
+
+`render-bundle`은 `--workspace-root`와 `--render-only`를 직접 붙인다. 따라서 okstra-run 경로의 initial run status는 `prepared`, task status는 `instruction-set-generated`로 시작한다.
+
+## 5. Claude lead phase 1-7
+
+```mermaid
+flowchart TD
+    P1[Phase 1<br/>task bundle intake] --> P2[Phase 2<br/>worker prompt preparation]
+    P2 --> P3[Phase 3<br/>TeamCreate]
+    P3 -->|team ok| P4[Phase 4<br/>dispatch workers with team_name]
+    P3 -->|team unavailable| P5[Phase 5<br/>background fallback]
+    P4 --> C[Phase 5.5<br/>convergence]
+    P5 --> C
+    C --> P6[Phase 6<br/>report-writer synthesis]
+    P6 --> PV{implementation-planning?}
+    PV -->|yes| PBV[Plan-body verification]
+    PV -->|no| P7[Phase 7<br/>persist + validate]
+    PBV --> P7
+    P7 --> Done[final report + manifests updated]
+```
+
+분석 worker와 report-writer의 역할은 분리된다. `report-writer`는 Phase 4/5 분석 worker가 아니라 Phase 6 final report author다. 단, `release-handoff`는 single-lead phase이므로 이 phase graph를 일부러 타지 않는다.
+
+## 6. artifact layout
+
+```mermaid
+flowchart TD
+    Root["<PROJECT_ROOT>/.project-docs/okstra/tasks/<group>/<task>/"] --> IS[instruction-set/]
+    Root --> Runs[runs/<task-type>/]
+    Root --> Hist[history/timeline.json]
+    IS --> Profile[analysis-profile.md]
+    IS --> Brief[task-brief.md]
+    IS --> Lead[claude-execution-prompt.md]
+    Runs --> Man[manifests/run-manifest-*.json]
+    Runs --> Prompts[prompts/*-worker-prompt-*.md]
+    Runs --> Results[worker-results/*.md]
+    Runs --> Reports[reports/final-report-*.md<br/>reports/*.data.json]
+    Runs --> State[state/*.json]
+    Runs --> Status[status/final-status-*.json]
+```
+
+`runtime/`은 build output이므로 이 흐름을 고칠 때는 source인 `scripts/`, `skills/`, `agents/`, `prompts/`, `templates/`, `validators/`를 수정하고 `npm run build`로 갱신한다.
+
+## 7. 공통 분기 규칙
+
+```mermaid
+flowchart TD
+    T[task-type selected] --> W{active worktree in registry?}
+    W -->|yes| Reuse[reuse existing worktree<br/>base-ref prompt skipped]
+    W -->|no| Base[ask base-ref<br/>validate with git rev-parse]
+    Base --> D{Use defaults?}
+    Reuse --> D
+    D -->|defaults| R{non-implementation<br/>has analyser roster?}
+    D -->|customize| M[lead/model/directive/related/clarification prompts]
+    R -->|yes| WO[worker multi-pick still shown]
+    R -->|no| Confirm
+    WO --> Confirm
+    M --> Special{release-handoff?}
+    Special -->|yes| PR[PR template override/scope]
+    Special -->|no| Confirm
+    PR --> Confirm
+```
+
+중요한 점은 `Use defaults`가 model 기본값을 뜻한다는 것이다. non-implementation task-type에서는 defaults를 골라도 worker roster 질문은 계속 나온다. 반대로 `implementation`은 worker override 질문이 없다. profile default roster와 executor binding을 사용한다.
+
+## 8. 주의할 불일치 지점
+
+- `okstra-run` wizard 경로는 implementation approved plan에 이미 approval marker가 있어야 통과한다. `scripts/okstra.sh`에는 `--approve`가 있어 checkbox를 CLI ack로 flip할 수 있지만, 현재 wizard `render_args()`에는 `approve` flag가 없다.
+- `release-handoff`도 task worktree provisioning 대상이다. 정상적인 handoff는 같은 task-key의 implementation/final-verification worktree를 재사용하는 흐름이 안전하다. 새 task로 시작하면 새 worktree가 만들어지고, profile의 "implementation commit이 있어야 함" entry gate에서 막힐 수 있다.
+- `release-handoff`는 profile에 `Required workers:` block이 없다. runtime도 worker roster를 강제로 empty로 만든다.
+- 모든 task-type은 한 run 안에서 다음 lifecycle phase를 시작하지 않는다. "다음 단계 진행해"는 현재 phase 산출을 마무리하라는 뜻으로만 해석한다.
+