okstra 0.71.2 → 0.72.0

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

package/runtime/validators/validate-run.py

@@ -1369,6 +1369,19 @@ def _data_path_for(report_path: Path) -> Path:
     return report_path.with_suffix(".data.json")
 
 
+def _load_final_report_data(report_path: Path) -> dict:
+    """Best-effort parse of the final-report data.json sibling. Returns {} when
+    absent or unparseable — those conditions are already surfaced as failures by
+    validate_final_report_data; this loader only feeds cross-field checks."""
+    data_path = _data_path_for(report_path)
+    if not data_path.is_file():
+        return {}
+    try:
+        return json.loads(data_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
 def validate_final_report_data(report_path: Path, failures: list[str]) -> None:
     """Validate the final-report data.json against the v1.0 schema.
 
@@ -1748,6 +1761,31 @@ def _validate_improvement_discovery(
             failures.append(f"improvement-discovery: {err}")
 
 
+def _validate_fix_cycle(run_manifest: dict, data: dict, failures: list[str]) -> None:
+    """Enforce: when the run-manifest carries a fixCycleId, the final-report
+    data.json MUST contain a fixCycle block whose ``cycle`` matches it.
+
+    Direction is one-way: a fixCycle block present without a run-manifest
+    fixCycleId is NOT rejected — same posture as the schema-optional block.
+    This check owns only the run→report direction (no missing/mismatched
+    block when the run is attached), never the reverse."""
+    cycle_id = (run_manifest or {}).get("fixCycleId", "")
+    if not cycle_id:
+        return
+    block = (data or {}).get("fixCycle")
+    if not isinstance(block, dict):
+        failures.append(
+            f"fix-cycle: run-manifest fixCycleId={cycle_id} but data.json has "
+            "no fixCycle block"
+        )
+        return
+    if block.get("cycle") != cycle_id:
+        failures.append(
+            f"fix-cycle: data.json fixCycle.cycle={block.get('cycle')!r} does "
+            f"not match run-manifest fixCycleId={cycle_id!r}"
+        )
+
+
 def _validate_session_conformance(
     team_state: dict,
     team_state_path: Path,
@@ -2157,6 +2195,9 @@ def main() -> int:
     # safety net for hand-edited or pre-v1.0 reports.
     task_type = effective_run_task_type(run_manifest, task_manifest)
     validate_final_report_data(report_path, failures)
+    _validate_fix_cycle(
+        run_manifest, _load_final_report_data(report_path), failures
+    )
     validate_report(report_path, contract["required_agent_status_entries"], failures)
     validate_team_state_usage(team_state, failures)
 

package/src/render-bundle.mjs

@@ -18,11 +18,14 @@ Usage:
     [--gemini-model <m>] [--report-writer-model <m>] \\
     [--related-tasks <list>] [--base-ref <ref>] \\
     [--clarification-response <path>] [--work-category <cat>] \\
-    [--stage <auto|N>] [--stages <csv>] [--pr-template-path <path>]
+    [--stage <auto|N>] [--stages <csv>] [--pr-template-path <path>] \\
+    [--fix-cycle <yes|no>]
 
   --stage             implementation / final-verification only
   --stages            release-handoff only: PR stage bundle csv (empty = whole-task)
   --pr-template-path  release-handoff only
+  --fix-cycle         entry phase only: record this re-entry of a done task as a
+                      bug-fix cycle (yes opens/continues the cycle)
 
 release-handoff takes NO --task-brief (briefs belong to entry phases) —
 prepare generates the run's input document from the cited verification