okstra 0.82.1 → 0.84.0

package/runtime/{skills/okstra-coding-preflight/SKILL.md → prompts/okstra-coding-preflight/overview.md}

@@ -1,11 +1,4 @@
----
-name: okstra-coding-preflight
-description: Provides language-specific coding conventions, idioms, and test-writing guidance for Java, Kotlin, JavaScript, TypeScript, Node.js, Python, SQL, and Rust. okstra lead/workers MUST consult this skill before writing, editing, refactoring, or testing code in any of these languages — including any new file, function, or test — even when the task seems simple enough to handle directly. Detect the target language from the file extension, project config (package.json/Cargo.toml/pyproject.toml/pom.xml/build.gradle), or task brief, and apply the matching conventions.
-user-invocable: false
-hide: true
----
-
-# okstra Code Preflight
+# Okstra Coding Preflight
 
 ## These apply to every worker writing or editing project code (executor and verifiers alike). Enforcement is self-check: the agent runs each rule's check immediately before reporting "done"; skipping a check is itself a contract violation.
 
@@ -16,42 +9,38 @@ hide: true
 5. **Function length cap — 50 lines** — A single function/method body must stay within 50 lines, counting only effective code (exclude blank lines, comments, and pure data declarations such as large enums, lookup tables, or constant maps). Crossing the cap is an extraction signal, not a style nit. *Self-check: for any function newly added or substantially edited, count effective body lines; if over 50, split before declaring complete, or surface the violation and confirm with the user.*
 
 
-## Quick start
+## Routed resource selection
 
-Before writing or editing **any** code:
+Read `clean-code.md` for the language-agnostic principles, then select language, framework, and architecture resources in three ordered stages. Each stage is a list of rules; a rule has one or more conditions; if ANY condition matches, include that rule's resource. Iterate EVERY rule in a stage — do not stop at the first match, because one change set can touch multiple languages, frameworks, or architectures. De-duplicate the final set, then state in one sentence which resources you applied (e.g., *"Applying TS + Node server + hexagonal; domain at src/domain/."*).
 
-1. Identify the target language (file extension, project config, or explicit user request).
-2. Read the matching language reference from `languages/`.
-3. Read [clean-code.md](clean-code.md) for the language-agnostic principles.
-4. **Check for architecture overlays.** If the project uses ports-and-adapters (signals: `domain/` + `ports/` + `adapters/` folders, `*.port.*` files, NestJS hex split), also read [architecture/hexagonal.md](architecture/hexagonal.md). Record the detected layout in one line so later edits don't re-discover it.
-5. In **one short sentence** to the user, state which conventions you will apply (e.g., *"Applying Kotlin conventions + hexagonal overlay; domain at `src/domain/`."*).
-6. Then write code.
+### Stage 1 — Language (iterate all rules)
 
-If the language is not listed below, stop and ask the user for the canonical style guide they want to follow before writing code.
+| Resource | Include when any condition matches |
+|---|---|
+| [languages/javascript-typescript.md](languages/javascript-typescript.md) | a touched file is `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`; or a JS package manifest (`package.json`) implies JS/TS work |
+| [languages/python.md](languages/python.md) | a touched file is `.py`; or manifests include `pyproject.toml`, `requirements.txt`, `setup.py`, `setup.cfg` |
+| [languages/rust.md](languages/rust.md) | a touched file is `.rs`; or `Cargo.toml` is in scope |
+| [languages/java.md](languages/java.md) | a touched file is `.java`; or manifests include `pom.xml` / `build.gradle` |
+| [languages/kotlin.md](languages/kotlin.md) | a touched file is `.kt` / `.kts`; or manifests include `build.gradle.kts` |
+| [languages/sql.md](languages/sql.md) | a touched file is `.sql`; migration directories are touched; `prisma/schema.prisma` is touched; or embedded query strings / ORM query builders change |
 
-## Language router
+### Stage 2 — Framework / runtime (iterate all rules)
 
-| Language | Reference | Triggers |
-|---|---|---|
-| Java | [languages/java.md](languages/java.md) | `.java`, `pom.xml`, `build.gradle` |
-| Kotlin | [languages/kotlin.md](languages/kotlin.md) | `.kt`, `.kts`, `build.gradle.kts` |
-| JavaScript / TypeScript | [languages/javascript-typescript.md](languages/javascript-typescript.md) | `.js`, `.ts`, `.tsx`, `.jsx` |
-| Node.js (server) | [languages/nodejs.md](languages/nodejs.md) | `package.json` with server entry, `express`, `fastify`, `nestjs` |
-| Python | [languages/python.md](languages/python.md) | `.py`, `pyproject.toml`, `requirements.txt`, `setup.py`, `setup.cfg` |
-| SQL | [languages/sql.md](languages/sql.md) | `.sql`, migration directories, `prisma/schema.prisma`, raw queries embedded in code |
-| Rust | [languages/rust.md](languages/rust.md) | `.rs`, `Cargo.toml` |
+| Resource | Include when any condition matches |
+|---|---|
+| [frameworks/node-server.md](frameworks/node-server.md) | `package.json` or its dependencies/scripts show server-side Node work (`express`, `fastify`, `nestjs`, server entrypoints, API routes, CLI services); or a touched file is a Node runtime module |
 
-For Node.js work, load **both** `javascript-typescript.md` and `nodejs.md`.
+Node.js server work also matches Stage 1's JavaScript/TypeScript rule — load both `languages/javascript-typescript.md` and `frameworks/node-server.md`.
 
-## Architecture overlays
+### Stage 3 — Architecture (iterate all rules)
 
-Loaded **in addition to** the language reference when the project matches. Overlays add architectural rules that cut across languages.
+| Resource | Include when any condition matches |
+|---|---|
+| [architectures/hexagonal.md](architectures/hexagonal.md) | ports-and-adapters / hexagonal signals: `domain/` + `ports/` + `adapters/` (or `core/` + `infrastructure/` + `application/`), `*.port.*` files, NestJS hex split, or `abstract class` files at a domain boundary |
 
-| Overlay | Reference | When to load |
-|---|---|---|
-| Hexagonal (ports & adapters) | [architecture/hexagonal.md](architecture/hexagonal.md) | Project has `domain/` + `ports/` + `adapters/` (or equivalent: `core/`, `infrastructure/`, `application/`), `*.port.*` files, or `abstract class` files at a domain boundary. Confirm once with the user if ambiguous. |
+If a layout looks hexagonal but is non-standard, ask one question — *"does this project follow ports-and-adapters? where is the domain?"* — and record the answer. Architecture overlays default to none when no rule matches.
 
-If you suspect an overlay applies but the layout is non-standard, ask one question — *"does this project follow ports-and-adapters? where is the domain?"* — and record the answer.
+If no Stage 1 language rule matches (an unlisted language), stop and ask the user for the canonical style guide before writing code — do not invent a default.
 
 ## Mandatory pre-write checks (every language)
 
@@ -61,7 +50,7 @@ If you suspect an overlay applies but the layout is non-standard, ask one questi
 - [ ] **Testing discipline:** the test does not stub/spy methods on the SUT itself (collaborators are fine), and assertions are on outcomes (return values, state, events, boundary calls) — not on which internal helper was called.
 - [ ] **Hexagonal overlay (if loaded):** no business logic inside any port body, adapter methods are I/O only (no post-fetch JS filtering on domain state, no `findValid*`/`findActive*` adapter names hiding rules), all domain objects declared under `domain/`.
 - [ ] Existing code searched: `grep` for the symbol / file / identifier you are about to add. Do not duplicate.
-- [ ] Project conventions checked: `.editorconfig`, `CONTRIBUTING.md`, formatter config (`.prettierrc`, `rustfmt.toml`, `ktlint`, `google-java-format`, etc.). **Project rules override this skill on conflict.**
+- [ ] Project conventions checked: `.editorconfig`, `CONTRIBUTING.md`, formatter config (`.prettierrc`, `rustfmt.toml`, `ktlint`, `google-java-format`, etc.). **Project rules override this resource pack on conflict.**
 
 ## Completion sweep (before declaring a multi-file change done)
 
@@ -73,6 +62,6 @@ Per-file checks miss cross-cutting issues; each commit can be individually clean
 
 ## Boundaries
 
-- This skill does **not** auto-format. Run the project's formatter yourself.
-- This skill does **not** replace repo-local rules. Repo rules win on conflict.
-- This skill does **not** cover every language. If the target language is missing, stop and ask.
+- This preflight does **not** auto-format. Run the project's formatter yourself.
+- This preflight does **not** replace repo-local rules. Repo rules win on conflict.
+- This preflight does **not** cover every language. If the target language is missing, stop and ask.

package/runtime/prompts/okstra-coding-preflight/scripts/preedit-check.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# PreToolUse hook for okstra-coding-preflight.
+#
+# Inspects the target file path of a Write/Edit/MultiEdit/NotebookEdit
+# call. If the extension matches a language covered by this skill,
+# emits a `hookSpecificOutput.additionalContext` JSON payload that
+# reminds the agent to invoke the skill before writing.
+#
+# Fires at most once per session per language (marker file).
+# Exits 0 in every case — never blocks the tool call.
+
+set -euo pipefail
+
+input="$(cat)"
+
+tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty')"
+case "$tool_name" in
+  Write|Edit|MultiEdit|NotebookEdit) ;;
+  *) exit 0 ;;
+esac
+
+file_path="$(printf '%s' "$input" \
+  | jq -r '.tool_input.file_path // .tool_input.notebook_path // empty')"
+[[ -z "$file_path" ]] && exit 0
+
+lang=""
+ref=""
+extra_hint=""
+case "$file_path" in
+  *.java)
+    lang="Java"
+    ref="languages/java.md"
+    ;;
+  *.kt|*.kts)
+    lang="Kotlin"
+    ref="languages/kotlin.md"
+    ;;
+  *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs)
+    lang="JavaScript-TypeScript"
+    ref="languages/javascript-typescript.md"
+    extra_hint=" If this file is part of a Node.js server (Express/Fastify/Nest/etc.), also read languages/nodejs.md."
+    ;;
+  *.py)
+    lang="Python"
+    ref="languages/python.md"
+    ;;
+  *.sql)
+    lang="SQL"
+    ref="languages/sql.md"
+    ;;
+  *.rs)
+    lang="Rust"
+    ref="languages/rust.md"
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+session_id="$(printf '%s' "$input" | jq -r '.session_id // "no-session"')"
+marker_dir="${TMPDIR:-/tmp}/mcbsc"
+mkdir -p "$marker_dir"
+marker="${marker_dir}/${session_id}_${lang}"
+
+if [[ -f "$marker" ]]; then
+  exit 0
+fi
+
+: > "$marker"
+
+skill_root="$HOME/.okstra/prompts/okstra-coding-preflight"
+msg="[okstra-coding-preflight] About to edit a ${lang} file (${file_path}). Before writing, you MUST Read ${skill_root}/${ref} plus ${skill_root}/clean-code.md (the skill is user-invocable:false — read the files directly).${extra_hint} If the project uses ports-and-adapters (domain/ + ports/ + adapters/, *.port.* files), also Read ${skill_root}/architecture/hexagonal.md. (Fires once per session per language.)"
+
+jq -nc \
+  --arg event "PreToolUse" \
+  --arg ctx "$msg" \
+  '{hookSpecificOutput: {hookEventName: $event, additionalContext: $ctx}}'
+
+exit 0

package/runtime/prompts/profiles/_coding-conventions-preflight.md

@@ -15,7 +15,7 @@ prompt (agents/workers/_cli-wrapper-template.md → Prompt Composition).
 
 Load the applicable coding conventions for every language the diff will touch, then state in ONE line which conventions apply (e.g. `Applying TS + hexagonal overlay; domain at src/domains/*/domain/`). Lint/test green is necessary but NOT sufficient — self-mocked tests, interaction-only assertions, and untruthful names all pass a green pipeline; this gate is what keeps them out of the diff.
 
-- **Language-specific rules load per situation — never inline them here.** Detect each touched file's language (extension / project manifest) and load the matching reference by reading okstra's installed coding-conventions files directly at `~/.claude/skills/okstra-coding-preflight/` (placed there by `okstra install`): read `languages/<lang>.md` (mock/spy API, idioms, test framework) + `clean-code.md` + any `architecture/*` overlay via the Read tool by absolute path. The skill is `user-invocable: false`, so do NOT rely on Skill-tool auto-invocation — read the files directly. For a ports-and-adapters / NestJS-hex layout (`domain/` + `ports/` + `adapters/`, `*.port.*`), load the hexagonal overlay too. This per-language split is the skill's job — the executor does not carry a multi-language block in context.
+- **Resource selection — read the routed pack, never inline it here.** Use this worker prompt's `**Coding preflight pack:**` anchor header as the absolute path to the installed routed pack. Detect each touched file's language and framework (extension / project manifest: `package.json`, `Cargo.toml`, `pyproject.toml`, `pom.xml`, `build.gradle*`, `prisma/schema.prisma`) and read resources from that pack via the Read tool by absolute path. Always read `overview.md` (the router) + `clean-code.md`, then select per the router's three ordered stages — Stage 1 language → `languages/<lang>.md`, Stage 2 framework → `frameworks/<fw>.md` (e.g. `frameworks/node-server.md` for server-side Node), Stage 3 architecture → `architectures/<arch>.md` (e.g. `architectures/hexagonal.md` for ports-and-adapters / NestJS-hex). Each stage is a list of rules; include EVERY matching resource (a change set can touch multiple languages/frameworks/architectures) — do not stop at the first match. These files are runtime resources, not Skill-tool skills, so always read them by path.
 - **Project review rule packs:** also look for project-local review skills in `<PROJECT_ROOT>/skills/*review*`, `<PROJECT_ROOT>/.claude/skills/*review*`, and up to two parent directories' `skills/*review*/SKILL.md`. Read the relevant `SKILL.md` plus referenced `references/*.md` files and apply their rules during implementation. This is a prevention pass, not a PR-comment generation workflow: do not dispatch reviewer subagents from the executor. For Fonts Ninja-style PR review packs, the executor must avoid newly introduced duplicate helper stacks, tautological tests that merely re-call the delegated helper, self-mocking, domain rules in adapters/ports, domain objects outside `domain/`, dead APIs, weak public names, and functions that fail the plain-English read.
 - **Language-agnostic principles that ALWAYS bind (the TDD loop MUST satisfy them):** (1) no self-mocking of the SUT — stub/spy only injected collaborators, never the subject's own methods; (2) behavioral assertions on outcomes (return value, state, persisted rows, events, boundary calls) — never `toHaveBeenCalled*` on an internal helper as the only/primary assertion; (3) truthful names — a `get*` / `find*` that writes/inserts, or a name encoding the caller's use-case (`*ForInit`) or hiding a domain rule (`findValid*`), is a defect; (4) single-purpose functions ≤50 effective lines, plain-English readability.
-- **Graceful degradation (codex / gemini executor runtimes, or any runtime where the `~/.claude/skills/okstra-coding-preflight/` files are absent or unreadable):** do NOT skip the gate — apply the agnostic principles above plus the project's own `CLAUDE.md` / `CONTRIBUTING` / formatter+lint config, and record `coding-conventions: skill-unavailable → applied <project rules + agnostic principles>` in the final report. Never claim a skill read that did not happen.
+- **Graceful degradation (codex / gemini executor runtimes, or any runtime where the resolved coding-preflight pack files are absent or unreadable):** do NOT skip the gate — apply the agnostic principles above plus the project's own `CLAUDE.md` / `CONTRIBUTING` / formatter+lint config, and record `coding-conventions: resource-unavailable → applied <project rules + agnostic principles>` in the final report. Never claim a resource read that did not happen.

package/runtime/prompts/profiles/_common-contract.md

@@ -7,14 +7,14 @@ profile document.
 -->
 - Team contract (shared):
   - `Claude lead` is synthesis-only and stays distinct from `Claude worker` (or, in `implementation`, the `Executor` and verifiers).
-  - `Report writer worker` is the **author** of the final-report file; `Claude lead` reviews and approves the produced draft and does NOT write the file itself (see `okstra-team-contract` and `okstra-report-writer` for the authoritative contract).
+  - `Report writer worker` is the **author** of the final-report file; `Claude lead` reviews and approves the produced draft and does NOT write the file itself (see `team-contract` and `report-writer` for the authoritative contract).
   - default model assignments are resolved from centralised defaults; the fallback values are `Claude lead`/`Report writer worker`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.5`, `Gemini worker`=`auto`. Phase-specific overrides (e.g. `implementation`'s executor binding) live in the per-profile document.
   - every required worker listed in the per-profile `Required workers:` block must be attempted; the final verdict waits until each has either a result or an explicit terminal status (`timeout`, `error`, `not-run`).
   - unnamed generic parallel workers must not replace the required role roster, and no additional sub-agent dispatch is allowed beyond this roster.
 - Worker interaction model (shared — read before inferring behaviour from the roster):
   - the per-profile `Required workers:` block is a **roster**, not a behaviour contract. Each role's interaction mode changes across operating phases of the same run.
   - **Phase 4 / 5 (independent analysis)**: analyser workers (`claude`, `codex`, `gemini` when opted in) produce findings independently and have no access to one another's outputs. `report-writer` does not analyse.
-  - **Phase 5.5 (convergence — peer review by workers)**: the lead replays each analyser's findings to the *other* analysers and collects `AGREE` / `DISAGREE` / `SUPPLEMENT` verdicts across up to `effectiveMaxRounds` rounds. Workers act as peer reviewers of each other's findings in this phase; the lead mediates but does not vote. See `skills/okstra-convergence/SKILL.md` for the round protocol, queue invariants, and final classification (`full-consensus` / `partial-consensus` / `contested` / `worker-unique`). For `requirements-discovery`, `error-analysis`, and `implementation-planning` this phase runs in **adversarial mode** (`convergence.adversarial=true`): verifiers try to refute each finding against its cited evidence and the burden of proof sits on the claim — see that skill's §"Adversarial Verification Mode".
+  - **Phase 5.5 (convergence — peer review by workers)**: the lead replays each analyser's findings to the *other* analysers and collects `AGREE` / `DISAGREE` / `SUPPLEMENT` verdicts across up to `effectiveMaxRounds` rounds. Workers act as peer reviewers of each other's findings in this phase; the lead mediates but does not vote. See `prompts/lead/convergence.md` for the round protocol, queue invariants, and final classification (`full-consensus` / `partial-consensus` / `contested` / `worker-unique`). For `requirements-discovery`, `error-analysis`, and `implementation-planning` this phase runs in **adversarial mode** (`convergence.adversarial=true`): verifiers try to refute each finding against its cited evidence and the burden of proof sits on the claim — see that skill's §"Adversarial Verification Mode".
   - Do NOT conclude "no peer review happens" from the roster alone — every profile that lists ≥2 analyser workers runs convergence by default (`convergence.enabled=true` in `task-manifest.json`).
 - Tooling — read-only MCP availability (shared):
   - MCP is not implicit okstra context. Query an MCP server only when the task brief explicitly lists it as source material for this run. Any MCP-derived finding MUST cite server, table, and the SELECT used. MCP MUST NEVER be used as a write path — schema/data mutations go through repository migration files reviewed by humans.

package/runtime/prompts/profiles/_implementation-executor.md

@@ -11,7 +11,7 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
 
 ## Executor role binding (carried over from the thin core)
 
-- **Executor dispatch labelling.** When Lead dispatches the Executor it MUST set the Agent `name` to `<provider>-executor` (e.g. `codex-executor`, `claude-executor`) — NOT the generic `<provider>-worker` — so the FleetView teammate pill names the job; see `agents/SKILL.md` Phase 4 "Agent `name` on dispatch". For a `codex` / `gemini` Executor, Lead MUST additionally inject a `**Pane role:** executor` line into the dispatched prompt body so the CLI wrapper titles its tmux trace pane `<cli>-executor-<pid>` (the wrapper reads that line per `agents/workers/_cli-wrapper-template.md`). Token attribution is unaffected — the collector matches any `agentName` beginning `<provider>-`.
+- **Executor dispatch labelling.** When Lead dispatches the Executor it MUST set the Agent `name` to `<provider>-executor` (e.g. `codex-executor`, `claude-executor`) — NOT the generic `<provider>-worker` — so the FleetView teammate pill names the job; see `prompts/lead/okstra-lead-contract.md` Phase 4 "Agent `name` on dispatch". For a `codex` / `gemini` Executor, Lead MUST additionally inject a `**Pane role:** executor` line into the dispatched prompt body so the CLI wrapper titles its tmux trace pane `<cli>-executor-<pid>` (the wrapper reads that line per `agents/workers/_cli-wrapper-template.md`). Token attribution is unaffected — the collector matches any `agentName` beginning `<provider>-`.
 - The `Executor` (bound in `implementation.md` thin core) is the **only worker permitted to use Edit / Write / state-mutating Bash commands** on project files. All other workers run read-only. When the executor provider is `codex` or `gemini`, the actual file mutation happens inside the executor CLI's own auto-edit mode (e.g. `codex exec --sandbox workspace-write`, gemini's equivalent) — not through Claude-side Edit/Write tools — but the safety rules in this sidecar still apply identically.
 - Worktree cwd handling — when the thin core's Task worktree block resolves status to `created` or `reused`, the Executor MUST run every Edit / Write / build / test / commit command with the worktree path as cwd. Treat it as `project_root` for the duration of this run. Do NOT mutate the caller's original checkout. Do NOT `cd` out of the worktree to reach files; if a file outside the worktree is needed, the dependency is a planning gap — record it in `Out-of-plan edits` and continue.
   - **How to set cwd per Bash call**: the Claude Bash tool inherits its cwd from the lead session, which is NOT the worktree. To put cwd-sensitive toolchains (`cargo`, `npm`, `pnpm`, `bun`, `pytest`, `make`, `go`) into the worktree, prefix the command with `cd {{EXECUTOR_WORKTREE_PATH}} && ` inside the same Bash invocation — e.g. `cd {{EXECUTOR_WORKTREE_PATH}} && cargo test -p foo`. **Never wrap in `bash -lc "..."` or `bash -c "..."`** — the wrapper hides the leading `cd` token from Claude Code's permission auto-allow layer (causing prompts on every call) without any safety benefit. For tools that accept an explicit working-directory flag (`git -C <path>`, `cargo --manifest-path`, `pytest --rootdir`), prefer that form over the `cd && ` chain. Edit / Write / Read tool calls already use absolute paths and need no cwd handling. The codex / gemini executor CLI wrappers (`okstra-codex-exec.sh -C`, `okstra-gemini-exec.sh --include-directories`) already inject worktree cwd at the CLI layer, so this rule applies primarily to the Claude executor.
@@ -19,7 +19,7 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
 
 ## Pre-implementation context exploration (executor before first edit)
 
-- **Coding-conventions preflight (BLOCKING — runs before the first `Edit` / `Write`, and binds the TDD loop below).** The gate body is a single source at `prompts/profiles/_coding-conventions-preflight.md` (sibling of this sidecar): skill-file pointers (`~/.claude/skills/okstra-coding-preflight/`), project review rule packs, the always-binding language-agnostic principles, and graceful degradation. Do NOT re-type that content from memory — deliver it by file so it cannot drift or be dropped:
+- **Coding-conventions preflight (BLOCKING — runs before the first `Edit` / `Write`, and binds the TDD loop below).** The gate body is a single source at `prompts/profiles/_coding-conventions-preflight.md` (sibling of this sidecar): resolved `Coding preflight pack:` runtime-resource path usage, project review rule packs, the always-binding language-agnostic principles, and graceful degradation. Do NOT re-type that content from memory — deliver it by file so it cannot drift or be dropped:
   - **Claude executor:** Read `_coding-conventions-preflight.md` end-to-end before the first `Edit` / `Write`, then state in ONE line which conventions apply (e.g. `Applying TS + hexagonal overlay; domain at src/domains/*/domain/`).
   - **CLI executor (BLOCKING when the executor provider is `codex` or `gemini`):** the executor CLI process does NOT share the lead's context, and it cannot Read this sidecar's directory — that path sits outside the CLI sandbox and the CLI only sees its stdin prompt, so a file reference never reaches it. The lead MUST physically append the **body** of `_coding-conventions-preflight.md` into the persisted executor prompt at dispatch time: Read the file from the same absolute directory you read this sidecar from, then `Write`/`cat` its body into the persisted prompt. Never hand-retype it. Enforcement: the CLI wrapper agents refuse an implementation-Executor dispatch whose persisted prompt lacks the literal heading `Coding-conventions preflight`, returning `<SENTINEL_PREFIX>_PREFLIGHT_MISSING` (see `agents/workers/_cli-wrapper-template.md` → Prompt Composition).
 - **Stage discipline transcription (when a preceding stage is `done`):** the lead MUST transcribe the `Stage discipline` rule (from this run's rendered profile — the INCLUDEd `_stage-discipline.md` body) verbatim into the dispatched CLI executor prompt, so a codex/gemini executor honors the prior-stage behavior-freeze. Declaration-level — no wrapper sentinel.

package/runtime/prompts/profiles/_implementation-verifier.md

@@ -9,7 +9,7 @@ at Phase 5, BEFORE constructing the verifier worker dispatch prompts.
 
 ## Verifier roles (resolved at run-prep time)
 
-- **Verifier dispatch labelling.** When Lead dispatches a verifier (here, and identically in `final-verification`) it MUST set the Agent `name` to `<provider>-verifier` (e.g. `claude-verifier`, `codex-verifier`) — NOT the generic `<provider>-worker` — so the FleetView teammate pill names the job; see `agents/SKILL.md` Phase 4 "Agent `name` on dispatch". For a `codex` / `gemini` verifier, Lead MUST additionally inject a `**Pane role:** verifier` line into the dispatched prompt body so the CLI wrapper titles its tmux trace pane `<cli>-verifier-<pid>` (the wrapper reads that line per `agents/workers/_cli-wrapper-template.md`). Token attribution is unaffected — the collector matches any `agentName` beginning `<provider>-`.
+- **Verifier dispatch labelling.** When Lead dispatches a verifier (here, and identically in `final-verification`) it MUST set the Agent `name` to `<provider>-verifier` (e.g. `claude-verifier`, `codex-verifier`) — NOT the generic `<provider>-worker` — so the FleetView teammate pill names the job; see `prompts/lead/okstra-lead-contract.md` Phase 4 "Agent `name` on dispatch". For a `codex` / `gemini` verifier, Lead MUST additionally inject a `**Pane role:** verifier` line into the dispatched prompt body so the CLI wrapper titles its tmux trace pane `<cli>-verifier-<pid>` (the wrapper reads that line per `agents/workers/_cli-wrapper-template.md`). Token attribution is unaffected — the collector matches any `agentName` beginning `<provider>-`.
 - The verifier slots are `Claude verifier` and `Codex verifier`, plus `Gemini verifier` **only when `gemini` is in the resolved `--workers` roster**. Every verifier in the resolved roster is dispatched regardless of which provider holds the executor role; the executor's own provider is run *separately* as a verifier (a fresh CLI session with no shared context) so that no verdict is produced from the same session that wrote the diff. Verifiers MUST NOT call Edit, Write, or any Bash command that mutates files outside the run's artifact directories. If a verifier wants a fix, it records the recommendation in its worker result; it does not apply the fix itself.
 - Session isolation — not model-variant divergence — is the primary self-review safeguard: each verifier is a separate CLI invocation with its own context window, so reusing the same model variant for executor and same-provider verifier is acceptable. Different model variants (e.g. executor=opus / Claude verifier=sonnet) remain recommended when available.
 - Phase-specific model defaults override the shared defaults: `Claude verifier`=`opus`, `Codex verifier`=`gpt-5.5`, `Gemini verifier`=`auto` (only when present in the roster). The `Executor`'s model is taken from the provider-specific worker model corresponding to `--executor`: claude→`--claude-model` (default `opus`), codex→`--codex-model` (default `gpt-5.5`), gemini→`--gemini-model` (default `auto`).
@@ -88,7 +88,7 @@ The final report keeps both — executor's `Validation evidence` AND each verifi
 Re-running commands proves the diff *builds and passes*; it does NOT prove the diff is *well-designed*. Lint/test green is necessary but not sufficient — self-mocked tests, interaction-only assertions, and untruthful names all survive a green pipeline. This gate is the filter for exactly those defects, so the executor's design errors are caught here instead of in post-merge PR review. It is a real gate, not a checklist: it enumerates the full diff and a blocking hit forces `FAIL`.
 
 - **Scope (no silent sampling).** Enumerate every changed source/test file via `git diff --name-only <base>...HEAD` and review each one. Skipping a changed file silently is a `contract-violated` outcome. If a file's language has no reference and is not covered by the agnostic checks below, record `design-review skipped: <file> (language=<x> no reference)` — never pass it silently.
-- **Load the same conventions the executor used, per language.** For each touched language load the coding-conventions reference by reading `~/.claude/skills/okstra-coding-preflight/languages/<lang>.md` + `clean-code.md` + the `architecture/hexagonal.md` overlay when the layout matches; degrade to the agnostic checks below when those files are not readable. The verifier does NOT inline language rules — it loads them per situation, identical to the executor preflight.
+- **Load the same conventions the executor used via the routed pack.** Use this worker prompt's `**Coding preflight pack:**` anchor header as the absolute path to the installed routed pack. Read `overview.md` first, then `clean-code.md`, then apply the router's three ordered stages: language, framework, architecture. In each stage, iterate every rule, treat a rule as matched when any listed condition is true, and accumulate every matching resource — including `frameworks/node-server.md` for server-side Node work and `architectures/hexagonal.md` for ports-and-adapters / NestJS-hex layouts. Degrade to the agnostic checks below when the resolved pack is unreadable, and record either `coding-conventions: resources=<...>` or `coding-conventions: resource-unavailable → applied <project rules + agnostic principles>`. The verifier does NOT inline language rules — it loads the same situation-specific resources as the executor preflight.
 - **Load project review rule packs when present.** Search the project root, `.claude/skills`, and up to two parent `skills/` directories for `*review*/SKILL.md` rule packs. Read their referenced `references/*.md` files and apply them as an overlay on this static review. If a premium review skill exists, use its coverage philosophy (recall-first enumeration followed by verify-only confirmation) as the verifier's mental model, but do NOT dispatch extra reviewer agents unless the task explicitly configured them. Record `project-review-rules: <paths read>` or `project-review-rules: none found` in the worker result.
 - **Blocking checks (any hit → verdict `FAIL`, cited `path:line` + rule name, recommended fix recorded — the verifier does NOT apply it):**
   - **New duplication / DRY:** two or more newly added or meaningfully modified blocks implement the same helper stack, transform, or domain rule. Literal copy-paste is always blocking; semantically equivalent transforms across services are blocking unless the approved plan explicitly justified keeping them separate. Recommend the shared module location.

package/runtime/prompts/profiles/error-analysis.md

@@ -37,8 +37,8 @@
   - **Codebase-first ambiguity resolution (defect rule)**: any ambiguity about repro, file behavior, or symbol semantics that can be answered by `Read` / `Grep` / log inspection MUST be resolved that way and recorded with file:line (or log-line) evidence. Writing a clarification row for something the codebase or shipped logs already answer is a defect of this phase.
   - **Evidence note required inside `Statement`**: every clarification row includes `Evidence checked: <path:line>` or `Evidence checked: none — <reporter-only reason>` in the `Statement` cell. `none` is allowed ONLY when the row's nature is "only the reporter can answer this" (reporter-side data, business priority, environment they observed). A row with `none` that *could* have been answered by code or logs is a defect.
 - Cross-verification mode:
-  - Phase 5.5 convergence runs in **adversarial mode** for this phase (`convergence.adversarial=true`). Verifiers actively try to refute each root-cause / reproduction claim by directly re-inspecting the cited code, logs, or config; the burden of proof sits on the claim. See `skills/okstra-convergence/SKILL.md` §"Adversarial Verification Mode". A single evidence-backed refutation prevents a finding from reaching consensus.
-  - **Coverage critic (opt-in)**: when `convergence.critic.enabled=true` (chosen via the okstra-run picker or `--critic`), a reused-worker critic pass is dispatched concurrently with the first convergence reverify round to surface missed findings; its gaps are merged only after a 1-round adversarial reverify that follows convergence. See `skills/okstra-convergence/SKILL.md` "Coverage critic pass".
+  - Phase 5.5 convergence runs in **adversarial mode** for this phase (`convergence.adversarial=true`). Verifiers actively try to refute each root-cause / reproduction claim by directly re-inspecting the cited code, logs, or config; the burden of proof sits on the claim. See `prompts/lead/convergence.md` §"Adversarial Verification Mode". A single evidence-backed refutation prevents a finding from reaching consensus.
+  - **Coverage critic (opt-in)**: when `convergence.critic.enabled=true` (chosen via the okstra-run picker or `--critic`), a reused-worker critic pass is dispatched concurrently with the first convergence reverify round to surface missed findings; its gaps are merged only after a 1-round adversarial reverify that follows convergence. See `prompts/lead/convergence.md` "Coverage critic pass".
 - Non-goals:
   - implementation details unless they are necessary to validate the cause
   - **source code edits, builds, migrations, or deployments** — this run produces evidence and cause analysis only; the fix belongs to a later `implementation-planning` run followed by an `implementation` run

package/runtime/prompts/profiles/final-verification.md

@@ -48,7 +48,7 @@
   4. **Verifier dissent preserved** — if workers reach different verdicts, the disagreement is visible in section 1.2; synthesis hides nothing.
   5. **No source-mutation audit** — scan the run's session transcripts for Edit / Write or state-mutating Bash commands that touch paths OUTSIDE `<PROJECT_ROOT>/.okstra/**` and outside the assigned run-artifact paths. Writes to worker prompts, audit sidecars, team-state, the final-report `data.json`, and rendered reports under the run directory are allowed okstra artifacts. Any source/schema/deployment mutation means the run has crossed into implementation and MUST be re-routed; do NOT silently strip the evidence.
 - Cross-verification mode:
-  - **Acceptance critic (opt-in)**: when `convergence.critic.enabled=true` (chosen via the okstra-run picker or `--critic`), a reused-worker **acceptance devil's-advocate** pass is dispatched concurrently with the first convergence reverify round to surface candidate acceptance blockers the verifiers may have missed; candidates are verified only after convergence completes. Each candidate is verified **confirm-or-downgrade**: confirmed → an `Acceptance Blockers` row (which, since `accepted` requires zero blockers, moves the verdict to `conditional-accept` / `blocked`); unconfirmed → a `Residual Risk` row (never dropped). See `skills/okstra-convergence/SKILL.md` "Acceptance critic pass (final-verification)".
+  - **Acceptance critic (opt-in)**: when `convergence.critic.enabled=true` (chosen via the okstra-run picker or `--critic`), a reused-worker **acceptance devil's-advocate** pass is dispatched concurrently with the first convergence reverify round to surface candidate acceptance blockers the verifiers may have missed; candidates are verified only after convergence completes. Each candidate is verified **confirm-or-downgrade**: confirmed → an `Acceptance Blockers` row (which, since `accepted` requires zero blockers, moves the verdict to `conditional-accept` / `blocked`); unconfirmed → a `Residual Risk` row (never dropped). See `prompts/lead/convergence.md` "Acceptance critic pass (final-verification)".
 - Non-goals:
   - proposing unrelated refactors beyond the delivered scope
   - **source code edits, follow-up bug fixes, or scope expansion** — this run renders a verdict only; defects detected here become inputs to a new `error-analysis` or `implementation-planning` run

package/runtime/prompts/profiles/implementation-planning.md

@@ -40,9 +40,9 @@
 - Approval gate (phase-specific addendum to shared authority rule):
   - The YAML frontmatter `approved: true|false` field is the only authorised approval gate. report-writer always emits `approved: false`. The user clears it either by (a) editing the frontmatter line to `approved: true` directly, or (b) invoking the next phase with `--approve` so the CLI flips the frontmatter on the user's behalf. `okstra_ctl.run._validate_approved_plan` reads this field and refuses entry until it is `true`.
 - Cross-verification mode:
-  - Phase 5.5 finding convergence runs in **adversarial mode** for this phase (`convergence.adversarial=true`). Verifiers actively try to refute each worker finding (requirement gap / risk / option) by re-inspecting its cited evidence; the burden of proof sits on the claim. See `skills/okstra-convergence/SKILL.md` §"Adversarial Verification Mode".
-  - §5.5.9 plan-body verification runs with an **adversarial posture** (`skills/okstra-convergence/SKILL.md` §"Adversarial plan-body posture"): verifiers open and confirm every cited path / command and put the burden of proof on the plan. The gate threshold is unchanged — a *majority* `DISAGREE` (`majority-disagree`) is still required to block approval; a single dissent does not.
-  - **Coverage critic (opt-in)**: when `convergence.critic.enabled=true` (chosen via the okstra-run picker or `--critic`), a reused-worker critic pass is dispatched concurrently with the first convergence reverify round to surface missed findings; its gaps are merged only after a 1-round adversarial reverify that follows convergence. See `skills/okstra-convergence/SKILL.md` "Coverage critic pass".
+  - Phase 5.5 finding convergence runs in **adversarial mode** for this phase (`convergence.adversarial=true`). Verifiers actively try to refute each worker finding (requirement gap / risk / option) by re-inspecting its cited evidence; the burden of proof sits on the claim. See `prompts/lead/convergence.md` §"Adversarial Verification Mode".
+  - §5.5.9 plan-body verification runs with an **adversarial posture** (`prompts/lead/convergence.md` §"Adversarial plan-body posture"): verifiers open and confirm every cited path / command and put the burden of proof on the plan. The gate threshold is unchanged — a *majority* `DISAGREE` (`majority-disagree`) is still required to block approval; a single dissent does not.
+  - **Coverage critic (opt-in)**: when `convergence.critic.enabled=true` (chosen via the okstra-run picker or `--critic`), a reused-worker critic pass is dispatched concurrently with the first convergence reverify round to surface missed findings; its gaps are merged only after a 1-round adversarial reverify that follows convergence. See `prompts/lead/convergence.md` "Coverage critic pass".
 - Non-goals:
   - code-level micro-optimization unless it changes the implementation approach
   - **source code edits of any kind** — this run produces a plan document only; Edit/Write on project source files is forbidden until the plan is approved and a separate `implementation` run starts
@@ -90,7 +90,7 @@
   - the YAML frontmatter MUST include the line `implementation-option:` directly under `approved:` (report-writer always emits it with an **empty value**). The user selects which Option Candidate the next `implementation` run executes by filling this line with that option's name (manual edit or `--implementation-option <name>` CLI). When left empty, the `implementation` run falls back to the `Recommended Option`.
   - **the frontmatter `approved: false` line is rendered unconditionally; if the plan-body verification gate (§5.5.9) returns `blocked-by-disagreement` or `aborted-non-result`, the writer MUST keep `approved: false` and the validator refuses any report that ships with `approved: true` under such a gate result.**
   - every ambiguity flagged during pre-planning that the user must resolve before approval registered as a `Blocks=approval` row in the `## 1. Clarification Items` table (do NOT create a separate `Open Questions` block under the implementation plan body — the unified table is the single home)
-  - **§5.5.9 Plan Body Verification (BLOCKING).** After report-writer finishes the draft, the lead MUST run a worker peer-review round on the consolidated plan body (Option Candidates / Trade-off Matrix / Recommended Option / Stage Map and per-stage sections / Dependency / Validation Checklist / Rollback / Requirement Coverage) and populate `### 5.5.9 Plan Body Verification` in the final report. The round protocol, plan-item ID scheme (`P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*`), verdict semantics, gate-result classification, and dissent log format are defined in `skills/okstra-convergence/SKILL.md` "Plan-body verification mode". The four gate-result values are `passed`, `passed-with-dissent`, `blocked-by-disagreement`, `aborted-non-result`. When the gate would have been `blocked-by-disagreement` or `aborted-non-result`, the lead MUST NOT silently flip it to one of the passing values to "unblock" the run — that is a contract violation. When `convergence.adversarial=true` (the default for this phase), this round uses the adversarial posture — verifiers confirm cited paths/commands and the burden of proof is on the plan — but the gate threshold stays `majority-disagree` (see that skill's §"Adversarial plan-body posture").
+  - **§5.5.9 Plan Body Verification (BLOCKING).** After report-writer finishes the draft, the lead MUST run a worker peer-review round on the consolidated plan body (Option Candidates / Trade-off Matrix / Recommended Option / Stage Map and per-stage sections / Dependency / Validation Checklist / Rollback / Requirement Coverage) and populate `### 5.5.9 Plan Body Verification` in the final report. The round protocol, plan-item ID scheme (`P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*`), verdict semantics, gate-result classification, and dissent log format are defined in `prompts/lead/convergence.md` "Plan-body verification mode". The four gate-result values are `passed`, `passed-with-dissent`, `blocked-by-disagreement`, `aborted-non-result`. When the gate would have been `blocked-by-disagreement` or `aborted-non-result`, the lead MUST NOT silently flip it to one of the passing values to "unblock" the run — that is a contract violation. When `convergence.adversarial=true` (the default for this phase), this round uses the adversarial posture — verifiers confirm cited paths/commands and the burden of proof is on the plan — but the gate threshold stays `majority-disagree` (see that skill's §"Adversarial plan-body posture").
   - **Decision-record evaluation (sole owner)**: this phase is the **single owner** of decision-record evaluation in the okstra lifecycle. The brief never evaluates or drafts decision records — it only forwards `adr-candidate:*` signals. Every `adr-candidate:*` entry inherited from the brief's `Open Questions` is a mandatory evaluation target. In addition, evaluate every decision the recommended option introduces against the three criteria:
     1. **Hard to reverse** — would changing the decision later cost meaningfully more than deciding now?
     2. **Surprising without context** — would a future reader, seeing only the code, wonder "why was it built this way?"?

package/runtime/prompts/profiles/requirements-discovery.md

@@ -52,8 +52,8 @@
   - **Codebase-first ambiguity resolution (defect rule)**: any ambiguity that can be answered by `Read` / `Grep` / file inspection MUST be resolved that way and recorded with file:line evidence. Writing a clarification row for something the codebase already answers is a defect of this phase.
   - **Evidence note required inside `Statement`**: every clarification row includes `Evidence checked: <path:line>` or `Evidence checked: none — <human-only reason>` in the `Statement` cell. `none` is allowed ONLY when the row's nature is "only a human can answer this" (reporter intent, business priority, external authority). A row with `none` that *could* have been answered by the codebase is a defect.
 - Cross-verification mode:
-  - Phase 5.5 convergence runs in **adversarial mode** for this phase (`convergence.adversarial=true`). Verifiers actively try to refute each worker's finding by directly re-inspecting the cited evidence; the burden of proof sits on the claim. See `skills/okstra-convergence/SKILL.md` §"Adversarial Verification Mode". A single evidence-backed refutation prevents a finding from reaching consensus.
-  - **Coverage critic (opt-in)**: when `convergence.critic.enabled=true` (chosen via the okstra-run picker or `--critic`), a reused-worker critic pass is dispatched concurrently with the first convergence reverify round to surface missed findings; its gaps are merged only after a 1-round adversarial reverify that follows convergence. See `skills/okstra-convergence/SKILL.md` "Coverage critic pass".
+  - Phase 5.5 convergence runs in **adversarial mode** for this phase (`convergence.adversarial=true`). Verifiers actively try to refute each worker's finding by directly re-inspecting the cited evidence; the burden of proof sits on the claim. See `prompts/lead/convergence.md` §"Adversarial Verification Mode". A single evidence-backed refutation prevents a finding from reaching consensus.
+  - **Coverage critic (opt-in)**: when `convergence.critic.enabled=true` (chosen via the okstra-run picker or `--critic`), a reused-worker critic pass is dispatched concurrently with the first convergence reverify round to surface missed findings; its gaps are merged only after a 1-round adversarial reverify that follows convergence. See `prompts/lead/convergence.md` "Coverage critic pass".
 - Non-goals:
   - full implementation design unless it is required to decide the next phase
   - **source code edits, plan authoring, builds, or deployments** — this run only classifies the work and routes it; deeper analysis and planning belong to subsequent phases

package/runtime/python/okstra_ctl/codex_dispatch.py

@@ -21,6 +21,7 @@ from typing import Any, Mapping, Sequence
 from .lead_events import LeadEvent, append_lead_event
 from .wrapper_status import status_path_for_prompt
 from .paths import task_dir
+from .worker_prompt_headers import WorkerPromptHeaderError, worker_prompt_headers
 
 
 SUPPORTED_CLI_WORKERS = {
@@ -32,7 +33,6 @@ BACKEND_MIXED = "mixed"
 MAX_WORKER_ATTEMPTS = 2
 REPORT_WRITER_WORKER_ID = "report-writer"
 REPORT_LANGUAGE_VALUES = {"en", "ko", "auto"}
-WORKER_PREAMBLE_PATH = Path.home() / ".okstra" / "templates" / "worker-prompt-preamble.md"
 ANALYSIS_WORKER_LABELS = {
     "codex": "Codex worker",
     "gemini": "Gemini worker",
@@ -676,19 +676,17 @@ def _base_prompt_headers(
     prompt_rel: str,
     result_rel: str,
 ) -> list[str]:
-    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"**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)}"
-        ),
-    ]
+    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
 
 
 def _analysis_input_lines(
@@ -814,53 +812,6 @@ def _implementation_executor_tail(
     return preflight_path.read_text(encoding="utf-8")
 
 
-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)
-
-
 def _project_relative_path(project_root: Path, path: Path) -> str:
     try:
         return path.relative_to(project_root).as_posix()

package/runtime/python/okstra_ctl/context_cost.py

@@ -23,15 +23,17 @@ INPUT_FILES = (
     "reference-expectations.md",
     "clarification-response.md",
 )
-# Per-run hot-path instruction assets the lead/workers load OUTSIDE the task
-# bundle: the lifecycle skills (Phase 1 / 2-5 / 5.5 / 6-7) plus the worker
+# Per-run hot-path instruction assets the lead loads OUTSIDE the task bundle:
+# the lifecycle lead contracts (Phase 1 / 2-5 / 5.5 / 6-7) plus the worker
 # agent specs. These are the prompt-diet (perf plan v2 P2) targets; the
 # bundle-local metrics below cannot see them, so they get their own metric.
-HOT_PATH_SKILLS = (
-    "okstra-context-loader",
-    "okstra-team-contract",
-    "okstra-convergence",
-    "okstra-report-writer",
+# The contracts ship as runtime resources under ~/.okstra/prompts/lead/, not
+# as agent skills.
+HOT_PATH_LEAD_RESOURCES = (
+    "context-loader",
+    "team-contract",
+    "convergence",
+    "report-writer",
 )
 WORKER_AGENT_FILES = (
     "claude-worker.md",
@@ -178,13 +180,14 @@ def _skill_assets_metric() -> dict:
     skill bodies + worker agent specs. These dominate the fixed per-run
     instruction footprint and are the prompt-diet ranking input."""
     entries = []
+    okstra_home = Path.home() / ".okstra"
     claude_home = Path.home() / ".claude"
-    for name in HOT_PATH_SKILLS:
+    for name in HOT_PATH_LEAD_RESOURCES:
         path = _installed_or_dev(
-            claude_home / "skills" / name / "SKILL.md",
-            f"skills/{name}/SKILL.md",
+            okstra_home / "prompts" / "lead" / f"{name}.md",
+            f"prompts/lead/{name}.md",
         )
-        entries.append((f"skill:{name}", path))
+        entries.append((f"resource:{name}", path))
     for fname in WORKER_AGENT_FILES:
         path = _installed_or_dev(
             claude_home / "agents" / fname,

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -12,6 +12,7 @@ from typing import Any, Mapping, Sequence
 
 from . import tmux
 from .lead_events import LeadEvent, append_lead_event
+from .worker_prompt_headers import WorkerPromptHeaderError, worker_prompt_headers
 from .wrapper_status import read_wrapper_status, status_path_for_prompt
 
 
@@ -290,9 +291,19 @@ def _job_from_roster_worker(
     state = _worker_state(team_state, worker_id)
     provider = _provider_for_worker(worker_id)
     model = _model_for_worker(worker_id, state, report_writer_model)
-    prompt_path = _resolve_project_path(project_root, _worker_prompt_path(manifest, worker_id))
-    result_path = _resolve_project_path(project_root, _require_string(state, "resultPath"))
-    _materialize_prompt_if_missing(prompt_path, worker_id, result_path, project_root)
+    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,
+    )
     return WorkerJob(
         worker_id=worker_id,
         provider=provider,
@@ -747,19 +758,31 @@ def _resolve_wrapper(provider: str, workspace_root: Path, options: _BuildOptions
     raise DispatchError(f"{script} not found (searched: {', '.join(str(c) for c in candidates)})")
 
 
-def _materialize_prompt_if_missing(prompt_path: Path, worker_id: str, result_path: Path, project_root: Path) -> None:
+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([
-            f"# {worker_id} worker prompt",
-            f"**Project Root:** {project_root}",
-            f"**Result Path:** {result_path}",
-            "",
-        ]),
-        encoding="utf-8",
-    )
+    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")
 
 
 def _provider_for_worker(worker_id: str) -> str: