okstra 0.116.0 → 0.118.0

package/docs/kr/performance-improvement-plan.md

@@ -1,147 +0,0 @@
-# okstra-run 성능 개선 계획
-
-## 인덱스
-
-- [1. 배경](#1-배경)
-- [2. 현재 구조 요약](#2-현재-구조-요약)
-  - [2.1 진입점](#21-진입점)
-  - [2.2 라이프사이클 (Phase 1~7)](#22-라이프사이클-phase-17)
-  - [2.3 워커 구조](#23-워커-구조)
-  - [2.4 핵심 파이프라인](#24-핵심-파이프라인)
-- [3. 무거움의 원인 분석](#3-무거움의-원인-분석)
-- [4. 개선 방안 우선순위](#4-개선-방안-우선순위)
-  - [4.1 (P1) Convergence 루프 축소](#41-p1-convergence-루프-축소--본-작업의-1번-대상)
-  - [4.2 (P2) 프롬프트 캐싱 적용](#42-p2-프롬프트-캐싱-적용)
-  - [4.3 (P3) Phase 1 fast-track 라우팅](#43-p3-phase-1-fast-track-라우팅)
-  - [4.4 (P4) 워커 정의 공통부 추출 / 템플릿 슬림화](#44-p4-워커-정의-공통부-추출--템플릿-슬림화)
-  - [4.5 (P5~) Render 병렬화, token-usage 증분화](#45-p5-render-병렬화-token-usage-증분화)
-- [5. 병렬 작업 가능성](#5-병렬-작업-가능성)
-  - [5.1 의존성 매트릭스](#51-의존성-매트릭스)
-  - [5.2 권장 분할](#52-권장-분할)
-  - [5.3 실행 형태](#53-실행-형태)
-- [6. P1 작업 착수 시 다음 단계](#6-p1-작업-착수-시-다음-단계)
-- [7. 트레이드오프 / 리스크](#7-트레이드오프--리스크)
-
-## 1. 배경
-
-`okstra-run` 스킬(또는 `scripts/okstra.sh`)을 통한 cross-verification 실행이 무겁게 느껴진다는 사용자 피드백을 바탕으로, 현재 파이프라인 구조를 분석하고 개선 후보를 도출한다. 본 문서는 분석 결과와 우선순위, 그리고 병렬 작업 가능성을 정리한다.
-
-## 2. 현재 구조 요약
-
-### 2.1 진입점
-
-- `scripts/okstra.sh:127-132` 및 `skills/okstra-run/SKILL.md` 는 모두 `scripts/okstra_ctl/run.py` 의 `prepare_task_bundle()` 함수를 호출한다.
-- 단일 reference point는 유지되고 있다.
-
-### 2.2 라이프사이클 (Phase 1~7)
-
-`scripts/okstra_ctl/workflow.py:12-31` 의 `PHASE_SEQUENCE` 정의에 따라 다음 단계가 순차 실행된다.
-
-| Phase | 이름 | 책임 |
-|---|---|---|
-| 1 | requirements-discovery | 라우팅 결정, 분류 |
-| 2 | error-analysis | 근본 원인 분석 (read-only) |
-| 3 | implementation-planning | 옵션 2개 이상 제시, 사용자 승인 요청 |
-| 4 | implementation | 승인된 계획 실행 (executor 1 + verifier 2~3) |
-| 5 | final-verification | 수용성 검증 |
-| 5.5 | convergence | 워커 결과 cross-verify, 최대 2라운드 |
-| 6 | release-handoff | lead 단독, git push + PR |
-| 7 | final-report | report-writer-worker 또는 lead가 최종 보고서 생성 |
-
-### 2.3 워커 구조
-
-`agents/workers/` 하위 4종:
-
-- `claude-worker.md` (113줄) — in-process subagent
-- `codex-worker.md` (209줄) — `okstra-codex-exec.sh` CLI 호출
-- `antigravity-worker.md` (209줄) — `okstra-antigravity-exec.sh` CLI 호출
-- `report-writer-worker.md` (117줄) — Phase 6/7 전용
-
-### 2.4 핵심 파이프라인
-
-- `scripts/okstra_ctl/run.py` (≈900줄) 가 중앙 오케스트레이터.
-- `prepare_task_bundle()` 내부에서 9개의 render 함수가 순차 호출됨 (`run.py:715-777`).
-- 템플릿: `templates/reports/final-report.template.md` (378줄), `templates/launch.template.md` (88줄), task-type profile 6종.
-
-## 3. 무거움의 원인 분석
-
-| # | 원인 | 영향도 | 위치 |
-|---|---|---|---|
-| A | Phase 5.5 convergence 의 최대 2라운드 × 3~4 워커 = 6~8회 re-dispatch | 大 | `skills/okstra-convergence/SKILL.md:55-77` |
-| B | 워커 프롬프트(20~40K 토큰) × 워커 수 × 라운드의 토큰 비용. 캐싱 없음 | 大 | `scripts/okstra_ctl/render.py` |
-| C | 거대 템플릿의 매 run 재렌더링 (final-report.template.md 378줄) | 中 | `templates/reports/` |
-| D | 9개 render 함수의 직렬 호출 | 中 | `run.py:715-777` |
-| E | 모든 task 가 동일한 7-phase 통과 (단순 typo 도 포함) | 中 | `workflow.py:12-31` |
-| F | codex-worker / antigravity-worker 정의 209줄 중 공통부 중복 | 中 | `agents/workers/` |
-| G | token usage 집계의 전체 JSONL 선형 스캔 | 小 | `scripts/okstra-token-usage.py` |
-
-## 4. 개선 방안 우선순위
-
-### 4.1 (P1) Convergence 루프 축소  ← 본 작업의 1번 대상
-
-- **현재**: 최대 2라운드를 기본으로 모든 항목에 대해 재검증.
-- **개선**: 1라운드를 기본으로 하고, **contested 분류 항목만 선택적 2라운드**. full/partial consensus 항목은 1라운드에서 즉시 확정.
-- **기대 효과**: 워커 호출 30~50% 감소, wall-clock 동등 비율 감소.
-- **변경 대상**:
-  - `skills/okstra-convergence/SKILL.md` (라운드 트리거 조건, contested 게이트 정의)
-  - 관련 render/state 정의 — `templates/reports/final-report.template.md` 의 consensus 섹션 헤더가 라운드 정보와 일치하도록 점검
-  - 필요 시 `scripts/okstra_ctl/` 내 convergence state 핸들링 코드
-
-### 4.2 (P2) 프롬프트 캐싱 적용
-
-- 거의 불변인 worker 정의 / launch profile 부분을 `cache_control: ephemeral` 로 마킹.
-- 변경 대상: `scripts/okstra_ctl/render.py` 의 worker prompt 조립부.
-
-### 4.3 (P3) Phase 1 fast-track 라우팅
-
-- 단순 작업(typo, docs-only, 명확한 1-file fix)은 Phase 2~5 우회. 안전망으로 Phase 5(final-verification)만 잔류시키는 "lite" 흐름.
-- 변경 대상: `scripts/okstra_ctl/workflow.py`, requirements-discovery 프롬프트.
-
-### 4.4 (P4) 워커 정의 공통부 추출 / 템플릿 슬림화
-
-- `agents/workers/_common.md` 추출, codex/antigravity 차별점만 남김.
-- final-report 템플릿은 Phase 6/7 외에는 inline expansion 제거하고 참조 링크만 전달.
-
-### 4.5 (P5~) Render 병렬화, token-usage 증분화
-
-- 효과는 작지만 난이도 낮음. 여유 있을 때 처리.
-
-## 5. 병렬 작업 가능성
-
-개선 후보들은 대부분 **서로 다른 파일에 작용**하므로 worktree 기반 병렬 작업이 가능하다.
-
-### 5.1 의존성 매트릭스
-
-| 작업 | 주요 변경 파일 | 충돌 가능성 |
-|---|---|---|
-| P1 Convergence 축소 | `skills/okstra-convergence/SKILL.md`, convergence state 코드 | P4 워커 공통화와 약한 충돌 (consensus 분류 텍스트) |
-| P2 프롬프트 캐싱 | `scripts/okstra_ctl/render.py` | P4 와 일부 겹침 (render 경유) |
-| P3 Fast-track 라우팅 | `workflow.py`, Phase 1 프롬프트 | 독립 |
-| P4 워커 공통부 / 템플릿 슬림 | `agents/workers/*.md`, `templates/` | P1, P2 와 약한 충돌 |
-| P5 Render 병렬화 | `run.py:715-777` | 독립 |
-
-### 5.2 권장 분할
-
-- **트랙 A (현재 작업)**: P1 — Convergence 1라운드 + contested-only 2라운드
-- **트랙 B (병렬 가능)**: P3 — Phase 1 fast-track 라우팅 (P1 과 파일 비중복)
-- **트랙 C (병렬 가능)**: P5 — Render 병렬화 / token-usage 증분화 (독립)
-
-P2 와 P4 는 P1 완료 후에 진행하는 편이 안전하다(템플릿/워커 정의가 함께 닿이기 때문).
-
-### 5.3 실행 형태
-
-- 각 트랙을 별도 git worktree 로 분리.
-- 트랙별 작업은 독립 PR 로 머지, 충돌 시 P1 우선.
-
-## 6. P1 작업 착수 시 다음 단계
-
-1. `skills/okstra-convergence/SKILL.md` 현재 라운드 로직 정밀 독해.
-2. consensus 분류(full / partial / contested / unique)가 어디서 산출되는지 확정.
-3. 1라운드 후 종료 조건과 2라운드 진입 조건(=contested 존재 여부 + 임계치)을 명세.
-4. `final-report.template.md` 의 라운드 표시부 정합성 검사.
-5. 변경 후 dry-run 으로 단순 task 1건 + contested 발생 task 1건을 비교 실행.
-
-## 7. 트레이드오프 / 리스크
-
-- 1라운드 기본화는 full consensus 항목의 추가 안전망을 제거한다. 만약 워커 간 hallucination 동조 위험이 우려되면, contested 외에도 "unique 비율이 임계 이상"인 경우를 2라운드 트리거에 포함시키는 방어선이 필요.
-- Fast-track 라우팅은 분류 오판 시 release-handoff 단계에서 검증 부족 위험. Phase 5 잔류로 완화.