okstra 0.72.0 → 0.74.0

package/docs/kr/architecture.md

@@ -496,7 +496,7 @@ task manifest, task index, instruction-set, runs, history가 이 루트 아래
 - `reports/final-report-<task-type>-<seq>.md`
 - `reports/final-report-<task-type>-<seq>.slim.md`  *(Phase 7 결정론적 후처리: AI 다음-phase 입력용 슬림 markdown)*
 - `reports/final-report-<task-type>-<seq>.html`     *(Phase 7 결정론적 후처리: 사람 reviewer 용 self-contained HTML, CSS/JS 인라인)*
-- `user-responses/user-response-<task-type>-<seq>.md` *(HTML 의 `Export user response` 버튼이 생성하는 사이드카; 사용자가 채워 저장하면 다음 phase 가 입력으로 소비)*
+- `user-responses/user-response-<task-type>-<seq>.md` *(HTML 의 `Export user response` 버튼이 같은 이름으로 다운로드해 주는 사이드카; 여기 저장해 두면 `--resume-clarification` 이 instruction-set 의 `clarification-response.md` 에 자동 첨부한다 — `clarification_items.clarification_response_with_sidecars`)*
 - `worker-results/<worker>-audit-<task-type>-<seq>.md` *(워커별 Reading Confirmation 사이드카; 본문이 아니라 audit 용)*
 - `status/final-<task-type>-<seq>.status`
 - `carry/stage-<N>.json` *(implementation 전용: stage N 실행 evidence sidecar; 다음 stage 가 자동 carry-in)*
@@ -969,6 +969,7 @@ Phase 7 step 1.5 가 final-report MD 한 본을 입력으로 두 view 를 결정
 - billable-equivalent token math와 USD cost estimation을 함께 기록합니다. Anthropic billing ratio(`cache_creation_5m=1.25x`, `cache_creation_1h=2.0x`, `cache_read=0.1x`, `output=5x`)를 반영합니다. transcript 의 `usage.cache_creation.ephemeral_5m_input_tokens` / `ephemeral_1h_input_tokens` 분해가 있으면 분리 집계합니다.
 - 가격표는 `scripts/okstra_token_usage/pricing.py` 에서 중앙 관리합니다. 모델 가격이 바뀌면 거기서 갱신합니다. 가격 매칭에 실패한 모델 id 는 `usageSummary.unmatchedModels` 필드로 사용자에게 노출됩니다 (silent zero 사고 방지).
 - **증분 스캔 캐시 (P6)**: 세션 jsonl 재스캔을 피하기 위해 `$OKSTRA_HOME/cache/token-usage/<transcript-dir>/<sessionId>.json` 에 파일별 byte cursor + 윈도우 적용 전 usage 이벤트 추출본을 보존합니다 (`scripts/okstra_token_usage/cursor.py`). run 윈도우(since/until)는 매 호출 시 이벤트 위에서 재평가하므로 재실행으로 윈도우가 좁아져도 합계는 전체 스캔과 동일합니다. 캐시는 파생 데이터라 식별자 불일치·truncate·손상 시 자동으로 전체 재스캔으로 폴백하며, `okstra-token-usage.py --no-cache` 로 강제 우회할 수 있습니다.
+- **단계 타임라인 (P0 계측)**: 수집기가 lead 세션 jsonl 의 `PROGRESS: phase-*` 체크포인트 라인(agents/SKILL.md "Progress reporting")을 run 윈도우로 스코핑해 추출하고, team-state 에 `phaseTimeline` 블록(`{source, phases: [{phase, firstAt, lastAt, markerCount, wallMsToNext}]}`)으로 기록합니다 (`scripts/okstra_token_usage/collect.py :: phase_timeline`). run 내부 단계별 wall-clock 의 측정 지점이며, `okstra-inspect` time facet 의 "Per-run phase breakdown" 이 소비합니다. 마커가 없는 run 은 `phases: []` 로 측정 불가를 명시합니다.
 
 ## Validators
 

package/docs/kr/cli.md

@@ -384,7 +384,7 @@ scripts/okstra.sh --task-type implementation \
 
 Phase 5.6 의 opt-in critic pass 를 수행할 provider 를 선택합니다. 값은 `off` | `claude` | `codex` | `gemini` 중 하나이며 기본값은 `off` 입니다.
 
-- critic pass 는 convergence(Phase 5.5) 직후 reused-worker 1라운드로 수행됩니다 — discovery / error-analysis / implementation-planning 에서는 coverage gap 탐지, final-verification 에서는 acceptance devil's-advocate 역할입니다. 상세 규약은 `okstra-convergence` skill 의 "Coverage critic pass" / "Acceptance critic pass" 섹션을 따릅니다.
+- critic 디스패치는 convergence(Phase 5.5) 첫 reverify 라운드와 동시에 실행되고(critic 입력은 Round 0 통합 결과로 고정), gap/blocker 검증 1라운드는 convergence 종료 후 Phase 5.6 에서 수행됩니다 — discovery / error-analysis / implementation-planning 에서는 coverage gap 탐지, final-verification 에서는 acceptance devil's-advocate 역할입니다. 상세 규약은 `okstra-convergence` skill 의 "Coverage critic pass" / "Acceptance critic pass" 섹션을 따릅니다.
 - in-session `okstra-run` wizard 의 critic 선택 단계와 동일한 값 공간을 공유합니다. 허용값 검증은 `prepare_task_bundle` 의 `_resolve_model_bindings` 가 수행하며, 그 외 값은 `PrepareError` 로 즉시 거부됩니다.
 
 ### `--approved-plan`

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

@@ -10,6 +10,7 @@
   - [2.4 worker 구조](#24-worker-구조)
 - [3. 성능 병목 가설](#3-성능-병목-가설)
 - [4. 측정 기준](#4-측정-기준)
+  - [4.1 실측 결과 (2026-06-11)](#41-실측-결과-2026-06-11-fontradar-v2-api-dev-9186)
 - [5. 개선 우선순위](#5-개선-우선순위)
   - [P0. Baseline 계측과 용어 정리](#p0-baseline-계측과-용어-정리)
   - [P1. Convergence 재검증 범위 축소](#p1-convergence-재검증-범위-축소)
@@ -98,12 +99,13 @@
 
 | ID | 병목 | 영향도 | 근거 / 확인 위치 | 판정 |
 |---|---|---:|---|---|
-| B1 | Convergence reverify round가 worker 수만큼 추가 dispatch를 만든다 | 높음 | `skills/okstra-convergence/SKILL.md` Round 1-N | 1차 개선 대상 |
-| B2 | analysis worker prompt와 required reading이 길다 | 높음 | `agents/SKILL.md`, `okstra-team-contract`, worker definitions | 별도 prompt diet 작업 |
-| B3 | report-writer가 worker 결과 + convergence + final-report-template을 다시 읽는다 | 중간 | `skills/okstra-report-writer/SKILL.md` | 구조상 필요. 중복 축소만 검토 |
+| B1 | Convergence reverify round가 worker 수만큼 추가 dispatch를 만든다 | 높음 | `skills/okstra-convergence/SKILL.md` Round 1-N | **해소** — P1 queue pruning 구현 + critic 직렬화 병렬화(§4.1 ②) |
+| B2 | analysis worker prompt와 required reading이 길다 | 높음 | `agents/SKILL.md`, `okstra-team-contract`, worker definitions | **대부분 해소** — analysis-packet-primary 실측 22KB/worker(§4.1) |
+| B3 | report-writer가 worker 결과 + convergence + final-report-template을 다시 읽는다 | ~~중간~~ 낮음 | `skills/okstra-report-writer/SKILL.md` | **입력 압축 기각** — 실측상 읽기 1~2분, 생성이 지배(§4.1 ③) |
 | B4 | prepare 단계에서 여러 render/write가 직렬 수행된다 | 낮음~중간 | `scripts/okstra_ctl/run.py` render block | 후순위 |
-| B5 | token usage collector가 session jsonl을 선형 스캔한다 | 낮음~중간 | `scripts/okstra_token_usage/` | run 종료 시 비용. 후순위 |
-| B6 | 단순 작업도 같은 full workflow를 탄다 | 중간 | task-type lifecycle / requirements routing | fast-track 설계 필요 |
+| B5 | token usage collector가 session jsonl을 선형 스캔한다 | 낮음~중간 | `scripts/okstra_token_usage/` | **해소** — P6 증분 캐시 구현 완료 |
+| B6 | 단순 작업도 같은 full workflow를 탄다 | 중간 | task-type lifecycle / requirements routing | fast-track 설계 필요 — 남은 최대 레버 |
+| B7 | report-writer 의 final-report/data.json **생성량 자체**가 크다 (90~140KB) | 높음 | 실측 §4.1 ③ — 생성 8~19분/run | 보고서 계약 슬림화 또는 report-writer 모델 선택 — **사용자 결정 필요** |
 
 확정 전제:
 
@@ -128,6 +130,18 @@ P1 구현 전 최소 fixture:
 2. mixed/unresolved 사례: Round 1 후 일부 finding만 남아 선택적 Round 2가 필요한 run.
 3. worker failure 사례: reverify dispatch 일부가 `timeout`/`error`인 run.
 
+### 4.1 실측 결과 (2026-06-11, fontradar-v2-api dev-9186)
+
+실 run 3개(req-discovery / impl-planning / implementation stage-1)의 산출물 mtime, team-state `phaseTimeline`, report-writer 세션 jsonl 툴콜 타임라인으로 측정했다.
+
+① **run 단계별 wall 분해** — 분석 run 에서 "본 분석"은 wall 의 17~24%에 불과하다. 셋업 4~6분 / 분석 16~24분 / convergence+critic 23분 / report-writer 12~24분.
+
+② **critic 직렬화** — reverify 종료 후에야 critic 이 디스패치되어 런당 6~12분이 직렬로 낭비됐다. critic 입력은 Round 0 통합 결과로 고정이므로 첫 reverify 라운드와 병렬 디스패치로 변경했다 (`skills/okstra-convergence/SKILL.md` §When).
+
+③ **report-writer 는 생성 지배** — 세션 툴콜 실측: 전체 입력(~404KB, 16 files) 읽기는 **1~2분**, data.json 생성(스켈레톤 Write 후 섹션별 Edit 증분 작성)이 **8~19분**, 자체 검증·audit 이 ~3분. 따라서 B3 입력 압축의 wall 절감은 ~1분 수준이라 **기각**. 남는 레버는 출력 측(B7): 보고서 계약 슬림화(품질 trade-off, 사용자 결정) 또는 `--report-writer-model` 하향(기존 knob).
+
+④ **계측 자동화** — Phase 7 수집기가 lead 의 `PROGRESS: phase-*` 마커를 추출해 team-state `phaseTimeline` 으로 영속한다 (`scripts/okstra_token_usage/collect.py :: phase_timeline`). 이후 run 부터 본 섹션의 ①을 수작업 mtime 분석 없이 `/okstra-inspect time` 으로 확인할 수 있다. `okstra context-cost` 의 reportWriter 표면도 실 dispatch 계약(현재 seq + analysis-packet)에 정렬했다.
+
 ## 5. 개선 우선순위
 
 ### P0. Baseline 계측과 용어 정리
@@ -347,8 +361,14 @@ Optional Round 2:
 3. P3 fast-track과 P4 prompt caching은 별도 설계/검증이 필요한 후속 작업으로 둔다.
 4. prepare render 병렬화와 token usage 증분화는 효과가 작거나 종료 단계 비용이므로 P1 이후 병렬 보조 작업으로 처리한다.
 
+**2026-06-11 갱신** — §4.1 실측으로 P0/P1/P6 + critic 병렬화 + phaseTimeline 계측이 완료됐고, B3(report-writer 입력 압축)는 기각됐다. 남은 우선순위는 두 개뿐이며 둘 다 사용자 결정이 선행한다:
+
+1. **B7 — report-writer 출력 측 단축**: 보고서 계약 슬림화(템플릿/스키마 축소, validator 계약 변경 수반) 또는 기본 report-writer 모델 하향. 런당 5~12분 절감 추정.
+2. **B6/P3 — fast-track routing**: 단순 작업의 lifecycle 단축. 승인 게이트 정책 결정 필요.
+
 ### 구현 plan 링크
 
-- P0 + P1: `docs/superpowers/plans/2026-05-14-convergence-queue-pruning.md`
+- P0 + P1: `docs/superpowers/plans/2026-05-14-convergence-queue-pruning.md` (구현 완료 — convergence state v1.2 에 반영)
 - P6: `docs/superpowers/plans/2026-06-10-p6-token-usage-incremental.md` (구현 완료)
-- P2 / P3 / P4 / P5: 미작성 (각 트랙별로 별도 plan 작성 필요)
+- critic 병렬화 + phaseTimeline 계측: plan 없이 직접 구현 (2026-06-11, `CHANGES.md` 해당 항목 참조)
+- P3 / P4 / P5 / B7: 미작성 (각 트랙별로 별도 plan 작성 필요)

package/docs/project-structure-overview.md

@@ -183,6 +183,7 @@ Important modules:
 | `worktree.py`, `worktree_registry.py` | One worktree per task-key, branch registry, sync dirs/files/snapshots |
 | `project_meta.py`, `resolver.py`, `path_resolve.py` | Project/task/run resolution |
 | `clarification_items.py` | Unified §5 clarification table parser and approval blockers |
+| `md_table.py` | Markdown pipe-table escape/split SSOT — `mdcell` 필터(`escape_pipes`)와 `\|` 인식 `split_pipe_row`; renderer·HTML view·validators 공용 |
 | `qa_commands.py` | QA command deny-list validation for plans |
 | `pr_template.py` | PR body template resolution for release-handoff |
 | `report_views.py`, `render_final_report.py`, `final_report_schema.py` | Final-report data.json → Markdown → slim/HTML pipeline |