okstra 0.82.1 → 0.83.0

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

@@ -0,0 +1,490 @@
+# 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.

package/docs/task-process/README.md

@@ -57,7 +57,7 @@ flowchart TD
 | phase boundary | [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py) |
 | task worktree | [`scripts/okstra_ctl/worktree.py`](../../scripts/okstra_ctl/worktree.py) |
 | worker roster parser | [`scripts/okstra_ctl/workers.py`](../../scripts/okstra_ctl/workers.py) |
-| lead operating contract | [`agents/SKILL.md`](../../agents/SKILL.md) |
+| lead operating contract | [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md) |
 | phase profiles | [`prompts/profiles/`](../../prompts/profiles/) |
 | final report shape | [`templates/reports/final-report.template.md`](../../templates/reports/final-report.template.md) |
 

package/docs/task-process/error-analysis.md

@@ -97,5 +97,5 @@ final report는 다음을 담아야 한다.
 - [`templates/reports/error-analysis-input.template.md`](../../templates/reports/error-analysis-input.template.md)
 - [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py)
 - [`scripts/okstra_ctl/wizard.py`](../../scripts/okstra_ctl/wizard.py)
-- [`agents/SKILL.md`](../../agents/SKILL.md)
+- [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)
 

package/docs/task-process/final-verification.md

@@ -164,4 +164,4 @@ source edit, follow-up fix, scope expansion은 전부 금지다. 결함을 발
 - [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py)
 - [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py)
 - [`scripts/okstra_ctl/render.py`](../../scripts/okstra_ctl/render.py)
-- [`agents/SKILL.md`](../../agents/SKILL.md)
+- [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)

package/docs/task-process/implementation-planning.md

@@ -124,5 +124,5 @@ flowchart TD
 - [`templates/reports/final-report.template.md`](../../templates/reports/final-report.template.md)
 - [`scripts/okstra_ctl/render.py`](../../scripts/okstra_ctl/render.py)
 - [`validators/validate-run.py`](../../validators/validate-run.py)
-- [`agents/SKILL.md`](../../agents/SKILL.md)
+- [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)
 

package/docs/task-process/implementation.md

@@ -145,5 +145,5 @@ flowchart TD
 - [`scripts/okstra_ctl/wizard.py`](../../scripts/okstra_ctl/wizard.py)
 - [`validators/validate-implementation-plan-stages.py`](../../validators/validate-implementation-plan-stages.py)
 - [`scripts/okstra_ctl/qa_commands.py`](../../scripts/okstra_ctl/qa_commands.py)
-- [`agents/SKILL.md`](../../agents/SKILL.md)
+- [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)
 

package/docs/task-process/release-handoff.md

@@ -62,7 +62,7 @@ sequenceDiagram
     P-->>W: lead prompt for current session
 ```
 
-profile에 `Required workers:` block이 없고 `run.py`도 `release-handoff`에서는 worker override를 비운다. 따라서 `agents/SKILL.md`의 일반 TeamCreate / convergence / report-writer 흐름을 타지 않는 것이 의도된 동작이다.
+profile에 `Required workers:` block이 없고 `run.py`도 `release-handoff`에서는 worker override를 비운다. 따라서 `prompts/lead/okstra-lead-contract.md`의 일반 TeamCreate / convergence / report-writer 흐름을 타지 않는 것이 의도된 동작이다.
 
 ## 4. entry gate
 

package/docs/task-process/requirements-discovery.md

@@ -79,7 +79,7 @@ flowchart TD
     R --> P7[Phase 7 token usage, validate, persist]
 ```
 
-`requirements-discovery`는 convergence default가 1 round다. 이 예외는 `render._build_convergence_block()`와 `agents/SKILL.md` 모두에서 명시된다.
+`requirements-discovery`는 convergence default가 1 round다. 이 예외는 `render._build_convergence_block()`와 `prompts/lead/okstra-lead-contract.md` 모두에서 명시된다.
 
 ## 5. 산출물과 routing
 
@@ -111,5 +111,5 @@ Non-goal은 source edit, plan authoring, build, deployment다.
 - [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py)
 - [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py)
 - [`prompts/profiles/requirements-discovery.md`](../../prompts/profiles/requirements-discovery.md)
-- [`agents/SKILL.md`](../../agents/SKILL.md)
+- [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.82.1",
+  "version": "0.83.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.82.1",
-  "builtAt": "2026-06-15T04:53:43.767Z",
+  "package": "0.83.0",
+  "builtAt": "2026-06-15T16:01:38.767Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/TODO.md

@@ -2,6 +2,8 @@
 
 이 파일은 okstra 워크플로우의 워커 종료 / Phase 4 대기 시간 개선 작업, 그리고 워커 설정 일관성 감사(2026-05-03)에서 도출됐지만 단일 라운드에서 안전하게 처리할 수 없어 별도 라운드로 미룬 항목을 기록한다.
 
+> Historical note: entries before 2026-06-15 may reference the former internal-skill layout; current lead contracts live under `prompts/lead/` and current coding-preflight resources live under `prompts/coding-preflight/`.
+
 ---
 
 ## 항목 C2 — Worker-results 경로 표준 결정 [해결됨, 2026-05-03]

package/runtime/agents/workers/claude-worker.md

@@ -45,7 +45,7 @@ Unlike the Codex / Gemini workers, you are an in-process Claude subagent — you
 
 4. Anchor all file operations to the absolute `Project Root` from the lead prompt. Use absolute paths — do NOT rely on inherited cwd. Never use `cd` to change directory.
    - **Executor exception (implementation phase only):** when this worker is dispatched as the `Executor` and the lead prompt provides an `EXECUTOR_WORKTREE_PATH` that differs from the session's inherited cwd, cwd-sensitive Bash commands (`cargo *`, `npm *`, `pnpm *`, `bun *`, `pytest`, `make *`, `go *`, language-toolchain test/build commands) MUST be prefixed with `cd <EXECUTOR_WORKTREE_PATH> && ` in the same Bash invocation — e.g. `cd /Users/.../worktrees/foo && cargo test -p bar`. Do NOT wrap the whole thing in `bash -lc "..."` or `bash -c "..."`; pass the chained command directly to the Bash tool so the leading `cd` token remains visible to the permission layer. The `cd` is scoped to the single Bash subshell and does not mutate the session's shell state, so this does not conflict with the "never use cd" rule above (which prevents the worker from drifting the session cwd across calls).
-   - **Executor coding-conventions preflight (BLOCKING, before your first `Edit` / `Write`):** when dispatched as the `Executor`, you MUST run the coding-conventions preflight defined in the executor sidecar (`prompts/profiles/_implementation-executor.md` → "Pre-implementation context exploration") before writing any code — detect each touched file's language and read okstra's installed coding-conventions files directly — `~/.claude/skills/okstra-coding-preflight/languages/<lang>.md` + `clean-code.md` + any `architecture/hexagonal.md` overlay (placed by `okstra install`), then state in one line which conventions apply. The skill is `user-invocable: false` and subagents do NOT auto-trigger skills, so read the files via the Read tool by absolute path rather than relying on Skill invocation; if those files are not readable in your runtime, degrade per that sidecar section (agnostic principles + project lint/convention files) — never skip the gate.
+   - **Executor coding-conventions preflight (BLOCKING, before your first `Edit` / `Write`):** when dispatched as the `Executor`, you MUST run the coding-conventions preflight defined in the executor sidecar (`prompts/profiles/_implementation-executor.md` → "Pre-implementation context exploration") before writing any code. Use this worker prompt's `**Coding preflight pack:**` anchor header; read that pack's `overview.md` and `clean-code.md`, then follow the routed pack's language → framework → architecture stages, iterating every rule and loading every matching resource (for example `frameworks/node-server.md` and `architectures/hexagonal.md` when their conditions match). The preflight pack is a runtime resource, not an auto-invoked skill; read the files via the Read tool by absolute path.
    - **Verifier QA-gate exception:** verifier roles MAY use the same `cd <WORKTREE> && <cmd>` shape when executing project-declared `qaCommands` (lint / format / typecheck / test) from `project.json`, since those commands are cwd-sensitive by nature. Outside the QA gate, verifiers still read with absolute paths only — do NOT use `cd` for file inspection.
    - **No extra chaining beyond `cd && cmd`:** the permission matcher only allows the exact two-segment shape `cd <PATH> && <single-command>`. Do NOT append additional pipes, semicolons, redirects, or `&&` chains — e.g. `cd ... && cargo test ... 2>&1 | tail -20; echo "exit:$?"` will trigger a permission prompt every dispatch because the trailing `| tail`, `; echo`, and `2>&1` tokens disqualify the prefix match against `Bash(cargo:*)`. Let Claude Code capture the full stdout/stderr and exit code natively — do not post-process with `tail`, `head`, or `echo "exit:$?"`. If output truncation is genuinely needed, run the command first and read the result in a separate tool call.
 
@@ -68,7 +68,7 @@ Before producing any output, you MUST:
 
 When returning results, start the file with a YAML frontmatter block, then organize the body into the following sections in this exact order.
 
-**Frontmatter (mandatory)** — set `workerId: "claude"`. Copy `id`, `aliases`, `taskType`, `task-id`, `task-group`, `project-id`, `date` verbatim from the primary input (`analysis-packet.md`; fall back to `analysis-material.md` only if the packet is missing a field). Full schema and a concrete example live in the `okstra-team-contract` skill's "Result Frontmatter" subsection.
+**Frontmatter (mandatory)** — set `workerId: "claude"`. Copy `id`, `aliases`, `taskType`, `task-id`, `task-group`, `project-id`, `date` verbatim from the primary input (`analysis-packet.md`; fall back to `analysis-material.md` only if the packet is missing a field). Full schema and a concrete example live in the team-contract resource (`prompts/lead/team-contract.md`) "Result Frontmatter" subsection.
 
 1. **Findings** - what you identified
 2. **Missing Information or Assumptions** - gaps in the analysis
@@ -80,15 +80,15 @@ Include file paths and line numbers when discussing code evidence.
 
 **Item IDs (mandatory).** Every row in sections 1–5 (and any optional section 6) MUST carry a worker-internal item ID unique within this file. Use the leading column for table-form items (`F-001`, `M-001`, `S-001`, `U-001`, `R-001` per section) or a `[<ID>]` prefix for bullet/numbered items. The ID shape is your choice but it MUST appear — the lead's §6.1 / §6.2 / §2.1 synthesis preserves these IDs in its `Source items (worker:item)` column to keep cross-worker traceability intact. See `prompts/profiles/_common-contract.md` "Cross-worker traceability" SSOT.
 
-**Ticket tagging:** For runs whose task type is `requirements-discovery`, `error-analysis`, `implementation-planning`, or `implementation`, every item in sections 1–5 MUST carry a ticket identifier. Use the `Ticket ID` column in table-form items and the `[TICKETID: <id>]` prefix in bullet/numbered items. Fill priority: `Issue / Ticket` from the input → `Task ID` (no prefix, e.g. `8852`) → `unknown`. Multiple tickets are comma-separated. Full rules live in the `okstra-team-contract` skill's Ticket Tagging section.
+**Ticket tagging:** For runs whose task type is `requirements-discovery`, `error-analysis`, `implementation-planning`, or `implementation`, every item in sections 1–5 MUST carry a ticket identifier. Use the `Ticket ID` column in table-form items and the `[TICKETID: <id>]` prefix in bullet/numbered items. Fill priority: `Issue / Ticket` from the input → `Task ID` (no prefix, e.g. `8852`) → `unknown`. Multiple tickets are comma-separated. Full rules live in the team-contract resource (`prompts/lead/team-contract.md`) Ticket Tagging section.
 
-This contract mirrors the `okstra-team-contract` skill's Worker Output Contract — that skill is the authoritative source if the two ever diverge.
+This contract mirrors the team-contract resource (`prompts/lead/team-contract.md`) Worker Output Contract — that resource is the authoritative source if the two ever diverge.
 
 ## Stop Condition (BLOCKING)
 
-When Lead dispatches you with `team_name` (Teams mode), its `Agent()` call returns `Spawned successfully` **immediately** and does NOT block on your completion — Lead detects your completion by self-scheduled polling of your worker-results file (see `okstra-team-contract` "Worker-completion detection (self-scheduled polling)"). Therefore you MUST write your worker-results file at the canonical Result Path before returning: that file's appearance is the ONLY completion signal Lead uses. Lingering after your worker-results file is on disk extends Phase 4 wall-clock time for the entire run and delays convergence. Be deliberate about stopping.
+When Lead dispatches you with `team_name` (Teams mode), its `Agent()` call returns `Spawned successfully` **immediately** and does NOT block on your completion — Lead detects your completion by self-scheduled polling of your worker-results file (see `team-contract` "Worker-completion detection (self-scheduled polling)"). Therefore you MUST write your worker-results file at the canonical Result Path before returning: that file's appearance is the ONLY completion signal Lead uses. Lingering after your worker-results file is on disk extends Phase 4 wall-clock time for the entire run and delays convergence. Be deliberate about stopping.
 
-After your `Write` to the assigned worker-results file (path provided by Lead as `**Result Path:**` — the canonical anchor header defined in `okstra-team-contract` "Worker Prompt Composition" — or derived under `runs/<task-type>/worker-results/claude-worker-<task-type>-<seq>.md`) succeeds:
+After your `Write` to the assigned worker-results file (path provided by Lead as `**Result Path:**` — the canonical anchor header defined in `team-contract` "Worker Prompt Composition" — or derived under `runs/<task-type>/worker-results/claude-worker-<task-type>-<seq>.md`) succeeds:
 
 1. Return your final assistant message **immediately**. Begin every return with your model identity, copied verbatim from the `**Model:** Claude worker, <modelExecutionValue>` line in your dispatch prompt (per Worker Preamble → "Return message to the lead"), then the status line — for an analysis dispatch:
    ```
@@ -114,7 +114,7 @@ If the header line is absent from the dispatch prompt, return `CLAUDE_WORKER_ERR
 
 **Tool failure (worker-reported)** — if `Write` of the prompt history file, `mkdir`, any MCP call, or any other pre-/in-analysis tool call fails (non-zero exit, exception, or empty result where data was required), append a `tool-failure` entry to the worker errors sidecar at the absolute path extracted from the `**Errors sidecar path:**` header. If the file does not exist, create it with `{"schemaVersion": 1, "errors": []}` then append.
 
-The sidecar follows the schema in `skills/okstra-team-contract/SKILL.md` (Optional errors sidecar). Lead will dump it to the run error log after this subagent terminates.
+The sidecar follows the schema in `prompts/lead/team-contract.md` (Optional errors sidecar). Lead will dump it to the run error log after this subagent terminates.
 
 There is NO `cli-failure` category for this worker — Claude worker has no external CLI to invoke. Treat MCP errors and Bash errors uniformly as `tool-failure`.
 
@@ -122,7 +122,7 @@ There is NO `cli-failure` category for this worker — Claude worker has no exte
 
 - Return error messages as-is on failure.
 - Do not summarize or modify your own analysis output beyond the structured sections above.
-- Sections 1–5 are the common core — same dimensions for every analysis worker. Your specialization (broad reasoning depth, hidden-assumption surfacing, execution-risk decomposition) only enters Section 6 if you have additive content beyond the core. See `skills/okstra-team-contract/SKILL.md` "Worker Output Contract" for the authoritative split.
+- Sections 1–5 are the common core — same dimensions for every analysis worker. Your specialization (broad reasoning depth, hidden-assumption surfacing, execution-risk decomposition) only enters Section 6 if you have additive content beyond the core. See `prompts/lead/team-contract.md` "Worker Output Contract" for the authoritative split.
 
 ## Stage evidence emission (BLOCKING, implementation task only)