okstra 0.71.2 → 0.73.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.73.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.73.0",
+  "builtAt": "2026-06-11T14:40:52.876Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -42,7 +42,7 @@ This SKILL.md is the operating contract and phase index. Detailed procedures liv
 | 4. Execution | Spawn analysis workers (Teams preferred) | `okstra-team-contract` |
 | 5. Fallback | Sequential/background dispatch when Teams unavailable | `okstra-team-contract` |
 | 5.5 Convergence | Cross-verify findings across workers | `okstra-convergence` |
-| 5.6 Critic pass | (opt-in) reused-worker critic pass: coverage gaps (discovery/error-analysis/impl-planning) or acceptance devil's-advocate (final-verification), each verified one round | `okstra-convergence` "Coverage critic pass" / "Acceptance critic pass" |
+| 5.6 Critic pass | (opt-in) reused-worker critic pass: coverage gaps (discovery/error-analysis/impl-planning) or acceptance devil's-advocate (final-verification). The critic dispatch fires concurrently with the first 5.5 reverify round (its input is fixed at Round 0); gap/blocker verification (one round) completes here | `okstra-convergence` "Coverage critic pass" / "Acceptance critic pass" |
 | 6. Synthesis | Dispatch Report writer worker, review draft. **For `implementation-planning`: then run the Phase 6 plan-body verification sub-step (see Phase 6 section below).** | `okstra-report-writer` + `okstra-convergence` (sub-step) |
 | 7. Persist | Run token-usage collector, update manifests, ask about residual tmux panes, then ask whether to disband the worker team (reconcile stale members + `TeamDelete` only on approval) | `okstra-report-writer` + `_common-contract.md` "Phase wrap-up" / "Run-end teammate teardown" |
 
@@ -94,7 +94,7 @@ Required checkpoints:
 - `PROGRESS: phase-5-poll pending=<n> done=<m>` — emitted on each wakeup while the pending set is non-empty.
 - `PROGRESS: phase-5-collect worker=<role> status=<terminal-status>` — once per worker, immediately after the result file is verified.
 - `PROGRESS: phase-5.5-convergence round=<N> queue=<count>` — at the start of each convergence round (Phase 5.5).
-- `PROGRESS: phase-5.6-critic provider=<provider> gaps=<n>` — when the coverage critic pass runs (Phase 5.6, opt-in). Omitted when `convergence.critic.enabled == false`.
+- `PROGRESS: phase-5.6-critic provider=<provider> gaps=<n>` — after the critic result is collected (Phase 5.6, opt-in; the critic dispatch itself fires concurrently with the first 5.5 reverify round). Omitted when `convergence.critic.enabled == false`.
 - `PROGRESS: phase-6-synthesis dispatching report-writer-worker` — at the start of Phase 6.
 - `PROGRESS: phase-7-persist updating manifests` — at the start of Phase 7.
 - `PROGRESS: phase-7-teardown disbanding team` — after token-usage collection and after the pane-disposition prompt, only when the user approved worker teammate cleanup, immediately before reconciling stale members + `TeamDelete` (Teams mode only; see `_common-contract.md` "Run-end teammate teardown"). Skipped in the no-`team_name` fallback or when the user keeps the team.

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/profiles/error-analysis.md

@@ -32,7 +32,7 @@
   - **Evidence note required inside `Statement`**: every clarification row includes `Evidence checked: <path:line>` or `Evidence checked: none — <reporter-only reason>` in the `Statement` cell. `none` is allowed ONLY when the row's nature is "only the reporter can answer this" (reporter-side data, business priority, environment they observed). A row with `none` that *could* have been answered by code or logs is a defect.
 - Cross-verification mode:
   - Phase 5.5 convergence runs in **adversarial mode** for this phase (`convergence.adversarial=true`). Verifiers actively try to refute each root-cause / reproduction claim by directly re-inspecting the cited code, logs, or config; the burden of proof sits on the claim. See `skills/okstra-convergence/SKILL.md` §"Adversarial Verification Mode". A single evidence-backed refutation prevents a finding from reaching consensus.
-  - **Coverage critic (opt-in)**: when `convergence.critic.enabled=true` (chosen via the okstra-run picker or `--critic`), a reused-worker critic pass runs after convergence to surface missed findings; its gaps are merged only after a 1-round adversarial reverify. See `skills/okstra-convergence/SKILL.md` "Coverage critic pass".
+  - **Coverage critic (opt-in)**: when `convergence.critic.enabled=true` (chosen via the okstra-run picker or `--critic`), a reused-worker critic pass is dispatched concurrently with the first convergence reverify round to surface missed findings; its gaps are merged only after a 1-round adversarial reverify that follows convergence. See `skills/okstra-convergence/SKILL.md` "Coverage critic pass".
 - Non-goals:
   - implementation details unless they are necessary to validate the cause
   - **source code edits, builds, migrations, or deployments** — this run produces evidence and cause analysis only; the fix belongs to a later `implementation-planning` run followed by an `implementation` run

package/runtime/prompts/profiles/final-verification.md

@@ -48,7 +48,7 @@
   4. **Verifier dissent preserved** — if workers reach different verdicts, the disagreement is visible in section 1.2; synthesis hides nothing.
   5. **No source-mutation audit** — scan the run's session transcripts for Edit / Write or state-mutating Bash commands that touch paths OUTSIDE `<PROJECT_ROOT>/.okstra/**` and outside the assigned run-artifact paths. Writes to worker prompts, audit sidecars, team-state, the final-report `data.json`, and rendered reports under the run directory are allowed okstra artifacts. Any source/schema/deployment mutation means the run has crossed into implementation and MUST be re-routed; do NOT silently strip the evidence.
 - Cross-verification mode:
-  - **Acceptance critic (opt-in)**: when `convergence.critic.enabled=true` (chosen via the okstra-run picker or `--critic`), a reused-worker **acceptance devil's-advocate** pass runs after convergence to surface candidate acceptance blockers the verifiers may have missed. Each candidate is verified **confirm-or-downgrade**: confirmed → an `Acceptance Blockers` row (which, since `accepted` requires zero blockers, moves the verdict to `conditional-accept` / `blocked`); unconfirmed → a `Residual Risk` row (never dropped). See `skills/okstra-convergence/SKILL.md` "Acceptance critic pass (final-verification)".
+  - **Acceptance critic (opt-in)**: when `convergence.critic.enabled=true` (chosen via the okstra-run picker or `--critic`), a reused-worker **acceptance devil's-advocate** pass is dispatched concurrently with the first convergence reverify round to surface candidate acceptance blockers the verifiers may have missed; candidates are verified only after convergence completes. Each candidate is verified **confirm-or-downgrade**: confirmed → an `Acceptance Blockers` row (which, since `accepted` requires zero blockers, moves the verdict to `conditional-accept` / `blocked`); unconfirmed → a `Residual Risk` row (never dropped). See `skills/okstra-convergence/SKILL.md` "Acceptance critic pass (final-verification)".
 - Non-goals:
   - proposing unrelated refactors beyond the delivered scope
   - **source code edits, follow-up bug fixes, or scope expansion** — this run renders a verdict only; defects detected here become inputs to a new `error-analysis` or `implementation-planning` run

package/runtime/prompts/profiles/implementation-planning.md

@@ -41,7 +41,7 @@
 - Cross-verification mode:
   - Phase 5.5 finding convergence runs in **adversarial mode** for this phase (`convergence.adversarial=true`). Verifiers actively try to refute each worker finding (requirement gap / risk / option) by re-inspecting its cited evidence; the burden of proof sits on the claim. See `skills/okstra-convergence/SKILL.md` §"Adversarial Verification Mode".
   - §5.5.9 plan-body verification runs with an **adversarial posture** (`skills/okstra-convergence/SKILL.md` §"Adversarial plan-body posture"): verifiers open and confirm every cited path / command and put the burden of proof on the plan. The gate threshold is unchanged — a *majority* `DISAGREE` (`majority-disagree`) is still required to block approval; a single dissent does not.
-  - **Coverage critic (opt-in)**: when `convergence.critic.enabled=true` (chosen via the okstra-run picker or `--critic`), a reused-worker critic pass runs after convergence to surface missed findings; its gaps are merged only after a 1-round adversarial reverify. See `skills/okstra-convergence/SKILL.md` "Coverage critic pass".
+  - **Coverage critic (opt-in)**: when `convergence.critic.enabled=true` (chosen via the okstra-run picker or `--critic`), a reused-worker critic pass is dispatched concurrently with the first convergence reverify round to surface missed findings; its gaps are merged only after a 1-round adversarial reverify that follows convergence. See `skills/okstra-convergence/SKILL.md` "Coverage critic pass".
 - Non-goals:
   - code-level micro-optimization unless it changes the implementation approach
   - **source code edits of any kind** — this run produces a plan document only; Edit/Write on project source files is forbidden until the plan is approved and a separate `implementation` run starts

package/runtime/prompts/profiles/requirements-discovery.md

@@ -53,7 +53,7 @@
   - **Evidence note required inside `Statement`**: every clarification row includes `Evidence checked: <path:line>` or `Evidence checked: none — <human-only reason>` in the `Statement` cell. `none` is allowed ONLY when the row's nature is "only a human can answer this" (reporter intent, business priority, external authority). A row with `none` that *could* have been answered by the codebase is a defect.
 - Cross-verification mode:
   - Phase 5.5 convergence runs in **adversarial mode** for this phase (`convergence.adversarial=true`). Verifiers actively try to refute each worker's finding by directly re-inspecting the cited evidence; the burden of proof sits on the claim. See `skills/okstra-convergence/SKILL.md` §"Adversarial Verification Mode". A single evidence-backed refutation prevents a finding from reaching consensus.
-  - **Coverage critic (opt-in)**: when `convergence.critic.enabled=true` (chosen via the okstra-run picker or `--critic`), a reused-worker critic pass runs after convergence to surface missed findings; its gaps are merged only after a 1-round adversarial reverify. See `skills/okstra-convergence/SKILL.md` "Coverage critic pass".
+  - **Coverage critic (opt-in)**: when `convergence.critic.enabled=true` (chosen via the okstra-run picker or `--critic`), a reused-worker critic pass is dispatched concurrently with the first convergence reverify round to surface missed findings; its gaps are merged only after a 1-round adversarial reverify that follows convergence. See `skills/okstra-convergence/SKILL.md` "Coverage critic pass".
 - Non-goals:
   - full implementation design unless it is required to decide the next phase
   - **source code edits, plan authoring, builds, or deployments** — this run only classifies the work and routes it; deeper analysis and planning belong to subsequent phases

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

@@ -299,3 +299,29 @@ def section_1_present_but_unparsed(report_text: str) -> bool:
     if SECTION_HEADING_PATTERN.search(report_text):
         return False
     return bool(_LOOSE_SECTION_1_RE.search(report_text))
+
+
+def clarification_response_with_sidecars(source: Path) -> str:
+    """clarification-response 원문 뒤에 `user-responses/` 사이드카를 덧붙인 본문.
+
+    ``source`` 가 ``runs/<task-type>/reports/final-report-*.md`` 레이아웃일 때만
+    형제 ``user-responses/`` 디렉토리를 찾는다(HTML 뷰의 `Export user response`
+    가 내려준 파일을 사용자가 거기 저장). 그 외 경로·사이드카 부재 시 원문 그대로 —
+    호출자는 항상 이 함수를 거쳐 instruction-set 사본을 쓰면 된다.
+    """
+    text = source.read_text(encoding="utf-8")
+    responses_dir = source.parent.parent / "user-responses"
+    if source.parent.name != "reports" or not responses_dir.is_dir():
+        return text
+    sidecars = sorted(
+        p for p in responses_dir.glob("user-response-*.md") if p.is_file()
+    )
+    if not sidecars:
+        return text
+    parts = [text.rstrip("\n"), "\n\n---\n\n# Attached User Responses\n"]
+    for sidecar in sidecars:
+        parts.append(
+            f"\n## {sidecar.name}\n\n"
+            f"{sidecar.read_text(encoding='utf-8').strip()}\n"
+        )
+    return "".join(parts)

package/runtime/python/okstra_ctl/context_cost.py

@@ -306,19 +306,46 @@ def _analysis_worker_metric(task_root: Path, project_root: Path) -> dict:
     }
 
 
+_SEQ_RESULT_RE = re.compile(r"-(\d{3,})\.md$")
+
+
+def _current_seq_worker_results(run_dir: Path) -> list[Path]:
+    """현재 run seq 의 분석 worker 결과만 추린다.
+
+    같은 worker-results 디렉토리에 seq-less 레거시(`codex-worker.md`)와 이전
+    seq 결과가 공존한다(관측: dev-9186 에 5월 레거시 72KB 혼입 → reportWriter
+    표면 과대 측정). 실 dispatch 계약은 현재 seq 파일만 열거하므로 max seq 로
+    스코핑한다."""
+    candidates = [
+        path for path in (run_dir / "worker-results").glob("*.md")
+        if "-audit-" not in path.name and "report-writer" not in path.name
+    ]
+    by_seq: dict[str, list[Path]] = {}
+    for path in candidates:
+        match = _SEQ_RESULT_RE.search(path.name)
+        if match:
+            by_seq.setdefault(match.group(1), []).append(path)
+    if not by_seq:
+        return []
+    return sorted(by_seq[max(by_seq)])
+
+
 def _report_writer_metric(run_dir: Path | None, task_root: Path, project_root: Path) -> dict:
     instruction_set = task_root / "instruction-set"
     files = [instruction_set / name for name in INPUT_FILES]
+    # 실 dispatch 계약(report-writer prompt 의 required reading)은 packet 이
+    # 있으면 analysis-material 대신 analysis-packet 을 읽는다 — worker metric
+    # 의 packet-primary 규칙과 동일.
+    packet = instruction_set / "analysis-packet.md"
+    if packet.is_file():
+        files = [path for path in files if path.name != "analysis-material.md"]
+        files.append(packet)
     files.extend([
         instruction_set / "final-report-template.md",
         instruction_set / "final-report-schema.json",
     ])
     if run_dir is not None:
-        worker_results = run_dir / "worker-results"
-        files.extend(
-            path for path in worker_results.glob("*.md")
-            if "-audit-" not in path.name and "report-writer" not in path.name
-        )
+        files.extend(_current_seq_worker_results(run_dir))
         convergence = _latest_matching_file(
             run_dir / "state", f"convergence-{run_dir.name}-*.json"
         )

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 ""