okstra 0.71.1 → 0.72.0

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)

package/runtime/python/okstra_ctl/run_context.py

@@ -103,15 +103,14 @@ def task_mutex(task_key: str) -> Iterator[None]:
 
 
 @contextmanager
-def consumers_mutex(plan_run_root: Path) -> Iterator[None]:
-    """plan run-root 별 consumers.jsonl append mutex.
-
-    lock 은 consumers.jsonl 과 같은 디렉토리에 두어 run-root 마다 1:1 로
-    격리한다. 마지막 경로 세그먼트(예: seq ``001``)만 키로 쓰면 서로 다른
-    task/project 의 동일 seq run 이 같은 lock 을 공유하므로 금지.
-    """
-    plan_run_root.mkdir(parents=True, exist_ok=True)
-    path = plan_run_root / ".consumers.lock"
+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)
@@ -121,6 +120,13 @@ def consumers_mutex(plan_run_root: Path) -> Iterator[None]:
             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
+
+
 def _atomic_write_json(path: Path, payload: dict) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     tmp = path.with_suffix(path.suffix + ".tmp")

package/runtime/python/okstra_ctl/wizard.py

@@ -50,7 +50,7 @@ from okstra_ctl.workers import (
     validate_workers_against_profile,
 )
 from okstra_ctl.workflow import PHASE_SEQUENCE
-from okstra_ctl import worktree_registry
+from okstra_ctl import fix_cycles, worktree_registry
 from okstra_ctl.worktree import (
     compute_worktree_path,
     is_git_work_tree,
@@ -58,7 +58,7 @@ from okstra_ctl.worktree import (
     preview_stage_worktree_decision,
     preview_worktree_decision,
 )
-from okstra_ctl.paths import task_runs_dir
+from okstra_ctl.paths import task_dir, task_runs_dir
 from okstra_ctl.run_context import latest_run_inputs
 from okstra_project.dirs import project_json_path
 from okstra_project.state import (
@@ -268,6 +268,7 @@ S_CLARIFICATION = "clarification"
 S_PR_TEMPLATE_PICK = "pr_template_pick"
 S_PR_TEMPLATE = "pr_template"
 S_PR_TEMPLATE_SCOPE = "pr_template_scope"
+S_FIX_CYCLE_CONFIRM = "fix_cycle_confirm"
 S_BRANCH_CONFIRM = "branch_confirm"
 S_CONFIRM = "confirm"
 S_EDIT_TARGET = "edit_target"
@@ -376,6 +377,8 @@ class WizardState:
     last_pr_template_cached: str = ""
 
     # confirm / edit
+    # "" | "yes" | "no" — done(release-handoff) task 재진입의 fix-cycle 기록 여부
+    fix_cycle: str = ""
     branch_confirmed: Optional[bool] = None
     confirmed: Optional[bool] = None
     edit_target: str = ""
@@ -796,6 +799,26 @@ def _branch_confirm_required(state: WizardState) -> bool:
     return state.task_type != "final-verification"
 
 
+def _fix_cycle_confirm_required(state: WizardState) -> bool:
+    """완료(release-handoff) task 에 entry phase 로 재진입하고, 아직 열린 fix
+    cycle 이 없을 때만 묻는다."""
+    if state.task_type not in fix_cycles.FIX_CYCLE_ENTRY_PHASES:
+        return False
+    task_root = task_dir(Path(state.project_root),
+                         state.task_group, state.task_id)
+    manifest = task_root / "task-manifest.json"
+    if not manifest.is_file():
+        return False
+    try:
+        data = json.loads(manifest.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    workflow = data.get("workflow") or {}
+    if workflow.get("lastCompletedPhase") != "release-handoff":
+        return False
+    return fix_cycles.open_cycle(fix_cycles.read_rows(task_root)) is None
+
+
 def _stage_auto_allowed(state: WizardState) -> bool:
     return state.task_type == "implementation"
 
@@ -2424,6 +2447,30 @@ def _submit_pr_template_scope(state: WizardState, value: str) -> Optional[str]:
     return f"pr-template-scope: {value}"
 
 
+def _build_fix_cycle_confirm(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "fix_cycle_confirm")
+    opts = t["options"]
+    return Prompt(
+        step=S_FIX_CYCLE_CONFIRM, kind="pick", label=t["label"],
+        options=[
+            _opt("yes", opts["yes"]),
+            _opt("no", opts["no"]),
+            _opt("abort", opts["abort"]),
+        ],
+        echo_template=t["echo_template"])
+
+
+def _submit_fix_cycle_confirm(state: WizardState, value: str) -> Optional[str]:
+    v = value.strip().lower()
+    if v == "abort":
+        state.aborted = True
+        return "fix-cycle: abort"
+    if v not in ("yes", "no"):
+        raise WizardError(f"expected 'yes' / 'no' / 'abort', got: {value!r}")
+    state.fix_cycle = v
+    return f"fix-cycle: {v}"
+
+
 def _build_branch_confirm(state: WizardState) -> Prompt:
     if state.task_type == "implementation":
         return _build_branch_confirm_impl_stage(state)
@@ -2854,14 +2901,24 @@ STEPS: list[Step] = [
                             and S_PR_TEMPLATE_SCOPE not in s.answered),
          build=_build_pr_template_scope, submit=_submit_pr_template_scope,
          owns=("pr_template_scope",)),
+    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",)),
     Step(S_BRANCH_CONFIRM,
          applies=lambda s: (_ready_for_confirm(s)
+                            and (not _fix_cycle_confirm_required(s)
+                                 or bool(s.fix_cycle))
                             and _branch_confirm_required(s)
                             and s.branch_confirmed is None),
          build=_build_branch_confirm, submit=_submit_branch_confirm,
          owns=("branch_confirmed",)),
     Step(S_CONFIRM,
          applies=lambda s: (_ready_for_confirm(s)
+                            and (not _fix_cycle_confirm_required(s)
+                                 or bool(s.fix_cycle))
                             and (not _branch_confirm_required(s)
                                  or s.branch_confirmed is True)
                             and s.confirmed is None),
@@ -2944,9 +3001,10 @@ _FIELD_DEFAULTS: dict[str, Any] = {
     "task_group_pending_text": False, "task_id_pending_text": False,
     "profile_workers": [], "profile_optional_workers": [],
     "keep_existing_brief": None,
-    "brief_path": "", "reuse_worktree": None, "base_ref": "",
+    "brief_path": "", "brief_path_pending_text": False,
+    "reuse_worktree": None, "base_ref": "",
     "base_ref_pending_text": False, "approved_plan_path": "",
-    "approved_plan_pending_text": False,
+    "approved_plan_pending_text": False, "approve_plan_candidate": "",
     "selected_stage": "auto",
     "handoff_mode": "", "handoff_stages": "",
     "executor": "", "critic": "", "critic_pending_text": False,
@@ -2959,6 +3017,7 @@ _FIELD_DEFAULTS: dict[str, Any] = {
     "clarification_response_path": "", "clarification_pending_text": False,
     "pr_template_path": "", "pr_template_pending_text": False,
     "pr_template_scope": "",
+    "fix_cycle": "",
     "branch_confirmed": None, "confirmed": None, "edit_target": "",
 }
 
@@ -3126,6 +3185,7 @@ def render_args(state: WizardState) -> dict[str, str]:
         "related-tasks": state.related_tasks_raw,
         "clarification-response": state.clarification_response_path,
         "pr-template-path": pr_template,
+        "fix-cycle": state.fix_cycle,
     }
 
 

package/runtime/python/okstra_token_usage/claude.py

@@ -243,6 +243,19 @@ def _needle_scan(jsonl_path: Path, entry: dict, needle_lower: str) -> bool:
     return False
 
 
+def _cached_needle_scan(jsonl_path: Path, cache: dict, needle_lower: str) -> bool:
+    """`cache['needles']` 의 per-needle cursor 를 유지하며 `_needle_scan` 수행.
+    파일당 MAX_NEEDLES 개까지 오래된 순으로 교체 보존한다."""
+    needles = cache.setdefault("needles", {})
+    entry = needles.get(needle_lower)
+    if entry is None:
+        entry = {"offset": 0, "found": False}
+        while len(needles) >= MAX_NEEDLES:
+            needles.pop(next(iter(needles)))
+        needles[needle_lower] = entry
+    return _needle_scan(jsonl_path, entry, needle_lower)
+
+
 def find_claude_team_sessions(
     cwd: Path,
     team_name: str,
@@ -276,14 +289,7 @@ def find_claude_team_sessions(
         for p in proj_dir.glob("*.jsonl"):
             if incremental:
                 cache = load_cache(p)
-                needles = cache.setdefault("needles", {})
-                entry = needles.get(needle_lower)
-                if entry is None:
-                    entry = {"offset": 0, "found": False}
-                    while len(needles) >= MAX_NEEDLES:
-                        needles.pop(next(iter(needles)))
-                    needles[needle_lower] = entry
-                if _needle_scan(p, entry, needle_lower):
+                if _cached_needle_scan(p, cache, needle_lower):
                     out[p.stem] = p
                 save_cache(p, cache)
             else:
@@ -294,3 +300,53 @@ def find_claude_team_sessions(
         if direct.is_file():
             out.setdefault(lead_sid, direct)
     return out
+
+
+_TEAM_TAG_NEEDLE = '"teamname":"'
+
+
+def find_claude_agent_sessions(
+    cwd: Path,
+    agent_prefixes: list[str],
+    projects_root: Path | None = None,
+    *,
+    incremental: bool = False,
+) -> dict[str, Path]:
+    """Map sessionId -> jsonl path for non-team sessions whose recorded
+    `agentName` matches one of ``agent_prefixes``.
+
+    no-team run(teamCreate `skipped`(concurrent-run) / `error` fallback)의
+    worker 세션은 team 태그가 없어 teamName needle 로는 발견되지 않는다. 대신
+    하네스가 dispatch `name` 인자로 기록하는 `agentName` 을 needle 로 찾되,
+    team 태그가 있는 세션은 제외한다 — 그것은 동시 team-mode run 의 worker 다.
+
+    같은 agentName 을 쓰는 다른 run 의 세션도 걸릴 수 있으므로, 호출자는 반드시
+    run 윈도우로 totals 를 스코핑하고 in-window 이벤트가 없는 세션을 버려야
+    한다. 윈도우가 겹치는 두 no-team run 이 같은 role 을 dispatch 한 경우의
+    교차 귀속은 구조적으로 분리 불가 — usage 블록의 sessionId 목록으로만
+    추적 가능하다.
+    """
+    proj_dir = claude_project_dir(cwd, projects_root)
+    out: dict[str, Path] = {}
+    if not proj_dir.is_dir():
+        return out
+    agent_needles = [f'"agentname":"{p.lower()}' for p in agent_prefixes if p]
+    if not agent_needles:
+        return out
+    for p in proj_dir.glob("*.jsonl"):
+        if incremental:
+            cache = load_cache(p)
+            matched = any(_cached_needle_scan(p, cache, n) for n in agent_needles)
+            team_tagged = matched and _cached_needle_scan(p, cache, _TEAM_TAG_NEEDLE)
+            save_cache(p, cache)
+        else:
+            matched = any(
+                _needle_scan(p, {"offset": 0, "found": False}, n)
+                for n in agent_needles
+            )
+            team_tagged = matched and _needle_scan(
+                p, {"offset": 0, "found": False}, _TEAM_TAG_NEEDLE
+            )
+        if matched and not team_tagged:
+            out[p.stem] = p
+    return out

package/runtime/python/okstra_token_usage/collect.py

@@ -7,7 +7,11 @@ from pathlib import Path
 from okstra_project.dirs import OKSTRA_RELATIVE
 
 from .blocks import na_block, usage_block
-from .claude import claude_session_totals, find_claude_team_sessions
+from .claude import (
+    claude_session_totals,
+    find_claude_agent_sessions,
+    find_claude_team_sessions,
+)
 from .codex import codex_session_total, find_codex_session
 from .gemini import find_gemini_session, gemini_session_total
 from .paths import claude_project_dir, utc_now
@@ -197,6 +201,31 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
             unattributed_sessions.append(sid)
             unattributed_totals.append(totals)
 
+    # no-team run (teamCreate skipped/concurrent-run, or error fallback) —
+    # worker 세션에 team 태그가 없어 위 needle 탐색이 비므로, agentName 기반
+    # 발견으로 보강한다. run 윈도우 밖 세션(in-window 이벤트 없음 = startedAt
+    # 부재)은 같은 agentName 의 타 run 세션이므로 버린다.
+    team_create_status = str((state.get("teamCreate") or {}).get("status", "")).strip()
+    if team_create_status in ("skipped", "error"):
+        worker_prefix_pool = [
+            prefix
+            for w in state.get("workers", [])
+            for prefix in match_prefixes(w.get("workerId") or "")
+        ]
+        agent_sessions = find_claude_agent_sessions(
+            cwd, worker_prefix_pool, incremental=incremental
+        )
+        for sid, path in agent_sessions.items():
+            if sid == lead_sid or sid in claude_sessions:
+                continue
+            totals = claude_session_totals(path, since=run_since, until=run_until,
+                                           incremental=incremental)
+            if not totals.get("startedAt"):
+                continue
+            agent = totals.get("agentName")
+            if agent:
+                by_agent.setdefault(agent, []).append((sid, path, totals))
+
     # Lead.
     if lead_path is not None:
         totals = claude_session_totals(lead_path, since=run_since, until=run_until,

package/runtime/schemas/final-report-v1.0.schema.json

@@ -625,6 +625,31 @@
       }
     },
 
+    "fixCycle": {
+      "type": "object",
+      "description": "RENDER_IF fixCycle present — the post-release bug-fix cycle this run belongs to.",
+      "required": ["cycle", "targetReport", "symptom"],
+      "additionalProperties": false,
+      "properties": {
+        "cycle": { "type": "string", "pattern": "^fc-[0-9]{2,}$" },
+        "targetReport": { "type": "string" },
+        "symptom": { "type": "string" },
+        "runs": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["taskType", "runSeq"],
+            "additionalProperties": false,
+            "properties": {
+              "taskType": { "type": "string" },
+              "runSeq": { "type": "integer" },
+              "runManifest": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+
     "clarificationItems": {
       "type": "array",
       "items": { "$ref": "#/$defs/ClarificationRow" }

package/runtime/skills/okstra-brief/SKILL.md

@@ -431,6 +431,9 @@ never error:
 1. **okstra-internal (authoritative)** — always check first:
    - `<PROJECT_ROOT>/.okstra/glossary.md` if present
    - `<PROJECT_ROOT>/.okstra/decisions/` titles if present
+   - 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.
 2. **Explicit source material only** — if the reporter cited a path outside
    okstra's subtree, read it as source evidence only; do not treat it as
    okstra memory.
@@ -602,6 +605,11 @@ Required sections:
 - **Related Artifacts** — files, URLs, issues, prior task-keys.
 - **Open Questions** — anything the user already flagged as undecided
   (becomes raw material for `requirements-discovery`).
+- **Task Continuity Notes** — if the target task's
+  `history/fix-cycles.jsonl` exists, cite each cycle here 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.
 
 Sections **deliberately omitted** (do NOT add them, do NOT prompt for them):
 

package/runtime/skills/okstra-report-writer/SKILL.md

@@ -279,6 +279,8 @@ Section numbering follows `templates/reports/final-report.template.md` exactly
 6. **Recommended Next Steps** — prioritized actions. After Phase 7's follow-up spawner runs, append a row per newly created task-key (see "Phase 6 → Phase 7 execution sequence" above).
 7. **Follow-up Tasks** — auto-spawn-eligible table. Each row drives `okstra-spawn-followups.py`; see template §7 for the row schema.
 
+**§5.10 Fix History (data-presence gated).** When the run-manifest carries a `fixCycleId`, fill the data.json `fixCycle` block (`cycle` / `targetReport` / `symptom` / `runs`). Read the values from the task root's `history/fix-cycles.jsonl`: `cycle` MUST equal `fixCycleId`, `targetReport` / `symptom` come from that cycle's `opened` row, and `runs` lists its attached `run` rows (`taskType` / `runSeq` / `runManifest`). The validator (`validators/validate-run.py` → `_validate_fix_cycle`) fails the run when the block is missing or `fixCycle.cycle` does not match `fixCycleId`. When the run-manifest has no `fixCycleId`, OMIT the `fixCycle` block entirely — the renderer omits §5.10.
+
 ### Writing Guidelines
 
 - Write in Markdown. **Prefer tables over prose bullet lists** for any section that enumerates multiple items with the same shape (evidence rows, risks, options, dependencies, rollback steps, follow-ups, open questions). Bullets are reserved for short, single-line standalone statements (e.g., "- 추가 정보 요청 없음."). When the template provides a table form, do NOT degrade it back to bullets in the rendered report.

package/runtime/skills/okstra-run/SKILL.md

@@ -178,7 +178,8 @@ okstra render-bundle \
   --report-writer-model "<args.report-writer-model>" \
   --related-tasks "<args.related-tasks>" \
   --clarification-response "<args.clarification-response>" \
-  --pr-template-path "<args.pr-template-path>"
+  --pr-template-path "<args.pr-template-path>" \
+  --fix-cycle "<args.fix-cycle>"
 ```
 
 `render-bundle` auto-supplies `--workspace-root` and forces `--render-only`. Stdout prints `okstra task root:`, `okstra instruction-set:`, and the full rendered lead prompt. Parse the labelled lines for `TASK_ROOT` and `INSTRUCTION_SET_PATH`. Also watch for an optional `okstra concurrent-run stages:` label line — present only when a concurrent run is detected (see "동시-run 감지 분기" below).

package/runtime/templates/project-docs/task-index.template.md

@@ -37,6 +37,7 @@ taskType: "{{FM_TASK_TYPE}}"
 - Next Recommended Phase: `{{WORKFLOW_NEXT_RECOMMENDED_PHASE}}`
 - Awaiting Approval: `{{WORKFLOW_AWAITING_APPROVAL}}`
 - Routing Status: `{{WORKFLOW_ROUTING_STATUS}}`
+- Fix cycles: {{FIX_CYCLES_SUMMARY}}
 
 ## Phase States
 

package/runtime/templates/reports/final-report.template.md

@@ -556,6 +556,20 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 | Cand ID | Lens | Title | Scope | Severity | Effort | Consensus | Source workers | Recommended next-phase | Evidence |
 |---------|------|-------|-------|----------|--------|-----------|----------------|------------------------|----------|
 
+{% endif %}
+{% if fixCycle and fixCycle.cycle %}
+## 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 %}
 ## 6. Cross Verification Results