okstra 0.137.0 → 0.138.0

package/runtime/python/okstra_ctl/render.py

@@ -1948,10 +1948,15 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
         "- Worker prompt paths in `task-manifest.json` are assigned prompt-history "
         "locations, not pre-rendered completion markers. An absent file means its "
         "dispatch history has not been materialized yet.\n"
-        "- Construct each required worker prompt and follow the lifecycle core plus "
-        "selected adapter to persist its assigned history through `write_artifact` "
-        "and start it through `dispatch_worker`. Existing-history handling must stay "
-        "idempotent under those contracts.\n"
+        "- Code-backed `dispatch_worker` mappings leave missing roster prompts to "
+        "`okstra_ctl.initial_prompt_materialization` and its canonical "
+        "`materialize_initial_prompts()` entry point. The selected adapter supplies "
+        "its declared delivery mode; do not construct or overwrite those prompts "
+        "manually.\n"
+        "- For native in-process dispatch, use the same canonical initial-prompt headers, "
+        "persist the assigned prompt history through `write_artifact`, and apply "
+        "the adapter-declared `lazy-path-reference` delivery mode before starting the "
+        "worker. This native path does not apply to reverify or critic dispatches.\n"
         "- Use `await_workers` through the selected adapter and confirm terminal state "
         "plus every required Result Path. File presence alone is never a signal to "
         "skip; worker selection and skipped status come from `team-state`.\n"

package/runtime/python/okstra_ctl/run.py

@@ -96,11 +96,7 @@ from .workflow import compute_workflow_state, load_phase_forbidden
 from .locks import worktree_provision_mutex
 from . import stage_targets as _stage_targets
 from .plan_run_root import plan_run_root_from_approved_plan
-from . import stage_integrate as _stage_integrate
 from . import implementation_stage as _implementation_stage
-from .stage_reconcile import (
-    auto_reconcile_best_effort as _stage_auto_reconcile_best_effort,
-)
 from .work_categories import resolve_work_category
 from .worktree import (
     WorktreeProvision,
@@ -437,40 +433,13 @@ def _validate_stage_structure(plan_path: str) -> None:
 
 
 RUN_STEP_BUDGET = _stage_targets.RUN_STEP_BUDGET
-_FVTarget = _stage_targets.FinalVerificationTarget
-
-
-def _stage_target_prepare_error(exc: _stage_targets.StageTargetError) -> PrepareError:
-    return PrepareError(str(exc))
-
-
-
-
-
-
-def _resolve_single_stage_target(
-    *, requested_stage: str, done_rows: list, stage_base: str,
-    stage_worktree_path: str, stage_head: str, stage_dirty: bool,
-) -> "_FVTarget":
-    """Compatibility wrapper for single-stage verification target selection."""
-    try:
-        return _stage_targets.resolve_single_stage_target(
-            requested_stage=requested_stage,
-            done_rows=done_rows,
-            stage_base=stage_base,
-            stage_worktree_path=stage_worktree_path,
-            stage_head=stage_head,
-            stage_dirty=stage_dirty,
-        )
-    except _stage_targets.StageTargetError as exc:
-        raise _stage_target_prepare_error(exc) from exc
 
 
 def _stage_map_reject_detail(stages, errs):
     """빈/손상 Stage Map 의 거부 사유 문자열을 돌려준다. 정상이면 None.
 
     빈/손상 Stage Map 을 흘려보내면 whole-task 완료 게이트
-    (resolve_whole_task_target 의 `for stage in stage_map`)가 0회 순회로 vacuous
+    (`_resolve_whole_task_target`의 `for stage in stage_map`)가 0회 순회로 vacuous
     통과해 미완 task 를 '완성'으로 배포·검증한다. 빈 파싱(heading rename·표 손상)과
     stage 번호 비단조(중간 행 누락 → S2)의 판정을 한 곳에 모아, run.py 의 prepare
     게이트와 wizard 의 stage picker 가 같은 기준을 상속하게 한다(single-reference)."""
@@ -1432,16 +1401,6 @@ def _git_out(cwd, *args) -> str:
     return r.stdout.strip() if r.returncode == 0 else ""
 
 
-def _auto_reconcile_best_effort(inp: "PrepareInputs", plan_run_root: Path) -> None:
-    _stage_auto_reconcile_best_effort(inp, plan_run_root)
-
-
-
-def _is_dirty_excluding_okstra(cwd) -> bool:
-    from .worktree import is_dirty_excluding_okstra
-    return is_dirty_excluding_okstra(cwd)
-
-
 def _single_stage_final_verification_worktree(inp: "PrepareInputs") -> WorktreeProvision:
     """Placeholder until the selected stage registry row is resolved."""
     return WorktreeProvision(
@@ -1471,57 +1430,46 @@ def _format_integration(integ) -> str:
     return "\n".join(lines)
 
 
-def _reserve_final_verification_target(
-    inp: "PrepareInputs", ctx: dict, ctx_stage_map: list,
+def _final_verification_target_request(
+    inp: "PrepareInputs",
+    ctx_stage_map: list[dict],
+) -> _stage_targets.FinalVerificationTargetRequest:
+    stage = (
+        int(inp.stage)
+        if inp.stage and inp.stage != "auto"
+        else None
+    )
+    return _stage_targets.FinalVerificationTargetRequest(
+        project_root=Path(inp.project_root),
+        project_id=inp.project_id,
+        task_group=inp.task_group,
+        task_id=inp.task_id,
+        work_category=inp.work_category,
+        approved_plan_path=Path(inp.approved_plan_path),
+        stage=stage,
+        stage_map=tuple(ctx_stage_map),
+    )
+
+
+def _apply_final_verification_target(
+    ctx: dict,
+    acquisition: _stage_targets.FinalVerificationTargetAcquisition,
 ) -> None:
-    """final-verification 의 검증 target 을 registry/consumers/git 에서
-    해소하고 gate 를 강제한다. 위반 시 PrepareError. 결과를 ctx 의
-    VERIFICATION_* 키로 주입한다."""
-    from .consumers import backfill_done_from_carry, read_stage_consumer_state
-    from . import worktree_registry as _reg
-
-    plan_run_root = plan_run_root_from_approved_plan(inp.approved_plan_path)
-    # carry sidecars are the SSOT for stage completion — recover missing `done`
-    # rows before the whole-task gate checks every stage.
-    backfill_done_from_carry(plan_run_root)
-    _auto_reconcile_best_effort(inp, plan_run_root)
-    done_rows = read_stage_consumer_state(plan_run_root).done_rows
-
-    if inp.stage and inp.stage != "auto":
-        n = int(inp.stage)
-        row = _reg.get_stage_row(inp.project_id, inp.task_group, inp.task_id, n)
-        wt_path = (row or {}).get("worktree_path", "")
-        stage_base = (row or {}).get("base_ref", "")
-        stage_branch = (row or {}).get("branch", "")
-        head = _git_out(wt_path, "rev-parse", "HEAD") if wt_path else ""
-        target = _resolve_single_stage_target(
-            requested_stage=inp.stage, done_rows=done_rows,
-            stage_base=stage_base, stage_worktree_path=wt_path,
-            stage_head=head,
-            stage_dirty=_is_dirty_excluding_okstra(wt_path) if wt_path else False,
-        )
-        ctx["EXECUTOR_WORKTREE_PATH"] = wt_path
-        ctx["EXECUTOR_WORKTREE_BRANCH"] = stage_branch
-        ctx["EXECUTOR_WORKTREE_BASE_REF"] = stage_base
+    """Translate acquired domain facts into render-context fields."""
+    target = acquisition.target
+    if target.scope == "single-stage":
+        stage = target.stages[0]
+        ctx["EXECUTOR_WORKTREE_PATH"] = target.worktree_path
+        ctx["EXECUTOR_WORKTREE_BRANCH"] = acquisition.worktree_branch
+        ctx["EXECUTOR_WORKTREE_BASE_REF"] = target.base
         ctx["EXECUTOR_WORKTREE_STATUS"] = "reused-stage"
         ctx["EXECUTOR_WORKTREE_NOTE"] = (
-            f"final-verification uses implementation stage {n} worktree"
+            f"final-verification uses implementation stage {stage} worktree"
         )
-    else:
-        wt_path = ctx["EXECUTOR_WORKTREE_PATH"]
-        anchor = _reg.get_implementation_base(
-            inp.project_id, inp.task_group, inp.task_id) or ""
-        # whole-task 통합(머지+teardown)+게이트 강제는 container 와 공유하는
-        # 순수 헬퍼가 단일 책임. ctx 주입만 run.py 측에 남긴다.
-        whole = _stage_targets.resolve_and_integrate_whole_task(
-            project_id=inp.project_id, task_group=inp.task_group,
-            task_id=inp.task_id, task_worktree_path=wt_path,
-            stage_map=ctx_stage_map, done_rows=done_rows,
-            anchor_base=anchor, teardown=True,
+    if acquisition.integration_result is not None:
+        ctx["STAGE_INTEGRATION"] = _format_integration(
+            acquisition.integration_result
         )
-        ctx["STAGE_INTEGRATION"] = _format_integration(whole["integrate_result"])
-        target = whole["target"]
-
     diff_stat = _git_out(target.worktree_path, "diff", "--stat",
                          f"{target.base}..{target.head}")
     ctx["VERIFICATION_SCOPE"] = target.scope
@@ -2263,7 +2211,10 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         ctx["CLAUDE_RESUME_COMMAND_RELATIVE_PATH"] = ""
         ctx["CLAUDE_RESUME_COMMAND_FILENAME"] = ""
     if inp.task_type == "final-verification":
-        _reserve_final_verification_target(inp, ctx, ctx_stage_map)
+        acquisition = _stage_targets.acquire_final_verification_target(
+            _final_verification_target_request(inp, ctx_stage_map)
+        )
+        _apply_final_verification_target(ctx, acquisition)
 
     _write_bundle_artifacts(
         inp, ctx, project_root, lead_runtime, claude_session_id,

package/runtime/python/okstra_ctl/stage_targets.py

@@ -8,10 +8,12 @@ the stage lifecycle rules behind one interface instead of leaking raw
 from __future__ import annotations
 
 import heapq
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import Any
 
+from .stage_integrate import IntegrateResult
+
 
 RUN_STEP_BUDGET = 8
 
@@ -38,6 +40,29 @@ class FinalVerificationTarget:
     reports: list[str]
 
 
+@dataclass(frozen=True)
+class FinalVerificationTargetRequest:
+    """Semantic inputs needed to acquire one final-verification target."""
+
+    project_root: Path
+    project_id: str
+    task_group: str
+    task_id: str
+    work_category: str
+    approved_plan_path: Path
+    stage: int | None
+    stage_map: tuple[dict[str, Any], ...]
+
+
+@dataclass(frozen=True)
+class FinalVerificationTargetAcquisition:
+    """Resolved target facts returned to the prepare adapter."""
+
+    target: FinalVerificationTarget
+    worktree_branch: str
+    integration_result: IntegrateResult | None
+
+
 @dataclass(frozen=True)
 class StageLifecycle:
     stage: int
@@ -473,7 +498,7 @@ def resolve_stage_base_commit(
     )
 
 
-def resolve_whole_task_target(
+def _resolve_whole_task_target(
     *,
     stage_map: list[dict[str, Any]],
     done_rows: list[dict[str, Any]],
@@ -533,65 +558,80 @@ def _merged_stage_map(
     }
 
 
-def resolve_and_integrate_whole_task(
+def _resolve_and_integrate_whole_task_unlocked(
     *, project_id: str, task_group: str, task_id: str,
     task_worktree_path: str, stage_map: list[dict[str, Any]],
     done_rows: list[dict[str, Any]], anchor_base: str, teardown: bool,
 ) -> dict[str, Any]:
-    """whole-task stage 통합(머지[+선택 teardown]) → 게이트 강제 → target 해소.
-
-    final-verification(teardown=True)과 container(teardown=False)의 단일 참조점.
-    ctx/PrepareInputs 결합 없는 헬퍼. 머지 충돌·미머지·dirty(.okstra 외)면
-    `PrepareError`. 반환: head_commit / merged_stage_map / target_ref / target /
-    integrate_result.
-
-    머지(`git merge`)+teardown 은 task-key 단위 `worktree_provision_mutex` 로
-    감싼다 — 동시 `container up` 둘 또는 container up × whole-task
-    final-verification 이 같은 공유 worktree 의 index/HEAD 에 동시에 머지하면
-    index.lock 충돌·반쯤 적용된 머지로 트리가 깨진다. 두 호출 지점(container 의
-    `_integrate_source_tree`, run.py 의 `_reserve_final_verification_target`)
-    모두 이 락 밖에서 진입하므로 self-deadlock 없이 여기서 1회만 잡는다."""
+    """Integrate and resolve a whole-task target while the caller owns the lock."""
     from .stage_integrate import IntegrateError, integrate_stages
     from .worktree import _git, is_dirty_excluding_okstra
-    from .locks import worktree_provision_mutex
-    from okstra_project.dirs import okstra_home
-    from okstra_project.state import slugify
-
-    with worktree_provision_mutex(
-        okstra_home(), project_id, slugify(task_group), slugify(task_id),
-    ):
-        try:
-            integ = integrate_stages(
-                project_id=project_id, task_group=task_group, task_id=task_id,
-                task_worktree_path=task_worktree_path, stage_map=stage_map,
-                done_rows=done_rows, teardown=teardown,
-            )
-        except IntegrateError as exc:
-            raise PrepareError(str(exc)) from exc
 
-        head = _git(task_worktree_path, "rev-parse", "HEAD").stdout.strip()
-        merged = _merged_stage_map(task_worktree_path, done_rows, head)
-        try:
-            target = resolve_whole_task_target(
-                stage_map=stage_map, done_rows=done_rows, anchor_base=anchor_base,
-                task_worktree_path=task_worktree_path, task_head=head,
-                task_dirty=is_dirty_excluding_okstra(task_worktree_path),
-                merged=merged,
-            )
-        except StageTargetError as exc:
-            raise PrepareError(str(exc)) from exc
+    try:
+        integration = integrate_stages(
+            project_id=project_id,
+            task_group=task_group,
+            task_id=task_id,
+            task_worktree_path=task_worktree_path,
+            stage_map=stage_map,
+            done_rows=done_rows,
+            teardown=teardown,
+        )
+    except IntegrateError as exc:
+        raise PrepareError(str(exc)) from exc
+
+    head = _git(task_worktree_path, "rev-parse", "HEAD").stdout.strip()
+    merged = _merged_stage_map(task_worktree_path, done_rows, head)
+    try:
+        target = _resolve_whole_task_target(
+            stage_map=stage_map,
+            done_rows=done_rows,
+            anchor_base=anchor_base,
+            task_worktree_path=task_worktree_path,
+            task_head=head,
+            task_dirty=is_dirty_excluding_okstra(task_worktree_path),
+            merged=merged,
+        )
+    except StageTargetError as exc:
+        raise PrepareError(str(exc)) from exc
     return {
         "head_commit": head,
         "merged_stage_map": merged,
         "target_ref": target.head,
         "target": target,
-        "integrate_result": integ,
+        "integrate_result": integration,
     }
 
 
-def resolve_single_stage_target(
+def resolve_and_integrate_whole_task(
+    *, project_id: str, task_group: str, task_id: str,
+    task_worktree_path: str, stage_map: list[dict[str, Any]],
+    done_rows: list[dict[str, Any]], anchor_base: str, teardown: bool,
+) -> dict[str, Any]:
+    """Locked whole-task integration interface shared with the container."""
+    from okstra_project.dirs import okstra_home
+    from okstra_project.state import slugify
+
+    from .locks import worktree_provision_mutex
+
+    with worktree_provision_mutex(
+        okstra_home(), project_id, slugify(task_group), slugify(task_id),
+    ):
+        return _resolve_and_integrate_whole_task_unlocked(
+            project_id=project_id,
+            task_group=task_group,
+            task_id=task_id,
+            task_worktree_path=task_worktree_path,
+            stage_map=stage_map,
+            done_rows=done_rows,
+            anchor_base=anchor_base,
+            teardown=teardown,
+        )
+
+
+def _resolve_single_stage_target(
     *,
-    requested_stage: str,
+    requested_stage: int,
     done_rows: list[dict[str, Any]],
     stage_base: str,
     stage_worktree_path: str,
@@ -601,7 +641,7 @@ def resolve_single_stage_target(
     """Resolve single-stage final-verification target, enforcing all gates."""
     from .consumers import latest_done_by_stage
 
-    n = int(requested_stage)
+    n = requested_stage
     done_by_stage = latest_done_by_stage(done_rows)
     if n not in done_by_stage:
         raise StageTargetError(
@@ -626,3 +666,149 @@ def resolve_single_stage_target(
         stages=[n],
         reports=[done_by_stage[n].get("report_path", "")],
     )
+
+
+def _read_final_verification_done_rows(
+    request: FinalVerificationTargetRequest,
+    registry_coordinates: tuple[str, str, str],
+) -> list[dict[str, Any]]:
+    from .consumers import backfill_done_from_carry, read_stage_consumer_state
+    from .plan_run_root import plan_run_root_from_approved_plan
+    from .stage_reconcile import auto_reconcile_best_effort
+
+    plan_run_root = plan_run_root_from_approved_plan(request.approved_plan_path)
+    backfill_done_from_carry(plan_run_root)
+    project_id, task_group, task_id = registry_coordinates
+    auto_reconcile_best_effort(
+        replace(
+            request,
+            project_id=project_id,
+            task_group=task_group,
+            task_id=task_id,
+        ),
+        plan_run_root,
+    )
+    return read_stage_consumer_state(plan_run_root).done_rows
+
+
+def _final_verification_registry_coordinates(
+    request: FinalVerificationTargetRequest,
+) -> tuple[str, str, str]:
+    from okstra_project.state import slugify
+
+    def segment(value: str) -> str:
+        return slugify(value) or "_"
+
+    return (
+        segment(request.project_id),
+        segment(request.task_group),
+        segment(request.task_id),
+    )
+
+
+def _acquire_single_stage_target(
+    request: FinalVerificationTargetRequest,
+    done_rows: list[dict[str, Any]],
+    registry_coordinates: tuple[str, str, str],
+) -> FinalVerificationTargetAcquisition:
+    from . import worktree_registry
+    from .worktree import _git, is_dirty_excluding_okstra
+
+    stage = request.stage
+    assert stage is not None
+    row = worktree_registry.get_stage_row(*registry_coordinates, stage)
+    worktree_path = (row or {}).get("worktree_path", "")
+    head = ""
+    if worktree_path and Path(worktree_path).is_dir():
+        head_result = _git(worktree_path, "rev-parse", "HEAD")
+        if head_result.returncode == 0:
+            head = head_result.stdout.strip()
+    if not head:
+        worktree_path = ""
+    target = _resolve_single_stage_target(
+        requested_stage=stage,
+        done_rows=done_rows,
+        stage_base=(row or {}).get("base_ref", ""),
+        stage_worktree_path=worktree_path,
+        stage_head=head,
+        stage_dirty=(
+            is_dirty_excluding_okstra(worktree_path) if worktree_path else False
+        ),
+    )
+    return FinalVerificationTargetAcquisition(
+        target=target,
+        worktree_branch=(row or {}).get("branch", ""),
+        integration_result=None,
+    )
+
+
+def _acquire_whole_task_target(
+    request: FinalVerificationTargetRequest,
+    done_rows: list[dict[str, Any]],
+    registry_coordinates: tuple[str, str, str],
+) -> FinalVerificationTargetAcquisition:
+    from . import worktree_registry
+
+    project_id, task_group, task_id = registry_coordinates
+    entry = worktree_registry.lookup(project_id, task_group, task_id)
+    worktree_path = (
+        entry.worktree_path if entry is not None else str(request.project_root)
+    )
+    whole = _resolve_and_integrate_whole_task_unlocked(
+        project_id=project_id,
+        task_group=task_group,
+        task_id=task_id,
+        task_worktree_path=worktree_path,
+        stage_map=list(request.stage_map),
+        done_rows=done_rows,
+        anchor_base=(
+            worktree_registry.get_implementation_base(
+                project_id, task_group, task_id
+            )
+            or ""
+        ),
+        teardown=True,
+    )
+    return FinalVerificationTargetAcquisition(
+        target=whole["target"],
+        worktree_branch=entry.branch if entry is not None else "",
+        integration_result=whole["integrate_result"],
+    )
+
+
+def acquire_final_verification_target(
+    request: FinalVerificationTargetRequest,
+) -> FinalVerificationTargetAcquisition:
+    """Acquire a stable final-verification target behind one task-key lock."""
+    from okstra_project.dirs import okstra_home
+    from okstra_project.state import slugify
+
+    from .locks import worktree_provision_mutex
+
+    try:
+        with worktree_provision_mutex(
+            okstra_home(),
+            request.project_id,
+            slugify(request.task_group),
+            slugify(request.task_id),
+        ):
+            registry_coordinates = _final_verification_registry_coordinates(request)
+            done_rows = _read_final_verification_done_rows(
+                request,
+                registry_coordinates,
+            )
+            if request.stage is not None:
+                return _acquire_single_stage_target(
+                    request,
+                    done_rows,
+                    registry_coordinates,
+                )
+            return _acquire_whole_task_target(
+                request,
+                done_rows,
+                registry_coordinates,
+            )
+    except PrepareError:
+        raise
+    except (OSError, RuntimeError, StageTargetError, ValueError) as exc:
+        raise PrepareError(str(exc)) from exc

package/runtime/python/okstra_ctl/wizard.py

@@ -81,8 +81,8 @@ from okstra_ctl.worktree import (
     compute_worktree_path,
     is_git_work_tree,
     main_worktree_path,
-    preview_stage_worktree_decision,
     preview_worktree_decision,
+    resolve_stage_worktree_decision,
 )
 from okstra_ctl.paths import RunRef, task_dir, task_runs_dir
 from okstra_ctl.work_categories import resolve_work_category
@@ -3175,7 +3175,7 @@ def _worktree_preview_line_impl(state: WizardState) -> str:
         )
         return _msg(state.workspace_root, "confirmation", "worktree_impl_auto",
                     path=str(parent_dir))
-    decision = preview_stage_worktree_decision(
+    decision = resolve_stage_worktree_decision(
         project_id=state.project_id, task_group_segment=state.task_group,
         task_id_segment=state.task_id,
         work_category=_preview_work_category(state),

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -16,6 +16,10 @@ from .worker_prompt_policy import (
 MAX_FINAL_VERIFICATION_DIRECTIVE_LINES = 40
 MAX_FINAL_VERIFICATION_BODY_LINES = 96
 
+PROMPT_DELIVERY_MODE_HEADER = "**Prompt Delivery Mode:**"
+PROMPT_DELIVERY_MODES = frozenset({"eager-include", "lazy-path-reference"})
+MODEL_HEADER = "**Model:**"
+
 _DIRECTIVE_HEADING = "## Run-specific directive"
 _WORKER_ERROR_CONTRACT_HEADER = "**Worker Error Contract Path:**"
 _PRIMARY_PACKET_RE = re.compile(
@@ -48,6 +52,7 @@ _NON_BODY_PREFIXES = (
     "**Verification head ref:**",
     "**Verification target path:**",
     "**Verification target digest:**",
+    PROMPT_DELIVERY_MODE_HEADER,
 )
 _REQUIRED_TARGET_PREFIXES = (
     "**Worktree:**",
@@ -81,6 +86,8 @@ class PromptRecord:
     worker_id: str
     dispatch_kind: str
     path: Path
+    expected_model: str | None = None
+    expected_delivery_mode: str | None = None
 
 
 def validate_final_verification_initial_prompt(text: str) -> list[str]:
@@ -194,6 +201,10 @@ def validate_initial_prompt_records(
             f"{record.worker_id}: {error}"
             for error in _validate_prompt_for_plan(text, plan, manifest)
         )
+        errors.extend(
+            f"{record.worker_id}: {error}"
+            for error in _validate_record_metadata(text, record)
+        )
         if plan.equality_group:
             group = equality_groups.setdefault(plan.equality_group, {})
             group[record.worker_id] = text
@@ -202,6 +213,68 @@ def validate_initial_prompt_records(
     return errors
 
 
+def _validate_record_metadata(text: str, record: PromptRecord) -> list[str]:
+    errors = _validate_delivery_mode(
+        _header_values(text, PROMPT_DELIVERY_MODE_HEADER),
+        record.expected_delivery_mode,
+    )
+    if record.expected_model is None:
+        return errors
+    model = _model_value(_header_values(text, MODEL_HEADER))
+    if model is None:
+        errors.append(
+            "exactly one non-empty **Model:** <label>, <model> header is required"
+        )
+    elif model != record.expected_model:
+        errors.append(
+            f"prompt model does not match requested model: {record.expected_model}"
+        )
+    return errors
+
+
+def _validate_delivery_mode(
+    values: list[str],
+    expected: str | None,
+) -> list[str]:
+    errors = []
+    if len(values) != 1 or not values[0]:
+        errors.append(
+            "exactly one non-empty **Prompt Delivery Mode:** header is required"
+        )
+    errors.extend(
+        f"unsupported Prompt Delivery Mode: {value}"
+        for value in values
+        if value and value not in PROMPT_DELIVERY_MODES
+    )
+    if (
+        expected is not None
+        and len(values) == 1
+        and values[0]
+        and values[0] != expected
+    ):
+        errors.append(
+            f"Prompt Delivery Mode does not match requested mode: {expected}"
+        )
+    return errors
+
+
+def _header_values(text: str, prefix: str) -> list[str]:
+    return [
+        line.strip()[len(prefix):].strip()
+        for line in text.splitlines()
+        if line.strip().startswith(prefix)
+    ]
+
+
+def _model_value(values: list[str]) -> str | None:
+    if len(values) != 1:
+        return None
+    parts = [part.strip() for part in values[0].rsplit(",", 1)]
+    if len(parts) != 2 or not all(parts):
+        return None
+    return parts[1]
+
+
 def _resolve_record_plan(
     manifest: Mapping[str, Any],
     record: PromptRecord,