okstra 0.71.2 → 0.72.0

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

@@ -0,0 +1,94 @@
+# Fix Cycle — 완료된 task 의 사후 버그 핫픽스 이력 설계
+
+- 날짜: 2026-06-11
+- 상태: 설계 승인 대기
+- 배경: okstra 로 완료(release-handoff 까지)한 task 의 산출물에서 이후 버그가 발견되는 경우, 같은 task-id 위에서 핫픽스를 수행하고 그 수정 이력을 1급 레코드로 등록하며, 이후 brief / final-report / task 브라우징에서 해당 이력이 인지되어야 한다.
+
+## 결정 요약
+
+| 결정 지점 | 선택 |
+|---|---|
+| lifecycle 형태 | 기존 phase 재진입 (error-analysis → planning → implementation → …) + 이력 계층만 신설. 전용 hotfix task-type 없음 |
+| 진입 식별 | 자동 감지 + okstra-run wizard 확인 단계 (`fix_cycle_confirm`), CLI 는 `--fix-cycle <yes|no>` |
+| 이력 SSOT | `<task_root>/history/fix-cycles.jsonl` append-only 이벤트 행 (consumers.jsonl idiom) |
+| 소비처 | ① 후속 run 의 analysis-packet ② okstra-brief 인용 ③ final-report `## 5.10 Fix History` ④ task-manifest / task-index / task-catalog 요약 |
+
+## 1. 개념 모델
+
+**fix cycle** 은 "완료된 task 의 기존 산출물에서 발견된 버그 1건을 고치는 재진입 run 묶음"이다.
+
+- id: `fc-<NN>` (task 내 단조 증가, 2자리 zero-pad).
+- 상태: `open` → `closed` 둘뿐. 이벤트 행으로 표현하며 별도 mutable 상태 파일은 두지 않는다.
+- 대상 링크: 픽스 대상인 이전 final-report 의 project-relative 경로 (`target_report`). open 시점 task-manifest 의 `latestReportPath` 에서 채운다.
+- 증상 한 줄(`symptom`): 재진입 brief 의 `Request Summary` 첫 문장에서 파생한다. 사용자 추가 입력 없음.
+- 동시 open cycle 은 task 당 1개로 제한한다. 두 번째 버그는 첫 cycle 종료 후에 연다 (KISS).
+
+## 2. SSOT 파일 계약 — `history/fix-cycles.jsonl`
+
+위치: `<task_root>/history/fix-cycles.jsonl`. reader/writer 는 신규 모듈 `scripts/okstra_ctl/fix_cycles.py` 단 한 곳이다. [consumers.py](../../../scripts/okstra_ctl/consumers.py) 의 idiom 을 그대로 따른다 — append-only + mutex(`run_context` 의 mutex 헬퍼 재사용) + last-wins 읽기.
+
+이벤트 행 3종:
+
+```jsonl
+{"event":"opened","cycle":"fc-01","target_report":"<상대경로>","symptom":"...","opened_at":"<ISO>"}
+{"event":"run","cycle":"fc-01","task_type":"error-analysis","run_seq":3,"run_manifest":"<상대경로>"}
+{"event":"closed","cycle":"fc-01","closed_by":"release-handoff","report":"<상대경로>","closed_at":"<ISO>"}
+```
+
+- idempotency 키: `(cycle, event, run_manifest|None)` 튜플. 같은 행은 중복 append 되지 않는다.
+- 경로 필드는 run-manifest 와 같은 규칙으로 프로젝트 루트 기준 상대경로만 저장한다.
+- 파생 읽기 API: `open_cycle(rows) -> dict|None`, `summarize(rows) -> dict` (소비처들이 공유). `summarize` 의 `latest` 는 `{cycle, symptom, targetReport, closedAt}`.
+
+## 3. 진입: 자동 감지 + wizard 확인
+
+감지 조건 (prepare 시점):
+
+- 대상 task 의 `workflow.lastCompletedPhase == "release-handoff"` (done 계열 상태), **그리고**
+- 이번 run 의 task-type 이 분석 entry phase (`requirements-discovery` / `error-analysis` / `implementation-planning`) 중 하나일 때.
+- `improvement-discovery` sidetrack 은 제외.
+
+확인 UI:
+
+- okstra-run wizard 에 `fix_cycle_confirm` 단계 신설 — [wizard.py](../../../scripts/okstra_ctl/wizard.py) 의 `branch_confirm` 과 같은 step-registry 패턴 (`required` 술어 = 감지 조건, `owns` = `fix_cycle_confirmed`).
+- 옵션: "버그 픽스 사이클로 기록 (추천)" / "일반 후속 작업" / "직접 입력" — okstra-run 프롬프트 3-옵션 picker 규칙 준수.
+- CLI 비대화 경로(okstra.sh / Node CLI)는 `--fix-cycle <yes|no>` 플래그를 [prepare_task_bundle()](../../../scripts/okstra_ctl/run.py) 입력(`PrepareInputs`)으로 전달한다. 플래그가 주어지면 wizard 단계는 건너뛴다. 세 entry-point 모두 `prepare_task_bundle` 로 수렴하는 단일 참조 규칙을 유지하며, 환경 변수는 사용하지 않는다.
+
+확인되면 prepare 가 `opened` 행을 기록한다.
+
+## 4. run 부착과 종료
+
+- cycle 이 `open` 인 동안 같은 task 에서 도는 **모든** run 의 prepare 가 `run` 행을 append 한다 (task-type 불문 — 핫픽스 사이클의 implementation / final-verification / release-handoff 포함).
+- run-manifest 와 timeline 항목에 `fixCycleId` 필드를 추가한다 (open cycle 없으면 필드 생략).
+- 종료: release-handoff 결과가 기록되어 workflow 가 `done-or-follow-up` 에 도달하는 시점에 `closed` 행을 append 한다 ([workflow.py](../../../scripts/okstra_ctl/workflow.py) 의 `DEFAULT_NEXT_PHASE`). final-verification `accepted` 만으로는 닫지 않는다 — 아직 release 가 나가지 않은 상태이기 때문.
+
+## 5. 소비처 4곳 — 전부 파생 뷰
+
+쓰기 1곳(`fix_cycles.py`), 읽기 N곳 원칙. 모든 소비처는 `fix_cycles.summarize()` 가 만든 같은 요약을 사용한다.
+
+1. **analysis-packet**: [analysis_packet.py](../../../scripts/okstra_ctl/analysis_packet.py) 의 `build_analysis_packet()` 이 fix-cycles.jsonl 존재 시 `## Fix History` 섹션을 packet 에 주입한다 — open cycle 상세(대상 보고서·증상·부착 run 목록) + closed cycle 한 줄 목록. lead / worker 가 분석 입력으로 받는다.
+2. **task-manifest / task-index / task-catalog**: manifest 에 파생 요약 필드 `fixCycles` (`{count, openCycleId|null, latest: {cycle, symptom, targetReport, closedAt}}`), task-index 와 `.okstra/discovery/task-catalog.json` 항목에 같은 요약 1줄. manifest/index 작성 경로([render.py](../../../scripts/okstra_ctl/render.py))에서 함께 갱신한다.
+3. **final-report**: [final-report.template.md](../../../templates/reports/final-report.template.md) 에 조건부 `## 5.10 Fix History` 섹션 신설 (5.4~5.9 사용 중 확인). fix cycle 에 부착된 run 의 보고서에 cycle id · 대상 보고서 · 증상 · cycle 내 선행 run 목록이 들어간다. `final_report_schema.py` 에 대응 필드를 추가한다.
+4. **okstra-brief**: [skills/okstra-brief/SKILL.md](../../../skills/okstra-brief/SKILL.md) Step 3 (domain alignment scan) 에 "대상 task 의 `history/fix-cycles.jsonl` 이 존재하면 `summarize` 요약을 읽어 brief 의 `Task Continuity Notes` 에 인용" 지시를 추가한다.
+
+## 6. 강제 지점 (선언 ≠ 강제)
+
+| 계약 | 강제 위치 |
+|---|---|
+| 행 스키마 · idempotency · 단일 open cycle | `fix_cycles.py` 코드 + `tests/test_okstra_fix_cycles.py` |
+| `## 5.10 Fix History` 섹션 형태 | 기존 report validator 경로 (`validators/`) 에 검사 추가 |
+| wizard 단계 · `--fix-cycle` 플래그 | 기존 wizard / prepare 단위 테스트 패턴으로 커버 |
+| 감지 조건 (done + entry phase) | `prepare_task_bundle` 단위 테스트 |
+
+## 7. 문서
+
+- `docs/kr/architecture.md` — "Phase 간 정보 전달" 인근에 "Fix cycle (사후 버그 핫픽스 이력)" 절 추가, storage model 트리에 `history/fix-cycles.jsonl` 반영.
+- `docs/kr/cli.md` — `--fix-cycle` 플래그.
+- `CHANGES.md` — `사용자 영향:` 라인 포함 항목 추가.
+- 전부 한국어.
+
+## 비목표
+
+- 전용 hotfix task-type / fast path 신설 (phase gate 우회 없음).
+- task 당 동시 다중 open cycle.
+- 기존 timeline.json / run-manifest 의 구조 변경 (`fixCycleId` 필드 1개 추가 외).
+- 과거 완료 task 의 이력 소급 backfill.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.71.2",
+  "version": "0.72.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.71.2",
-  "builtAt": "2026-06-11T04:23:08.954Z",
+  "package": "0.72.0",
+  "builtAt": "2026-06-11T07:01:57.638Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/bin/lib/okstra/cli.sh

@@ -142,6 +142,10 @@ while [[ $# -gt 0 ]]; do
       DIRECTIVE="$(require_option_value --directive "${2-}")"
       shift 2
       ;;
+    --fix-cycle)
+      FIX_CYCLE="$(require_option_value --fix-cycle "${2-}")"
+      shift 2
+      ;;
     --clarification-response)
       CLARIFICATION_RESPONSE_PATH="$(require_option_value --clarification-response "${2-}")"
       shift 2
@@ -204,7 +208,7 @@ while [[ $# -gt 0 ]]; do
           printf '  hint: did you mean --task-id?\n' >&2
           ;;
       esac
-      printf '  valid options: --render-only --resume-clarification --yes --workers --lead-model --claude-model --codex-model --gemini-model --report-writer-model --related-tasks --task-type --project-id --project-root --task-group --task-id --task-brief --directive --clarification-response --approved-plan --approve --implementation-option --stage --qa-waiver --no-plan-verification -h|--help\n' >&2
+      printf '  valid options: --render-only --resume-clarification --yes --workers --lead-model --claude-model --codex-model --gemini-model --report-writer-model --related-tasks --task-type --project-id --project-root --task-group --task-id --task-brief --directive --fix-cycle --clarification-response --approved-plan --approve --implementation-option --stage --qa-waiver --no-plan-verification -h|--help\n' >&2
       usage
       exit 1
       ;;

package/runtime/bin/lib/okstra/globals.sh

@@ -37,6 +37,7 @@ TASK_KEY_INPUT=""
 TASK_KEY=""
 ANALYSIS_PROFILE=""
 DIRECTIVE=""
+FIX_CYCLE=""
 CLARIFICATION_RESPONSE_PATH=""
 APPROVED_PLAN_PATH=""
 APPROVE_PLAN_ACK="false"

package/runtime/bin/lib/okstra/usage.sh

@@ -3,7 +3,7 @@
 usage() {
   cat >&2 <<USAGE_EOF
 usage:
-  $DISPLAY_COMMAND_NAME [--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] --project-id <project-id> [--project-root <path>] --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>]
+  $DISPLAY_COMMAND_NAME [--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] --project-id <project-id> [--project-root <path>] --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>] [--fix-cycle <yes|no>]
 
 summary:
   $DISPLAY_TOOL_NAME prepares a task-keyed instruction bundle for Claude Code and launches an interactive Claude session by default.
@@ -32,6 +32,11 @@ optional arguments:
                        inside instruction-set/analysis-material.md. Lead, workers, and skills (e.g. okstra-schedule)
                        may treat this as a hard hint that overrides default heuristics. Use to express intent
                        like "render a Gantt even with single XL task" or "emphasize rollout risk".
+  --fix-cycle <yes|no> When re-entering an entry phase (requirements-discovery / error-analysis /
+                       implementation-planning) on a task that already completed through
+                       release-handoff, decide whether to record this work as a bug-fix cycle.
+                       'yes' opens a new cycle and attaches this run to it; 'no' or omitted records
+                       nothing.
   --clarification-response
                        Low-level path argument. Carries an edited final-report.md from a prior
                        requirements-discovery or error-analysis run into this run as Section 0

package/runtime/bin/okstra.sh

@@ -108,6 +108,7 @@ PY_ARGS=(
   --task-brief "$BRIEF_PATH"
 )
 [[ -n "${DIRECTIVE-}" ]] && PY_ARGS+=(--directive "$DIRECTIVE")
+[[ -n "${FIX_CYCLE-}" ]] && PY_ARGS+=(--fix-cycle "$FIX_CYCLE")
 [[ -n "${WORKERS_OVERRIDE-}" ]] && PY_ARGS+=(--workers "$WORKERS_OVERRIDE")
 [[ -n "${LEAD_MODEL_OVERRIDE-}" ]] && PY_ARGS+=(--lead-model "$LEAD_MODEL_OVERRIDE")
 [[ -n "${CLAUDE_MODEL_OVERRIDE-}" ]] && PY_ARGS+=(--claude-model "$CLAUDE_MODEL_OVERRIDE")

package/runtime/prompts/wizard/prompts.ko.json

@@ -181,6 +181,15 @@
       "options": { "proceed": "진행", "edit": "base-ref 다시 고르기", "abort": "중단" },
       "echo_template": "branch-confirm: {value}"
     },
+    "fix_cycle_confirm": {
+      "label": "이 task 는 release-handoff 까지 완료된 task 입니다. 이번 재진입을 기존 산출물에 대한 버그 픽스 사이클로 기록할까요?",
+      "options": {
+        "yes": "버그 픽스 사이클로 기록 (추천)",
+        "no": "일반 후속 작업 (기록 안 함)",
+        "abort": "중단"
+      },
+      "echo_template": "fix-cycle: {value}"
+    },
     "base_ref_text": {
       "label": "base ref 를 입력해주세요 (branch, tag, 또는 short/full SHA)",
       "echo_template": "base-ref: {value}"

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -51,6 +51,7 @@ def build_analysis_packet(
     clarification_response_path: Path | None,
     directive: str,
     instruction_set_relative_path: str,
+    fix_history_text: str = "",
 ) -> str:
     """Return the primary compact input for Claude/Codex/Gemini analysers."""
     brief_text = task_brief_path.read_text(encoding="utf-8")
@@ -71,6 +72,7 @@ def build_analysis_packet(
     parts.extend(_brief_block(brief_text))
     parts.extend(_profile_block(task_type, profile_text))
     parts.extend(_reference_block(reference_text))
+    parts.extend(_fix_history_block(fix_history_text))
     parts.extend(_clarification_block(clarification_text))
     parts.extend(_directive_block(directive))
     return "\n".join(part.rstrip() for part in parts).rstrip() + "\n"
@@ -158,6 +160,21 @@ def _reference_block(reference_text: str) -> list[str]:
     return ["", "## Reference Expectations", "", body]
 
 
+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,
+        "",
+    ]
+
+
 def _clarification_block(clarification_text: str) -> list[str]:
     if not clarification_text.strip():
         return []

package/runtime/python/okstra_ctl/fix_cycles.py

@@ -0,0 +1,172 @@
+"""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"
+
+# 완료(release-handoff) task 에 fix-cycle 로 재진입할 수 있는 entry phase 들.
+# prepare(run.py) 의 게이트와 wizard 의 감지 술어가 공유하는 SSOT.
+FIX_CYCLE_ENTRY_PHASES = (
+    "requirements-discovery", "error-analysis", "implementation-planning")
+
+
+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 ""

package/runtime/python/okstra_ctl/render.py

@@ -27,6 +27,7 @@ from okstra_project.dirs import OKSTRA_DIR_NAME, project_json_path
 # phase 시퀀스 / 기본 next-phase 매핑의 SSOT 는 workflow 모듈이다. 과거
 # render_task_manifest 가 동일한 리스트/딕셔너리를 로컬에 중복 정의했는데,
 # 이는 silent drift 위험이 있어 SSOT import 로 통합한다.
+from . import fix_cycles
 from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
 
 
@@ -597,6 +598,8 @@ def render_task_catalog_discovery(output_path: str, ctx: dict) -> None:
                 "latestResumeCommandPath": s(manifest, "latestResumeCommandPath")
                 or s(latest_run, "resumeCommandPath"),
                 "historyTimelinePath": timeline_relative or rel(timeline_path),
+                "fixCycles": manifest.get("fixCycles")
+                or {"count": 0, "openCycleId": None, "latest": None},
             }
         )
     entries.sort(
@@ -945,6 +948,9 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
         "latestReportPath": latest_report_relative,
         "latestResumeCommandPath": latest_resume_command_relative,
         "teamStatePath": latest_team_state_relative,
+        "fixCycles": fix_cycles.summarize(
+            fix_cycles.read_rows(Path(manifest_path).parent)
+        ),
         "workflow": {
             "phaseSequence": PHASE_SEQUENCE,
             "currentPhase": current_phase,
@@ -1247,6 +1253,8 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "renderOnly": ctx.get("RENDER_ONLY", ""),
         "createdAt": ctx.get("RUN_TIMESTAMP_ISO", ""),
     }
+    if ctx.get("FIX_CYCLE_ID"):
+        payload["fixCycleId"] = ctx["FIX_CYCLE_ID"]
     _write_json(Path(run_manifest_path), payload)
 
 
@@ -1287,8 +1295,7 @@ def render_timeline(timeline_path: str, ctx: dict) -> None:
         else {}
     )
     workflow = workflow or {}
-    filtered.append(
-        {
+    entry = {
             "runTimestamp": ctx.get("RUN_TIMESTAMP_ISO", ""),
             "runDirectoryPath": ctx.get("RUN_DIR_RELATIVE_PATH", ""),
             "runManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
@@ -1329,8 +1336,10 @@ def render_timeline(timeline_path: str, ctx: dict) -> None:
                 "routingStatus": workflow.get("routingStatus", ""),
                 "lastSafeCheckpoint": workflow.get("lastSafeCheckpoint", {}),
             },
-        }
-    )
+    }
+    if ctx.get("FIX_CYCLE_ID"):
+        entry["fixCycleId"] = ctx["FIX_CYCLE_ID"]
+    filtered.append(entry)
     payload = {
         "schemaVersion": "1.0",
         "projectId": ctx.get("PROJECT_ID", ""),
@@ -1342,6 +1351,20 @@ def render_timeline(timeline_path: str, ctx: dict) -> None:
     _write_json(path, payload)
 
 
+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.get('openCycleId')}" if fc.get("openCycleId") else "all closed"
+    )
+    return (
+        f"{fc.get('count')} cycle(s), {state} — "
+        f"latest `{latest.get('cycle', '')}`: {latest.get('symptom', '')}"
+    )
+
+
 def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
     template = Path(template_path).read_text(encoding="utf-8")
     task_manifest_path = Path(ctx["TASK_MANIFEST_PATH"])
@@ -1501,6 +1524,7 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
         ),
         "{{WORKFLOW_PHASE_STATE_LINES}}": "\n".join(phase_state_lines),
         "{{WORKFLOW_LAST_SAFE_CHECKPOINT_LINES}}": "\n".join(checkpoint_lines),
+        "{{FIX_CYCLES_SUMMARY}}": _fix_cycles_index_line(task_manifest),
     }
     fm_ctx = dict(ctx)
     fm_ctx.setdefault("DOC_TYPE", _doc_type_from_template_path(template_path))

package/runtime/python/okstra_ctl/run.py

@@ -28,6 +28,7 @@ from pathlib import Path
 
 from okstra_project import project_json_path, upsert_project_json
 from okstra_project.state import slugify
+from . import fix_cycles
 from .analysis_packet import build_analysis_packet
 from .clarification_items import scan_approval_gate
 from .qa_commands import format_errors as _format_qa_errors, validate_qa_commands
@@ -311,6 +312,9 @@ class PrepareInputs:
     # Only meaningful for `--task-type implementation-planning`; the manifest
     # records the value for other phases too to keep the schema stable.
     plan_verification_enabled: bool = True
+    # "" | "yes" | "no" — done(release-handoff) task 재진입을 fix-cycle 로
+    # 기록할지의 사용자 의사. "yes" 면 새 cycle 을 열고 이번 run 을 부착한다.
+    fix_cycle: str = ""
 
 
 @dataclass
@@ -1793,6 +1797,8 @@ def _write_instruction_set_sources(
         ),
         directive=inp.directive,
         instruction_set_relative_path=ctx["INSTRUCTION_SET_RELATIVE_PATH"],
+        fix_history_text=fix_cycles.packet_summary(
+            fix_cycles.read_rows(Path(ctx["TASK_MANIFEST_PATH"]).parent)),
     )
     (instruction_set / "analysis-packet.md").write_text(packet, encoding="utf-8")
     return instruction_set
@@ -1882,6 +1888,77 @@ def _persist_run_inputs(
     )
 
 
+def _read_existing_manifest(manifest_path: Path) -> dict:
+    if not manifest_path.exists():
+        return {}
+    try:
+        return json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _maybe_open_fix_cycle(inp: PrepareInputs, task_root: Path, existing: dict,
+                          now: str):
+    """--fix-cycle yes 검증 후 새 cycle 을 연다. 부적격이면 PrepareError."""
+    if inp.task_type not in fix_cycles.FIX_CYCLE_ENTRY_PHASES:
+        raise PrepareError(
+            "--fix-cycle yes 는 entry phase("
+            f"{', '.join(fix_cycles.FIX_CYCLE_ENTRY_PHASES)})에서만 허용됩니다: "
+            f"{inp.task_type}")
+    workflow = existing.get("workflow") or {}
+    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")
+    fix_cycles.append_opened(
+        task_root, target_report=str(existing.get("latestReportPath", "")),
+        symptom=fix_cycles.derive_symptom(brief_text), opened_at=now)
+    return fix_cycles.open_cycle(fix_cycles.read_rows(task_root))
+
+
+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 면 닫는다. manifest 는 prepare 가
+      이번 run 으로 재작성하기 *전* 값이어야 하므로 finalize 직전에 호출한다.
+    - opened: --fix-cycle yes 일 때만. 완료 task + entry phase 미충족이면
+      PrepareError.
+    - run: open cycle 이 있으면 이번 run 을 무조건 부착.
+    """
+    task_root = Path(ctx["TASK_MANIFEST_PATH"]).parent
+    existing = _read_existing_manifest(Path(ctx["TASK_MANIFEST_PATH"]))
+    workflow = existing.get("workflow") or {}
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    open_c = fix_cycles.open_cycle(fix_cycles.read_rows(task_root))
+
+    if open_c and workflow.get("lastCompletedPhase") == "release-handoff":
+        rows = fix_cycles.read_rows(task_root)
+        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
+
+    if inp.fix_cycle == "yes" and open_c is None:
+        open_c = _maybe_open_fix_cycle(inp, task_root, existing, now)
+
+    if open_c is None:
+        return ""
+    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_MANIFESTS_SEQ", 0) or 0),
+        run_manifest=run_manifest_rel)
+    return open_c["cycle"]
+
+
 def _finalize_status_and_render_manifests(
     inp: PrepareInputs, ctx: dict, task_index_template: Path
 ) -> None:
@@ -2183,6 +2260,13 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         prompt_seq=ctx["RUN_PROMPTS_SEQ"],
     )
 
+    # ---- fix-cycle 기록 (manifest 재작성 전 디스크 값으로 lazy-close 판정) ----
+    # instruction-set 빌드보다 *앞*에서 호출해 이번 run 에서 새로 open 되는
+    # cycle 도 analysis-packet 의 Fix History 에 보이도록 한다. finalize 가
+    # 여전히 이후에 manifest 를 재작성하므로 lazy-close 의 "디스크 manifest 는
+    # prepare 재작성 전 값" 불변식은 유지된다.
+    ctx["FIX_CYCLE_ID"] = _record_fix_cycle_events(inp, ctx)
+
     # ---- write instruction-set scaffolding + lead prompt ----
     instruction_set = _write_instruction_set_sources(
         inp, ctx, profile_content, review_material
@@ -2256,6 +2340,14 @@ def main(argv: list[str]) -> int:
         ),
     )
     p.add_argument("--directive", default="")
+    p.add_argument(
+        "--fix-cycle", default="", choices=["", "yes", "no"], dest="fix_cycle",
+        help=(
+            "done(release-handoff)까지 완료된 task 에 entry phase 로 재진입할 때 "
+            "이번 작업을 버그 픽스 사이클로 기록할지 결정. 'yes' = 새 cycle "
+            "open + run 부착, 'no'/'' = 기록 안 함."
+        ),
+    )
     p.add_argument("--workers", default="", dest="workers_override")
     p.add_argument("--lead-model", default="")
     p.add_argument("--claude-model", default="")
@@ -2413,6 +2505,7 @@ def main(argv: list[str]) -> int:
         approve_plan_ack=args.approve_plan_ack,
         implementation_option=args.implementation_option,
         plan_verification_enabled=args.plan_verification_enabled,
+        fix_cycle=args.fix_cycle,
     )
     try:
         out = prepare_task_bundle(inputs)