okstra 0.102.2 → 0.102.3

package/docs/superpowers/plans/2026-06-15-worker-prompt-header-error-contract.md

@@ -1,490 +0,0 @@
-# Worker Prompt Header Error Contract 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:** Make worker prompt header rendering failures surface through dispatcher-native `DispatchError` boundaries instead of leaking helper-local exception types or tracebacks.
-
-**Architecture:** Keep `worker_prompt_headers.py` as the single renderer for the eight team-contract anchor headers, but give it a domain-specific exception type. Each dispatcher boundary (`codex_dispatch.py`, `dispatch_core.py`) converts that shared exception into its own public `DispatchError`, preserving existing CLI/error contracts. No graphify/plugin refresh work is included; the user explicitly excluded that external-plugin failure.
-
-**Tech Stack:** Python 3.11+, `pytest`, existing Okstra dispatcher modules under `scripts/okstra_ctl/`, npm build/check wrappers.
-
----
-
-## Current Evidence
-
-- `scripts/okstra_ctl/worker_prompt_headers.py` renders the worker anchor headers in one shared helper.
-- The helper currently raises raw `ValueError` from `_run_seq()` and `_require_string()` when required manifest fields are missing.
-- `scripts/okstra_ctl/codex_dispatch.py` catches only its local `DispatchError` in `main()`, so a malformed manifest can bypass the clean CLI error path.
-- `scripts/okstra_ctl/dispatch_core.py` already uses local `DispatchError` for malformed dispatch inputs, but `_materialize_prompt_if_missing()` delegates directly to `worker_prompt_headers()` without wrapping helper failures.
-- The only remaining issue in scope is this exception-boundary gap. The graphify update failure is intentionally out of scope.
-
-## File Structure
-
-- Modify: `scripts/okstra_ctl/worker_prompt_headers.py`
-  - Responsibility: render deterministic worker prompt anchor headers.
-  - Add: `WorkerPromptHeaderError` for malformed manifest/context input.
-  - Change: `_run_seq()` and `_require_string()` raise `WorkerPromptHeaderError`.
-
-- Modify: `scripts/okstra_ctl/codex_dispatch.py`
-  - Responsibility: Codex CLI-wrapper dispatch boundary.
-  - Change: import `WorkerPromptHeaderError` and convert it to Codex-local `DispatchError` in `_base_prompt_headers()`.
-
-- Modify: `scripts/okstra_ctl/dispatch_core.py`
-  - Responsibility: backend-neutral deterministic worker dispatch.
-  - Change: import `WorkerPromptHeaderError` and convert it to dispatch-core-local `DispatchError` in `_materialize_prompt_if_missing()`.
-
-- Modify: `tests/test_worker_prompt_headers.py`
-  - Responsibility: shared header renderer regression tests.
-  - Add: helper raises `WorkerPromptHeaderError` for malformed fallback manifest input.
-
-- Modify: `tests/test_codex_dispatch.py`
-  - Responsibility: Codex dispatcher regression tests.
-  - Add: `_base_prompt_headers()` wraps shared header errors as Codex `DispatchError`.
-
-- Modify: `tests/test_dispatch_core.py`
-  - Responsibility: backend-neutral dispatcher regression tests.
-  - Add: `_materialize_prompt_if_missing()` wraps shared header errors as dispatch-core `DispatchError` and does not create a prompt file on failure.
-
-- Modify: `CHANGES.md`
-  - Responsibility: user-visible behavior log.
-  - Add: clean dispatcher error behavior entry under `2026-06-15` after the current dispatch entry.
-
----
-
-### Task 1: Add Shared Header Error Type
-
-**Files:**
-- Modify: `scripts/okstra_ctl/worker_prompt_headers.py`
-- Test: `tests/test_worker_prompt_headers.py`
-
-- [ ] **Step 1: Write the failing helper regression test**
-
-Add `pytest` to the test imports and import the new exception type:
-
-```python
-import pytest
-
-from okstra_ctl.worker_prompt_headers import (  # noqa: E402
-    WorkerPromptHeaderError,
-    worker_prompt_headers,
-)
-```
-
-Append this test to `tests/test_worker_prompt_headers.py`:
-
-```python
-def test_worker_prompt_headers_raise_contract_error_for_missing_manifest_fields(
-    tmp_path: Path,
-) -> None:
-    with pytest.raises(WorkerPromptHeaderError, match="teamStatePath"):
-        worker_prompt_headers(
-            project_root=tmp_path / "project",
-            prompt_rel=".okstra/run/prompts/codex.md",
-            result_rel=".okstra/run/worker-results/codex.md",
-            worker_id="codex",
-            manifest={},
-            active_context={},
-        )
-```
-
-- [ ] **Step 2: Run the helper test and verify it fails for the intended reason**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_worker_prompt_headers.py::test_worker_prompt_headers_raise_contract_error_for_missing_manifest_fields -q
-```
-
-Expected: FAIL because `WorkerPromptHeaderError` is not importable yet, or because the helper still raises `ValueError`.
-
-- [ ] **Step 3: Implement `WorkerPromptHeaderError` in the shared helper**
-
-In `scripts/okstra_ctl/worker_prompt_headers.py`, add this class after the imports:
-
-```python
-class WorkerPromptHeaderError(Exception):
-    """Raised when worker prompt anchor headers cannot be rendered."""
-```
-
-Replace `_run_seq()` with:
-
-```python
-def _run_seq(manifest: Mapping[str, Any]) -> str:
-    seqs = manifest.get("runSequencesByCategory")
-    if not isinstance(seqs, Mapping):
-        raise WorkerPromptHeaderError("run manifest has no runSequencesByCategory object")
-    return _require_string(seqs, "manifests")
-```
-
-Replace `_require_string()` with:
-
-```python
-def _require_string(payload: Mapping[str, Any], key: str) -> str:
-    value = payload.get(key)
-    if not isinstance(value, str) or not value.strip():
-        raise WorkerPromptHeaderError(f"missing required string field: {key}")
-    return value
-```
-
-- [ ] **Step 4: Run the helper regression test and verify it passes**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_worker_prompt_headers.py::test_worker_prompt_headers_raise_contract_error_for_missing_manifest_fields -q
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Run all shared helper tests**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_worker_prompt_headers.py -q
-```
-
-Expected: PASS for all tests in `tests/test_worker_prompt_headers.py`.
-
----
-
-### Task 2: Wrap Codex Dispatcher Header Errors
-
-**Files:**
-- Modify: `scripts/okstra_ctl/codex_dispatch.py`
-- Test: `tests/test_codex_dispatch.py`
-
-- [ ] **Step 1: Write the failing Codex boundary regression test**
-
-Extend the `tests/test_codex_dispatch.py` import from `okstra_ctl.codex_dispatch` to include `_base_prompt_headers`:
-
-```python
-from okstra_ctl.codex_dispatch import (  # noqa: E402
-    DispatchError,
-    _base_prompt_headers,
-    build_dispatch_plan,
-    dispatch_plan,
-)
-```
-
-Append this test near the other prompt-generation tests:
-
-```python
-def test_base_prompt_headers_wraps_worker_header_errors() -> None:
-    with pytest.raises(DispatchError, match="teamStatePath"):
-        _base_prompt_headers(
-            project_root=Path("/project"),
-            manifest={},
-            active_context={},
-            worker_id="codex",
-            prompt_rel=".okstra/run/prompts/codex.md",
-            result_rel=".okstra/run/worker-results/codex.md",
-        )
-```
-
-- [ ] **Step 2: Run the Codex regression test and verify it fails for the intended reason**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_codex_dispatch.py::test_base_prompt_headers_wraps_worker_header_errors -q
-```
-
-Expected: FAIL because `_base_prompt_headers()` raises `WorkerPromptHeaderError` instead of Codex `DispatchError`.
-
-- [ ] **Step 3: Convert shared header errors to Codex `DispatchError`**
-
-In `scripts/okstra_ctl/codex_dispatch.py`, replace the worker header import with:
-
-```python
-from .worker_prompt_headers import WorkerPromptHeaderError, worker_prompt_headers
-```
-
-Replace `_base_prompt_headers()` 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]:
-    try:
-        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,
-        )
-    except WorkerPromptHeaderError as exc:
-        raise DispatchError(str(exc)) from exc
-```
-
-- [ ] **Step 4: Run the Codex regression test and verify it passes**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_codex_dispatch.py::test_base_prompt_headers_wraps_worker_header_errors -q
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Smoke-test the Codex boundary exception type**
-
-Run:
-
-```bash
-python3 - <<'PY'
-from pathlib import Path
-import sys
-
-sys.path.insert(0, "scripts")
-
-from okstra_ctl.codex_dispatch import DispatchError, _base_prompt_headers
-
-try:
-    _base_prompt_headers(
-        project_root=Path("/project"),
-        manifest={},
-        active_context={},
-        worker_id="codex",
-        prompt_rel=".okstra/run/prompts/codex.md",
-        result_rel=".okstra/run/worker-results/codex.md",
-    )
-except DispatchError as exc:
-    print(type(exc).__name__, str(exc))
-else:
-    raise SystemExit("expected DispatchError")
-PY
-```
-
-Expected output:
-
-```text
-DispatchError missing required string field: teamStatePath
-```
-
----
-
-### Task 3: Wrap Backend-Neutral Dispatcher Header Errors
-
-**Files:**
-- Modify: `scripts/okstra_ctl/dispatch_core.py`
-- Test: `tests/test_dispatch_core.py`
-
-- [ ] **Step 1: Write the failing dispatch-core regression test**
-
-Add `pytest` to `tests/test_dispatch_core.py` imports:
-
-```python
-import pytest
-```
-
-Append this test to `tests/test_dispatch_core.py`:
-
-```python
-def test_materialize_prompt_wraps_worker_header_errors(tmp_path: Path) -> None:
-    prompt_path = tmp_path / "project" / "prompts" / "claude-worker-prompt.md"
-
-    with pytest.raises(dispatch_core.DispatchError, match="teamStatePath"):
-        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=tmp_path / "project",
-            manifest={},
-            active_context={},
-        )
-
-    assert not prompt_path.exists()
-```
-
-- [ ] **Step 2: Run the dispatch-core regression test and verify it fails for the intended reason**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_dispatch_core.py::test_materialize_prompt_wraps_worker_header_errors -q
-```
-
-Expected: FAIL because `_materialize_prompt_if_missing()` raises `WorkerPromptHeaderError` instead of dispatch-core `DispatchError`.
-
-- [ ] **Step 3: Convert shared header errors to dispatch-core `DispatchError`**
-
-In `scripts/okstra_ctl/dispatch_core.py`, replace the worker header import with:
-
-```python
-from .worker_prompt_headers import WorkerPromptHeaderError, worker_prompt_headers
-```
-
-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)
-    try:
-        headers = 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,
-        )
-    except WorkerPromptHeaderError as exc:
-        raise DispatchError(str(exc)) from exc
-    prompt_path.write_text("\n".join([*headers, ""]), encoding="utf-8")
-```
-
-- [ ] **Step 4: Run the dispatch-core regression test and verify it passes**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_dispatch_core.py::test_materialize_prompt_wraps_worker_header_errors -q
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Run all backend-neutral dispatch prompt tests**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_dispatch_core.py -q
-```
-
-Expected: PASS for all tests in `tests/test_dispatch_core.py`.
-
----
-
-### Task 4: Verify Integration and Update User-Facing Log
-
-**Files:**
-- Modify: `CHANGES.md`
-- Verify: `tests/test_worker_prompt_headers.py`, `tests/test_codex_dispatch.py`, `tests/test_dispatch_core.py`, `tests/test_docs_runtime_contract.py`, generated `runtime/`
-
-- [ ] **Step 1: Run the focused regression suite**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_worker_prompt_headers.py tests/test_codex_dispatch.py::test_base_prompt_headers_wraps_worker_header_errors tests/test_dispatch_core.py::test_materialize_prompt_wraps_worker_header_errors -q
-```
-
-Expected: PASS for the shared helper test file and both new dispatcher boundary tests.
-
-- [ ] **Step 2: Run the prompt/dispatch contract suite**
-
-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: PASS for all prompt, dispatch, and runtime-contract tests.
-
-- [ ] **Step 3: Update `CHANGES.md` under `## 2026-06-15`**
-
-Insert this entry after the current `fix(dispatch): worker 프롬프트가 coding-preflight 팩 경로를 앵커 헤더로 직접 수신` section:
-
-```markdown
-### fix(dispatch): worker prompt header 오류를 dispatcher 경계에서 정규화
-
-- **배경**: worker prompt anchor header 렌더러를 공유 모듈로 추출한 뒤 malformed fallback manifest 가 renderer 내부 예외를 그대로 노출할 수 있었다. Codex CLI dispatcher 는 `DispatchError` 만 clean error 로 처리하므로 helper 예외가 그대로 올라오면 traceback 형태로 보일 위험이 있었다.
-- **해결**: shared renderer 는 `WorkerPromptHeaderError` 를 던지고, Codex dispatcher 와 backend-neutral dispatch core 는 이를 각자의 `DispatchError` 로 변환한다. 정상 header 렌더링 경로와 기존 deterministic prompt materialization 은 그대로 유지한다.
-- 사용자 영향: 잘못된 run manifest/context 로 fallback worker prompt 를 만들 수 없는 경우에도 내부 helper 예외나 traceback 대신 dispatcher 의 일관된 오류 메시지로 실패한다.
-```
-
-- [ ] **Step 4: Refresh runtime build output**
-
-Run:
-
-```bash
-npm run build
-```
-
-Expected: exit code 0 and build sync completion, including `scripts/`, `prompts/`, `skills/`, `agents/`, `templates/`, and `validators/` sources.
-
-- [ ] **Step 5: Run the full project check**
-
-Run:
-
-```bash
-npm run check
-```
-
-Expected: exit code 0. JavaScript tests, Python tests, and `validators/validate-workflow.sh` all pass.
-
-- [ ] **Step 6: Smoke-test runtime import after build**
-
-Run:
-
-```bash
-python3 - <<'PY'
-from pathlib import Path
-import sys
-
-sys.path.insert(0, "runtime/scripts")
-
-from okstra_ctl.codex_dispatch import DispatchError, _base_prompt_headers
-
-try:
-    _base_prompt_headers(
-        project_root=Path("/project"),
-        manifest={},
-        active_context={},
-        worker_id="codex",
-        prompt_rel=".okstra/run/prompts/codex.md",
-        result_rel=".okstra/run/worker-results/codex.md",
-    )
-except DispatchError as exc:
-    print(type(exc).__name__, str(exc))
-else:
-    raise SystemExit("expected DispatchError")
-PY
-```
-
-Expected output:
-
-```text
-DispatchError missing required string field: teamStatePath
-```
-
-- [ ] **Step 7: Commit the finished fix**
-
-Run:
-
-```bash
-git add scripts/okstra_ctl/worker_prompt_headers.py scripts/okstra_ctl/codex_dispatch.py scripts/okstra_ctl/dispatch_core.py tests/test_worker_prompt_headers.py tests/test_codex_dispatch.py tests/test_dispatch_core.py CHANGES.md
-git commit -m "fix(dispatch): normalize worker prompt header errors"
-```
-
-Expected: one conventional commit containing source changes, regression tests, and the user-facing behavior log. `runtime/` stays generated and is not hand-edited.
----
-
-## Self-Review Checklist
-
-- [ ] The plan covers the only remaining in-scope issue: shared header renderer exceptions leaking past dispatcher error boundaries.
-- [ ] The graphify update failure is excluded because the user classified it as an external plugin issue.
-- [ ] No compatibility shim or duplicate renderer is introduced; `worker_prompt_headers.py` remains the single header-rendering implementation.
-- [ ] Tests assert observable behavior: public exception type at the dispatcher boundary and absence of a partial prompt file on dispatch-core failure.
-- [ ] `CHANGES.md` states the user impact and the mechanism that enforces the cleaner failure mode.