okstra 0.71.2 → 0.73.0

package/docs/kr/architecture.md

@@ -366,6 +366,15 @@ okstra phase 는 PRD / issue file 을 직접 쓰지 않습니다. 동등한 결
 - 답변 편집과 재실행을 한 번에 처리하려면 `--resume-clarification` 모드를 사용합니다. 자세한 동작은 `### --resume-clarification` 섹션을 참고합니다.
 - **Stage carry-in (`implementation` → 다음 stage)**: 각 `implementation` run 은 `runs/implementation/carry/stage-<N>.json` evidence sidecar 를 남깁니다. 다음 stage 가 실행될 때 이 파일을 자동으로 carry-in 합니다. 어떤 `implementation` run 이 어떤 stage 를 소비했는지는 `runs/implementation-planning/consumers.jsonl` 에 역링크로 누적됩니다.
 
+### Fix cycle (사후 버그 핫픽스 이력)
+
+release-handoff 까지 완료된 task 의 산출물에서 버그가 발견되면, 같은 task-id 에 entry phase (`requirements-discovery` / `error-analysis` / `implementation-planning`) 로 재진입해 고칩니다 — 전용 hotfix task-type 은 없고 phase gate 는 그대로입니다. 이 재진입 run 묶음이 **fix cycle** 이며, SSOT 는 `<task_root>/history/fix-cycles.jsonl` 의 append-only 이벤트 행 (`opened` / `run` / `closed`, 모듈 `scripts/okstra_ctl/fix_cycles.py` 단독 소유) 입니다. entry phase 목록은 `fix_cycles.FIX_CYCLE_ENTRY_PHASES` 한 곳에서만 정의되고 prepare 게이트와 wizard 감지 술어가 공유합니다.
+
+- **진입**: okstra-run wizard 가 완료 task + entry phase 재진입을 감지해 `fix_cycle_confirm` 단계로 확인합니다. CLI 는 `--fix-cycle <yes|no>` (미지정 시 기록하지 않음). `--fix-cycle yes` 는 두 가드를 모두 통과해야 cycle 을 엽니다 — task-type 이 entry phase 이고, manifest 의 `workflow.lastCompletedPhase` 가 `release-handoff` 여야 하며, 위반 시 `PrepareError`. open cycle 은 task 당 동시 1개입니다.
+- **부착**: cycle 이 open 인 동안 같은 task 의 모든 run 이 (이후 `--fix-cycle` 플래그 없이도) `run` 행으로 부착되고, run-manifest / timeline 항목에 `fixCycleId` 가 찍힙니다.
+- **종료**: open cycle 에 release-handoff run 이 부착된 뒤 manifest 의 `workflow.lastCompletedPhase` 가 `release-handoff` 가 되면, 다음 prepare 가 `closed` 행을 lazy-append 합니다.
+- **소비처 (전부 파생 뷰)**: ① 후속 run 의 analysis-packet `## Fix History` 섹션 ② okstra-brief 의 Task Continuity Notes 인용 ③ final-report `## 5.10 Fix History` (run-manifest 에 `fixCycleId` 가 있으면 data.json `fixCycle` 블록을 validator `_validate_fix_cycle` 가 강제) ④ task-manifest `fixCycles` 요약 + task-index / task-catalog 한 줄. 네 소비처 모두 `fix_cycles.summarize()` / `packet_summary()` 파생 뷰만 읽습니다.
+
 ### release-handoff stage-group 모드
 
 `release-handoff` 는 두 모드로 동작합니다 (설계 `docs/superpowers/specs/2026-06-10-stage-group-handoff-design.md`).
@@ -460,7 +469,8 @@ task manifest, task index, instruction-set, runs, history가 이 루트 아래
 │       │   └── errors-<task-type>-<seq>.jsonl        # optional, lead-only writer
 │       └── worker-results/
 └── history/
-    └── timeline.json
+    ├── timeline.json
+    └── fix-cycles.jsonl          # optional, fix cycle 진입 시에만 생성 (append-only)
 ```
 
 실제 디렉터리 세그먼트는 안전한 경로 생성을 위해 slug 형태로 정규화될 수 있습니다.
@@ -486,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)*
@@ -572,6 +582,7 @@ scripts/okstra.sh workflow가 사용하는 project-local Claude assets는 아래
 - `artifacts`
 - `resultContract`
 - `claudeSession`
+- `fixCycles` *(파생 요약 — `{count, openCycleId, latest:{cycle, symptom, targetReport, closedAt}}`; 매 prepare 재계산)*
 
 이 manifest는 아래 목적을 가집니다.
 
@@ -632,6 +643,7 @@ canonical metadata는 항상 `task-manifest.json`을 기준으로 확인합니
 - current run status
 - workflow snapshot
 - team contract
+- `fixCycleId` *(fix cycle 부착 시에만; 없으면 필드 생략)*
 
 ## Timeline contract
 
@@ -651,6 +663,7 @@ canonical metadata는 항상 `task-manifest.json`을 기준으로 확인합니
 - resume command relative path
 - related tasks
 - workflow snapshot
+- `fixCycleId` *(fix cycle 부착 시에만; 없으면 필드 생략)*
 같은 task-type을 다시 실행하면 같은 `runs/<task-type>/` 폴더를 재사용하더라도 `run-manifest-<task-type>-<seq>.json`과 관련 artifact 경로가 per-category sequence suffix(`<task-type>-<seq>`)로 분리되므로 각 실행이 별도 이력으로 누적됩니다. cross-category 식별자는 manifest의 `runDateTimeSegment` ISO timestamp 필드입니다.
 
 ## Claude operating contract
@@ -956,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

@@ -20,6 +20,7 @@
   - [`--resume-clarification`](#--resume-clarification)
   - [`--project-root`](#--project-root)
   - [`--directive`](#--directive)
+  - [`--fix-cycle`](#--fix-cycle)
   - [`--workers`](#--workers)
   - [`--claude-model`](#--claude-model)
   - [`--lead-model`](#--lead-model)
@@ -51,7 +52,7 @@
 기본 명령(첫 진입 / full args):
 
 ```bash
-scripts/okstra.sh [--render-only] [--yes] [--no-plan-verification] --task-type <task-type> [--workers worker1,worker2] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--gemini-model <model>] [--report-writer-model <model>] [--executor claude|codex|gemini] [--critic off|claude|codex|gemini] [--related-tasks taskA,taskB] [--work-category bugfix|feature|refactor|ops|improvement|unknown] [--base-ref <branch|tag|sha>] [--clarification-response <previous-final-report>] [--approved-plan <plan-path>] [--approve] --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>]
+scripts/okstra.sh [--render-only] [--yes] [--no-plan-verification] --task-type <task-type> [--workers worker1,worker2] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--gemini-model <model>] [--report-writer-model <model>] [--executor claude|codex|gemini] [--critic off|claude|codex|gemini] [--related-tasks taskA,taskB] [--work-category bugfix|feature|refactor|ops|improvement|unknown] [--base-ref <branch|tag|sha>] [--clarification-response <previous-final-report>] [--approved-plan <plan-path>] [--approve] --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>] [--fix-cycle <yes|no>]
 ```
 
 후속 phase 단축 형식(기존 task-manifest.json이 존재할 때):
@@ -289,6 +290,11 @@ scripts/okstra.sh --task-type implementation-planning ... \
   --directive "Phase 2개(Part 1 ~4d, Part 2 ~5d, 순차)로 총 ~10d. Gantt 꼭 그려줘 (임계 경로 표시)."
 ```
 
+### `--fix-cycle`
+
+- `--fix-cycle <yes|no>` — release-handoff 까지 완료된 task 에 entry phase (`requirements-discovery` / `error-analysis` / `implementation-planning`) 로 재진입할 때, 이번 재진입을 버그 픽스 사이클로 기록할지 여부. 미지정 시 기록하지 않습니다 (okstra-run wizard 경로는 `fix_cycle_confirm` 단계가 같은 입력을 받습니다).
+- `yes` 는 두 조건을 모두 만족해야 새 cycle 을 엽니다 — task-type 이 entry phase 이고, manifest 의 `workflow.lastCompletedPhase` 가 `release-handoff` 여야 합니다. 둘 중 하나라도 어긋나면 prepare 가 거부합니다. cycle 이 이미 open 이면 같은 task 의 이후 run 은 이 플래그 없이도 자동으로 부착됩니다.
+
 ### `--workers`
 
 이번 run에서 사용할 worker 목록을 직접 지정합니다.
@@ -378,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 작성 필요)