okstra 0.102.2 → 0.102.3

package/docs/superpowers/plans/2026-06-15-worker-prompt-anchor-final-fixups.md

@@ -1,828 +0,0 @@
-# Worker Prompt Anchor Final Fixups Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** 모든 deterministic worker prompt materializer가 `team-contract` 의 anchor header 계약을 같은 런타임 홈 기준으로 만족하게 만든다.
-
-**Architecture:** `scripts/okstra_ctl/worker_prompt_headers.py` 를 새 단일 헬퍼로 두고, worker prompt anchor header 8줄을 여기서만 렌더링한다. `codex_dispatch.py` 와 `dispatch_core.py` 는 같은 헬퍼를 호출해 `Worker Preamble Path`, `Coding preflight pack`, error-log/sidecar 경로를 동일하게 계산한다. 런타임 리소스 경로는 `active-run-context.runtimeResources` 를 우선하고, 없으면 `OKSTRA_HOME` 기반 `okstra_home()` 으로 fallback 한다.
-
-**Tech Stack:** Python 3.14, pytest, Node build/test runner, existing `okstra_ctl` Python modules.
-
----
-
-## Current Evidence
-
-- `team-contract` 는 모든 worker prompt 가 header 8줄로 시작해야 한다고 규정한다: `prompts/lead/team-contract.md:64-75`.
-- `codex_dispatch.py` 는 `Coding preflight pack` 은 active context / `OKSTRA_HOME` 을 따르지만, `Worker Preamble Path` 는 module constant `Path.home() / ".okstra"` 로 고정한다: `scripts/okstra_ctl/codex_dispatch.py:35`, `scripts/okstra_ctl/codex_dispatch.py:670-695`.
-- `dispatch_core.py` fallback prompt 는 `# {worker_id} worker prompt` 로 시작하고, `Prompt History Path`, `Assigned worker prompt history path`, `Worker Preamble Path`, `Errors log path`, `Errors sidecar path` 를 쓰지 않는다: `scripts/okstra_ctl/dispatch_core.py:760-776`.
-- 현재 tests 는 fallback prompt 의 `Coding preflight pack` 존재만 확인한다: `tests/test_dispatch_core.py:11-44`.
-
-## File Structure
-
-- Create `scripts/okstra_ctl/worker_prompt_headers.py`
-  - Responsibility: worker prompt anchor header 8줄 렌더링 SSOT.
-  - Owns path fallback helpers for preamble, coding-preflight pack, run errors log, worker errors sidecar.
-- Create `tests/test_worker_prompt_headers.py`
-  - Responsibility: shared header renderer의 active-context 우선순위와 `OKSTRA_HOME` fallback 검증.
-- Modify `scripts/okstra_ctl/codex_dispatch.py`
-  - Responsibility: `_base_prompt_headers()` 에서 shared helper 호출.
-  - Remove local `WORKER_PREAMBLE_PATH` and local path helper duplication used only for headers.
-- Modify `scripts/okstra_ctl/dispatch_core.py`
-  - Responsibility: missing prompt fallback에서도 full anchor header block을 shared helper로 생성.
-- Modify `tests/test_codex_dispatch.py`
-  - Responsibility: Codex materialized prompt가 custom `OKSTRA_HOME` preamble path와 coding-preflight path를 함께 받는지 검증.
-- Modify `tests/test_dispatch_core.py`
-  - Responsibility: fallback prompt가 header 8줄로 시작하고 default-home hardcode 없이 custom runtime home을 쓰는지 검증.
-- Modify `tests/test_docs_runtime_contract.py`
-  - Responsibility: prompt materializer가 default `~/.okstra` preamble/coding-preflight path를 하드코딩하지 않는다는 contract guard.
-- Modify `CHANGES.md`
-  - Responsibility: user-visible dispatch robustness fix 기록.
-
----
-
-### Task 1: Add Shared Worker Prompt Header Renderer
-
-**Files:**
-- Create: `scripts/okstra_ctl/worker_prompt_headers.py`
-- Create: `tests/test_worker_prompt_headers.py`
-
-- [ ] **Step 1: Write failing tests for active-context paths and fallback paths**
-
-Create `tests/test_worker_prompt_headers.py` with:
-
-```python
-from __future__ import annotations
-
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "scripts"))
-
-from okstra_ctl.worker_prompt_headers import worker_prompt_headers  # noqa: E402
-
-
-def test_worker_prompt_headers_use_active_context_paths(
-    tmp_path: Path, monkeypatch
-) -> None:
-    monkeypatch.setenv("OKSTRA_HOME", str(tmp_path / "custom-home"))
-    project_root = tmp_path / "project"
-    headers = worker_prompt_headers(
-        project_root=project_root,
-        prompt_rel=".okstra/run/prompts/codex.md",
-        result_rel=".okstra/run/worker-results/codex.md",
-        worker_id="codex",
-        manifest={},
-        active_context={
-            "runtimeResources": {
-                "codingPreflightDir": "/runtime/prompts/coding-preflight",
-            },
-            "errorLogs": {
-                "runErrorsLogPath": ".okstra/run/logs/errors.jsonl",
-                "sidecarsByWorkerId": {
-                    "codex": ".okstra/run/worker-results/codex-errors.json",
-                },
-            },
-        },
-    )
-
-    assert headers == [
-        f"**Project Root:** {project_root}",
-        "**Prompt History Path:** .okstra/run/prompts/codex.md",
-        "**Result Path:** .okstra/run/worker-results/codex.md",
-        f"Assigned worker prompt history path: {project_root / '.okstra/run/prompts/codex.md'}",
-        f"**Worker Preamble Path:** {tmp_path / 'custom-home' / 'templates' / 'worker-prompt-preamble.md'}",
-        "**Coding preflight pack:** /runtime/prompts/coding-preflight",
-        f"**Errors log path:** {project_root / '.okstra/run/logs/errors.jsonl'}",
-        f"**Errors sidecar path:** {project_root / '.okstra/run/worker-results/codex-errors.json'}",
-    ]
-
-
-def test_worker_prompt_headers_fall_back_to_manifest_and_okstra_home(
-    tmp_path: Path, monkeypatch
-) -> None:
-    monkeypatch.setenv("OKSTRA_HOME", str(tmp_path / "runtime-home"))
-    project_root = tmp_path / "project"
-    headers = worker_prompt_headers(
-        project_root=project_root,
-        prompt_rel=".okstra/run/prompts/codex.md",
-        result_rel=".okstra/run/worker-results/codex.md",
-        worker_id="codex",
-        manifest={
-            "taskType": "error-analysis",
-            "runDirectoryPath": ".okstra/tasks/group/task/runs/error-analysis",
-            "runSequencesByCategory": {
-                "state": "001",
-                "workerResults": "001",
-            },
-        },
-        active_context={},
-    )
-
-    assert headers == [
-        f"**Project Root:** {project_root}",
-        "**Prompt History Path:** .okstra/run/prompts/codex.md",
-        "**Result Path:** .okstra/run/worker-results/codex.md",
-        f"Assigned worker prompt history path: {project_root / '.okstra/run/prompts/codex.md'}",
-        f"**Worker Preamble Path:** {tmp_path / 'runtime-home' / 'templates' / 'worker-prompt-preamble.md'}",
-        f"**Coding preflight pack:** {tmp_path / 'runtime-home' / 'prompts' / 'coding-preflight'}",
-        f"**Errors log path:** {project_root / '.okstra/tasks/group/task/runs/error-analysis/logs/errors-error-analysis-001.jsonl'}",
-        f"**Errors sidecar path:** {project_root / '.okstra/tasks/group/task/runs/error-analysis/worker-results/codex-worker-errors-error-analysis-001.json'}",
-    ]
-```
-
-- [ ] **Step 2: Run tests and verify they fail because the helper does not exist**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_worker_prompt_headers.py -q
-```
-
-Expected: fail with `ModuleNotFoundError: No module named 'okstra_ctl.worker_prompt_headers'`.
-
-- [ ] **Step 3: Implement the shared helper**
-
-Create `scripts/okstra_ctl/worker_prompt_headers.py` with:
-
-```python
-"""Shared worker prompt anchor header rendering."""
-from __future__ import annotations
-
-from pathlib import Path
-from typing import Any, Mapping
-
-from .paths import okstra_home
-
-
-def worker_prompt_headers(
-    *,
-    project_root: Path,
-    prompt_rel: str,
-    result_rel: str,
-    worker_id: str,
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-) -> list[str]:
-    """Render the team-contract worker prompt anchor headers."""
-    prompt_path = _resolve_project_path(project_root, prompt_rel)
-    return [
-        f"**Project Root:** {project_root}",
-        f"**Prompt History Path:** {prompt_rel}",
-        f"**Result Path:** {result_rel}",
-        f"Assigned worker prompt history path: {prompt_path}",
-        f"**Worker Preamble Path:** {_worker_preamble_path()}",
-        f"**Coding preflight pack:** {_coding_preflight_pack_path(active_context)}",
-        f"**Errors log path:** {_errors_log_path(project_root, manifest, active_context)}",
-        (
-            f"**Errors sidecar path:** "
-            f"{_worker_errors_sidecar_path(project_root, manifest, active_context, worker_id)}"
-        ),
-    ]
-
-
-def _worker_preamble_path() -> Path:
-    return okstra_home() / "templates" / "worker-prompt-preamble.md"
-
-
-def _coding_preflight_pack_path(active_context: Mapping[str, Any]) -> Path:
-    runtime_resources = active_context.get("runtimeResources")
-    if isinstance(runtime_resources, Mapping):
-        value = _string_value(runtime_resources.get("codingPreflightDir"))
-        if value:
-            return Path(value)
-    return okstra_home() / "prompts" / "coding-preflight"
-
-
-def _errors_log_path(
-    project_root: Path,
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-) -> Path:
-    error_logs = active_context.get("errorLogs")
-    if isinstance(error_logs, Mapping):
-        value = _string_value(error_logs.get("runErrorsLogPath"))
-        if value:
-            return _resolve_project_path(project_root, value)
-    run_dir = _run_directory_path(project_root, manifest)
-    task_type = _require_string(manifest, "taskType")
-    seq = _sequence(manifest, "state")
-    return run_dir / "logs" / f"errors-{task_type}-{seq}.jsonl"
-
-
-def _worker_errors_sidecar_path(
-    project_root: Path,
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    worker_id: str,
-) -> Path:
-    error_logs = active_context.get("errorLogs")
-    if isinstance(error_logs, Mapping):
-        sidecars = error_logs.get("sidecarsByWorkerId")
-        if isinstance(sidecars, Mapping):
-            value = _string_value(sidecars.get(worker_id))
-            if value:
-                return _resolve_project_path(project_root, value)
-    run_dir = _run_directory_path(project_root, manifest)
-    task_type = _require_string(manifest, "taskType")
-    seq = _sequence(manifest, "workerResults")
-    return run_dir / "worker-results" / f"{worker_id}-worker-errors-{task_type}-{seq}.json"
-
-
-def _run_directory_path(project_root: Path, manifest: Mapping[str, Any]) -> Path:
-    value = _string_value(manifest.get("runDirectoryPath"))
-    if value:
-        return _resolve_project_path(project_root, value)
-    team_state_path = _resolve_project_path(
-        project_root,
-        _require_string(manifest, "teamStatePath"),
-    )
-    return team_state_path.parent.parent
-
-
-def _sequence(manifest: Mapping[str, Any], key: str) -> str:
-    seqs = manifest.get("runSequencesByCategory")
-    if isinstance(seqs, Mapping):
-        return _string_value(seqs.get(key)) or _run_seq(manifest)
-    return _run_seq(manifest)
-
-
-def _run_seq(manifest: Mapping[str, Any]) -> str:
-    seqs = manifest.get("runSequencesByCategory")
-    if not isinstance(seqs, Mapping):
-        raise ValueError("run manifest has no runSequencesByCategory object")
-    return _require_string(seqs, "manifests")
-
-
-def _resolve_project_path(project_root: Path, value: str) -> Path:
-    path = Path(value)
-    return path if path.is_absolute() else project_root / path
-
-
-def _require_string(payload: Mapping[str, Any], key: str) -> str:
-    value = payload.get(key)
-    if not isinstance(value, str) or not value.strip():
-        raise ValueError(f"missing required string field: {key}")
-    return value
-
-
-def _string_value(value: Any) -> str:
-    return value.strip() if isinstance(value, str) else ""
-```
-
-- [ ] **Step 4: Run the new helper tests**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_worker_prompt_headers.py -q
-```
-
-Expected: `2 passed`.
-
-- [ ] **Step 5: Commit Task 1**
-
-Run:
-
-```bash
-git add scripts/okstra_ctl/worker_prompt_headers.py tests/test_worker_prompt_headers.py
-git commit -m "fix(dispatch): centralize worker prompt anchors"
-```
-
----
-
-### Task 2: Route Codex Dispatch Headers Through the Shared Helper
-
-**Files:**
-- Modify: `scripts/okstra_ctl/codex_dispatch.py:23-35`
-- Modify: `scripts/okstra_ctl/codex_dispatch.py:670-700`
-- Modify: `scripts/okstra_ctl/codex_dispatch.py:827-871`
-- Modify: `tests/test_codex_dispatch.py:439-457`
-
-- [ ] **Step 1: Strengthen the Codex custom-runtime test first**
-
-Replace `tests/test_codex_dispatch.py:439-457` with:
-
-```python
-def test_build_dispatch_plan_materializes_codex_runtime_resources_from_okstra_home(
-    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
-) -> None:
-    runtime_home = tmp_path / "custom-okstra-home"
-    monkeypatch.setenv("OKSTRA_HOME", str(runtime_home))
-    paths = _write_codex_run(tmp_path, write_codex_prompt=False)
-
-    build_dispatch_plan(
-        project_root=paths["project_root"],
-        run_manifest_path=paths["manifest_path"],
-        workspace_root=paths["workspace_root"],
-        okstra_bin=paths["okstra_bin"],
-        requested_workers=["codex"],
-    )
-
-    prompt = paths["prompt_path"].read_text(encoding="utf-8")
-    expected_preamble = runtime_home / "templates" / "worker-prompt-preamble.md"
-    expected_preflight = runtime_home / "prompts" / "coding-preflight"
-    default_preamble = Path.home() / ".okstra" / "templates" / "worker-prompt-preamble.md"
-
-    assert f"**Worker Preamble Path:** {expected_preamble}" in prompt
-    assert f"**Coding preflight pack:** {expected_preflight}" in prompt
-    if default_preamble != expected_preamble:
-        assert f"**Worker Preamble Path:** {default_preamble}" not in prompt
-```
-
-- [ ] **Step 2: Run the targeted Codex test and verify it fails on the preamble assertion**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_codex_dispatch.py::test_build_dispatch_plan_materializes_codex_runtime_resources_from_okstra_home -q
-```
-
-Expected: fail because the prompt still contains the default-home `Worker Preamble Path`.
-
-- [ ] **Step 3: Replace local Codex header rendering with shared helper**
-
-In `scripts/okstra_ctl/codex_dispatch.py`, change imports near line 23 from:
-
-```python
-from .paths import okstra_home, task_dir
-```
-
-to:
-
-```python
-from .paths import task_dir
-from .worker_prompt_headers import worker_prompt_headers
-```
-
-Delete this module constant near line 35:
-
-```python
-WORKER_PREAMBLE_PATH = Path.home() / ".okstra" / "templates" / "worker-prompt-preamble.md"
-```
-
-Replace `_base_prompt_headers()` body with:
-
-```python
-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,
-) -> list[str]:
-    return worker_prompt_headers(
-        project_root=project_root,
-        prompt_rel=prompt_rel,
-        result_rel=result_rel,
-        worker_id=worker_id,
-        manifest=manifest,
-        active_context=active_context,
-    )
-```
-
-Delete the local helpers that are now replaced by `worker_prompt_headers.py`:
-
-```python
-def _coding_preflight_pack_path(active_context: Mapping[str, Any]) -> Path:
-    runtime_resources = active_context.get("runtimeResources")
-    if isinstance(runtime_resources, Mapping):
-        value = _string_value(runtime_resources.get("codingPreflightDir"))
-        if value:
-            return Path(value)
-    return okstra_home() / "prompts" / "coding-preflight"
-```
-
-```python
-def _errors_log_path(
-    project_root: Path,
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-) -> Path:
-    error_logs = active_context.get("errorLogs")
-    if isinstance(error_logs, Mapping):
-        value = _string_value(error_logs.get("runErrorsLogPath"))
-        if value:
-            return _resolve_project_path(project_root, value)
-    run_dir = _run_directory_path(project_root, manifest)
-    return run_dir / "logs" / f"errors-{_require_string(manifest, 'taskType')}-{_sequence(manifest, 'state')}.jsonl"
-
-
-def _worker_errors_sidecar_path(
-    project_root: Path,
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    worker_id: str,
-) -> Path:
-    error_logs = active_context.get("errorLogs")
-    if isinstance(error_logs, Mapping):
-        sidecars = error_logs.get("sidecarsByWorkerId")
-        if isinstance(sidecars, Mapping):
-            value = _string_value(sidecars.get(worker_id))
-            if value:
-                return _resolve_project_path(project_root, value)
-    run_dir = _run_directory_path(project_root, manifest)
-    task_type = _require_string(manifest, "taskType")
-    seq = _sequence(manifest, "workerResults")
-    return run_dir / "worker-results" / f"{worker_id}-worker-errors-{task_type}-{seq}.json"
-
-
-def _run_directory_path(project_root: Path, manifest: Mapping[str, Any]) -> Path:
-    value = _string_value(manifest.get("runDirectoryPath"))
-    if value:
-        return _resolve_project_path(project_root, value)
-    return _resolve_required_path(project_root, manifest, "teamStatePath", "team-state").parent.parent
-
-
-def _sequence(manifest: Mapping[str, Any], key: str) -> str:
-    seqs = manifest.get("runSequencesByCategory")
-    if not isinstance(seqs, Mapping):
-        return _run_seq(manifest)
-    return _string_value(seqs.get(key)) or _run_seq(manifest)
-```
-
-- [ ] **Step 4: Run Codex focused tests**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_worker_prompt_headers.py tests/test_codex_dispatch.py -q
-```
-
-Expected: all tests pass.
-
-- [ ] **Step 5: Commit Task 2**
-
-Run:
-
-```bash
-git add scripts/okstra_ctl/codex_dispatch.py tests/test_codex_dispatch.py
-git commit -m "fix(dispatch): resolve codex preamble from runtime home"
-```
-
----
-
-### Task 3: Make Dispatch Core Fallback Prompts Contract-Compliant
-
-**Files:**
-- Modify: `scripts/okstra_ctl/dispatch_core.py:14-16`
-- Modify: `scripts/okstra_ctl/dispatch_core.py:281-297`
-- Modify: `scripts/okstra_ctl/dispatch_core.py:751-779`
-- Modify: `tests/test_dispatch_core.py:11-44`
-
-- [ ] **Step 1: Replace fallback prompt tests with contract-header assertions**
-
-Replace `tests/test_dispatch_core.py:11-44` with:
-
-```python
-def test_materialize_prompt_writes_contract_anchor_headers(
-    tmp_path: Path, monkeypatch
-) -> None:
-    runtime_home = tmp_path / "runtime-home"
-    monkeypatch.setenv("OKSTRA_HOME", str(runtime_home))
-    project_root = tmp_path / "project"
-    prompt_path = project_root / "prompts" / "claude-worker-prompt.md"
-    manifest = {
-        "taskType": "error-analysis",
-        "runDirectoryPath": ".okstra/tasks/group/task/runs/error-analysis",
-        "runSequencesByCategory": {
-            "state": "001",
-            "workerResults": "001",
-        },
-    }
-    active_context = {
-        "runtimeResources": {
-            "codingPreflightDir": "/tmp/rt/prompts/coding-preflight",
-        },
-        "errorLogs": {
-            "runErrorsLogPath": ".okstra/run/logs/errors.jsonl",
-            "sidecarsByWorkerId": {
-                "claude": ".okstra/run/worker-results/claude-errors.json",
-            },
-        },
-    }
-
-    dispatch_core._materialize_prompt_if_missing(
-        prompt_path=prompt_path,
-        prompt_rel="prompts/claude-worker-prompt.md",
-        worker_id="claude",
-        result_rel="worker-results/claude.md",
-        project_root=project_root,
-        manifest=manifest,
-        active_context=active_context,
-    )
-
-    lines = prompt_path.read_text(encoding="utf-8").splitlines()
-    assert lines[:8] == [
-        f"**Project Root:** {project_root}",
-        "**Prompt History Path:** prompts/claude-worker-prompt.md",
-        "**Result Path:** worker-results/claude.md",
-        f"Assigned worker prompt history path: {prompt_path}",
-        f"**Worker Preamble Path:** {runtime_home / 'templates' / 'worker-prompt-preamble.md'}",
-        "**Coding preflight pack:** /tmp/rt/prompts/coding-preflight",
-        f"**Errors log path:** {project_root / '.okstra/run/logs/errors.jsonl'}",
-        f"**Errors sidecar path:** {project_root / '.okstra/run/worker-results/claude-errors.json'}",
-    ]
-    assert not lines[0].startswith("#")
-
-
-def test_materialize_prompt_falls_back_to_okstra_home_and_manifest_paths(
-    tmp_path: Path, monkeypatch
-) -> None:
-    runtime_home = tmp_path / "custom-home"
-    monkeypatch.setenv("OKSTRA_HOME", str(runtime_home))
-    project_root = tmp_path / "project"
-    prompt_path = project_root / "prompts" / "claude-worker-prompt.md"
-
-    dispatch_core._materialize_prompt_if_missing(
-        prompt_path=prompt_path,
-        prompt_rel="prompts/claude-worker-prompt.md",
-        worker_id="claude",
-        result_rel="worker-results/claude.md",
-        project_root=project_root,
-        manifest={
-            "taskType": "implementation",
-            "runDirectoryPath": ".okstra/tasks/group/task/runs/implementation/stage-1",
-            "runSequencesByCategory": {
-                "state": "003",
-                "workerResults": "003",
-            },
-        },
-        active_context={},
-    )
-
-    text = prompt_path.read_text(encoding="utf-8")
-    assert f"**Worker Preamble Path:** {runtime_home / 'templates' / 'worker-prompt-preamble.md'}" in text
-    assert f"**Coding preflight pack:** {runtime_home / 'prompts' / 'coding-preflight'}" in text
-    assert (
-        f"**Errors log path:** {project_root / '.okstra/tasks/group/task/runs/implementation/stage-1/logs/errors-implementation-003.jsonl'}"
-        in text
-    )
-    assert (
-        f"**Errors sidecar path:** {project_root / '.okstra/tasks/group/task/runs/implementation/stage-1/worker-results/claude-worker-errors-implementation-003.json'}"
-        in text
-    )
-```
-
-- [ ] **Step 2: Run dispatch-core tests and verify they fail on signature/header mismatch**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_dispatch_core.py -q
-```
-
-Expected: fail because `_materialize_prompt_if_missing()` does not accept `prompt_rel`, `result_rel`, or `manifest`, and its prompt starts with a Markdown heading.
-
-- [ ] **Step 3: Wire dispatch core to shared helper**
-
-In `scripts/okstra_ctl/dispatch_core.py`, replace imports near lines 13-16 with:
-
-```python
-from . import tmux
-from .lead_events import LeadEvent, append_lead_event
-from .worker_prompt_headers import worker_prompt_headers
-from .wrapper_status import read_wrapper_status, status_path_for_prompt
-```
-
-In `_job_from_roster_worker()`, replace lines 291-296 with:
-
-```python
-    state = _worker_state(team_state, worker_id)
-    provider = _provider_for_worker(worker_id)
-    model = _model_for_worker(worker_id, state, report_writer_model)
-    prompt_rel = _worker_prompt_path(manifest, worker_id)
-    result_rel = _require_string(state, "resultPath")
-    prompt_path = _resolve_project_path(project_root, prompt_rel)
-    result_path = _resolve_project_path(project_root, result_rel)
-    _materialize_prompt_if_missing(
-        prompt_path=prompt_path,
-        prompt_rel=prompt_rel,
-        worker_id=worker_id,
-        result_rel=result_rel,
-        project_root=project_root,
-        manifest=manifest,
-        active_context=active_context,
-    )
-```
-
-Delete local `_coding_preflight_pack_path()` from `dispatch_core.py`.
-
-Replace `_materialize_prompt_if_missing()` with:
-
-```python
-def _materialize_prompt_if_missing(
-    *,
-    prompt_path: Path,
-    prompt_rel: str,
-    worker_id: str,
-    result_rel: str,
-    project_root: Path,
-    manifest: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-) -> None:
-    if prompt_path.is_file():
-        return
-    prompt_path.parent.mkdir(parents=True, exist_ok=True)
-    prompt_path.write_text(
-        "\n".join([
-            *worker_prompt_headers(
-                project_root=project_root,
-                prompt_rel=prompt_rel,
-                result_rel=result_rel,
-                worker_id=worker_id,
-                manifest=manifest,
-                active_context=active_context,
-            ),
-            "",
-        ]),
-        encoding="utf-8",
-    )
-```
-
-- [ ] **Step 4: Run dispatch-core and Codex tests together**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_worker_prompt_headers.py tests/test_dispatch_core.py tests/test_codex_dispatch.py -q
-```
-
-Expected: all tests pass.
-
-- [ ] **Step 5: Commit Task 3**
-
-Run:
-
-```bash
-git add scripts/okstra_ctl/dispatch_core.py tests/test_dispatch_core.py
-git commit -m "fix(dispatch): materialize full fallback prompt anchors"
-```
-
----
-
-### Task 4: Add Contract Guards and User-Visible Change Note
-
-**Files:**
-- Modify: `tests/test_docs_runtime_contract.py`
-- Modify: `CHANGES.md:19-23`
-
-- [ ] **Step 1: Add a contract test that blocks prompt materializer default-home literals**
-
-Append this test after `test_worker_prompt_contract_carries_coding_preflight_pack_anchor()` in `tests/test_docs_runtime_contract.py`:
-
-```python
-def test_prompt_materializers_do_not_hardcode_default_runtime_home():
-    forbidden_literals = [
-        'Path.home() / ".okstra" / "templates" / "worker-prompt-preamble.md"',
-        'Path.home() / ".okstra" / "prompts" / "coding-preflight"',
-    ]
-    for relative_path in [
-        "scripts/okstra_ctl/codex_dispatch.py",
-        "scripts/okstra_ctl/dispatch_core.py",
-    ]:
-        text = _read_doc(relative_path)
-        for literal in forbidden_literals:
-            assert literal not in text, f"{relative_path}: {literal}"
-```
-
-- [ ] **Step 2: Run the contract test before the source changes from Tasks 2-3 are present**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_docs_runtime_contract.py::test_prompt_materializers_do_not_hardcode_default_runtime_home -q
-```
-
-Expected before Task 2 source changes: fail on `scripts/okstra_ctl/codex_dispatch.py` containing the default preamble literal. Expected after Task 2 and Task 3: pass.
-
-- [ ] **Step 3: Update the `fix(dispatch)` entry in `CHANGES.md`**
-
-Replace `CHANGES.md:22` with:
-
-```markdown
-- **해결**: `paths.py` 가 이미 계산하는 `OKSTRA_CODING_PREFLIGHT_DIR` 을 machine-readable active-run-context 에 `runtimeResources.codingPreflightDir` 로 승격하고, 모든 worker prompt 앵커 헤더에 `**Coding preflight pack:** <절대경로>`(Worker Preamble Path 다음, error-log 헤더 앞, header #6)를 추가했다. deterministic dispatcher(`codex_dispatch.py`, `dispatch_core.py`)는 shared anchor renderer 로 `Worker Preamble Path` 와 `Coding preflight pack` 을 같은 `OKSTRA_HOME` 기준으로 주입하고, fallback prompt 도 `team-contract` 의 8줄 anchor header block 으로 시작한다.
-```
-
-- [ ] **Step 4: Run docs contract tests**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_docs_runtime_contract.py -q
-```
-
-Expected: all tests pass.
-
-- [ ] **Step 5: Commit Task 4**
-
-Run:
-
-```bash
-git add tests/test_docs_runtime_contract.py CHANGES.md
-git commit -m "test(dispatch): guard worker prompt anchor paths"
-```
-
----
-
-### Task 5: Final Verification
-
-**Files:**
-- Verify: `runtime/`
-- Verify: graphify output, if `graphify` is available in the environment
-
-- [ ] **Step 1: Run focused Python tests**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_worker_prompt_headers.py tests/test_codex_dispatch.py tests/test_dispatch_core.py tests/test_docs_runtime_contract.py -q
-```
-
-Expected: all selected tests pass.
-
-- [ ] **Step 2: Build runtime**
-
-Run:
-
-```bash
-npm run build
-```
-
-Expected: build exits 0 and reports sources synced into `runtime/`.
-
-- [ ] **Step 3: Run full project check**
-
-Run:
-
-```bash
-npm run check
-```
-
-Expected: JS tests, Python tests, and workflow validator all pass.
-
-- [ ] **Step 4: Run a runtime-home smoke for Codex prompt materialization**
-
-Run:
-
-```bash
-PYTHONPATH=scripts OKSTRA_HOME=/tmp/okstra-custom python3 -c 'from pathlib import Path
-from okstra_ctl.codex_dispatch import _base_prompt_headers
-manifest = {}
-active_context = {"runtimeResources": {"codingPreflightDir": "/tmp/okstra-custom/prompts/coding-preflight"}, "errorLogs": {"runErrorsLogPath": ".okstra/run/logs/errors.jsonl", "sidecarsByWorkerId": {"codex": ".okstra/run/results/codex-errors.json"}}}
-headers = _base_prompt_headers(project_root=Path("/project"), manifest=manifest, active_context=active_context, worker_id="codex", prompt_rel=".okstra/run/prompts/codex.md", result_rel=".okstra/run/results/codex.md")
-assert "**Worker Preamble Path:** /tmp/okstra-custom/templates/worker-prompt-preamble.md" in headers
-assert "**Coding preflight pack:** /tmp/okstra-custom/prompts/coding-preflight" in headers
-print("codex runtime anchors ok")'
-```
-
-Expected: prints `codex runtime anchors ok`.
-
-- [ ] **Step 5: Verify runtime surface still exposes only public skills and installed resources**
-
-Run:
-
-```bash
-node --input-type=module -e "
-import assert from 'node:assert/strict';
-import { readdirSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { USER_SKILL_NAMES, OBSOLETE_INTERNAL_SKILL_NAMES } from './src/skill-catalog.mjs';
-const names = readdirSync('runtime/skills', { withFileTypes: true })
-  .filter((entry) => entry.isDirectory())
-  .map((entry) => entry.name)
-  .sort();
-assert.deepEqual(names, [...USER_SKILL_NAMES].sort());
-for (const name of OBSOLETE_INTERNAL_SKILL_NAMES) {
-  assert.equal(existsSync(join('runtime/skills', name)), false, name);
-}
-assert.equal(existsSync('runtime/prompts/lead/okstra-lead-contract.md'), true);
-assert.equal(existsSync('runtime/prompts/coding-preflight/overview.md'), true);
-assert.equal(existsSync('runtime/prompts/coding-preflight/languages/python.md'), true);
-console.log('runtime surface ok');
-"
-```
-
-Expected: prints `runtime surface ok`.
-
-- [ ] **Step 6: Refresh graphify output after code changes**
-
-Run:
-
-```bash
-graphify update .
-```
-
-Expected: command exits 0 and refreshes `graphify-out/` for the changed Python dispatch modules.
-
-- [ ] **Step 7: Commit final build artifacts if runtime changed**
-
-Run:
-
-```bash
-git add runtime graphify-out
-git commit -m "build: refresh runtime prompt dispatch assets"
-```
-
-If `runtime/` or `graphify-out/` has no changes, skip this commit and record that there was no generated output to commit.