okstra 0.71.1 → 0.72.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 형태로 정규화될 수 있습니다.
@@ -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

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 목록을 직접 지정합니다.