okstra 0.122.0 → 0.123.0

package/runtime/python/okstra_ctl/run.py

@@ -46,6 +46,7 @@ from .final_report_schema import load_schema
 from .final_report_paths import final_report_data_path as _final_report_data_path
 from .lead_events import LeadEvent, append_lead_event
 from .lead_runtime import ALLOWED_LEAD_RUNTIMES
+from .model_discovery import normalize_execution_for_dispatch
 from .models import ModelAssignment, default_model, resolve_model_metadata
 from .schema_excerpt import build_schema_excerpt
 from .path_resolve import relative_to_project_root, resolve_user_file
@@ -1412,6 +1413,27 @@ def _resolve_model_bindings(inp: PrepareInputs, workers: list[str]) -> _ModelBin
     )
 
 
+def _normalized_execution(meta: ModelAssignment, provider: str, role: str) -> str:
+    """Route a role's catalog execution value through the CLI-identity normalizer
+    so the manifest carries the dispatch-correct spelling. SSOT for the mapping
+    lives in model_discovery; this is only the run.py call seam."""
+    return normalize_execution_for_dispatch(
+        provider=provider, execution=meta.execution, display=meta.display, role=role,
+    )
+
+
+def _worker_execution_value(
+    meta: ModelAssignment, provider: str, role: str, workers: list[str],
+) -> str:
+    """Normalize a worker role's execution value only when that provider's
+    worker is in the resolved roster; otherwise return the raw catalog value.
+    A worker that will not be dispatched must not probe its CLI or hard-fail
+    the whole prep (the CLI-identity check belongs only to workers that run)."""
+    if provider in workers:
+        return _normalized_execution(meta, provider=provider, role=role)
+    return meta.execution
+
+
 StageRunClaim = _implementation_stage.StageRunClaim
 
 
@@ -1577,7 +1599,9 @@ def _write_instruction_set_sources(
     instruction_set = Path(ctx["INSTRUCTION_SET_PATH"])
     instruction_set.mkdir(parents=True, exist_ok=True)
     profile_rendered = profile_content
-    for key in (
+    if inp.task_type == "implementation":
+        profile_rendered += "\n\n{{DESIGN_PREP_CONTEXT}}"
+    profile_tokens = (
         "EXECUTOR_PROVIDER",
         "EXECUTOR_DISPLAY_NAME",
         "EXECUTOR_WORKER_AGENT",
@@ -1588,10 +1612,28 @@ def _write_instruction_set_sources(
         "EXECUTOR_WORKTREE_BASE_REF",
         "EXECUTOR_WORKTREE_STATUS",
         "EXECUTOR_WORKTREE_NOTE",
+        "DESIGN_PREP_CONTEXT",
         "PHASE_FORBIDDEN_ACTIONS",
-    ):
+    )
+    for key in profile_tokens:
         profile_rendered = profile_rendered.replace("{{" + key + "}}", ctx.get(key, ""))
     (instruction_set / "analysis-profile.md").write_text(profile_rendered, encoding="utf-8")
+    if inp.task_type == "implementation":
+        executor_source = (
+            Path(ctx["WORKSPACE_ROOT"])
+            / "prompts"
+            / "profiles"
+            / "_implementation-executor.md"
+        )
+        executor_rendered = executor_source.read_text(encoding="utf-8")
+        for key in profile_tokens:
+            executor_rendered = executor_rendered.replace(
+                "{{" + key + "}}", ctx.get(key, "")
+            )
+        (instruction_set / "implementation-executor.md").write_text(
+            executor_rendered,
+            encoding="utf-8",
+        )
     (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:
@@ -2058,16 +2100,22 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "CLAUDE_WORKER_MODEL": cw.display,
         "CLAUDE_WORKER_MODEL_EXECUTION_VALUE": cw.execution,
         "CODEX_WORKER_MODEL": co.display,
-        "CODEX_WORKER_MODEL_EXECUTION_VALUE": co.execution,
+        "CODEX_WORKER_MODEL_EXECUTION_VALUE": _worker_execution_value(
+            co, "codex", "worker", workers,
+        ),
         "ANTIGRAVITY_WORKER_MODEL": ge.display,
-        "ANTIGRAVITY_WORKER_MODEL_EXECUTION_VALUE": ge.execution,
+        "ANTIGRAVITY_WORKER_MODEL_EXECUTION_VALUE": _worker_execution_value(
+            ge, "antigravity", "worker", workers,
+        ),
         "REPORT_WRITER_MODEL": rw.display,
         "REPORT_WRITER_MODEL_EXECUTION_VALUE": rw.execution,
         "EXECUTOR_PROVIDER": executor_provider,
         "EXECUTOR_DISPLAY_NAME": executor_display_name,
         "EXECUTOR_WORKER_AGENT": executor_worker_agent,
         "EXECUTOR_MODEL_DISPLAY": executor_model_meta.display,
-        "EXECUTOR_MODEL_EXECUTION_VALUE": executor_model_meta.execution,
+        "EXECUTOR_MODEL_EXECUTION_VALUE": _normalized_execution(
+            executor_model_meta, provider=executor_provider, role="executor",
+        ),
         "CRITIC_CHOICE": critic_choice,
         "RELATED_TASKS_JSON": related_tasks_json_str,
         "RELATED_TASKS_BULLETS": bullets,

package/runtime/python/okstra_ctl/user_response.py

@@ -26,6 +26,7 @@ from okstra_ctl.clarification_items import (
     parse_clarification_rows,
     scan_approval_gate,
     section_1_present_but_unparsed,
+    _section_1_slice,
 )
 
 _APPROVAL_HEADING_RE = re.compile(r"^## APPROVAL\s*$", re.MULTILINE)
@@ -146,8 +147,14 @@ def list_awaiting_tasks(home: Path, project_id: str, limit: int) -> list[dict]:
     return out[:limit] if limit > 0 else out
 
 
-_SECTION_REF_RE = re.compile(r"§[\d.]+|C-\d+|[\w./-]+\.\w+:\d+")
+# ID tokens are the report body's own cross-reference labels (RB-002, FU-001,
+# O-002, C-017 …) — always uppercase-led so `gpt-5` and lowercase slugs don't
+# match. `§x.y` and `path.ext:line` are the other two ref shapes.
+_SECTION_REF_RE = re.compile(r"§[\d.]+|[A-Z]{1,4}-\d+|[\w./-]+\.\w+:\d+")
+_ID_TOKEN_RE = re.compile(r"^[A-Z]{1,4}-\d+$")
 _ALTERNATIVES_CUE = "Alternatives:"
+_DEFINITION_SNIPPET_CAP = 200
+_SNIPPET_NOISE_RE = re.compile(r'<a id="[^"]*"></a>|`|\*\*')
 
 
 def _alternatives_from_expected(expected_form: str) -> list[str]:
@@ -159,6 +166,63 @@ def _alternatives_from_expected(expected_form: str) -> list[str]:
     return [p.strip(" .,;—-") for p in parts if p.strip(" .,;—-")]
 
 
+def _clean_snippet(line: str) -> str:
+    s = _SNIPPET_NOISE_RE.sub("", line).strip()
+    s = re.sub(r"^[-*+]\s+|^\d+\.\s+", "", s)  # drop a leading list marker
+    s = re.sub(r"\s*\|\s*", " | ", s).strip(" |")
+    s = re.sub(r"\s+", " ", s)
+    if len(s) > _DEFINITION_SNIPPET_CAP:
+        s = s[:_DEFINITION_SNIPPET_CAP].rstrip() + "…"
+    return s
+
+
+def _resolve_id_token(report_text: str, token: str, s1_slice: str | None) -> str | None:
+    """Find where an internal report token (RB-002, FU-001, …) is defined.
+
+    Prefer a body line where the token is followed by a `:`/`—`/`-`/`)`
+    separator (its definition), else the first body occurrence. §1 rows are
+    skipped so the clarification statement being explained is never returned
+    as its own definition."""
+    definition_re = re.compile(rf"{re.escape(token)}\**\s*[)\]]?\s*[:—–-]")
+    fallback: str | None = None
+    for line in report_text.splitlines():
+        if token not in line:
+            continue
+        stripped = line.strip()
+        if s1_slice is not None and stripped and stripped in s1_slice:
+            continue
+        if definition_re.search(stripped):
+            return _clean_snippet(stripped)
+        if fallback is None:
+            fallback = _clean_snippet(stripped)
+    return fallback
+
+
+def _resolve_section_ref(report_text: str, ref: str) -> str | None:
+    num = ref.lstrip("§")
+    heading_re = re.compile(rf"^#{{1,6}}\s+{re.escape(num)}(?=[.\s]).*$", re.MULTILINE)
+    m = heading_re.search(report_text)
+    return _clean_snippet(m.group(0).lstrip("# ").strip()) if m else None
+
+
+def resolve_refs(report_text: str, refs: list[str]) -> list[dict]:
+    """Resolve each context ref to its plain-text definition from the report
+    body, or None when the report text alone cannot resolve it (a `path:line`
+    pointer). The deterministic lookup the skill uses to rewrite each
+    clarification question in self-contained plain language."""
+    s1_slice = _section_1_slice(report_text)
+    resolved: list[dict] = []
+    for ref in refs:
+        if ref.startswith("§"):
+            definition = _resolve_section_ref(report_text, ref)
+        elif _ID_TOKEN_RE.match(ref):
+            definition = _resolve_id_token(report_text, ref, s1_slice)
+        else:
+            definition = None
+        resolved.append({"ref": ref, "definition": definition})
+    return resolved
+
+
 def show_open_rows(report_path: Path) -> dict:
     text = report_path.read_text(encoding="utf-8")
     rows = []
@@ -172,7 +236,8 @@ def show_open_rows(report_path: Path) -> dict:
                      "status": it.status, "statement": statement,
                      "recommended": expected,  # raw cell keeps answer + rationale
                      "alternatives": _alternatives_from_expected(expected),
-                     "contextRefs": refs})
+                     "contextRefs": refs,
+                     "resolvedRefs": resolve_refs(text, refs)})
     return {"reportPath": str(report_path), "rows": rows}
 
 

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