okstra 0.137.0 → 0.138.0

package/runtime/python/okstra_ctl/codex_dispatch.py

@@ -22,6 +22,13 @@ from .final_report_paths import (
     final_report_data_path as _final_report_data_path,
     final_report_markdown_path as _final_report_markdown_path,
 )
+from .initial_prompt_materialization import (
+    InitialPromptMaterializationError,
+    InitialPromptMaterializationRequest,
+    InitialPromptWorkerRequest,
+    PromptDeliveryMode,
+    materialize_initial_prompts,
+)
 from .lead_events import LeadEvent, append_lead_event
 from .dispatch_state import (
     BACKEND_CLI_WRAPPER,
@@ -40,8 +47,6 @@ from .dispatch_state import (
     string_list as _string_list,
     string_value as _string_value,
     utc_now as _utc_now,
-    validate_initial_prompts as _validate_initial_prompts,
-    worker_prompt_path as _worker_prompt_path,
     worker_state as _worker_state,
     worktree_path as _worktree_path,
     write_json as _write_json,
@@ -51,28 +56,12 @@ from .report_finalize import (
     STEP_VALIDATE_RUN,
     FinalizeContext,
     FinalizeError,
-    project_relative_path as _project_relative_path,
     resolve_optional_path as _resolve_optional_path,
     run_finalize,
     run_seq as _run_seq,
 )
 from .wrapper_status import status_path_for_prompt
-from .report_language import resolve_report_language
-from .worker_prompt_headers import WorkerPromptHeaderError, worker_prompt_headers
-from .worker_prompt_contract import PromptRecord, validate_initial_prompt_records
-from .worker_prompt_body import (
-    analysis_input_lines as _analysis_input_lines,
-    analysis_prompt_body as _analysis_prompt_body,
-    existing_input_lines as _existing_input_lines,
-    instruction_path as _instruction_path,
-    mcp_pointer_line as _mcp_pointer_line,
-    report_writer_prompt_body,
-    REPORT_WRITER_WORKER_ID,
-)
-from .worker_prompt_policy import (
-    PromptPlan,
-    resolve_prompt_plan_for_manifest,
-)
+from .worker_prompt_body import REPORT_WRITER_WORKER_ID
 
 
 SUPPORTED_CLI_WORKERS = {
@@ -109,6 +98,18 @@ class DispatchPlan:
         }
 
 
+@dataclass(frozen=True)
+class _DispatchInputs:
+    project_root: Path
+    manifest_path: Path
+    manifest: Mapping[str, Any]
+    selected_workers: tuple[str, ...]
+    team_state_path: Path
+    team_state: Mapping[str, Any]
+    active_context: Mapping[str, Any]
+    lead_events_path: Path
+
+
 def build_dispatch_plan(
     *,
     project_root: Path,
@@ -120,15 +121,60 @@ def build_dispatch_plan(
     enable_codex_report_writer: bool = False,
     report_writer_codex_model: str = "",
 ) -> DispatchPlan:
+    inputs = _load_dispatch_inputs(
+        project_root,
+        run_manifest_path,
+        requested_workers,
+        enable_codex_report_writer=enable_codex_report_writer,
+    )
+    worker_requests, prompt_paths = _materialize_selected_worker_prompts(
+        project_root=inputs.project_root,
+        manifest_path=inputs.manifest_path,
+        workspace_root=workspace_root,
+        team_state=inputs.team_state,
+        selected_workers=inputs.selected_workers,
+        report_writer_codex_model=report_writer_codex_model,
+    )
+    workers = _build_selected_worker_dispatches(
+        project_root=inputs.project_root,
+        manifest=inputs.manifest,
+        team_state=inputs.team_state,
+        active_context=inputs.active_context,
+        workspace_root=workspace_root,
+        okstra_bin=okstra_bin,
+        idle_timeout_seconds=idle_timeout_seconds,
+        selected_workers=inputs.selected_workers,
+        worker_requests=worker_requests,
+        prompt_paths=prompt_paths,
+    )
+    return DispatchPlan(
+        project_root=inputs.project_root,
+        workspace_root=workspace_root,
+        manifest_path=inputs.manifest_path,
+        team_state_path=inputs.team_state_path,
+        lead_events_path=inputs.lead_events_path,
+        manifest=inputs.manifest,
+        workers=workers,
+    )
+
+
+def _load_dispatch_inputs(
+    project_root: Path,
+    run_manifest_path: Path,
+    requested_workers: Sequence[str],
+    *,
+    enable_codex_report_writer: bool,
+) -> _DispatchInputs:
     project_root = project_root.resolve()
     manifest_path = _resolve_project_path(project_root, str(run_manifest_path))
     manifest = _load_json_object(manifest_path, "run manifest")
     _validate_codex_manifest(manifest, manifest_path)
-
-    selected_workers = _select_workers(
-        manifest,
-        requested_workers,
-        enable_codex_report_writer=enable_codex_report_writer,
+    selected_workers = tuple(
+        _select_workers(
+            manifest,
+            requested_workers,
+            enable_codex_report_writer=enable_codex_report_writer,
+        )
     )
     team_state_path = _resolve_required_path(project_root, manifest, "teamStatePath")
     team_state = _load_json_object(team_state_path, "team-state")
@@ -145,17 +191,67 @@ def build_dispatch_plan(
     active_context = _load_optional_json_object(
         _resolve_optional_path(project_root, manifest.get("activeRunContextPath"))
     )
-    lead_events_path = _resolve_required_path(project_root, manifest, "leadEventsPath")
-    _materialize_missing_worker_prompts(
+    return _DispatchInputs(
         project_root=project_root,
+        manifest_path=manifest_path,
         manifest=manifest,
+        selected_workers=selected_workers,
+        team_state_path=team_state_path,
         team_state=team_state,
         active_context=active_context,
-        selected_workers=selected_workers,
-        workspace_root=workspace_root,
-        report_writer_codex_model=report_writer_codex_model,
+        lead_events_path=_resolve_required_path(project_root, manifest, "leadEventsPath"),
     )
-    workers = tuple(
+
+
+def _materialize_selected_worker_prompts(
+    *,
+    project_root: Path,
+    manifest_path: Path,
+    workspace_root: Path,
+    team_state: Mapping[str, Any],
+    selected_workers: Sequence[str],
+    report_writer_codex_model: str,
+) -> tuple[tuple[InitialPromptWorkerRequest, ...], tuple[Path, ...]]:
+    worker_requests = tuple(
+        InitialPromptWorkerRequest(
+            worker_id=worker_id,
+            model=_requested_worker_model(
+                worker_id,
+                team_state,
+                report_writer_codex_model,
+            ),
+        )
+        for worker_id in selected_workers
+    )
+    try:
+        prompt_paths = materialize_initial_prompts(
+            InitialPromptMaterializationRequest(
+                project_root=project_root,
+                run_manifest_path=manifest_path,
+                runtime_root=workspace_root,
+                delivery_mode=PromptDeliveryMode.EAGER_INCLUDE,
+                workers=worker_requests,
+            )
+        )
+    except InitialPromptMaterializationError as exc:
+        raise DispatchError(f"{exc.reason}: {exc}") from exc
+    return worker_requests, prompt_paths
+
+
+def _build_selected_worker_dispatches(
+    *,
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    workspace_root: Path,
+    okstra_bin: Path | None,
+    idle_timeout_seconds: int,
+    selected_workers: Sequence[str],
+    worker_requests: Sequence[InitialPromptWorkerRequest],
+    prompt_paths: Sequence[Path],
+) -> tuple[WorkerJob, ...]:
+    return tuple(
         _build_worker_dispatch(
             worker_id=worker_id,
             project_root=project_root,
@@ -165,19 +261,15 @@ def build_dispatch_plan(
             workspace_root=workspace_root,
             okstra_bin=okstra_bin,
             idle_timeout_seconds=idle_timeout_seconds,
-            report_writer_codex_model=report_writer_codex_model,
+            model_execution_value=worker_request.model,
+            prompt_path=prompt_path,
+        )
+        for worker_id, worker_request, prompt_path in zip(
+            selected_workers,
+            worker_requests,
+            prompt_paths,
+            strict=True,
         )
-        for worker_id in selected_workers
-    )
-    _validate_initial_prompts(manifest, workers)
-    return DispatchPlan(
-        project_root=project_root,
-        workspace_root=workspace_root,
-        manifest_path=manifest_path,
-        team_state_path=team_state_path,
-        lead_events_path=lead_events_path,
-        manifest=manifest,
-        workers=workers,
     )
 
 
@@ -357,146 +449,6 @@ def _parser() -> argparse.ArgumentParser:
     return parser
 
 
-def _materialize_missing_worker_prompts(
-    *,
-    project_root: Path,
-    manifest: Mapping[str, Any],
-    team_state: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    selected_workers: Sequence[str],
-    workspace_root: Path,
-    report_writer_codex_model: str,
-) -> None:
-    for worker_id in selected_workers:
-        prompt_path = _resolve_project_path(
-            project_root, _worker_prompt_path(manifest, worker_id)
-        )
-        if prompt_path.is_file():
-            continue
-        prompt = _render_missing_worker_prompt(
-            project_root=project_root,
-            manifest=manifest,
-            team_state=team_state,
-            active_context=active_context,
-            worker_id=worker_id,
-            workspace_root=workspace_root,
-            report_writer_codex_model=report_writer_codex_model,
-        )
-        prompt_path.parent.mkdir(parents=True, exist_ok=True)
-        prompt_path.write_text(prompt, encoding="utf-8")
-
-
-def _render_missing_worker_prompt(
-    *,
-    project_root: Path,
-    manifest: Mapping[str, Any],
-    team_state: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    worker_id: str,
-    workspace_root: Path,
-    report_writer_codex_model: str,
-) -> str:
-    if worker_id == REPORT_WRITER_WORKER_ID:
-        return _render_missing_report_writer_prompt(
-            project_root=project_root,
-            manifest=manifest,
-            team_state=team_state,
-            active_context=active_context,
-            report_writer_codex_model=report_writer_codex_model,
-        )
-    return _render_missing_analysis_worker_prompt(
-        project_root=project_root,
-        manifest=manifest,
-        team_state=team_state,
-        active_context=active_context,
-        worker_id=worker_id,
-        workspace_root=workspace_root,
-    )
-
-
-def _render_missing_analysis_worker_prompt(
-    *,
-    project_root: Path,
-    manifest: Mapping[str, Any],
-    team_state: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    worker_id: str,
-    workspace_root: Path,
-) -> str:
-    worker_state = _worker_state(team_state, worker_id)
-    result_rel = _require_string(worker_state, "resultPath")
-    prompt_rel = _worker_prompt_path(manifest, worker_id)
-    model = _require_string(worker_state, "modelExecutionValue")
-    role = _analysis_pane_role(manifest, active_context, worker_id)
-    plan = _initial_prompt_plan(manifest, worker_id)
-    lines = _base_prompt_headers(
-        project_root=project_root,
-        manifest=manifest,
-        active_context=active_context,
-        worker_id=worker_id,
-        prompt_rel=prompt_rel,
-        result_rel=result_rel,
-    )
-    lines.extend(_worktree_headers(manifest, active_context, role))
-    lines.extend(
-        _analysis_prompt_body(
-            manifest,
-            active_context,
-            worker_id,
-            model,
-            role,
-            plan,
-        )
-    )
-    executor_tail = _implementation_executor_tail(
-        manifest,
-        active_context,
-        project_root,
-        workspace_root,
-        role,
-    )
-    if executor_tail:
-        lines.extend(["", executor_tail.rstrip()])
-    return "\n".join(lines).rstrip() + "\n"
-
-
-def _render_missing_report_writer_prompt(
-    *,
-    project_root: Path,
-    manifest: Mapping[str, Any],
-    team_state: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    report_writer_codex_model: str,
-) -> str:
-    worker_state = _worker_state(team_state, REPORT_WRITER_WORKER_ID)
-    markdown_path = _resolve_required_path(project_root, manifest, "expectedReportPath")
-    data_json_path = _final_report_data_path(markdown_path)
-    result_rel = _project_relative_path(project_root, data_json_path)
-    worker_result_rel = _require_string(worker_state, "resultPath")
-    model = (report_writer_codex_model or "").strip()
-    if not model:
-        raise DispatchError(
-            "Codex report-writer dispatch requires --report-writer-codex-model"
-        )
-    lines = _base_prompt_headers(
-        project_root=project_root,
-        manifest=manifest,
-        active_context=active_context,
-        worker_id=REPORT_WRITER_WORKER_ID,
-        prompt_rel=_worker_prompt_path(manifest, REPORT_WRITER_WORKER_ID),
-        result_rel=result_rel,
-        audit_source_rel=worker_result_rel,
-    )
-    lines.extend(report_writer_prompt_body(
-        manifest,
-        active_context,
-        team_state,
-        model,
-        resolve_report_language(project_root, manifest, active_context),
-    ))
-    return "\n".join(lines).rstrip() + "\n"
-
-
 def _build_worker_dispatch(
     *,
     worker_id: str,
@@ -507,7 +459,8 @@ def _build_worker_dispatch(
     workspace_root: Path,
     okstra_bin: Path | None,
     idle_timeout_seconds: int,
-    report_writer_codex_model: str,
+    model_execution_value: str,
+    prompt_path: Path,
 ) -> WorkerJob:
     if worker_id == REPORT_WRITER_WORKER_ID:
         return _build_report_writer_dispatch(
@@ -517,15 +470,13 @@ def _build_worker_dispatch(
             workspace_root=workspace_root,
             okstra_bin=okstra_bin,
             idle_timeout_seconds=idle_timeout_seconds,
-            report_writer_codex_model=report_writer_codex_model,
+            model_execution_value=model_execution_value,
+            prompt_path=prompt_path,
         )
     worker_state = _worker_state(team_state, worker_id)
-    prompt_rel = _worker_prompt_path(manifest, worker_id)
-    prompt_path = _resolve_project_path(project_root, prompt_rel)
     result_path = _resolve_project_path(
         project_root, _require_string(worker_state, "resultPath")
     )
-    model_execution_value = _require_string(worker_state, "modelExecutionValue")
     wrapper = _resolve_wrapper(worker_id, workspace_root, okstra_bin)
     worktree_path = _worktree_path(manifest, active_context)
     role = _pane_role(prompt_path)
@@ -555,17 +506,10 @@ def _build_report_writer_dispatch(
     workspace_root: Path,
     okstra_bin: Path | None,
     idle_timeout_seconds: int,
-    report_writer_codex_model: str,
+    model_execution_value: str,
+    prompt_path: Path,
 ) -> WorkerJob:
-    model_execution_value = (report_writer_codex_model or "").strip()
-    if not model_execution_value:
-        raise DispatchError(
-            "Codex report-writer dispatch requires --report-writer-codex-model"
-        )
     worker_state = _worker_state(team_state, REPORT_WRITER_WORKER_ID)
-    prompt_path = _resolve_project_path(
-        project_root, _worker_prompt_path(manifest, REPORT_WRITER_WORKER_ID)
-    )
     data_json_path = _final_report_data_path(
         _resolve_required_path(project_root, manifest, "expectedReportPath")
     )
@@ -573,7 +517,6 @@ def _build_report_writer_dispatch(
     worker_result_path = _resolve_project_path(
         project_root, _require_string(worker_state, "resultPath")
     )
-    _replace_report_writer_model_line(prompt_path, model_execution_value)
     return WorkerJob(
         worker_id=REPORT_WRITER_WORKER_ID,
         # codex 경로의 report-writer 는 claude 가 아니라 codex wrapper 로 돈다.
@@ -597,157 +540,6 @@ def _build_report_writer_dispatch(
     )
 
 
-def _base_prompt_headers(
-    *,
-    project_root: Path,
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    worker_id: str,
-    prompt_rel: str,
-    result_rel: str,
-    audit_source_rel: str | None = None,
-) -> list[str]:
-    try:
-        return worker_prompt_headers(
-            project_root=project_root,
-            prompt_rel=prompt_rel,
-            result_rel=result_rel,
-            audit_source_rel=audit_source_rel,
-            worker_id=worker_id,
-            dispatch_kind="initial",
-            manifest=manifest,
-            active_context=active_context,
-        )
-    except WorkerPromptHeaderError as exc:
-        raise DispatchError(str(exc)) from exc
-
-
-def _initial_prompt_plan(
-    manifest: Mapping[str, Any],
-    worker_id: str,
-) -> PromptPlan:
-    try:
-        return resolve_prompt_plan_for_manifest(
-            manifest=manifest,
-            worker_id=worker_id,
-            dispatch_kind="initial",
-        )
-    except ValueError as exc:
-        raise DispatchError(str(exc)) from exc
-
-
-def _analysis_pane_role(
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    worker_id: str,
-) -> str:
-    if _require_string(manifest, "taskType") != "implementation":
-        return "worker"
-    if _executor_provider(manifest) != worker_id:
-        return "worker"
-    worktree = _worktree_path(manifest, active_context)
-    if not worktree:
-        raise DispatchError("implementation executor prompt generation requires a worktree path")
-    return "executor"
-
-
-def _executor_provider(manifest: Mapping[str, Any]) -> str:
-    team_contract = manifest.get("teamContract")
-    if not isinstance(team_contract, Mapping):
-        return ""
-    executor = team_contract.get("executor")
-    if not isinstance(executor, Mapping):
-        return ""
-    return _string_value(executor.get("provider"))
-
-
-def _worktree_headers(
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    role: str,
-) -> list[str]:
-    task_type = _require_string(manifest, "taskType")
-    worktree = _worktree_path(manifest, active_context)
-    if task_type != "implementation" or not worktree:
-        return []
-    headers = [f"**Worktree:** {worktree}"]
-    if role == "executor":
-        headers.append(f"cwd for every mutating command: {worktree}")
-    return headers
-
-
-def _implementation_executor_tail(
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    project_root: Path,
-    workspace_root: Path,
-    role: str,
-) -> str:
-    if role != "executor" or _require_string(manifest, "taskType") != "implementation":
-        return ""
-    profiles = workspace_root / "prompts" / "profiles"
-    parts: list[str] = []
-    analysis_profile = _instruction_path(
-        manifest,
-        active_context,
-        "analysisProfilePath",
-    )
-    if not analysis_profile:
-        raise DispatchError("implementation executor profile path is missing")
-    executor_profile = (
-        _resolve_project_path(project_root, analysis_profile).parent
-        / "implementation-executor.md"
-    )
-    if not executor_profile.is_file():
-        raise DispatchError(
-            f"resolved implementation executor profile not found: {executor_profile}"
-        )
-    parts.append(executor_profile.read_text(encoding="utf-8"))
-    preflight_path = profiles / "_coding-conventions-preflight.md"
-    if preflight_path.is_file():
-        parts.append(preflight_path.read_text(encoding="utf-8"))
-    else:
-        parts.append("# Coding-conventions preflight\n\nApply project-local conventions before editing.")
-    diff_review_path = profiles / "_implementation-diff-review.md"
-    if diff_review_path.is_file():
-        parts.append(diff_review_path.read_text(encoding="utf-8"))
-    selfcheck_path = profiles / "_implementation-self-check.md"
-    if selfcheck_path.is_file():
-        parts.append(selfcheck_path.read_text(encoding="utf-8"))
-    parts.extend(_clarification_response_section(manifest, active_context, project_root))
-    return "\n\n".join(parts)
-
-
-def _clarification_response_section(
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    project_root: Path,
-) -> list[str]:
-    """The user's answers, inlined for a CLI executor.
-
-    A CLI worker runs in its own process and receives only the prompt text, so
-    a path reference never reaches it. Passing the clarification response as a
-    path meant the executor implemented the pre-answer plan while the report
-    described the answers as carried in — the user answered and nothing
-    downstream acted on it.
-    """
-    relative = _instruction_path(manifest, active_context, "clarificationResponsePath")
-    if not relative:
-        return []
-    path = _resolve_project_path(project_root, relative)
-    if not path.is_file():
-        return []
-    body = path.read_text(encoding="utf-8").strip()
-    if not body:
-        return []
-    return [
-        "# Clarification answers carried in (authoritative)\n\n"
-        "The user answered these before this run. Where an answer conflicts "
-        "with the approved plan text, the answer wins — implement the answer "
-        f"and say so in your result.\n\nSource: `{relative}`\n\n{body}"
-    ]
-
-
 def _validate_codex_manifest(manifest: Mapping[str, Any], path: Path) -> None:
     if manifest.get("leadRuntime") != "codex":
         raise DispatchError(f"run manifest is not a Codex lead run: {path}")
@@ -755,6 +547,24 @@ def _validate_codex_manifest(manifest: Mapping[str, Any], path: Path) -> None:
         raise DispatchError(f"run manifest has no leadEventsPath: {path}")
 
 
+def _requested_worker_model(
+    worker_id: str,
+    team_state: Mapping[str, Any],
+    report_writer_codex_model: str,
+) -> str:
+    if worker_id != REPORT_WRITER_WORKER_ID:
+        return _require_string(
+            _worker_state(team_state, worker_id),
+            "modelExecutionValue",
+        )
+    model = report_writer_codex_model.strip()
+    if model:
+        return model
+    raise DispatchError(
+        "Codex report-writer dispatch requires --report-writer-codex-model"
+    )
+
+
 def _select_workers(
     manifest: Mapping[str, Any],
     requested_workers: Sequence[str],
@@ -1031,23 +841,6 @@ def _failure_reason(exit_code: int, missing_paths: Sequence[Path]) -> str:
     return "worker dispatch failed"
 
 
-def _replace_report_writer_model_line(
-    prompt_path: Path,
-    model_execution_value: str,
-) -> None:
-    if not prompt_path.is_file():
-        raise DispatchError(f"report-writer prompt not found: {prompt_path}")
-    lines = prompt_path.read_text(encoding="utf-8").splitlines()
-    marker = "**Model:** Report writer worker,"
-    replacement = f"{marker} {model_execution_value}"
-    updated = [
-        replacement if line.startswith(marker) else line
-        for line in lines
-    ]
-    if updated != lines:
-        prompt_path.write_text("\n".join(updated) + "\n", encoding="utf-8")
-
-
 def _parse_workers(raw: str) -> list[str]:
     return [item.strip() for item in raw.split(",") if item.strip()]