okstra 0.121.1 → 0.123.0

package/runtime/python/okstra_ctl/wizard.py

@@ -37,6 +37,12 @@ from okstra_ctl.models import (
     resolve_model_metadata,
 )
 from okstra_ctl.clarification_items import scan_approval_gate, user_response_sidecars
+from okstra_ctl.design_prep import (
+    DesignPrepError,
+    load_design_prep_items,
+    resolve_design_prep,
+    write_design_prep_input,
+)
 from okstra_ctl.final_report_paths import final_report_data_path
 from okstra_ctl.pr_template import PrTemplateError, resolve_pr_template_path
 from okstra_ctl.run import (
@@ -303,6 +309,9 @@ S_BASE_REF_TEXT = "base_ref_text"
 S_APPROVED_PLAN_PICK = "approved_plan_pick"
 S_APPROVED_PLAN = "approved_plan"
 S_APPROVE_PLAN_CONFIRM = "approve_plan_confirm"
+S_DESIGN_PREP_DECISION = "design_prep_decision"
+S_DESIGN_PREP_OVERRIDES = "design_prep_overrides"
+S_DESIGN_PREP_CONFIRM = "design_prep_confirm"
 S_STAGE_PICK = "stage_pick"
 S_HANDOFF_STAGE_PICK = "handoff_stage_pick"
 S_EXECUTOR = "executor"
@@ -403,6 +412,11 @@ class WizardState:
     # approve-confirm 단계가 3-옵션(yes_apply/yes/no)으로 확장된다.
     html_approval_sidecar: str = ""
     html_approval_option: str = ""
+    design_prep_queue: list[str] = field(default_factory=list)
+    design_prep_current: str = ""
+    design_prep_decision: str = ""
+    design_prep_overrides_json: str = ""
+    design_prep_notes: str = ""
     selected_stage: str = "auto"
     selected_stages: str = ""   # implementation 다중선택 위상정렬 CSV
     executor: str = ""
@@ -1077,6 +1091,7 @@ class Step:
     submit: Callable[[WizardState, str], Optional[str]]
     # Field names this step owns; resetting the step clears them.
     owns: tuple[str, ...] = ()
+    repeatable: bool = False
 
 
 def _opt(value: str, label: str = "", description: str = "") -> Option:
@@ -1939,6 +1954,234 @@ def _submit_approve_plan_confirm(state: WizardState, value: str) -> Optional[str
     return echo
 
 
+def _design_prep_items_by_id(state: WizardState) -> dict[str, dict[str, Any]]:
+    try:
+        items = load_design_prep_items(Path(state.approved_plan_path))
+    except DesignPrepError as exc:
+        raise WizardError(str(exc)) from exc
+    return {str(item["id"]): item for item in items}
+
+
+def _ensure_design_prep_queue(state: WizardState) -> None:
+    if state.design_prep_current or state.design_prep_queue:
+        return
+    if S_DESIGN_PREP_DECISION in state.answered:
+        return
+    report_path = Path(state.approved_plan_path)
+    if not re.fullmatch(
+        r"final-report-implementation-planning-\d+\.md",
+        report_path.name,
+    ):
+        return
+    data_path = report_path.with_name(
+        report_path.name.removesuffix(".md") + ".data.json"
+    )
+    if not data_path.is_file():
+        return
+    try:
+        items = load_design_prep_items(report_path)
+        effective = resolve_design_prep(report_path)
+    except DesignPrepError as exc:
+        raise WizardError(str(exc)) from exc
+    decisions = {
+        str(item["id"]): item.get("decision")
+        for item in effective.effective_items
+    }
+    unresolved = [
+        item for item in items
+        if item.get("status") in ("blocked", "provisional")
+        and decisions.get(str(item["id"])) == "unanswered"
+    ]
+    unresolved.sort(key=lambda item: item.get("status") != "blocked")
+    state.design_prep_queue = [str(item["id"]) for item in unresolved]
+    _advance_design_prep_item(state)
+
+
+def _advance_design_prep_item(state: WizardState) -> None:
+    state.design_prep_current = (
+        state.design_prep_queue.pop(0) if state.design_prep_queue else ""
+    )
+    state.design_prep_decision = ""
+    state.design_prep_overrides_json = ""
+    state.design_prep_notes = ""
+
+
+def _current_design_prep_item(state: WizardState) -> dict[str, Any]:
+    item = _design_prep_items_by_id(state).get(state.design_prep_current)
+    if item is None:
+        raise WizardError(
+            f"design preparation item is missing: {state.design_prep_current}"
+        )
+    return item
+
+
+def _design_prep_decision_applies(state: WizardState) -> bool:
+    if state.task_type != "implementation" or not state.approved_plan_path:
+        return False
+    _ensure_design_prep_queue(state)
+    return bool(state.design_prep_current and not state.design_prep_decision)
+
+
+def _build_design_prep_decision(state: WizardState) -> Prompt:
+    item = _current_design_prep_item(state)
+    proposal = item.get("aiProposal") or {}
+    t = _p(
+        state.workspace_root,
+        S_DESIGN_PREP_DECISION,
+        item_id=str(item["id"]),
+        title=str(item["title"]),
+        stage_refs=json.dumps(item.get("stageRefs") or [], ensure_ascii=False),
+        proposal_summary=str(proposal.get("summary") or ""),
+        details=json.dumps(proposal.get("details") or [], ensure_ascii=False),
+        assumptions=json.dumps(proposal.get("assumptions") or [], ensure_ascii=False),
+        guardrails=json.dumps(item.get("guardrails") or [], ensure_ascii=False),
+        request_path=str(item.get("requestPath") or ""),
+    )
+    return Prompt(
+        step=S_DESIGN_PREP_DECISION,
+        kind="pick",
+        label=t["label"],
+        options=[_opt(value, label) for value, label in _static_options(t)],
+        echo_template=t["echo_template"],
+    )
+
+
+def _submit_design_prep_decision(
+    state: WizardState,
+    value: str,
+) -> Optional[str]:
+    t = _p(state.workspace_root, S_DESIGN_PREP_DECISION,
+           item_id="", title="", stage_refs="", proposal_summary="",
+           details="", assumptions="", guardrails="", request_path="")
+    if value not in ("accept-draft", "modify-draft", "reject-draft", "later"):
+        raise WizardError(t["errors"]["invalid_decision"])
+    if value == "later":
+        item_id = state.design_prep_current
+        _advance_design_prep_item(state)
+        return t["echo_variants"]["later"].format(item_id=item_id)
+    state.design_prep_decision = value
+    state.design_prep_overrides_json = ""
+    state.design_prep_notes = ""
+    return t["echo_template"].format(value=value)
+
+
+def _design_prep_overrides_applies(state: WizardState) -> bool:
+    if state.design_prep_decision == "modify-draft":
+        return not state.design_prep_overrides_json
+    if state.design_prep_decision == "reject-draft":
+        return not state.design_prep_notes
+    return False
+
+
+def _build_design_prep_overrides(state: WizardState) -> Prompt:
+    t = _p(
+        state.workspace_root,
+        S_DESIGN_PREP_OVERRIDES,
+        item_id=state.design_prep_current,
+        decision=state.design_prep_decision,
+    )
+    return Prompt(
+        step=S_DESIGN_PREP_OVERRIDES,
+        kind="text",
+        label=t["label"],
+        echo_template=t["echo_template"],
+    )
+
+
+def _submit_design_prep_overrides(
+    state: WizardState,
+    value: str,
+) -> Optional[str]:
+    t = _p(state.workspace_root, S_DESIGN_PREP_OVERRIDES,
+           item_id=state.design_prep_current,
+           decision=state.design_prep_decision)
+    if state.design_prep_decision == "reject-draft":
+        if not value.strip():
+            raise WizardError(t["errors"]["note_required"])
+        state.design_prep_notes = value.strip()
+        return t["echo_variants"]["note"]
+    try:
+        overrides = json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise WizardError(t["errors"]["invalid_json"].format(error=exc)) from exc
+    if not isinstance(overrides, dict):
+        raise WizardError(t["errors"]["object_required"])
+    state.design_prep_overrides_json = json.dumps(
+        overrides, ensure_ascii=False, sort_keys=True
+    )
+    return t["echo_variants"]["overrides"]
+
+
+def _design_prep_confirm_applies(state: WizardState) -> bool:
+    if state.design_prep_decision == "accept-draft":
+        return True
+    if state.design_prep_decision == "modify-draft":
+        return bool(state.design_prep_overrides_json)
+    if state.design_prep_decision == "reject-draft":
+        return bool(state.design_prep_notes)
+    return False
+
+
+def _build_design_prep_confirm(state: WizardState) -> Prompt:
+    item = _current_design_prep_item(state)
+    t = _p(
+        state.workspace_root,
+        S_DESIGN_PREP_CONFIRM,
+        item_id=state.design_prep_current,
+        decision=state.design_prep_decision,
+        item_snapshot=json.dumps(item, ensure_ascii=False, indent=2, sort_keys=True),
+        overrides=state.design_prep_overrides_json or "{}",
+        notes=state.design_prep_notes or "(none)",
+    )
+    return Prompt(
+        step=S_DESIGN_PREP_CONFIRM,
+        kind="pick",
+        label=t["label"],
+        options=[_opt(value, label) for value, label in _static_options(t)],
+        echo_template=t["echo_template"],
+    )
+
+
+def _submit_design_prep_confirm(
+    state: WizardState,
+    value: str,
+) -> Optional[str]:
+    item_id = state.design_prep_current
+    t = _p(state.workspace_root, S_DESIGN_PREP_CONFIRM,
+           item_id=item_id, decision=state.design_prep_decision,
+           item_snapshot="", overrides="", notes="")
+    if value == "no":
+        state.design_prep_decision = ""
+        state.design_prep_overrides_json = ""
+        state.design_prep_notes = ""
+        return t["echo_variants"]["revise"].format(item_id=item_id)
+    if value != "yes":
+        raise WizardError(t["errors"]["confirmation_required"])
+    overrides = json.loads(state.design_prep_overrides_json or "{}")
+    try:
+        path = write_design_prep_input(
+            Path(state.approved_plan_path),
+            item_id,
+            state.design_prep_decision,
+            overrides,
+            state.design_prep_notes,
+            captured_by="okstra-wizard",
+        )
+    except DesignPrepError as exc:
+        raise WizardError(str(exc)) from exc
+    match = re.search(r"-r(\d+)-([0-9a-f-]{36})\.md$", path.name)
+    if match is None:
+        raise WizardError(f"design preparation writer returned invalid path: {path}")
+    echo = t["echo_variants"]["written"].format(
+        item_id=item_id,
+        revision=int(match.group(1)),
+        input_id=match.group(2),
+        path=path,
+    )
+    _advance_design_prep_item(state)
+    return echo
+
+
 def _build_stage_pick(state: WizardState) -> Prompt:
     """Parse the Stage Map from the approved plan and build the stage picker."""
     t = _p(state.workspace_root, "stage_pick")
@@ -3116,6 +3359,27 @@ STEPS: list[Step] = [
                             and S_APPROVE_PLAN_CONFIRM not in s.answered),
          build=_build_approve_plan_confirm, submit=_submit_approve_plan_confirm,
          owns=("approve_plan_candidate",)),
+    Step(S_DESIGN_PREP_DECISION,
+         applies=_design_prep_decision_applies,
+         build=_build_design_prep_decision,
+         submit=_submit_design_prep_decision,
+         owns=("design_prep_queue", "design_prep_current",
+               "design_prep_decision", "design_prep_overrides_json",
+               "design_prep_notes"),
+         repeatable=True),
+    Step(S_DESIGN_PREP_OVERRIDES,
+         applies=_design_prep_overrides_applies,
+         build=_build_design_prep_overrides,
+         submit=_submit_design_prep_overrides,
+         owns=("design_prep_overrides_json", "design_prep_notes"),
+         repeatable=True),
+    Step(S_DESIGN_PREP_CONFIRM,
+         applies=_design_prep_confirm_applies,
+         build=_build_design_prep_confirm,
+         submit=_submit_design_prep_confirm,
+         owns=("design_prep_decision", "design_prep_overrides_json",
+               "design_prep_notes"),
+         repeatable=True),
     Step(S_STAGE_PICK,
          applies=lambda s: (s.task_type in _STAGE_SCOPED_TASK_TYPES
                             and bool(s.approved_plan_path)
@@ -3374,6 +3638,9 @@ _FIELD_DEFAULTS: dict[str, Any] = {
     "base_ref_pending_text": False, "approved_plan_path": "",
     "approved_plan_pending_text": False, "approve_plan_candidate": "",
     "html_approval_sidecar": "", "html_approval_option": "",
+    "design_prep_queue": [], "design_prep_current": "",
+    "design_prep_decision": "", "design_prep_overrides_json": "",
+    "design_prep_notes": "",
     "selected_stage": "auto",
     "selected_stages": "",
     "handoff_mode": "", "handoff_stages": "",
@@ -3424,9 +3691,9 @@ def _build_group_prompt(state: WizardState, group_id: str) -> Prompt:
     """
     members: list[Prompt] = []
     for sid in PROMPT_GROUPS[group_id]:
-        if sid in state.answered:
-            continue
         step = STEP_BY_ID[sid]
+        if sid in state.answered and not step.repeatable:
+            continue
         if not step.applies(state):
             continue
         members.append(step.build(state))
@@ -3445,7 +3712,7 @@ def next_prompt(state: WizardState) -> Prompt:
     if state.confirmed:
         return Prompt(step=S_DONE, kind="done")
     for step in STEPS:
-        if step.id in state.answered:
+        if step.id in state.answered and not step.repeatable:
             continue
         if step.applies(state):
             group_id = _STEP_TO_GROUP.get(step.id)
@@ -3488,6 +3755,19 @@ def _sim_advance(state: WizardState, prompt: Prompt) -> None:
                 if q.step not in state.answered:
                     state.answered.append(q.step)
             return
+        if prompt.step == S_DESIGN_PREP_CONFIRM:
+            _advance_design_prep_item(state)
+            if prompt.step not in state.answered:
+                state.answered.append(prompt.step)
+            return
+        if prompt.step == S_DESIGN_PREP_OVERRIDES:
+            if state.design_prep_decision == "modify-draft":
+                state.design_prep_overrides_json = "{}"
+            else:
+                state.design_prep_notes = "simulation"
+            if prompt.step not in state.answered:
+                state.answered.append(prompt.step)
+            return
         STEP_BY_ID[prompt.step].submit(state, _sim_answer(prompt))
         if prompt.step not in state.answered:
             state.answered.append(prompt.step)

package/runtime/python/okstra_token_usage/report.py

@@ -14,6 +14,10 @@ _HERE = Path(__file__).resolve().parent.parent
 if str(_HERE) not in sys.path:
     sys.path.insert(0, str(_HERE))
 
+from okstra_ctl.design_prep import (  # noqa: E402
+    DesignPrepError,
+    materialize_design_prep_requests,
+)
 from okstra_ctl.final_report_paths import final_report_markdown_path  # noqa: E402
 from okstra_ctl.render_final_report import (  # noqa: E402
     FinalReportRenderError,
@@ -216,4 +220,11 @@ def populate_and_render(
         bytes_written = render_to_file(data_path, output_path)
     except FinalReportRenderError as exc:
         raise SubstituteRefusedError(f"render after substitute failed: {exc}") from exc
+    if data_path.name.startswith("final-report-implementation-planning-"):
+        try:
+            materialize_design_prep_requests(data_path)
+        except DesignPrepError as exc:
+            raise SubstituteRefusedError(
+                f"design-prep request materialization failed: {exc}"
+            ) from exc
     return changes, bytes_written