okstra 0.137.0 → 0.138.0

package/runtime/python/okstra_ctl/initial_prompt_materialization.py

@@ -0,0 +1,1053 @@
+"""Render, validate, and immutably publish initial worker prompts."""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any, Callable, Literal, Mapping, Sequence
+
+from .final_report_paths import final_report_data_path
+from .path_hints import hydrate_active_run_context
+from .report_language import resolve_report_language
+from .worker_prompt_body import (
+    REPORT_WRITER_WORKER_ID,
+    analysis_prompt_body,
+    instruction_path,
+    report_writer_prompt_body,
+)
+from .worker_prompt_contract import PromptRecord, validate_initial_prompt_records
+from .worker_prompt_headers import worker_prompt_headers
+from .worker_prompt_policy import PromptPlan, resolve_prompt_plan_for_manifest
+
+
+class PromptDeliveryMode(str, Enum):
+    EAGER_INCLUDE = "eager-include"
+    LAZY_PATH_REFERENCE = "lazy-path-reference"
+
+
+MaterializationReason = Literal[
+    "existing_prompt_invalid",
+    "existing_prompt_conflict",
+    "required_input_missing",
+    "render_failed",
+    "validation_failed",
+    "publication_failed",
+]
+
+
+@dataclass(frozen=True)
+class InitialPromptWorkerRequest:
+    worker_id: str
+    model: str
+
+
+@dataclass(frozen=True)
+class InitialPromptMaterializationRequest:
+    project_root: Path
+    run_manifest_path: Path
+    runtime_root: Path
+    delivery_mode: PromptDeliveryMode
+    workers: tuple[InitialPromptWorkerRequest, ...]
+
+
+class InitialPromptMaterializationError(RuntimeError):
+    reason: MaterializationReason
+
+    def __init__(self, reason: MaterializationReason, message: str) -> None:
+        super().__init__(message)
+        self.reason = reason
+
+
+MaterializeInitialPrompts = Callable[
+    [InitialPromptMaterializationRequest],
+    tuple[Path, ...],
+]
+
+_MATERIALIZABLE_AUDIENCES = frozenset({
+    "analysis",
+    "implementation-executor",
+    "implementation-verifier",
+    "report-writer",
+})
+_CLARIFICATION_INPUT_PREFIX = "- Clarification response:"
+_CLARIFICATION_AUTHORITY_HEADING = (
+    "# Clarification answers carried in (authoritative)"
+)
+_CLARIFICATION_AUTHORITY_HEADING_PREFIX = (
+    "# Clarification answers carried in"
+)
+_CLARIFICATION_AUTHORITY_INTRO = (
+    "The user answered these before this run. Where an answer conflicts "
+    "with the approved plan text, the answer wins — implement the answer "
+    "and say so in your result."
+)
+_CLARIFICATION_SOURCE_PREFIX = "Source:"
+_REQUIRED_PROMPT_RESOURCES_HEADING = "## Required prompt resources"
+
+
+@dataclass(frozen=True)
+class _MaterializationContext:
+    request: InitialPromptMaterializationRequest
+    project_root: Path
+    manifest: Mapping[str, Any]
+    team_state: Mapping[str, Any]
+    active_context: Mapping[str, Any]
+
+
+@dataclass(frozen=True)
+class _PromptItem:
+    worker: InitialPromptWorkerRequest
+    final_path: Path
+    plan: PromptPlan
+    existed: bool
+    clarification_input: tuple[str, Path] | None = None
+    resources: tuple["_PromptResource", ...] = ()
+    temp_path: Path | None = None
+
+
+@dataclass(frozen=True)
+class _PromptResource:
+    path: Path
+    text: str
+
+
+@dataclass(frozen=True)
+class _PublishedPrompt:
+    worker: InitialPromptWorkerRequest
+    path: Path
+    plan: PromptPlan
+    existed: bool
+
+
+def materialize_initial_prompts(
+    request: InitialPromptMaterializationRequest,
+) -> tuple[Path, ...]:
+    """Materialize selected initial prompts in request order."""
+    try:
+        return _materialize_initial_prompts(request)
+    except InitialPromptMaterializationError:
+        raise
+    except Exception as exc:
+        raise InitialPromptMaterializationError(
+            "render_failed",
+            f"unexpected initial prompt materialization failure: {exc}",
+        ) from exc
+
+
+def _materialize_initial_prompts(
+    request: InitialPromptMaterializationRequest,
+) -> tuple[Path, ...]:
+    context = _load_materialization_context(request)
+    resolved_items = [
+        _resolve_prompt_item(context, worker)
+        for worker in request.workers
+    ]
+    items: list[_PromptItem] = []
+    completed = False
+    try:
+        for item in resolved_items:
+            items.append(_prepare_prompt_item(context, item))
+        _validate_prepublication_set(context, items)
+        published = tuple(
+            _publish_or_reuse(context, item)
+            for item in items
+        )
+        _validate_published_set(context, published)
+        completed = True
+        return tuple(prompt.path for prompt in published)
+    finally:
+        cleanup_error = _remove_temp_files(items)
+        if completed and cleanup_error is not None:
+            raise InitialPromptMaterializationError(
+                "publication_failed",
+                f"cannot remove prompt staging file: {cleanup_error}",
+            ) from cleanup_error
+
+
+def _load_materialization_context(
+    request: InitialPromptMaterializationRequest,
+) -> _MaterializationContext:
+    project_root = request.project_root.resolve()
+    if not isinstance(request.delivery_mode, PromptDeliveryMode):
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            "delivery_mode must be a PromptDeliveryMode",
+        )
+    manifest_path = _resolve_input_path(project_root, request.run_manifest_path)
+    manifest = _load_json_object(manifest_path, "run manifest")
+    team_state = _load_referenced_json(project_root, manifest, "teamStatePath")
+    active_context = hydrate_active_run_context(
+        _load_referenced_json(
+            project_root,
+            manifest,
+            "activeRunContextPath",
+        )
+    )
+    return _MaterializationContext(
+        request=request,
+        project_root=project_root,
+        manifest=manifest,
+        team_state=team_state,
+        active_context=active_context,
+    )
+
+
+def _resolve_prompt_item(
+    context: _MaterializationContext,
+    worker: InitialPromptWorkerRequest,
+) -> _PromptItem:
+    _validate_worker_request(worker)
+    plan = _prompt_plan(context.manifest, worker.worker_id)
+    if plan.audience not in _MATERIALIZABLE_AUDIENCES:
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            f"prompt audience is not materializable: {plan.audience}",
+        )
+    clarification_input = _resolve_clarification_input(context, plan)
+    final_path = _worker_prompt_path(context, worker.worker_id)
+    existed = final_path.exists()
+    return _PromptItem(
+        worker=worker,
+        final_path=final_path,
+        plan=plan,
+        existed=existed,
+        clarification_input=clarification_input,
+    )
+
+
+def _prepare_prompt_item(
+    context: _MaterializationContext,
+    item: _PromptItem,
+) -> _PromptItem:
+    resources = _resolve_prompt_resources(
+        context,
+        item.plan,
+        existed=item.existed,
+    )
+    prepared_item = _with_prompt_resources(item, resources)
+    if item.existed:
+        _validate_existing_prompt(context, prepared_item)
+        return prepared_item
+    temp_path: Path | None = None
+    try:
+        item.final_path.parent.mkdir(parents=True, exist_ok=True)
+        text = _render_prompt(context, prepared_item)
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=item.final_path.parent,
+            prefix=f".{item.final_path.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as handle:
+            temp_path = Path(handle.name)
+            handle.write(text)
+    except InitialPromptMaterializationError:
+        raise
+    except Exception as exc:
+        if temp_path is not None:
+            try:
+                temp_path.unlink(missing_ok=True)
+            except OSError:
+                pass
+        raise InitialPromptMaterializationError(
+            "render_failed",
+            f"cannot render initial prompt for {item.worker.worker_id}: {exc}",
+        ) from exc
+    if temp_path is None:
+        raise InitialPromptMaterializationError(
+            "render_failed",
+            f"no staging file was created for {item.worker.worker_id}",
+        )
+    return _PromptItem(
+        worker=item.worker,
+        final_path=item.final_path,
+        plan=item.plan,
+        existed=False,
+        clarification_input=item.clarification_input,
+        resources=resources,
+        temp_path=temp_path,
+    )
+
+
+def _with_prompt_resources(
+    item: _PromptItem,
+    resources: tuple[_PromptResource, ...],
+) -> _PromptItem:
+    return _PromptItem(
+        worker=item.worker,
+        final_path=item.final_path,
+        plan=item.plan,
+        existed=item.existed,
+        clarification_input=item.clarification_input,
+        resources=resources,
+        temp_path=item.temp_path,
+    )
+
+
+def _render_prompt(
+    context: _MaterializationContext,
+    item: _PromptItem,
+) -> str:
+    worker = item.worker
+    state = _worker_state(context.team_state, worker.worker_id)
+    prompt_rel = _project_relative(context.project_root, item.final_path)
+    result_rel, audit_source_rel = _result_paths(context, state, worker.worker_id)
+    try:
+        lines = worker_prompt_headers(
+            project_root=context.project_root,
+            prompt_rel=prompt_rel,
+            result_rel=result_rel,
+            audit_source_rel=audit_source_rel,
+            worker_id=worker.worker_id,
+            dispatch_kind="initial",
+            manifest=context.manifest,
+            active_context=context.active_context,
+        )
+        lines.append(
+            f"**Prompt Delivery Mode:** {context.request.delivery_mode.value}"
+        )
+        lines.extend(_worktree_lines(context, item.plan))
+        lines.extend(_prompt_body(context, state, worker, item.plan))
+        lines.extend(_resource_lines(context, item))
+    except InitialPromptMaterializationError:
+        raise
+    except Exception as exc:
+        raise InitialPromptMaterializationError(
+            "render_failed",
+            f"cannot compose initial prompt for {worker.worker_id}: {exc}",
+        ) from exc
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _prompt_body(
+    context: _MaterializationContext,
+    state: Mapping[str, Any],
+    worker: InitialPromptWorkerRequest,
+    plan: PromptPlan,
+) -> list[str]:
+    if plan.audience == "report-writer":
+        return report_writer_prompt_body(
+            context.manifest,
+            context.active_context,
+            context.team_state,
+            worker.model,
+            resolve_report_language(
+                context.project_root,
+                context.manifest,
+                context.active_context,
+            ),
+        )
+    return analysis_prompt_body(
+        context.manifest,
+        context.active_context,
+        worker.worker_id,
+        worker.model,
+        _worker_role(plan),
+        plan,
+    )
+
+
+def _resource_lines(
+    context: _MaterializationContext,
+    item: _PromptItem,
+) -> list[str]:
+    if not item.resources:
+        return []
+    if context.request.delivery_mode is PromptDeliveryMode.LAZY_PATH_REFERENCE:
+        return [
+            "",
+            _REQUIRED_PROMPT_RESOURCES_HEADING,
+            "",
+            *(f"- `{resource.path}`" for resource in item.resources),
+        ]
+    bodies = [resource.text.rstrip() for resource in item.resources]
+    clarification = (
+        _eager_executor_clarification(item.clarification_input)
+        if item.plan.audience == "implementation-executor"
+        else ""
+    )
+    if clarification:
+        bodies.append(clarification)
+    return ["", "\n\n".join(bodies)]
+
+
+def _resolve_clarification_input(
+    context: _MaterializationContext,
+    plan: PromptPlan,
+) -> tuple[str, Path] | None:
+    relative = instruction_path(
+        context.manifest,
+        context.active_context,
+        "clarificationResponsePath",
+    )
+    if not relative:
+        return None
+    path = _resolve_owned_artifact_path(
+        context.project_root,
+        Path(relative),
+        "clarification response path",
+    )
+    return relative, path
+
+
+def _eager_executor_clarification(
+    clarification_input: tuple[str, Path] | None,
+) -> str:
+    if clarification_input is None:
+        return ""
+    relative, _ = clarification_input
+    body = _clarification_body(clarification_input)
+    if not body:
+        return ""
+    return (
+        f"{_CLARIFICATION_AUTHORITY_HEADING}\n\n"
+        f"{_CLARIFICATION_AUTHORITY_INTRO}\n\n"
+        f"Source: `{relative}`\n\n{body}"
+    )
+
+
+def _clarification_body(
+    clarification_input: tuple[str, Path] | None,
+) -> str:
+    if clarification_input is None:
+        return ""
+    _, path = clarification_input
+    if not path.is_file():
+        return ""
+    return _read_required_text(path, "required clarification response").strip()
+
+
+def _read_required_nonempty_text(path: Path, label: str) -> str:
+    text = _read_required_text(path, label)
+    if text.strip():
+        return text
+    cause = ValueError(f"{label} is empty: {path}")
+    raise InitialPromptMaterializationError(
+        "required_input_missing",
+        str(cause),
+    ) from cause
+
+
+def _read_required_text(path: Path, label: str) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            f"{label} cannot be read: {path}",
+        ) from exc
+
+
+def _resolve_prompt_resources(
+    context: _MaterializationContext,
+    plan: PromptPlan,
+    *,
+    existed: bool,
+) -> tuple[_PromptResource, ...]:
+    paths = _required_resource_path_candidates(context, plan)
+    if existed and context.request.delivery_mode is PromptDeliveryMode.EAGER_INCLUDE:
+        return ()
+    return tuple(
+        _PromptResource(
+            path=path.resolve(),
+            text=_read_required_nonempty_text(path, "required prompt resource"),
+        )
+        for path in paths
+    )
+
+
+def _required_resource_path_candidates(
+    context: _MaterializationContext,
+    plan: PromptPlan,
+) -> tuple[Path, ...]:
+    profiles = context.request.runtime_root.resolve() / "prompts" / "profiles"
+    if plan.audience == "implementation-executor":
+        paths = (
+            _executor_profile_path(context),
+            profiles / "_coding-conventions-preflight.md",
+            profiles / "_implementation-diff-review.md",
+            profiles / "_implementation-self-check.md",
+        )
+    elif plan.audience == "implementation-verifier":
+        paths = (
+            profiles / "_implementation-verifier.md",
+            profiles / "_implementation-self-check.md",
+        )
+    else:
+        return ()
+    return paths
+
+
+def _executor_profile_path(context: _MaterializationContext) -> Path:
+    instruction_set = context.active_context.get("instructionSet")
+    value = ""
+    if isinstance(instruction_set, Mapping):
+        value = _string_value(instruction_set.get("analysisProfilePath"))
+    value = value or _string_value(context.manifest.get("analysisProfilePath"))
+    if not value:
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            "implementation executor profile path is missing",
+        )
+    return _resolve_owned_artifact_path(
+        context.project_root,
+        _resolve_input_path(context.project_root, Path(value)).parent
+        / "implementation-executor.md",
+        "implementation executor profile path",
+    )
+
+
+def _validate_prepublication_set(
+    context: _MaterializationContext,
+    items: Sequence[_PromptItem],
+) -> None:
+    records = [_item_record(context, item) for item in items]
+    _validate_existing_record_subset(
+        context.manifest,
+        [
+            record
+            for item, record in zip(items, records, strict=True)
+            if item.existed
+        ],
+        "prepublication",
+    )
+    for item, record in zip(items, records, strict=True):
+        if item.existed:
+            continue
+        errors = validate_initial_prompt_records(
+            manifest=context.manifest,
+            records=[record],
+        )
+        if errors:
+            raise InitialPromptMaterializationError(
+                "validation_failed",
+                "rendered initial prompt contract: " + "; ".join(errors),
+            )
+    errors = validate_initial_prompt_records(
+        manifest=context.manifest,
+        records=records,
+    )
+    if errors:
+        raise InitialPromptMaterializationError(
+            "validation_failed",
+            "prepublication initial prompt contract: " + "; ".join(errors),
+        )
+
+
+def _publish_or_reuse(
+    context: _MaterializationContext,
+    item: _PromptItem,
+) -> _PublishedPrompt:
+    if item.existed:
+        return _published_prompt(item, existed=True)
+    temp_path = _required_temp_path(item)
+    try:
+        os.link(temp_path, item.final_path)
+    except FileExistsError:
+        _validate_existing_prompt(context, item)
+        return _published_prompt(item, existed=True)
+    except OSError as exc:
+        raise InitialPromptMaterializationError(
+            "publication_failed",
+            f"cannot publish initial prompt {item.final_path}: {exc}",
+        ) from exc
+    return _published_prompt(item, existed=False)
+
+
+def _validate_existing_prompt(
+    context: _MaterializationContext,
+    item: _PromptItem,
+) -> None:
+    text = _require_readable_prompt(
+        item.final_path,
+        item.worker.worker_id,
+        "existing_prompt_invalid",
+    )
+    _validate_existing_clarification_metadata(context, item, text)
+    _validate_existing_resource_metadata(context, item, text)
+    basic_record = PromptRecord(
+        item.worker.worker_id,
+        "initial",
+        item.final_path,
+    )
+    basic_errors = validate_initial_prompt_records(
+        manifest=context.manifest,
+        records=[basic_record],
+    )
+    if basic_errors:
+        raise InitialPromptMaterializationError(
+            "existing_prompt_invalid",
+            "existing initial prompt contract: " + "; ".join(basic_errors),
+        )
+    expected_record = PromptRecord(
+        item.worker.worker_id,
+        "initial",
+        item.final_path,
+        expected_model=item.worker.model,
+        expected_delivery_mode=context.request.delivery_mode.value,
+    )
+    expected_errors = validate_initial_prompt_records(
+        manifest=context.manifest,
+        records=[expected_record],
+    )
+    if expected_errors:
+        reason = _existing_metadata_reason(expected_errors)
+        raise InitialPromptMaterializationError(
+            reason,
+            "existing initial prompt metadata: " + "; ".join(expected_errors),
+        )
+
+
+def _validate_existing_clarification_metadata(
+    context: _MaterializationContext,
+    item: _PromptItem,
+    text: str,
+) -> None:
+    expected = (
+        item.clarification_input[0]
+        if item.clarification_input is not None
+        else None
+    )
+    enumerated = (
+        item.plan.audience in _MATERIALIZABLE_AUDIENCES
+        and not item.plan.packet_only
+    )
+    input_values = _backticked_line_values(
+        _markdown_section(text, "## Inputs"),
+        _CLARIFICATION_INPUT_PREFIX,
+    )
+    expected_inputs = [expected] if expected is not None and enumerated else []
+    if input_values != expected_inputs:
+        _raise_existing_clarification_invalid(
+            item,
+            "Clarification response",
+        )
+    _validate_eager_executor_clarification_authority(
+        context,
+        item,
+        text,
+        expected,
+    )
+
+
+def _validate_eager_executor_clarification_authority(
+    context: _MaterializationContext,
+    item: _PromptItem,
+    text: str,
+    expected: str | None,
+) -> None:
+    authority_expected = (
+        item.plan.audience == "implementation-executor"
+        and context.request.delivery_mode is PromptDeliveryMode.EAGER_INCLUDE
+        and bool(_clarification_body(item.clarification_input))
+    )
+    lines = text.splitlines()
+    heading_indexes = [
+        index
+        for index, line in enumerate(lines)
+        if line.startswith(_CLARIFICATION_AUTHORITY_HEADING_PREFIX)
+    ]
+    if not authority_expected and not heading_indexes:
+        return
+    if expected is None or len(heading_indexes) != 1:
+        _raise_existing_clarification_invalid(item, "clarification authority")
+    expected_lines = [
+        _CLARIFICATION_AUTHORITY_HEADING,
+        "",
+        _CLARIFICATION_AUTHORITY_INTRO,
+        "",
+        f"{_CLARIFICATION_SOURCE_PREFIX} `{expected}`",
+        "",
+    ]
+    heading_index = heading_indexes[0]
+    authority_lines = lines[
+        heading_index:heading_index + len(expected_lines)
+    ]
+    if not authority_expected or authority_lines != expected_lines:
+        _raise_existing_clarification_invalid(item, "clarification authority")
+
+
+def _validate_existing_resource_metadata(
+    context: _MaterializationContext,
+    item: _PromptItem,
+    text: str,
+) -> None:
+    if (
+        context.request.delivery_mode is not PromptDeliveryMode.LAZY_PATH_REFERENCE
+        or not item.resources
+    ):
+        return
+    expected_section = "\n".join([
+        "",
+        *(f"- `{resource.path}`" for resource in item.resources),
+    ])
+    actual_section = _markdown_section(
+        text,
+        _REQUIRED_PROMPT_RESOURCES_HEADING,
+    )
+    if (
+        text.count(_REQUIRED_PROMPT_RESOURCES_HEADING) != 1
+        or actual_section != expected_section
+    ):
+        raise InitialPromptMaterializationError(
+            "existing_prompt_invalid",
+            "existing required prompt resources do not match canonical "
+            f"paths for {item.worker.worker_id}",
+        )
+
+
+def _backticked_line_values(text: str, prefix: str) -> list[str]:
+    values = []
+    for line in text.splitlines():
+        if not line.startswith(prefix):
+            continue
+        suffix = line[len(prefix):].strip()
+        if len(suffix) >= 2 and suffix.startswith("`") and suffix.endswith("`"):
+            values.append(suffix[1:-1])
+        else:
+            values.append("")
+    return values
+
+
+def _markdown_section(text: str, heading: str) -> str:
+    lines = text.splitlines()
+    try:
+        start = lines.index(heading) + 1
+    except ValueError:
+        return ""
+    section = []
+    for line in lines[start:]:
+        if line.startswith("## "):
+            break
+        section.append(line)
+    return "\n".join(section)
+
+
+def _raise_existing_clarification_invalid(
+    item: _PromptItem,
+    field: str,
+) -> None:
+    raise InitialPromptMaterializationError(
+        "existing_prompt_invalid",
+        f"existing {field} metadata does not match active context "
+        f"for {item.worker.worker_id}",
+    )
+
+
+def _validate_published_set(
+    context: _MaterializationContext,
+    prompts: Sequence[_PublishedPrompt],
+) -> None:
+    records = [_published_record(context, prompt) for prompt in prompts]
+    for prompt, record in zip(prompts, records, strict=True):
+        reason: MaterializationReason = (
+            "existing_prompt_invalid"
+            if prompt.existed
+            else "validation_failed"
+        )
+        _require_readable_prompt(prompt.path, prompt.worker.worker_id, reason)
+    _validate_existing_record_subset(
+        context.manifest,
+        [
+            record
+            for prompt, record in zip(prompts, records, strict=True)
+            if prompt.existed
+        ],
+        "published",
+    )
+    for prompt, record in zip(prompts, records, strict=True):
+        if prompt.existed:
+            continue
+        errors = validate_initial_prompt_records(
+            manifest=context.manifest,
+            records=[record],
+        )
+        if errors:
+            raise InitialPromptMaterializationError(
+                "validation_failed",
+                "published initial prompt contract: " + "; ".join(errors),
+            )
+    errors = validate_initial_prompt_records(
+        manifest=context.manifest,
+        records=records,
+    )
+    if errors:
+        raise InitialPromptMaterializationError(
+            "validation_failed",
+            "published initial prompt contract: " + "; ".join(errors),
+        )
+
+
+def _item_record(
+    context: _MaterializationContext,
+    item: _PromptItem,
+) -> PromptRecord:
+    path = item.final_path if item.existed else _required_temp_path(item)
+    return PromptRecord(
+        item.worker.worker_id,
+        "initial",
+        path,
+        expected_model=item.worker.model,
+        expected_delivery_mode=context.request.delivery_mode.value,
+    )
+
+
+def _published_record(
+    context: _MaterializationContext,
+    prompt: _PublishedPrompt,
+) -> PromptRecord:
+    return PromptRecord(
+        prompt.worker.worker_id,
+        "initial",
+        prompt.path,
+        expected_model=prompt.worker.model,
+        expected_delivery_mode=context.request.delivery_mode.value,
+    )
+
+
+def _worker_prompt_path(
+    context: _MaterializationContext,
+    worker_id: str,
+) -> Path:
+    paths = context.manifest.get("workerPromptPathByWorkerId")
+    if not isinstance(paths, Mapping):
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            "run manifest has no workerPromptPathByWorkerId object",
+        )
+    value = _required_string(paths, worker_id)
+    return _resolve_owned_artifact_path(
+        context.project_root,
+        Path(value),
+        "initial prompt path",
+    )
+
+
+def _resolve_owned_artifact_path(
+    project_root: Path,
+    path: Path,
+    label: str,
+) -> Path:
+    resolved = _resolve_input_path(project_root, path).resolve()
+    artifact_root = (project_root / ".okstra").resolve()
+    if resolved == artifact_root or artifact_root not in resolved.parents:
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            f"{label} is outside .okstra: {resolved}",
+        )
+    return resolved
+
+
+def _result_paths(
+    context: _MaterializationContext,
+    state: Mapping[str, Any],
+    worker_id: str,
+) -> tuple[str, str | None]:
+    worker_result = _required_string(state, "resultPath")
+    if worker_id != REPORT_WRITER_WORKER_ID:
+        return worker_result, None
+    expected_report = _required_string(context.manifest, "expectedReportPath")
+    return str(final_report_data_path(Path(expected_report))), worker_result
+
+
+def _worktree_lines(
+    context: _MaterializationContext,
+    plan: PromptPlan,
+) -> list[str]:
+    if plan.audience not in {
+        "implementation-executor",
+        "implementation-verifier",
+    }:
+        return []
+    executor_worktree = context.active_context.get("executorWorktree")
+    value = (
+        _string_value(executor_worktree.get("path"))
+        if isinstance(executor_worktree, Mapping)
+        else ""
+    )
+    if not value:
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            "implementation prompt generation requires a worktree path",
+        )
+    lines = [f"**Worktree:** {value}"]
+    if plan.audience == "implementation-executor":
+        lines.append(f"cwd for every mutating command: {value}")
+    return lines
+
+
+def _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 InitialPromptMaterializationError(
+            "required_input_missing",
+            str(exc),
+        ) from exc
+
+
+def _worker_state(
+    team_state: Mapping[str, Any],
+    worker_id: str,
+) -> Mapping[str, Any]:
+    workers = team_state.get("workers")
+    if isinstance(workers, list):
+        for worker in workers:
+            if isinstance(worker, Mapping) and worker.get("workerId") == worker_id:
+                return worker
+    raise InitialPromptMaterializationError(
+        "required_input_missing",
+        f"team-state has no workerId={worker_id}",
+    )
+
+
+def _load_referenced_json(
+    project_root: Path,
+    payload: Mapping[str, Any],
+    key: str,
+) -> Mapping[str, Any]:
+    value = _required_string(payload, key)
+    return _load_json_object(
+        _resolve_input_path(project_root, Path(value)),
+        key,
+    )
+
+
+def _load_json_object(path: Path, label: str) -> Mapping[str, Any]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            f"cannot load {label}: {path}: {exc}",
+        ) from exc
+    if not isinstance(payload, dict):
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            f"{label} must be a JSON object: {path}",
+        )
+    return payload
+
+
+def _required_string(payload: Mapping[str, Any], key: str) -> str:
+    value = _string_value(payload.get(key))
+    if not value:
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            f"missing required string field: {key}",
+        )
+    return value
+
+
+def _validate_worker_request(worker: InitialPromptWorkerRequest) -> None:
+    if worker.worker_id.strip() and worker.model.strip():
+        return
+    raise InitialPromptMaterializationError(
+        "required_input_missing",
+        "worker_id and model are required",
+    )
+
+
+def _worker_role(plan: PromptPlan) -> str:
+    if plan.audience == "implementation-executor":
+        return "executor"
+    if plan.audience == "implementation-verifier":
+        return "verifier"
+    return "worker"
+
+
+def _existing_metadata_reason(
+    errors: Sequence[str],
+) -> MaterializationReason:
+    if any("does not match requested" in error for error in errors):
+        return "existing_prompt_conflict"
+    return "existing_prompt_invalid"
+
+
+def _validate_existing_record_subset(
+    manifest: Mapping[str, Any],
+    records: Sequence[PromptRecord],
+    stage: str,
+) -> None:
+    errors = validate_initial_prompt_records(
+        manifest=manifest,
+        records=records,
+    )
+    if errors:
+        raise InitialPromptMaterializationError(
+            "existing_prompt_invalid",
+            f"{stage} existing initial prompt contract: " + "; ".join(errors),
+        )
+
+
+def _published_prompt(
+    item: _PromptItem,
+    *,
+    existed: bool,
+) -> _PublishedPrompt:
+    return _PublishedPrompt(
+        worker=item.worker,
+        path=item.final_path,
+        plan=item.plan,
+        existed=existed,
+    )
+
+
+def _require_readable_prompt(
+    path: Path,
+    worker_id: str,
+    reason: MaterializationReason,
+) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise InitialPromptMaterializationError(
+            reason,
+            f"cannot read prompt for {worker_id}: {path}: {exc}",
+        ) from exc
+
+
+def _required_temp_path(item: _PromptItem) -> Path:
+    if item.temp_path is not None:
+        return item.temp_path
+    raise InitialPromptMaterializationError(
+        "render_failed",
+        f"no staging file exists for {item.worker.worker_id}",
+    )
+
+
+def _project_relative(project_root: Path, path: Path) -> str:
+    return path.relative_to(project_root).as_posix()
+
+
+def _resolve_input_path(project_root: Path, path: Path) -> Path:
+    return path if path.is_absolute() else project_root / path
+
+
+def _remove_temp_files(
+    items: Sequence[_PromptItem],
+) -> OSError | None:
+    first_error = None
+    for item in items:
+        if item.temp_path is None:
+            continue
+        try:
+            item.temp_path.unlink(missing_ok=True)
+        except OSError as exc:
+            first_error = first_error or exc
+    return first_error
+
+
+def _string_value(value: Any) -> str:
+    return value.strip() if isinstance(value, str) else ""