okstra 0.71.2 → 0.73.0

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/report_views.py

@@ -109,6 +109,8 @@ def render_html(src_md: str, *, run_meta: RunMeta, css: str, js: str) -> str:
 
     title = html.escape(f"{run_meta.task_key} — {run_meta.task_type} #{run_meta.seq}")
     response_ids_json = "[" + ",".join('"' + html.escape(rid) + '"' for rid in response_ids) + "]"
+    sidecar_name = html.escape(f"user-response-{run_meta.task_type}-{run_meta.seq}.md")
+    sidecar_dir = html.escape(f"runs/{run_meta.task_type}/user-responses/")
 
     return (
         f"<!DOCTYPE html>\n"
@@ -127,6 +129,8 @@ def render_html(src_md: str, *, run_meta: RunMeta, css: str, js: str) -> str:
         f"<main>{body_html}</main>\n"
         f"<footer class=\"report-footer\">\n"
         f"  <button type=\"button\" data-action=\"export-user-response\">Export user response</button>\n"
+        f"  <p class=\"user-response-hint\">Export 클릭 시 <code>{sidecar_name}</code> 가 다운로드됩니다 — "
+        f"<code>{sidecar_dir}</code> 에 저장하면 resume-clarification 이 자동으로 첨부합니다.</p>\n"
         f"  <pre id=\"user-response-output\" aria-live=\"polite\"></pre>\n"
         f"  <button type=\"button\" data-action=\"copy-user-response\">Copy</button>\n"
         f"</footer>\n"
@@ -353,6 +357,10 @@ def _emit_table(lines: list[str], start: int, section_path: list[str]) -> tuple[
         (j for j, h in enumerate(header_cells) if h.startswith("Statement")),
         -1,
     )
+    expected_form_col = next(
+        (j for j, h in enumerate(header_cells) if h.startswith("Expected form")),
+        -1,
+    )
     user_input_col = (
         header_cells.index("User input") if "User input" in header_cells else -1
     )
@@ -367,11 +375,14 @@ def _emit_table(lines: list[str], start: int, section_path: list[str]) -> tuple[
             statement = (
                 row[statement_col] if 0 <= statement_col < len(row) else ""
             )
+            expected_form = (
+                row[expected_form_col] if 0 <= expected_form_col < len(row) else ""
+            )
             cells_html: list[str] = []
             for idx, cell in enumerate(row):
                 if idx == user_input_col:
                     cells_html.append(
-                        f"<td>{_form_control(meta.row_id, meta.kind, meta.status, cell, statement)}</td>"
+                        f"<td>{_form_control(meta.row_id, meta.kind, meta.status, cell, statement, expected_form)}</td>"
                     )
                 else:
                     cells_html.append(
@@ -439,12 +450,51 @@ def _parse_enum_options(statement: str) -> list[tuple[str, str]]:
     return out if len(out) >= 2 else []
 
 
+_RECOMMENDED_CUE = "Recommended:"
+_ALTERNATIVES_CUE = "Alternatives:"
+
+
+def _parse_expected_form_options(expected_form: str) -> list[tuple[str, str]]:
+    """Parse the ``Expected form`` contract format
+    (``Recommended: <answer> — <rationale>; Alternatives: <options>``,
+    `_common-contract.md` §Clarification request policy) into select
+    ``(value, label)`` options. Returns ``[]`` when the cell carries no
+    ``Recommended:`` cue — the caller falls back to the statement enum."""
+    if not expected_form:
+        return []
+    rec_idx = expected_form.find(_RECOMMENDED_CUE)
+    if rec_idx < 0:
+        return []
+    rec_body = expected_form[rec_idx + len(_RECOMMENDED_CUE):]
+    alt_body = ""
+    alt_idx = rec_body.find(_ALTERNATIVES_CUE)
+    if alt_idx >= 0:
+        alt_body = rec_body[alt_idx + len(_ALTERNATIVES_CUE):]
+        rec_body = rec_body[:alt_idx]
+    # The rationale follows " — "; the option keeps only the answer part.
+    answer = rec_body.split(" — ", 1)[0].strip(" .,;—-")
+    options: list[tuple[str, str]] = []
+    if answer:
+        options.append(("recommended", f"추천: {answer}"))
+    enum_alts = _parse_enum_options(alt_body)
+    if enum_alts:
+        options.extend(
+            (letter, f"({letter}) {text}") for letter, text in enum_alts
+        )
+    else:
+        alt_text = alt_body.strip(" .,;—-")
+        if alt_text:
+            options.append(("alternative", alt_text))
+    return options
+
+
 def _form_control(
     response_id: str,
     kind: str,
     status: str,
     current_value: str,
     statement: str = "",
+    expected_form: str = "",
 ) -> str:
     rid = html.escape(response_id)
     disabled = "" if status.lower() in ("open", "answered", "") else " disabled"
@@ -456,14 +506,21 @@ def _form_control(
         "data-point": "값",
     }.get(kind_lc, "응답")
 
-    # decision 인 경우 statement 에서 (a)(b)(c) 후보를 추출해 select+기타 input 으로 렌더.
+    # decision 의 후보는 Expected form 의 `Recommended: …; Alternatives: …`
+    # 계약(_common-contract.md §Clarification request policy)이 1순위,
+    # statement 안 (a)(b)(c) 열거가 fallback. 후보가 있으면 select+기타 input.
     if kind_lc == "decision":
-        opts = _parse_enum_options(statement)
+        opts = _parse_expected_form_options(expected_form)
+        if not opts:
+            opts = [
+                (letter, f"({letter}) {text}")
+                for letter, text in _parse_enum_options(statement)
+            ]
         if opts:
             select_opts = "".join(
-                f'<option value="{letter}">'
-                f'{_inline(f"({letter}) " + text)}</option>'
-                for letter, text in opts
+                f'<option value="{html.escape(value)}">'
+                f"{_inline(label)}</option>"
+                for value, label in opts
             )
             select_html = (
                 f'<select name="{rid}" data-response-id="{rid}" '

package/runtime/python/okstra_ctl/run.py

@@ -28,8 +28,9 @@ 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 .clarification_items import clarification_response_with_sidecars, scan_approval_gate
 from .qa_commands import format_errors as _format_qa_errors, validate_qa_commands
 from .material import (
     build_analysis_material,
@@ -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
@@ -1772,9 +1776,9 @@ def _write_instruction_set_sources(
     (instruction_set / "analysis-material.md").write_text(review_material, encoding="utf-8")
     shutil.copyfile(inp.brief_path, instruction_set / "task-brief.md")
     if inp.clarification_response_path:
-        shutil.copyfile(
-            inp.clarification_response_path,
-            instruction_set / "clarification-response.md",
+        (instruction_set / "clarification-response.md").write_text(
+            clarification_response_with_sidecars(Path(inp.clarification_response_path)),
+            encoding="utf-8",
         )
     if inp.directive:
         (instruction_set / "directive.txt").write_text(inp.directive + "\n", encoding="utf-8")
@@ -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

@@ -2,12 +2,18 @@
 from __future__ import annotations
 
 import json
+import re
 from datetime import datetime
 from pathlib import Path
 
 from .cursor import MAX_NEEDLES, fresh_cache, load_cache, save_cache
 from .paths import claude_project_dir, ts_in_window
 
+# lead 의 단계 체크포인트 라인(agents/SKILL.md "Progress reporting") — phase id 가
+# `phase-<digit>` 로 시작하는 라인만 마커로 인정해 일반 대화의 오탐을 줄인다.
+_PROGRESS_RE = re.compile(r"^PROGRESS:\s+(phase-\d\S*(?:[ \t].*)?)$", re.MULTILINE)
+_PROGRESS_MARKER_MAX_CHARS = 160
+
 
 def _event_from_record(rec: dict) -> dict | None:
     """jsonl 레코드 1개 → 압축 이벤트. 집계에 기여하지 않으면 None.
@@ -48,6 +54,18 @@ def _event_from_record(rec: dict) -> dict | None:
                     if isinstance(b, dict) and b.get("type") == "tool_use")
         if tools:
             ev["u"] = tools
+        markers = [
+            m.group(1).strip()[:_PROGRESS_MARKER_MAX_CHARS]
+            for b in (msg.get("content") or [])
+            if isinstance(b, dict) and b.get("type") == "text"
+            for m in _PROGRESS_RE.finditer(b.get("text") or "")
+        ]
+        # 서로 다른 phase id 가 한 메시지에 섞이면 계약 인용/회고 요약이라 그
+        # 시각은 단계 경계가 아니다(관측: dev-9186 run 의 막판 요약 1건이 전
+        # phase 의 lastAt 을 오염). 같은 phase id 의 반복(병렬 dispatch 3줄,
+        # intake reading+complete)은 라이브 체크포인트로 인정한다.
+        if markers and len({m.split(None, 1)[0] for m in markers}) == 1:
+            ev["p"] = markers
     ts = rec.get("timestamp") or msg.get("timestamp")
     if ts:
         ev["t"] = ts
@@ -133,6 +151,7 @@ def _totals_from_events(events: list[dict], agent_name: str | None,
     input_t = output_t = cache_create_t = cache_read_t = 0
     cache_create_5m_t = cache_create_1h_t = 0
     tool_uses = 0
+    progress_markers: list[dict] = []
     first_ts: str | None = None
     last_ts: str | None = None
     for ev in events:
@@ -146,6 +165,8 @@ def _totals_from_events(events: list[dict], agent_name: str | None,
         cache_create_1h_t += ev.get("c1", 0)
         cache_read_t += ev.get("r", 0)
         tool_uses += ev.get("u", 0)
+        for marker in ev.get("p", ()):
+            progress_markers.append({"at": ts, "marker": marker})
         if ts:
             if first_ts is None or ts < first_ts:
                 first_ts = ts
@@ -179,6 +200,7 @@ def _totals_from_events(events: list[dict], agent_name: str | None,
         "model": model,
         "startedAt": first_ts,
         "endedAt": last_ts,
+        "progressMarkers": progress_markers,
     }
 
 

package/runtime/python/okstra_token_usage/collect.py

@@ -141,6 +141,51 @@ def resolve_run_window(team_state_path: Path, state: dict) -> tuple[str | None,
     return since, until
 
 
+def _wall_ms(start_iso: str | None, end_iso: str | None) -> int | None:
+    if not start_iso or not end_iso:
+        return None
+    try:
+        a = datetime.fromisoformat(start_iso.replace("Z", "+00:00"))
+        b = datetime.fromisoformat(end_iso.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return max(0, int((b - a).total_seconds() * 1000))
+
+
+def phase_timeline(markers: list[dict]) -> dict:
+    """lead 의 PROGRESS 체크포인트(agents/SKILL.md "Progress reporting")로
+    run 내부 단계 경계 wall-clock 을 복원한다 (perf plan v2 P0 계측).
+
+    phase id = marker 의 첫 토큰(`phase-5.5-convergence` 등). 같은 phase 의
+    반복 마커(poll/collect/dispatch)는 first/last 로 접는다. `wallMsToNext` 는
+    다음 phase 의 firstAt 까지 — 마지막 phase 는 None(run 종료 신호가 마커에
+    없으므로 추정하지 않는다). 마커가 하나도 없으면 phases 가 빈 채로 남아
+    "이 run 은 측정 불가"를 명시적으로 표현한다.
+    """
+    phases: list[dict] = []
+    by_id: dict[str, dict] = {}
+    for m in markers:
+        at = m.get("at")
+        phase_id = (m.get("marker") or "").split(None, 1)[0]
+        if not phase_id:
+            continue
+        entry = by_id.get(phase_id)
+        if entry is None:
+            entry = {"phase": phase_id, "firstAt": at, "lastAt": at,
+                     "markerCount": 0, "wallMsToNext": None}
+            by_id[phase_id] = entry
+            phases.append(entry)
+        entry["markerCount"] += 1
+        if at:
+            if entry["firstAt"] is None or at < entry["firstAt"]:
+                entry["firstAt"] = at
+            if entry["lastAt"] is None or at > entry["lastAt"]:
+                entry["lastAt"] = at
+    for current, nxt in zip(phases, phases[1:]):
+        current["wallMsToNext"] = _wall_ms(current["firstAt"], nxt["firstAt"])
+    return {"source": "lead-progress-markers", "phases": phases}
+
+
 def resolve_team_name(state: dict) -> str:
     """team-state 에서 이 run 의 team name 을 해소한다.
 
@@ -232,6 +277,7 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
                                        incremental=incremental)
         state["leadUsage"] = usage_block(totals, source="claude-jsonl")
         state["leadUsage"]["sessionId"] = lead_sid
+        state["phaseTimeline"] = phase_timeline(totals.get("progressMarkers") or [])
     else:
         state["leadUsage"] = na_block(
             f"lead session jsonl not found under {claude_project_dir(cwd)} (sessionId={lead_sid})"