okstra 0.71.2 → 0.72.0

package/docs/superpowers/plans/2026-06-11-fix-cycle.md

@@ -0,0 +1,1290 @@
+# Fix Cycle 구현 계획 (완료된 task 사후 버그 핫픽스 이력)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 완료(release-handoff)된 okstra task 에 재진입하는 버그 핫픽스 run 묶음을 `history/fix-cycles.jsonl` 이벤트 행으로 등록하고, analysis-packet / task-manifest·index·catalog / final-report §5.10 / okstra-brief 네 소비처가 같은 요약을 파생해 읽게 한다.
+
+**Architecture:** SSOT 는 신규 모듈 `scripts/okstra_ctl/fix_cycles.py` 가 단독 소유하는 append-only JSONL(`opened`/`run`/`closed` 행, consumers.jsonl idiom). 진입은 okstra-run wizard 의 `fix_cycle_confirm` 단계(자동 감지 + 확인) 또는 CLI `--fix-cycle yes|no` 플래그이며, 둘 다 `prepare_task_bundle()` 의 `PrepareInputs.fix_cycle` 한 입력으로 수렴한다. 종료는 prepare 시점 lazy-close.
+
+**Tech Stack:** Python 3 (okstra_ctl, pytest), Bash (okstra.sh/cli.sh), Jinja 템플릿 (final-report), JSON Schema (final-report-v1.0).
+
+**Spec:** [docs/superpowers/specs/2026-06-11-fix-cycle-design.md](../specs/2026-06-11-fix-cycle-design.md)
+
+**선행 규칙:** Python 작업 전 `okstra-coding-preflight` 스킬 참조. 커밋 메시지는 Conventional Commits, Claude trailer 금지. `runtime/` 은 절대 직접 수정하지 않는다.
+
+---
+
+### Task 1: `fix_cycles.py` 모듈 (SSOT reader/writer)
+
+**Files:**
+- Modify: `scripts/okstra_ctl/run_context.py` (flock 헬퍼 추출)
+- Create: `scripts/okstra_ctl/fix_cycles.py`
+- Test: `tests/test_okstra_fix_cycles.py`
+
+- [ ] **Step 1: 실패하는 테스트 작성**
+
+`tests/test_okstra_fix_cycles.py` 생성 (conftest 의 `_isolate_okstra_home` autouse fixture 가 자동 적용됨 — [tests/conftest.py:5](../../tests/conftest.py)):
+
+```python
+"""fix_cycles SSOT 모듈 단위 테스트."""
+from pathlib import Path
+
+from okstra_ctl import fix_cycles
+
+
+def _task_root(tmp_path: Path) -> Path:
+    root = tmp_path / ".okstra" / "tasks" / "grp" / "tid"
+    root.mkdir(parents=True)
+    return root
+
+
+def test_read_rows_empty_when_missing(tmp_path):
+    assert fix_cycles.read_rows(_task_root(tmp_path)) == []
+
+
+def test_open_close_lifecycle(tmp_path):
+    root = _task_root(tmp_path)
+    cycle = fix_cycles.append_opened(
+        root, target_report="runs/final-verification/reports/r.md",
+        symptom="결제 금액이 0원으로 저장됨", opened_at="2026-06-11T09:00:00Z")
+    assert cycle == "fc-01"
+    rows = fix_cycles.read_rows(root)
+    assert fix_cycles.open_cycle(rows)["cycle"] == "fc-01"
+
+    fix_cycles.append_closed(
+        root, cycle="fc-01", closed_by="release-handoff",
+        report="runs/release-handoff/reports/r.md",
+        closed_at="2026-06-11T12:00:00Z")
+    rows = fix_cycles.read_rows(root)
+    assert fix_cycles.open_cycle(rows) is None
+
+
+def test_single_open_cycle_append_opened_is_idempotent(tmp_path):
+    root = _task_root(tmp_path)
+    first = fix_cycles.append_opened(
+        root, target_report="a.md", symptom="s", opened_at="t1")
+    second = fix_cycles.append_opened(
+        root, target_report="b.md", symptom="s2", opened_at="t2")
+    assert first == second == "fc-01"
+    assert len(fix_cycles.read_rows(root)) == 1
+
+
+def test_cycle_id_increments_after_close(tmp_path):
+    root = _task_root(tmp_path)
+    fix_cycles.append_opened(root, target_report="a.md", symptom="s",
+                             opened_at="t1")
+    fix_cycles.append_closed(root, cycle="fc-01",
+                             closed_by="release-handoff", report="r.md",
+                             closed_at="t2")
+    assert fix_cycles.append_opened(
+        root, target_report="c.md", symptom="s3", opened_at="t3") == "fc-02"
+
+
+def test_append_run_idempotent_on_run_manifest(tmp_path):
+    root = _task_root(tmp_path)
+    fix_cycles.append_opened(root, target_report="a.md", symptom="s",
+                             opened_at="t1")
+    for _ in range(2):
+        fix_cycles.append_run(
+            root, cycle="fc-01", task_type="error-analysis", run_seq=3,
+            run_manifest="runs/error-analysis/manifests/m-3.json")
+    rows = [r for r in fix_cycles.read_rows(root) if r["event"] == "run"]
+    assert len(rows) == 1
+    assert rows[0]["task_type"] == "error-analysis"
+
+
+def test_append_closed_idempotent(tmp_path):
+    root = _task_root(tmp_path)
+    fix_cycles.append_opened(root, target_report="a.md", symptom="s",
+                             opened_at="t1")
+    for _ in range(2):
+        fix_cycles.append_closed(root, cycle="fc-01",
+                                 closed_by="release-handoff",
+                                 report="r.md", closed_at="t2")
+    rows = [r for r in fix_cycles.read_rows(root) if r["event"] == "closed"]
+    assert len(rows) == 1
+
+
+def test_summarize(tmp_path):
+    root = _task_root(tmp_path)
+    assert fix_cycles.summarize([]) == {
+        "count": 0, "openCycleId": None, "latest": None}
+    fix_cycles.append_opened(root, target_report="a.md",
+                             symptom="증상 한 줄", opened_at="t1")
+    fix_cycles.append_run(root, cycle="fc-01", task_type="error-analysis",
+                          run_seq=1, run_manifest="m.json")
+    summary = fix_cycles.summarize(fix_cycles.read_rows(root))
+    assert summary["count"] == 1
+    assert summary["openCycleId"] == "fc-01"
+    assert summary["latest"]["cycle"] == "fc-01"
+    assert summary["latest"]["symptom"] == "증상 한 줄"
+    assert summary["latest"]["closedAt"] is None
+
+
+def test_packet_summary_renders_markdown(tmp_path):
+    root = _task_root(tmp_path)
+    fix_cycles.append_opened(root, target_report="a.md", symptom="증상",
+                             opened_at="t1")
+    fix_cycles.append_run(root, cycle="fc-01", task_type="error-analysis",
+                          run_seq=2, run_manifest="m.json")
+    text = fix_cycles.packet_summary(fix_cycles.read_rows(root))
+    assert "fc-01" in text
+    assert "증상" in text
+    assert "error-analysis" in text
+    assert "a.md" in text
+
+
+def test_derive_symptom_from_brief():
+    brief = (
+        "---\nid: x\n---\n\n# Brief\n\n## Identity\n\n- key: v\n\n"
+        "## Request Summary\n\n- 결제 모듈이 금액을 0원으로 저장한다\n"
+        "- 추가 설명\n\n## Current Context\n\n- ...\n"
+    )
+    assert fix_cycles.derive_symptom(brief) == "결제 모듈이 금액을 0원으로 저장한다"
+
+
+def test_derive_symptom_missing_section_returns_empty():
+    assert fix_cycles.derive_symptom("# 아무 섹션 없음\n") == ""
+```
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_okstra_fix_cycles.py -v`
+Expected: FAIL — `ModuleNotFoundError`/`ImportError: cannot import name 'fix_cycles'`
+
+- [ ] **Step 3: run_context.py 의 flock 패턴을 공용 헬퍼로 추출**
+
+[run_context.py:106](../../scripts/okstra_ctl/run_context.py) 의 `consumers_mutex` 본문을 제네릭 헬퍼로 추출하고 `consumers_mutex` 는 그 헬퍼를 호출하게 바꾼다 (호출자가 2개가 되므로 추출 — 단일 참조 규칙):
+
+```python
+@contextmanager
+def dir_flock(dir_path: Path, lock_filename: str) -> Iterator[None]:
+    """dir_path 아래 lock_filename 파일 기반 exclusive flock.
+
+    lock 은 보호 대상 파일과 같은 디렉토리에 두어 디렉토리마다 1:1 로
+    격리한다 (마지막 세그먼트만 키로 쓰면 다른 task 의 동일 seq 가 같은
+    lock 을 공유하므로 금지)."""
+    dir_path.mkdir(parents=True, exist_ok=True)
+    path = dir_path / lock_filename
+    path.touch(exist_ok=True)
+    with path.open("r+") as f:
+        fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+
+
+@contextmanager
+def consumers_mutex(plan_run_root: Path) -> Iterator[None]:
+    """plan run-root 별 consumers.jsonl append mutex."""
+    with dir_flock(plan_run_root, ".consumers.lock"):
+        yield
+```
+
+기존 `consumers_mutex` 의 docstring 두 번째 문단(세그먼트 경고)은 `dir_flock` 으로 옮긴다. 기존 데코레이터가 `@contextmanager` 인지 파일 상단 import 를 확인하고 동일하게 맞춘다.
+
+- [ ] **Step 4: `fix_cycles.py` 구현**
+
+`scripts/okstra_ctl/fix_cycles.py` 생성:
+
+```python
+"""Append-only reader/writer for `<task_root>/history/fix-cycles.jsonl`.
+
+완료(release-handoff)된 task 에 재진입하는 버그 핫픽스 run 묶음(fix cycle)의
+SSOT. consumers.jsonl 과 같은 idiom — append-only + dir flock + last-wins 읽기.
+이 모듈이 유일한 reader/writer 이며, 소비처(analysis-packet / manifest /
+final-report / okstra-brief)는 모두 summarize()/packet_summary() 파생 뷰를 쓴다.
+
+행 3종 (event 필드로 구분):
+    {"event":"opened","cycle":"fc-01","target_report":...,"symptom":...,"opened_at":...}
+    {"event":"run","cycle":"fc-01","task_type":...,"run_seq":...,"run_manifest":...}
+    {"event":"closed","cycle":"fc-01","closed_by":...,"report":...,"closed_at":...}
+
+idempotency 키: (cycle, event, run_manifest|None). open cycle 은 task 당 1개.
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .run_context import dir_flock
+
+FIX_CYCLES_FILENAME = "fix-cycles.jsonl"
+_LOCK_FILENAME = ".fix-cycles.lock"
+
+
+def fix_cycles_path(task_root: Path) -> Path:
+    return Path(task_root) / "history" / FIX_CYCLES_FILENAME
+
+
+def read_rows(task_root: Path) -> List[Dict[str, Any]]:
+    p = fix_cycles_path(task_root)
+    if not p.exists():
+        return []
+    out: List[Dict[str, Any]] = []
+    for line in p.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if line:
+            out.append(json.loads(line))
+    return out
+
+
+def open_cycle(rows: List[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """closed 행이 없는 마지막 opened 행. open 은 동시 1개가 불변식."""
+    closed = {r["cycle"] for r in rows if r.get("event") == "closed"}
+    for r in reversed(rows):
+        if r.get("event") == "opened" and r["cycle"] not in closed:
+            return r
+    return None
+
+
+def _next_cycle_id(rows: List[Dict[str, Any]]) -> str:
+    n = sum(1 for r in rows if r.get("event") == "opened")
+    return f"fc-{n + 1:02d}"
+
+
+def append_opened(task_root: Path, *, target_report: str, symptom: str,
+                  opened_at: str) -> str:
+    """새 cycle 을 열고 id 를 반환. open cycle 이 이미 있으면 그 id 반환(멱등)."""
+    history = fix_cycles_path(task_root).parent
+    with dir_flock(history, _LOCK_FILENAME):
+        rows = read_rows(task_root)
+        existing = open_cycle(rows)
+        if existing:
+            return existing["cycle"]
+        cycle = _next_cycle_id(rows)
+        _append_row(task_root, {
+            "event": "opened", "cycle": cycle,
+            "target_report": target_report, "symptom": symptom,
+            "opened_at": opened_at,
+        })
+        return cycle
+
+
+def append_run(task_root: Path, *, cycle: str, task_type: str, run_seq: int,
+               run_manifest: str) -> None:
+    history = fix_cycles_path(task_root).parent
+    with dir_flock(history, _LOCK_FILENAME):
+        for r in read_rows(task_root):
+            if (r.get("event") == "run" and r.get("cycle") == cycle
+                    and r.get("run_manifest") == run_manifest):
+                return
+        _append_row(task_root, {
+            "event": "run", "cycle": cycle, "task_type": task_type,
+            "run_seq": run_seq, "run_manifest": run_manifest,
+        })
+
+
+def append_closed(task_root: Path, *, cycle: str, closed_by: str,
+                  report: str, closed_at: str) -> None:
+    history = fix_cycles_path(task_root).parent
+    with dir_flock(history, _LOCK_FILENAME):
+        for r in read_rows(task_root):
+            if r.get("event") == "closed" and r.get("cycle") == cycle:
+                return
+        _append_row(task_root, {
+            "event": "closed", "cycle": cycle, "closed_by": closed_by,
+            "report": report, "closed_at": closed_at,
+        })
+
+
+def _append_row(task_root: Path, record: Dict[str, Any]) -> None:
+    p = fix_cycles_path(task_root)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    with p.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(record, ensure_ascii=False) + "\n")
+
+
+def summarize(rows: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """소비처 공용 요약: {count, openCycleId, latest:{cycle,symptom,targetReport,closedAt}}."""
+    opened = [r for r in rows if r.get("event") == "opened"]
+    if not opened:
+        return {"count": 0, "openCycleId": None, "latest": None}
+    closed_at = {r["cycle"]: r.get("closed_at")
+                 for r in rows if r.get("event") == "closed"}
+    open_row = open_cycle(rows)
+    latest = opened[-1]
+    return {
+        "count": len(opened),
+        "openCycleId": open_row["cycle"] if open_row else None,
+        "latest": {
+            "cycle": latest["cycle"],
+            "symptom": latest.get("symptom", ""),
+            "targetReport": latest.get("target_report", ""),
+            "closedAt": closed_at.get(latest["cycle"]),
+        },
+    }
+
+
+def packet_summary(rows: List[Dict[str, Any]]) -> str:
+    """analysis-packet 의 `## Fix History` 섹션 본문 (마크다운). 행이 없으면 ''."""
+    opened = [r for r in rows if r.get("event") == "opened"]
+    if not opened:
+        return ""
+    closed = {r["cycle"]: r for r in rows if r.get("event") == "closed"}
+    lines: List[str] = []
+    for o in opened:
+        state = "closed" if o["cycle"] in closed else "open"
+        lines.append(
+            f"- `{o['cycle']}` ({state}) — {o.get('symptom', '')} "
+            f"(target: `{o.get('target_report', '')}`)")
+        for r in rows:
+            if r.get("event") == "run" and r.get("cycle") == o["cycle"]:
+                lines.append(
+                    f"  - run: {r.get('task_type', '')} seq {r.get('run_seq', '')}"
+                    f" (`{r.get('run_manifest', '')}`)")
+    return "\n".join(lines)
+
+
+_REQUEST_SUMMARY_RE = re.compile(
+    r"^## Request Summary\s*$", re.MULTILINE)
+
+
+def derive_symptom(brief_text: str) -> str:
+    """brief 의 `## Request Summary` 첫 비어있지 않은 줄 (불릿 마커 제거)."""
+    m = _REQUEST_SUMMARY_RE.search(brief_text)
+    if not m:
+        return ""
+    for line in brief_text[m.end():].splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        if line.startswith("#"):
+            return ""
+        return line.lstrip("-* ").strip()
+    return ""
+```
+
+- [ ] **Step 5: 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_okstra_fix_cycles.py -v`
+Expected: 전부 PASS
+
+Run: `python3 -m pytest tests/ -x -q -k "consumers or run_context"`
+Expected: PASS (consumers_mutex 리팩터 회귀 없음)
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add scripts/okstra_ctl/fix_cycles.py scripts/okstra_ctl/run_context.py tests/test_okstra_fix_cycles.py
+git commit -m "feat(okstra-ctl): fix-cycles.jsonl SSOT 모듈 추가 (사후 핫픽스 이력)"
+```
+
+---
+
+### Task 2: prepare 배선 — `--fix-cycle` 입력, opened/run 기록, lazy-close
+
+**Files:**
+- Modify: `scripts/okstra_ctl/run.py` (PrepareInputs `:269-313`, prepare_task_bundle `:1935`, argparse `:2258` 부근, PrepareInputs 구성 `:2386`)
+- Test: `tests/test_fix_cycle_prepare.py`
+
+- [ ] **Step 1: 실패하는 테스트 작성**
+
+기존 in-process prepare 테스트 패턴([tests/test_e2e_release_handoff_prepare.py:17](../../tests/test_e2e_release_handoff_prepare.py))을 참고해 `tests/test_fix_cycle_prepare.py` 작성. 먼저 그 파일을 Read 해 project fixture 구성 헬퍼(git init 여부, brief 시드 방식)를 그대로 복사한다. 테스트 본문:
+
+```python
+"""fix-cycle prepare 배선 통합 테스트 (render-only in-process)."""
+import json
+from pathlib import Path
+
+import pytest
+
+from okstra_ctl import fix_cycles
+from okstra_ctl.run import PrepareError, PrepareInputs, prepare_task_bundle
+
+# REPO/프로젝트 시드 헬퍼는 tests/test_e2e_release_handoff_prepare.py 의
+# 것을 차용한다 (Read 후 동일 구조로 작성 — brief 파일, project.json,
+# .okstra 디렉터리, git init).
+
+BRIEF = """## Identity\n\n- task: t\n\n## Request Summary\n\n- 결제 금액 0원 버그\n"""
+
+
+def _seed_done_manifest(task_root: Path) -> None:
+    """release-handoff 까지 끝난 기존 task-manifest 를 시드."""
+    task_root.mkdir(parents=True, exist_ok=True)
+    (task_root / "task-manifest.json").write_text(json.dumps({
+        "workflow": {"lastCompletedPhase": "release-handoff"},
+        "latestReportPath": "runs/final-verification/reports/prev.md",
+    }), encoding="utf-8")
+
+
+def test_fix_cycle_yes_opens_and_attaches(tmp_project):
+    # tmp_project: (project_root, task_root, inputs_factory) — 차용 헬퍼
+    project_root, task_root, make_inputs = tmp_project
+    _seed_done_manifest(task_root)
+    inp = make_inputs(task_type="error-analysis", fix_cycle="yes",
+                      render_only=True)
+    prepare_task_bundle(inp)
+    rows = fix_cycles.read_rows(task_root)
+    events = [r["event"] for r in rows]
+    assert events == ["opened", "run"]
+    assert rows[0]["symptom"] == "결제 금액 0원 버그"
+    assert rows[0]["target_report"] == "runs/final-verification/reports/prev.md"
+
+
+def test_fix_cycle_yes_on_unfinished_task_fails(tmp_project):
+    project_root, task_root, make_inputs = tmp_project
+    # manifest 없음(새 task) 또는 lastCompletedPhase != release-handoff
+    inp = make_inputs(task_type="error-analysis", fix_cycle="yes",
+                      render_only=True)
+    with pytest.raises(PrepareError):
+        prepare_task_bundle(inp)
+
+
+def test_open_cycle_attaches_all_subsequent_runs(tmp_project):
+    project_root, task_root, make_inputs = tmp_project
+    _seed_done_manifest(task_root)
+    prepare_task_bundle(make_inputs(task_type="error-analysis",
+                                    fix_cycle="yes", render_only=True))
+    # fix_cycle 플래그 없이도 open cycle 이면 run 행이 부착된다
+    prepare_task_bundle(make_inputs(task_type="error-analysis",
+                                    fix_cycle="", render_only=True))
+    runs = [r for r in fix_cycles.read_rows(task_root) if r["event"] == "run"]
+    assert len(runs) == 2
+
+
+def test_lazy_close_after_release_handoff_completes(tmp_project):
+    project_root, task_root, make_inputs = tmp_project
+    _seed_done_manifest(task_root)
+    prepare_task_bundle(make_inputs(task_type="error-analysis",
+                                    fix_cycle="yes", render_only=True))
+    # release-handoff run 행을 cycle 에 수동 부착 + manifest 를 다시 done 으로
+    fix_cycles.append_run(task_root, cycle="fc-01",
+                          task_type="release-handoff", run_seq=1,
+                          run_manifest="runs/release-handoff/manifests/m.json")
+    _seed_done_manifest(task_root)  # lastCompletedPhase 를 release-handoff 로 복원
+    prepare_task_bundle(make_inputs(task_type="error-analysis",
+                                    fix_cycle="", render_only=True))
+    rows = fix_cycles.read_rows(task_root)
+    assert any(r["event"] == "closed" and r["cycle"] == "fc-01" for r in rows)
+    # close 이후의 이번 run 은 cycle 에 부착되지 않는다
+    closed_idx = next(i for i, r in enumerate(rows) if r["event"] == "closed")
+    assert all(r["event"] != "run" for r in rows[closed_idx + 1:])
+```
+
+주의: `_seed_done_manifest` 는 prepare 가 manifest 를 재작성하기 전 상태를 흉내 낸다. prepare 후 manifest 의 `lastCompletedPhase` 가 기존값 보존됨은 [render.py:897](../../scripts/okstra_ctl/render.py) 의 기존 동작이므로 두 번째 시드는 안전망일 뿐이다. 실제 작성 시 차용 헬퍼의 시그니처에 맞춰 `tmp_project` fixture 를 이 파일 안에 정의한다.
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_fix_cycle_prepare.py -v`
+Expected: FAIL — `TypeError: ... unexpected keyword argument 'fix_cycle'`
+
+- [ ] **Step 3: PrepareInputs 필드 + argparse 추가**
+
+[run.py:313](../../scripts/okstra_ctl/run.py) 의 `plan_verification_enabled` 아래에:
+
+```python
+    fix_cycle: str = ""           # "" | "yes" | "no" — done task 재진입의 fix-cycle 기록 여부
+```
+
+argparse([run.py:2258](../../scripts/okstra_ctl/run.py) `--directive` 부근)에:
+
+```python
+    p.add_argument("--fix-cycle", default="", choices=["", "yes", "no"])
+```
+
+PrepareInputs 구성부([run.py:2394](../../scripts/okstra_ctl/run.py) `directive=args.directive` 부근)에:
+
+```python
+        fix_cycle=args.fix_cycle,
+```
+
+- [ ] **Step 4: `_record_fix_cycle_events` 헬퍼 구현 + 호출 배선**
+
+`prepare_task_bundle` 내부, ctx 가 완성된 뒤 `_finalize_status_and_render_manifests(...)` 호출([run.py:1885](../../scripts/okstra_ctl/run.py) 의 헬퍼를 부르는 지점) **직전**에 호출을 끼운다. 먼저 `grep -n "_finalize_status_and_render_manifests(inp" scripts/okstra_ctl/run.py` 로 호출 지점을, `grep -n '"RUN_SEQ"\|RUN_MANIFEST_PATH\|TASK_MANIFEST_PATH' scripts/okstra_ctl/run.py | head -20` 로 ctx 토큰의 정확한 이름을 확인한다 (run seq 토큰이 `RUN_SEQ` 가 아니면 실제 이름으로 치환).
+
+```python
+def _record_fix_cycle_events(inp: PrepareInputs, ctx: dict) -> str:
+    """fix-cycles.jsonl 의 lazy-close → opened → run 기록. cycle id 반환.
+
+    - lazy-close: open cycle 에 release-handoff run 이 부착됐고 manifest 의
+      lastCompletedPhase 가 release-handoff 면 닫는다.
+    - opened: --fix-cycle yes 일 때만. 감지 조건(완료 task + entry phase)
+      미충족이면 PrepareError.
+    - run: open cycle 이 있으면 이번 run 을 무조건 부착.
+    """
+    from datetime import datetime, timezone
+
+    from . import fix_cycles
+
+    task_root = Path(ctx["TASK_MANIFEST_PATH"]).parent
+    manifest_path = Path(ctx["TASK_MANIFEST_PATH"])
+    existing: dict = {}
+    if manifest_path.exists():
+        try:
+            existing = json.loads(manifest_path.read_text(encoding="utf-8"))
+        except Exception:
+            existing = {}
+    workflow = existing.get("workflow") or {}
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    rows = fix_cycles.read_rows(task_root)
+    open_c = fix_cycles.open_cycle(rows)
+
+    # lazy-close
+    if open_c and workflow.get("lastCompletedPhase") == "release-handoff":
+        handoff_attached = any(
+            r.get("event") == "run" and r.get("cycle") == open_c["cycle"]
+            and r.get("task_type") == "release-handoff" for r in rows)
+        if handoff_attached:
+            fix_cycles.append_closed(
+                task_root, cycle=open_c["cycle"],
+                closed_by="release-handoff",
+                report=str(existing.get("latestReportPath", "")),
+                closed_at=now)
+            open_c = None
+
+    # opened
+    if inp.fix_cycle == "yes" and open_c is None:
+        entry_phases = ("requirements-discovery", "error-analysis",
+                        "implementation-planning")
+        if inp.task_type not in entry_phases:
+            raise PrepareError(
+                f"--fix-cycle yes 는 entry phase({', '.join(entry_phases)})"
+                f"에서만 허용됩니다: {inp.task_type}")
+        if workflow.get("lastCompletedPhase") != "release-handoff":
+            raise PrepareError(
+                "--fix-cycle yes 는 release-handoff 까지 완료된 task 에만 "
+                "허용됩니다 (workflow.lastCompletedPhase 확인)")
+        brief_text = Path(inp.brief_path).read_text(encoding="utf-8")
+        cycle = fix_cycles.append_opened(
+            task_root,
+            target_report=str(existing.get("latestReportPath", "")),
+            symptom=fix_cycles.derive_symptom(brief_text), opened_at=now)
+        rows = fix_cycles.read_rows(task_root)
+        open_c = fix_cycles.open_cycle(rows)
+
+    # run 부착
+    if open_c is not None:
+        run_manifest_rel = os.path.relpath(
+            ctx["RUN_MANIFEST_PATH"], str(Path(inp.project_root)))
+        fix_cycles.append_run(
+            task_root, cycle=open_c["cycle"], task_type=inp.task_type,
+            run_seq=int(ctx.get("RUN_SEQ", 0) or 0),
+            run_manifest=run_manifest_rel)
+        return open_c["cycle"]
+    return ""
+```
+
+호출 배선 (`_finalize_status_and_render_manifests` 직전):
+
+```python
+    ctx["FIX_CYCLE_ID"] = _record_fix_cycle_events(inp, ctx)
+```
+
+`PrepareError` 클래스는 run.py 에 이미 존재한다 (`grep -n "class PrepareError" scripts/okstra_ctl/run.py` 로 위치 확인). `import json`, `import os` 는 파일 상단에 이미 있는지 확인 후 없으면 추가.
+
+- [ ] **Step 5: 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_fix_cycle_prepare.py tests/test_okstra_fix_cycles.py -v`
+Expected: 전부 PASS
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add scripts/okstra_ctl/run.py tests/test_fix_cycle_prepare.py
+git commit -m "feat(okstra-ctl): prepare 에 --fix-cycle 배선 (opened/run 기록 + lazy-close)"
+```
+
+---
+
+### Task 3: run-manifest / timeline `fixCycleId` + manifest·index·catalog 요약
+
+**Files:**
+- Modify: `scripts/okstra_ctl/render.py` (`render_run_manifest:1112`, `render_timeline:1253`, `render_task_manifest:864`, `render_task_index:1345`, `render_task_catalog_discovery:496`)
+- Modify: `templates/project-docs/task-index.template.md`
+- Test: `tests/test_fix_cycle_render.py`
+
+- [ ] **Step 1: 실패하는 테스트 작성**
+
+`tests/test_fix_cycle_render.py`. render 함수들은 `(path, ctx)` 시그니처이므로 최소 ctx 로 직접 호출한다. 기존 render 단위 테스트(`grep -rln "render_run_manifest\|render_task_manifest" tests/ | head -3` 로 찾아 Read)의 최소 ctx 구성을 차용해 다음을 단언:
+
+```python
+"""fixCycleId / fixCycles 파생 뷰 렌더 테스트."""
+import json
+from pathlib import Path
+
+from okstra_ctl import fix_cycles
+from okstra_ctl.render import render_run_manifest, render_task_manifest
+
+
+def test_run_manifest_includes_fix_cycle_id(tmp_path, minimal_run_ctx):
+    ctx = dict(minimal_run_ctx)
+    ctx["FIX_CYCLE_ID"] = "fc-01"
+    out = tmp_path / "run-manifest.json"
+    render_run_manifest(str(out), ctx)
+    payload = json.loads(out.read_text(encoding="utf-8"))
+    assert payload["fixCycleId"] == "fc-01"
+
+
+def test_run_manifest_omits_field_without_cycle(tmp_path, minimal_run_ctx):
+    out = tmp_path / "run-manifest.json"
+    render_run_manifest(str(out), dict(minimal_run_ctx))
+    payload = json.loads(out.read_text(encoding="utf-8"))
+    assert "fixCycleId" not in payload
+
+
+def test_task_manifest_includes_fix_cycles_summary(tmp_path, minimal_task_ctx):
+    task_root = tmp_path / "task"
+    fix_cycles.append_opened(task_root, target_report="a.md",
+                             symptom="s", opened_at="t1")
+    out = task_root / "task-manifest.json"
+    render_task_manifest(str(out), dict(minimal_task_ctx))
+    payload = json.loads(out.read_text(encoding="utf-8"))
+    assert payload["fixCycles"]["count"] == 1
+    assert payload["fixCycles"]["openCycleId"] == "fc-01"
+```
+
+`minimal_run_ctx` / `minimal_task_ctx` fixture 는 차용한 기존 테스트의 ctx dict 를 이 파일의 `@pytest.fixture` 로 옮겨 정의한다 (기존 테스트가 fixture 없이 inline dict 면 동일 dict 복사).
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_fix_cycle_render.py -v`
+Expected: FAIL — `KeyError: 'fixCycleId'` / `KeyError: 'fixCycles'`
+
+- [ ] **Step 3: render.py 4곳 수정**
+
+(a) `render_run_manifest` — payload dict 조립 직후, `_write_json` 호출 전에 ([render.py:1184](../../scripts/okstra_ctl/render.py) `concurrentRun` 블록과 같은 위치 부근):
+
+```python
+    if ctx.get("FIX_CYCLE_ID"):
+        payload["fixCycleId"] = ctx["FIX_CYCLE_ID"]
+```
+
+(b) `render_timeline` — run entry dict([render.py:1290](../../scripts/okstra_ctl/render.py) `filtered.append({...})`)에 같은 패턴:
+
+```python
+    entry = { ... 기존 키 ... }
+    if ctx.get("FIX_CYCLE_ID"):
+        entry["fixCycleId"] = ctx["FIX_CYCLE_ID"]
+    filtered.append(entry)
+```
+
+(c) `render_task_manifest` — payload([render.py:915-1052](../../scripts/okstra_ctl/render.py)) 에 파생 요약 추가. 파일 상단에 `from . import fix_cycles` 추가 후:
+
+```python
+        "fixCycles": fix_cycles.summarize(
+            fix_cycles.read_rows(Path(manifest_path).parent)),
+```
+
+(d) `render_task_catalog_discovery` — entry dict([render.py:547-601](../../scripts/okstra_ctl/render.py))에 각 task 의 요약 추가 (manifest 를 이미 읽고 있으므로 manifest 의 `fixCycles` 필드를 그대로 복사):
+
+```python
+            "fixCycles": manifest.get("fixCycles") or {
+                "count": 0, "openCycleId": None, "latest": None},
+```
+
+(e) `render_task_index` — mapping dict([render.py:1405-1504](../../scripts/okstra_ctl/render.py))에 토큰 추가:
+
+```python
+        "FIX_CYCLES_SUMMARY": _fix_cycles_index_line(manifest),
+```
+
+같은 파일에 헬퍼:
+
+```python
+def _fix_cycles_index_line(manifest: dict) -> str:
+    fc = manifest.get("fixCycles") or {}
+    if not fc.get("count"):
+        return "none"
+    latest = fc.get("latest") or {}
+    state = f"open: {fc['openCycleId']}" if fc.get("openCycleId") else "all closed"
+    return f"{fc['count']} cycle(s), {state} — latest `{latest.get('cycle', '')}`: {latest.get('symptom', '')}"
+```
+
+- [ ] **Step 4: task-index 템플릿에 토큰 추가**
+
+`templates/project-docs/task-index.template.md` 를 Read 해 기존 `{{TOKEN}}` 나열 형식을 확인하고, 상태 요약 라인들(latest run / current phase 부근)에 한 줄 추가:
+
+```markdown
+- Fix cycles: {{FIX_CYCLES_SUMMARY}}
+```
+
+- [ ] **Step 5: 테스트 통과 + 회귀 확인**
+
+Run: `python3 -m pytest tests/test_fix_cycle_render.py -v && python3 -m pytest tests/ -q -k "render or manifest or timeline or catalog"`
+Expected: 전부 PASS
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add scripts/okstra_ctl/render.py templates/project-docs/task-index.template.md tests/test_fix_cycle_render.py
+git commit -m "feat(okstra-ctl): run-manifest/timeline fixCycleId + manifest/index/catalog fixCycles 요약"
+```
+
+---
+
+### Task 4: analysis-packet `## Fix History` 주입
+
+**Files:**
+- Modify: `scripts/okstra_ctl/analysis_packet.py` (`build_analysis_packet:44`)
+- Modify: `scripts/okstra_ctl/run.py` (호출부 `:1784`)
+- Test: `tests/test_fix_cycle_packet.py`
+
+- [ ] **Step 1: 실패하는 테스트 작성**
+
+`tests/test_fix_cycle_packet.py` — 기존 packet 테스트(`grep -ln "build_analysis_packet" tests/` 로 찾아 Read, 입력 파일 시드 방식 차용):
+
+```python
+"""analysis-packet Fix History 블록 테스트."""
+from okstra_ctl.analysis_packet import build_analysis_packet
+
+
+def test_packet_includes_fix_history_when_text_given(packet_inputs):
+    packet = build_analysis_packet(
+        **packet_inputs,
+        fix_history_text="- `fc-01` (open) — 증상 (target: `a.md`)")
+    assert "## Fix History" in packet
+    assert "fc-01" in packet
+
+
+def test_packet_omits_fix_history_without_text(packet_inputs):
+    packet = build_analysis_packet(**packet_inputs, fix_history_text="")
+    assert "## Fix History" not in packet
+```
+
+`packet_inputs` fixture 는 차용한 기존 테스트의 필수 인자 dict (brief/profile/reference 파일 tmp_path 시드 포함).
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_fix_cycle_packet.py -v`
+Expected: FAIL — `TypeError: ... unexpected keyword argument 'fix_history_text'`
+
+- [ ] **Step 3: 구현**
+
+[analysis_packet.py:44](../../scripts/okstra_ctl/analysis_packet.py) 시그니처에 `fix_history_text: str = ""` 키워드 인자 추가. 조립부([analysis_packet.py:73](../../scripts/okstra_ctl/analysis_packet.py) `_reference_block` 다음, `_clarification_block` 앞)에:
+
+```python
+    parts += _fix_history_block(fix_history_text)
+```
+
+`_clarification_block`([analysis_packet.py:161-169](../../scripts/okstra_ctl/analysis_packet.py)) 과 같은 조건부 블록 패턴으로:
+
+```python
+def _fix_history_block(fix_history_text: str) -> list[str]:
+    if not fix_history_text.strip():
+        return []
+    return [
+        "",
+        "## Fix History",
+        "",
+        "Past bug-fix cycles registered on this task. Treat the open cycle's",
+        "symptom as a prior-defect signal when analysing.",
+        "",
+        fix_history_text,
+        "",
+    ]
+```
+
+호출부 [run.py:1784](../../scripts/okstra_ctl/run.py) 에 인자 추가 (호출 시점에 task_root 가 스코프에 있는지 확인하고, 없으면 `Path(ctx["TASK_MANIFEST_PATH"]).parent` 사용):
+
+```python
+        fix_history_text=fix_cycles.packet_summary(
+            fix_cycles.read_rows(Path(ctx["TASK_MANIFEST_PATH"]).parent)),
+```
+
+주의: packet 빌드가 Task 2 의 `_record_fix_cycle_events` 호출보다 먼저면 이번 run 의 `run` 행이 packet 에 안 보이는데, 그건 의도된 동작(이력은 과거분)이다 — 다만 이번 run 에서 새로 open 되는 cycle 은 packet 에 보여야 하므로, packet 빌드 시점이 `_record_fix_cycle_events` **이후**가 되도록 호출 순서를 확인하고, 아니라면 `_record_fix_cycle_events` 호출을 packet 빌드 앞으로 이동한다 (둘 다 ctx 완성 이후라면 순서 교환은 안전).
+
+- [ ] **Step 4: 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_fix_cycle_packet.py tests/test_fix_cycle_prepare.py -v`
+Expected: 전부 PASS
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/analysis_packet.py scripts/okstra_ctl/run.py tests/test_fix_cycle_packet.py
+git commit -m "feat(okstra-ctl): analysis-packet 에 Fix History 섹션 주입"
+```
+
+---
+
+### Task 5: wizard `fix_cycle_confirm` 단계
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py` (상수 `:271` 부근, WizardState/_FIELD_DEFAULTS `:2962` 부근, STEPS `:2857` 부근, `render_args:3074`)
+- Modify: `prompts/wizard/prompts.ko.json` (`branch_confirm:170-183` 옆)
+- Test: `tests/test_wizard_fix_cycle_confirm.py`
+
+- [ ] **Step 1: 실패하는 테스트 작성**
+
+기존 wizard 테스트 패턴(`tests/test_wizard_approve_plan_confirm.py` 를 Read 해 state 구성·step 진행 헬퍼 차용) 으로 `tests/test_wizard_fix_cycle_confirm.py`:
+
+```python
+"""wizard fix_cycle_confirm 단계 테스트."""
+import json
+from pathlib import Path
+
+from okstra_ctl import wizard
+
+
+def _seed_done_task(project_root: Path, group: str, tid: str) -> None:
+    task_root = project_root / ".okstra" / "tasks" / group / tid
+    task_root.mkdir(parents=True)
+    (task_root / "task-manifest.json").write_text(json.dumps({
+        "workflow": {"lastCompletedPhase": "release-handoff"},
+    }), encoding="utf-8")
+
+
+def test_step_appears_for_done_task_entry_phase(wizard_state_factory, tmp_path):
+    # wizard_state_factory: 차용 헬퍼 — identity 단계까지 채운 WizardState
+    state = wizard_state_factory(task_type="error-analysis",
+                                 task_group="grp", task_id="tid")
+    _seed_done_task(Path(state.project_root), "grp", "tid")
+    prompt = wizard.next_prompt(state)
+    assert prompt.step == "fix_cycle_confirm"
+    values = [o.value for o in prompt.options]
+    assert values == ["yes", "no", "abort"]
+
+
+def test_step_skipped_for_new_task(wizard_state_factory):
+    state = wizard_state_factory(task_type="error-analysis",
+                                 task_group="grp", task_id="new-tid")
+    prompt = wizard.next_prompt(state)
+    assert prompt.step != "fix_cycle_confirm"
+
+
+def test_step_skipped_for_non_entry_phase(wizard_state_factory, tmp_path):
+    state = wizard_state_factory(task_type="implementation",
+                                 task_group="grp", task_id="tid")
+    _seed_done_task(Path(state.project_root), "grp", "tid")
+    prompt = wizard.next_prompt(state)
+    assert prompt.step != "fix_cycle_confirm"
+
+
+def test_render_args_carries_fix_cycle(wizard_state_factory, tmp_path):
+    state = wizard_state_factory(task_type="error-analysis",
+                                 task_group="grp", task_id="tid")
+    _seed_done_task(Path(state.project_root), "grp", "tid")
+    state.fix_cycle = "yes"
+    state.confirmed = True
+    args = wizard.render_args(state)
+    assert args["fix-cycle"] == "yes"
+```
+
+`wizard_state_factory` 는 차용한 기존 테스트의 state 구성 코드를 fixture 로 정리한 것 (project_root=tmp_path, identity 필드·brief_path·base_ref·use_defaults 등 confirm 직전까지 채움). slugify 가 적용된 segment 경로(`grp`/`tid` 는 이미 slug-safe 값이라 동일)를 쓴다.
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_wizard_fix_cycle_confirm.py -v`
+Expected: FAIL — `AttributeError: 'WizardState' object has no attribute 'fix_cycle'` 또는 step 미출현 assert 실패
+
+- [ ] **Step 3: prompts.ko.json 에 step 문구 추가**
+
+[prompts.ko.json:183](../../prompts/wizard/prompts.ko.json) `branch_confirm` 블록 뒤에:
+
+```json
+"fix_cycle_confirm": {
+  "label": "이 task 는 release-handoff 까지 완료된 task 입니다. 이번 재진입을 기존 산출물에 대한 버그 픽스 사이클로 기록할까요?",
+  "options": {
+    "yes": "버그 픽스 사이클로 기록 (추천)",
+    "no": "일반 후속 작업 (기록 안 함)",
+    "abort": "중단"
+  },
+  "echo_template": "fix-cycle: {value}"
+},
+```
+
+- [ ] **Step 4: wizard.py 구현**
+
+(a) 상수([wizard.py:271](../../scripts/okstra_ctl/wizard.py) `S_BRANCH_CONFIRM` 옆):
+
+```python
+S_FIX_CYCLE_CONFIRM = "fix_cycle_confirm"
+```
+
+(b) `WizardState` dataclass 의 `branch_confirmed` 필드([wizard.py:379](../../scripts/okstra_ctl/wizard.py)) 옆에:
+
+```python
+    fix_cycle: str = ""  # "" | "yes" | "no" — done task 재진입의 fix-cycle 기록
+```
+
+`_FIELD_DEFAULTS`([wizard.py:2962](../../scripts/okstra_ctl/wizard.py)) 의 `"branch_confirmed": None` 옆에 `"fix_cycle": "",` 추가.
+
+(c) 감지 술어 (`_branch_confirm_required` 부근에 배치):
+
+```python
+_FIX_CYCLE_ENTRY_PHASES = ("requirements-discovery", "error-analysis",
+                           "implementation-planning")
+
+
+def _fix_cycle_confirm_required(state: WizardState) -> bool:
+    """완료(release-handoff) task 에 entry phase 로 재진입할 때만 묻는다."""
+    if state.task_type not in _FIX_CYCLE_ENTRY_PHASES:
+        return False
+    manifest = (Path(state.project_root) / ".okstra" / "tasks"
+                / slugify(state.task_group) / slugify(state.task_id)
+                / "task-manifest.json")
+    if not manifest.is_file():
+        return False
+    try:
+        workflow = json.loads(
+            manifest.read_text(encoding="utf-8")).get("workflow") or {}
+    except Exception:
+        return False
+    if workflow.get("lastCompletedPhase") != "release-handoff":
+        return False
+    from . import fix_cycles
+    return fix_cycles.open_cycle(
+        fix_cycles.read_rows(manifest.parent)) is None
+```
+
+`slugify` 는 wizard.py 가 이미 import 하는지 확인(`grep -n "slugify" scripts/okstra_ctl/wizard.py`)하고 없으면 `from .ids import slugify` 추가. 단, manifest 디렉터리 세그먼트가 slugify 적용 경로인지 raw 인지 `grep -n "tasks\" /\|tasks/" scripts/okstra_ctl/paths.py` 로 paths 모듈의 실제 계산을 확인해 동일하게 맞춘다 (paths 에 task_root 계산 헬퍼가 있으면 그것을 import 해 재사용 — 경로 규칙 중복 금지).
+
+(d) build/submit (`_build_branch_confirm:2427` 패턴):
+
+```python
+def _build_fix_cycle_confirm(state: WizardState) -> Prompt:
+    raw = _load_wizard_root(state.workspace_root)["steps"]["fix_cycle_confirm"]
+    t = _p(state.workspace_root, "fix_cycle_confirm")
+    return Prompt(
+        step=S_FIX_CYCLE_CONFIRM, kind="pick", text=t["label"],
+        options=[
+            Option(value="yes", label=raw["options"]["yes"]),
+            Option(value="no", label=raw["options"]["no"]),
+            Option(value="abort", label=raw["options"]["abort"]),
+        ])
+
+
+def _submit_fix_cycle_confirm(state: WizardState, value: str) -> Optional[str]:
+    v = value.strip().lower()
+    if v == "abort":
+        state.aborted = True
+        return None
+    if v not in ("yes", "no"):
+        return _msg(state.workspace_root, "errors", "invalid_option")
+    state.fix_cycle = v
+    return None
+```
+
+`Prompt`/`Option` 생성자 시그니처와 `_p`/`_msg` 반환 형태는 `_build_branch_confirm`([wizard.py:2427-2461](../../scripts/okstra_ctl/wizard.py))을 Read 해 동일하게 맞춘다 (위 코드는 형태 골격 — label 보간 키, abort 처리 방식, invalid 메시지 키를 기존 step 과 byte-level 로 일치시킬 것).
+
+(e) STEPS 등록 — `S_BRANCH_CONFIRM` 항목([wizard.py:2857](../../scripts/okstra_ctl/wizard.py)) **바로 앞**에:
+
+```python
+    Step(S_FIX_CYCLE_CONFIRM,
+         applies=lambda s: (_ready_for_confirm(s)
+                            and _fix_cycle_confirm_required(s)
+                            and not s.fix_cycle),
+         build=_build_fix_cycle_confirm, submit=_submit_fix_cycle_confirm,
+         owns=("fix_cycle",)),
+```
+
+그리고 `S_BRANCH_CONFIRM` 과 `S_CONFIRM` 의 `applies` 에 선행 조건 추가 — 두 람다 각각에 `and (not _fix_cycle_confirm_required(s) or bool(s.fix_cycle))` 을 덧붙여 fix-cycle 질문이 먼저 소진되게 한다.
+
+(f) `render_args`([wizard.py:3074](../../scripts/okstra_ctl/wizard.py)) 반환 dict 에:
+
+```python
+        "fix-cycle": state.fix_cycle,
+```
+
+- [ ] **Step 5: render-bundle 인자 패스스루**
+
+`okstra wizard` 의 render-args 출력을 소비하는 쪽이 `--fix-cycle` 을 python argparse 까지 전달해야 한다. `grep -n "directive" src/render-bundle.mjs src/wizard.mjs` 로 기존 인자 전달 방식을 확인하고, `directive` 와 동일한 패턴으로 `fix-cycle` → `--fix-cycle` 매핑을 추가한다 (usage 문자열 [src/render-bundle.mjs:16](../../src/render-bundle.mjs) 포함).
+
+- [ ] **Step 6: 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_wizard_fix_cycle_confirm.py tests/test_okstra_ctl_wizard.py -v`
+Expected: 전부 PASS (기존 wizard 회귀 포함)
+
+- [ ] **Step 7: 커밋**
+
+```bash
+git add scripts/okstra_ctl/wizard.py prompts/wizard/prompts.ko.json src/render-bundle.mjs tests/test_wizard_fix_cycle_confirm.py
+git commit -m "feat(wizard): done task 재진입 시 fix_cycle_confirm 단계 추가"
+```
+
+---
+
+### Task 6: bash CLI 플래그 배선
+
+**Files:**
+- Modify: `scripts/lib/okstra/cli.sh` (`--directive` 파싱 `:141` 옆 + usage `:207`)
+- Modify: `scripts/okstra.sh` (PY_ARGS 조립 `:110` 옆)
+
+- [ ] **Step 1: cli.sh 파싱 추가**
+
+[cli.sh:141](../../scripts/lib/okstra/cli.sh) `--directive` case 옆에:
+
+```bash
+      --fix-cycle)
+        FIX_CYCLE="$(require_option_value --fix-cycle "${2-}")"
+        shift 2
+        ;;
+```
+
+(shift 처리는 기존 case 들과 동일 형태로 — 실제 파일의 `--directive` case 전체를 보고 복제.) usage 문자열([cli.sh:207](../../scripts/lib/okstra/cli.sh))에 `[--fix-cycle <yes|no>]` 추가. 변수 초기화부가 있으면 `FIX_CYCLE=""` 추가.
+
+- [ ] **Step 2: okstra.sh PY_ARGS 조립**
+
+[okstra.sh:110](../../scripts/okstra.sh) 옆에:
+
+```bash
+[[ -n "${FIX_CYCLE-}" ]] && PY_ARGS+=(--fix-cycle "$FIX_CYCLE")
+```
+
+- [ ] **Step 3: 스모크 확인**
+
+Run: `bash -n scripts/okstra.sh scripts/lib/okstra/cli.sh`
+Expected: 문법 오류 없음 (exit 0)
+
+Run: `python3 -m okstra_ctl.run --help 2>&1 | grep fix-cycle` (PYTHONPATH=scripts 필요 시 `PYTHONPATH=scripts python3 -m okstra_ctl.run --help`)
+Expected: `--fix-cycle {,yes,no}` 노출
+
+- [ ] **Step 4: 커밋**
+
+```bash
+git add scripts/lib/okstra/cli.sh scripts/okstra.sh
+git commit -m "feat(cli): okstra.sh 에 --fix-cycle 플래그 배선"
+```
+
+---
+
+### Task 7: final-report `## 5.10 Fix History` — 템플릿 + schema + validator + report-writer 지시
+
+**Files:**
+- Modify: `templates/reports/final-report.template.md` (`:559` §5.9 endif 뒤)
+- Modify: `schemas/final-report-v1.0.schema.json`
+- Modify: `validators/validate-run.py`
+- Modify: `skills/okstra-report-writer/SKILL.md`
+- Test: `tests/test_fix_cycle_report_contract.py`
+
+- [ ] **Step 1: 실패하는 테스트 작성**
+
+validator 강제 규칙: **run-manifest 에 `fixCycleId` 가 있으면 data.json 에 `fixCycle` 블록이 있어야 하고 `fixCycle.cycle == fixCycleId`**. 기존 validate-run 테스트(`grep -ln "validate-run\|validate_run" tests/ | head -3` 로 찾아 Read, fixture 구성 차용)로 `tests/test_fix_cycle_report_contract.py`:
+
+```python
+"""run-manifest fixCycleId ↔ data.json fixCycle 계약 테스트."""
+# 차용한 기존 validate-run 테스트의 로딩 방식(importlib 또는 subprocess)을
+# 그대로 사용해 _validate_fix_cycle 를 호출한다.
+
+
+def test_missing_fix_cycle_block_fails(validator_module):
+    failures = []
+    validator_module._validate_fix_cycle(
+        run_manifest={"fixCycleId": "fc-01"}, data={}, failures=failures)
+    assert failures and "fixCycle" in failures[0]
+
+
+def test_mismatched_cycle_id_fails(validator_module):
+    failures = []
+    validator_module._validate_fix_cycle(
+        run_manifest={"fixCycleId": "fc-01"},
+        data={"fixCycle": {"cycle": "fc-02"}}, failures=failures)
+    assert failures
+
+
+def test_matching_cycle_passes(validator_module):
+    failures = []
+    validator_module._validate_fix_cycle(
+        run_manifest={"fixCycleId": "fc-01"},
+        data={"fixCycle": {"cycle": "fc-01", "targetReport": "a.md",
+                            "symptom": "s", "runs": []}},
+        failures=failures)
+    assert failures == []
+
+
+def test_no_cycle_no_requirement(validator_module):
+    failures = []
+    validator_module._validate_fix_cycle(
+        run_manifest={}, data={}, failures=failures)
+    assert failures == []
+```
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_fix_cycle_report_contract.py -v`
+Expected: FAIL — `AttributeError: ... no attribute '_validate_fix_cycle'`
+
+- [ ] **Step 3: validate-run.py 에 검사 추가**
+
+`_validate_improvement_discovery`([validate-run.py:1716](../../validators/validate-run.py)) 스타일로:
+
+```python
+def _validate_fix_cycle(run_manifest: dict, data: dict, failures: list) -> None:
+    """run-manifest 의 fixCycleId 가 있으면 data.json 의 fixCycle 블록을 강제."""
+    cycle_id = (run_manifest or {}).get("fixCycleId", "")
+    if not cycle_id:
+        return
+    block = (data or {}).get("fixCycle")
+    if not isinstance(block, dict):
+        failures.append(
+            f"fix-cycle: run-manifest fixCycleId={cycle_id} 인데 data.json 에 "
+            "fixCycle 블록이 없습니다")
+        return
+    if block.get("cycle") != cycle_id:
+        failures.append(
+            f"fix-cycle: data.json fixCycle.cycle={block.get('cycle')!r} 가 "
+            f"run-manifest fixCycleId={cycle_id!r} 와 다릅니다")
+```
+
+호출 지점: task_type 분기([validate-run.py:2184](../../validators/validate-run.py)) **바깥**(task-type 무관 공통 검사 자리)에 — run-manifest 와 data.json 둘 다 로드된 위치를 `grep -n "run_manifest\b" validators/validate-run.py | head` 로 찾아 그 직후에 `_validate_fix_cycle(run_manifest, data, failures)` 호출을 추가한다 (data.json 변수명도 실제 이름으로 맞춤).
+
+- [ ] **Step 4: schema 에 optional `fixCycle` 블록 추가**
+
+`schemas/final-report-v1.0.schema.json` 의 최상위 `properties` 에 (taskType 무관 optional — `allOf` required 강제는 두지 않는다, 강제는 Step 3 의 validator 가 담당):
+
+```json
+"fixCycle": {
+  "type": "object",
+  "description": "RENDER_IF fixCycle present — 이 run 이 속한 사후 버그 픽스 사이클",
+  "required": ["cycle", "targetReport", "symptom"],
+  "properties": {
+    "cycle": { "type": "string", "pattern": "^fc-[0-9]{2,}$" },
+    "targetReport": { "type": "string" },
+    "symptom": { "type": "string" },
+    "runs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["taskType", "runSeq"],
+        "properties": {
+          "taskType": { "type": "string" },
+          "runSeq": { "type": "integer" },
+          "runManifest": { "type": "string" }
+        }
+      }
+    }
+  }
+}
+```
+
+- [ ] **Step 5: 템플릿에 §5.10 추가**
+
+[final-report.template.md:559](../../templates/reports/final-report.template.md) §5.9 `{% endif %}` 바로 뒤에 (5.x 의 taskType 게이트와 달리 데이터 존재 게이트 — fix cycle 은 task-type 무관):
+
+```jinja
+{% if fixCycle %}
+## 5.10 Fix History
+
+> This run belongs to a post-release bug-fix cycle registered in `history/fix-cycles.jsonl`.
+
+- Cycle: `{{ fixCycle.cycle }}` — {{ fixCycle.symptom }}
+- Target report: `{{ fixCycle.targetReport }}`
+{% if fixCycle.runs %}
+- Runs in this cycle so far:
+{% for r in fixCycle.runs %}
+  - {{ r.taskType }} seq {{ r.runSeq }}{% if r.runManifest %} (`{{ r.runManifest }}`){% endif %}
+{% endfor %}
+{% endif %}
+{% endif %}
+```
+
+렌더 데이터 전달 확인: `grep -n "fixCycle\|def render" scripts/okstra_ctl/render_final_report.py | head` 로 data.json 루트가 템플릿 컨텍스트로 통째로 전달되는지 확인 — 통째 전달이면 추가 작업 없음, 명시 키 매핑이면 `fixCycle` 키를 매핑에 추가.
+
+- [ ] **Step 6: report-writer 지시 추가**
+
+`skills/okstra-report-writer/SKILL.md` 를 Read 해 data.json 작성 규칙 섹션을 찾고 한 항목 추가:
+
+```markdown
+- run-manifest 에 `fixCycleId` 가 있으면 data.json 에 `fixCycle` 블록(cycle / targetReport / symptom / runs)을 채운다. 값은 task root 의 `history/fix-cycles.jsonl` 에서 읽는다 — validator 가 누락·불일치를 거부한다.
+```
+
+- [ ] **Step 7: 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_fix_cycle_report_contract.py -v && python3 -m pytest tests/ -q -k "schema or validate"`
+Expected: 전부 PASS
+
+- [ ] **Step 8: 커밋**
+
+```bash
+git add templates/reports/final-report.template.md schemas/final-report-v1.0.schema.json validators/validate-run.py skills/okstra-report-writer/SKILL.md tests/test_fix_cycle_report_contract.py
+git commit -m "feat(report): final-report 5.10 Fix History 섹션 + fixCycle 계약 강제"
+```
+
+---
+
+### Task 8: okstra-brief 인용 지시
+
+**Files:**
+- Modify: `skills/okstra-brief/SKILL.md` (Step 3a `:426-438`, Step 4)
+
+- [ ] **Step 1: Step 3a 자산 목록에 추가**
+
+[SKILL.md:431-433](../../skills/okstra-brief/SKILL.md) okstra-internal 자산 목록(glossary/decisions)에 항목 추가:
+
+```markdown
+3. Fix history (when the brief targets an existing task): `<PROJECT_ROOT>/.okstra/tasks/<task-group>/<task-id>/history/fix-cycles.jsonl` — read every `opened`/`closed` row.
+```
+
+- [ ] **Step 2: Step 4 의 Task Continuity Notes 채움 규칙에 추가**
+
+Step 4([SKILL.md:485](../../skills/okstra-brief/SKILL.md)) 의 REQUIRED 섹션 채움 규칙 본문을 Read 해 형식을 확인하고, Task Continuity Notes 관련 지시에 추가:
+
+```markdown
+- If the target task's `history/fix-cycles.jsonl` exists, cite each cycle in `Task Continuity Notes` as one line — `fix-cycle fc-NN (open|closed): <symptom> (target: <target_report>)`. An open cycle means the new brief continues a bug-fix in progress; say so explicitly.
+```
+
+- [ ] **Step 3: 커밋**
+
+```bash
+git add skills/okstra-brief/SKILL.md
+git commit -m "feat(skills/okstra-brief): brief 생성 시 fix-cycles 이력 인용 지시"
+```
+
+---
+
+### Task 9: 문서 + 빌드 + 전체 검증
+
+**Files:**
+- Modify: `docs/kr/architecture.md` (Phase 간 정보 전달 `:362` 뒤, Storage model 트리 `:428`, Task manifest contract `:541`, Run manifest `:614`, Timeline `:640`)
+- Modify: `docs/kr/cli.md`
+- Modify: `CHANGES.md`
+
+- [ ] **Step 1: architecture.md 갱신 (전부 한국어)**
+
+(a) `### Phase 간 정보 전달`([architecture.md:362](../../docs/kr/architecture.md)) 뒤에 새 절:
+
+```markdown
+### 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` 단독 소유) 이다.
+
+- **진입**: okstra-run wizard 가 완료 task + entry phase 재진입을 감지해 `fix_cycle_confirm` 단계로 확인한다. CLI 는 `--fix-cycle <yes|no>` (미지정 시 기록하지 않음). open cycle 은 task 당 동시 1개.
+- **부착**: cycle 이 open 인 동안 같은 task 의 모든 run 이 `run` 행으로 부착되고, run-manifest / timeline 항목에 `fixCycleId` 가 찍힌다.
+- **종료**: release-handoff run 이 cycle 에 부착된 뒤 `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 가 강제) ④ task-manifest `fixCycles` 요약 + task-index / task-catalog 한 줄.
+```
+
+(b) Storage model 의 task root 트리([architecture.md:428](../../docs/kr/architecture.md))에서 `history/` 아래 `fix-cycles.jsonl` 추가 (트리에 history 가 안 보이면 `timeline.json` 이 표기된 위치를 찾아 그 옆에). (c) Task manifest contract 필드 목록에 `fixCycles` 추가. (d) Run manifest / Timeline contract 항목에 `fixCycleId` (fix cycle 부착 시) 추가.
+
+- [ ] **Step 2: cli.md 에 `--fix-cycle` 추가**
+
+`docs/kr/cli.md` 를 Read 해 플래그 표/목록 형식을 확인하고 동일 형식으로:
+
+```markdown
+- `--fix-cycle <yes|no>` — release-handoff 까지 완료된 task 에 entry phase 로 재진입할 때, 이번 재진입을 버그 픽스 사이클로 기록할지 여부. 미지정 시 기록하지 않음 (okstra-run wizard 경로는 `fix_cycle_confirm` 단계가 같은 입력을 받음).
+```
+
+- [ ] **Step 3: CHANGES.md 항목 추가**
+
+`## 2026-06-11` 섹션(이미 존재, [CHANGES.md:5](../../CHANGES.md))에 기존 항목 형식대로:
+
+```markdown
+### feat(okstra-ctl/wizard/report): 완료 task 사후 버그 핫픽스를 fix cycle 로 등록 — brief/final-report 가 이력 인지
+
+- **배경**: release-handoff 까지 끝난 task 의 산출물에서 버그가 발견돼 같은 task-id 로 재진입해도, 그 run 들이 "기존 산출물의 버그 픽스"라는 사실이 어디에도 1급 레코드로 남지 않아 이후 brief / final-report / task 탐색에서 이력이 보이지 않았다.
+- **해결**: `<task_root>/history/fix-cycles.jsonl` (append-only `opened`/`run`/`closed` 행, `scripts/okstra_ctl/fix_cycles.py` 단독 소유) 를 SSOT 로 신설. okstra-run wizard 가 완료 task 재진입을 감지해 `fix_cycle_confirm` 으로 확인하고(CLI `--fix-cycle <yes|no>`), open cycle 동안 모든 run 이 부착되며 release-handoff 완료 후 lazy-close 된다. analysis-packet `## Fix History` / okstra-brief Task Continuity Notes 인용 / final-report `## 5.10 Fix History` (validator 강제) / task-manifest·index·catalog 요약 네 곳이 같은 파생 요약을 읽는다.
+- 사용자 영향: 다음 release + `npx -y okstra@latest install` 후, 완료된 task 에 버그 픽스로 재진입하면 wizard 가 기록 여부를 묻고, 이후 같은 task 의 워커 입력·brief·최종 보고서·task 목록에서 해당 버그 픽스 이력이 자동으로 보인다. 기존 완료 task 의 과거 이력은 소급 생성되지 않는다.
+```
+
+- [ ] **Step 4: 빌드 + 전체 테스트 + validator**
+
+```bash
+npm run build
+python3 -m pytest tests/ -q
+bash validators/validate-workflow.sh
+node bin/okstra --version
+```
+
+Expected: build 성공, 전체 suite PASS, validator PASS, 버전 출력.
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add docs/kr/architecture.md docs/kr/cli.md CHANGES.md
+git commit -m "docs(kr): fix cycle 이력 계약 문서화 + CHANGES 항목"
+```