okstra 0.82.1 → 0.83.0

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:

package/runtime/python/okstra_ctl/paths.py

@@ -33,9 +33,15 @@ __all__ = [
     "next_run_seq",
     "task_dir",
     "task_runs_dir",
+    "okstra_home",
 ]
 
 
+def okstra_home() -> Path:
+    raw = os.environ.get("OKSTRA_HOME", "").strip()
+    return Path(raw).expanduser() if raw else Path.home() / ".okstra"
+
+
 def task_dir(project_root: Path, task_group: str, task_id: str) -> Path:
     """task root 경로: ``<project>/.okstra/tasks/<group-seg>/<id-seg>``.
 
@@ -188,6 +194,8 @@ def compute_run_paths(
     report_writer_worker_result = worker_results / f"report-writer-worker{suffixes['worker_results']}.md"
 
     run_errors_log = run_logs / f"errors-{task_type_segment}-{seqs['state']}.jsonl"
+    runtime_home = okstra_home()
+
     claude_worker_errors_sidecar = worker_results / f"claude-worker-errors{suffixes['worker_results']}.json"
     codex_worker_errors_sidecar = worker_results / f"codex-worker-errors{suffixes['worker_results']}.json"
     gemini_worker_errors_sidecar = worker_results / f"gemini-worker-errors{suffixes['worker_results']}.json"
@@ -209,7 +217,25 @@ def compute_run_paths(
         "OKSTRA_ROOT": str(okstra_root),
         "OKSTRA_TASKS_ROOT": str(tasks_root),
         "WORKER_PROMPT_PREAMBLE_PATH": str(
-            Path.home() / ".okstra" / "templates" / "worker-prompt-preamble.md"
+            runtime_home / "templates" / "worker-prompt-preamble.md"
+        ),
+        "OKSTRA_LEAD_CONTRACT_PATH": str(
+            runtime_home / "prompts" / "lead" / "okstra-lead-contract.md"
+        ),
+        "OKSTRA_CONTEXT_LOADER_PATH": str(
+            runtime_home / "prompts" / "lead" / "context-loader.md"
+        ),
+        "OKSTRA_TEAM_CONTRACT_PATH": str(
+            runtime_home / "prompts" / "lead" / "team-contract.md"
+        ),
+        "OKSTRA_CONVERGENCE_PATH": str(
+            runtime_home / "prompts" / "lead" / "convergence.md"
+        ),
+        "OKSTRA_REPORT_WRITER_PATH": str(
+            runtime_home / "prompts" / "lead" / "report-writer.md"
+        ),
+        "OKSTRA_CODING_PREFLIGHT_DIR": str(
+            runtime_home / "prompts" / "coding-preflight"
         ),
         "OKSTRA_DISCOVERY_DIR": str(discovery_dir),
         "TASK_ROOT": str(task_root),

package/runtime/python/okstra_ctl/render.py

@@ -28,6 +28,7 @@ from okstra_project.dirs import OKSTRA_DIR_NAME, project_json_path
 # render_task_manifest 가 동일한 리스트/딕셔너리를 로컬에 중복 정의했는데,
 # 이는 silent drift 위험이 있어 SSOT import 로 통합한다.
 from . import fix_cycles
+from .paths import okstra_home
 from .lead_runtime import lead_runtime_info
 from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
 
@@ -369,6 +370,14 @@ def _active_error_logs(ctx: dict) -> dict:
     }
 
 
+def _active_runtime_resources(ctx: dict) -> dict:
+    runtime_home = okstra_home()
+    return {
+        "codingPreflightDir": ctx.get("OKSTRA_CODING_PREFLIGHT_DIR")
+        or str(runtime_home / "prompts" / "coding-preflight"),
+    }
+
+
 def _active_executor_worktree(ctx: dict) -> dict:
     return {
         "status": ctx.get("EXECUTOR_WORKTREE_STATUS", ""),
@@ -419,6 +428,7 @@ def render_active_run_context(active_context_path: str, ctx: dict) -> None:
         "instructionSet": _active_instruction_set(ctx),
         "workers": _active_workers(ctx),
         "errorLogs": _active_error_logs(ctx),
+        "runtimeResources": _active_runtime_resources(ctx),
         "executorWorktree": _active_executor_worktree(ctx),
         "sourceArtifacts": _active_source_artifacts(ctx),
         "lazyReadPlan": _active_lazy_read_plan(),
@@ -1104,7 +1114,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
 def _build_convergence_block(ctx: dict) -> dict:
     """Resolve the `convergence` sub-tree written into task-manifest.json.
 
-    Defaults follow `skills/okstra-convergence/SKILL.md`:
+    Defaults follow `prompts/lead/convergence.md`:
     - `enabled` default True
     - `maxRounds` default 1 for `requirements-discovery`, 2 otherwise
     - `verificationMode` default "lightweight"
@@ -1667,6 +1677,35 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
     lead_agent_label = _lead_agent_label(ctx)
     lead_model = ctx.get("LEAD_MODEL", "")
     lead_model_execution = ctx.get("LEAD_MODEL_EXECUTION_VALUE", "")
+    home_prompts = okstra_home() / "prompts"
+    lead_contract_path = ctx.get("OKSTRA_LEAD_CONTRACT_PATH") or str(
+        home_prompts / "lead" / "okstra-lead-contract.md"
+    )
+    context_loader_path = ctx.get("OKSTRA_CONTEXT_LOADER_PATH") or str(
+        home_prompts / "lead" / "context-loader.md"
+    )
+    team_contract_path = ctx.get("OKSTRA_TEAM_CONTRACT_PATH") or str(
+        home_prompts / "lead" / "team-contract.md"
+    )
+    convergence_path = ctx.get("OKSTRA_CONVERGENCE_PATH") or str(
+        home_prompts / "lead" / "convergence.md"
+    )
+    report_writer_path = ctx.get("OKSTRA_REPORT_WRITER_PATH") or str(
+        home_prompts / "lead" / "report-writer.md"
+    )
+    coding_preflight_dir = ctx.get("OKSTRA_CODING_PREFLIGHT_DIR") or str(
+        home_prompts / "coding-preflight"
+    )
+    okstra_runtime_resources_block = (
+        "## Okstra Runtime Resources\n"
+        "\n"
+        f"- Lead contract: `{lead_contract_path}`\n"
+        f"- Context loader: `{context_loader_path}`\n"
+        f"- Team contract: `{team_contract_path}`\n"
+        f"- Convergence contract: `{convergence_path}`\n"
+        f"- Report writer contract: `{report_writer_path}`\n"
+        f"- Coding preflight pack: `{coding_preflight_dir}`"
+    )
 
     def fmt_assignment(role: str, model: str, execution: str) -> str:
         if execution and execution != model:
@@ -1852,7 +1891,7 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
             "## Team Creation Gate (BLOCKING)\n"
             "\n"
             "Before any `Agent` dispatch for workers, you MUST perform Phase 3 of the\n"
-            '`okstra` skill (`agents/SKILL.md` → "Phase 3 — Team creation"). Skipping\n'
+            f'okstra lead contract (`{lead_contract_path}` \u2192 "Phase 3 \u2014 Team creation"). Skipping\n'
             "this gate silently degrades the run to in-process background dispatch and\n"
             "loses the Teams split-pane observability surface, even though worker\n"
             "outputs may still appear correct on disk.\n"
@@ -1861,7 +1900,7 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
             "for this run (roster comes from `resultContract.requiredWorkerRoles` in\n"
             "`task-manifest.json` — it may be 1, 2, 3, or more workers):\n"
             "\n"
-            "1. Invoke the `okstra-team-contract` skill and verify the selected worker\n"
+            f"1. Read the team-contract resource (`{team_contract_path}`) and verify the selected worker\n"
             "   roster against `task-manifest.json`'s `resultContract.requiredWorkerRoles`.\n"
             f'2. Call `TeamCreate(team_name: "{team_name}", description: ...)`.\n'
             "3. Record the outcome in team-state under\n"
@@ -1943,8 +1982,10 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
     else:
         lead_intro_line = f"You are `{lead_role}` for project `{ctx.get('PROJECT_ID', '')}`."
         lead_bootstrap_instruction = (
-            "Invoke the `okstra` skill now. Read the manifests below for all task "
-            "metadata, paths, model assignments, and worker roster."
+            f"Read the Okstra lead contract at `{lead_contract_path}` now, then read "
+            "the manifests below for all task metadata, paths, model assignments, and "
+            "worker roster. Follow the contract's lazy-read rules for support resources; "
+            "do not invoke hidden/internal skills."
         )
         lead_session_block = (
             "## Session\n"
@@ -1957,9 +1998,9 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
             "\n"
             "- The `runs/<phase>/prompts/<worker>-worker-prompt-*.md` files referenced in `task-manifest.json → artifacts.workerPromptPathByWorkerId` are **NOT** rendered by the okstra runtime. Those paths are the *assigned* locations where the prompt history MUST be written at dispatch time.\n"
             "- Therefore: at the start of every phase the prompts/ directory is normally empty (or contains only previously-dispatched workers' files). This is expected. Do NOT narrate it as \"missing\", \"누락\", or \"not yet rendered\" — it just means dispatch has not happened yet.\n"
-            "- Before dispatching any required worker, **you (the lead) construct the worker prompt and persist it to the assigned absolute path using `Write`** (per `okstra-team-contract` rule 6). Only after persisting do you call the worker subagent (Agent tool / Codex / Gemini wrapper). The wrapper subagents will also re-write the same file on their end; the double-write is intentional and idempotent.\n"
+            "- Before dispatching any required worker, **you (the lead) construct the worker prompt and persist it to the assigned absolute path using `Write`** (per `team-contract` rule 6). Only after persisting do you call the worker subagent (Agent tool / Codex / Gemini wrapper). The wrapper subagents will also re-write the same file on their end; the double-write is intentional and idempotent.\n"
             "- Do not \"check if the file exists and skip dispatch\" — file presence is not a signal to skip. Worker selection and skipping rules come from team-state, never from prompts/ directory contents.\n"
-            f"- **Worker Preamble Path (single anchor — replaces inlined `[Required reading]` and `[Error reporting]` blocks).** Every worker prompt you construct MUST include the anchor header `**Worker Preamble Path:** {ctx.get('WORKER_PROMPT_PREAMBLE_PATH', str(Path.home() / '.okstra' / 'templates' / 'worker-prompt-preamble.md'))}`. The file at that path is the canonical SSOT for Required Reading + Error Reporting + Output sections; workers Read it end-to-end before producing output. Do NOT re-inline those blocks into worker prompt bodies — that is the legacy ~80-line dispatch boilerplate that this anchor is designed to replace."
+            f"- **Worker Preamble Path (single anchor — replaces inlined `[Required reading]` and `[Error reporting]` blocks).** Every worker prompt you construct MUST include the anchor header `**Worker Preamble Path:** {ctx.get('WORKER_PROMPT_PREAMBLE_PATH', str(okstra_home() / 'templates' / 'worker-prompt-preamble.md'))}`. The file at that path is the canonical SSOT for Required Reading + Error Reporting + Output sections; workers Read it end-to-end before producing output. Do NOT re-inline those blocks into worker prompt bodies — that is the legacy ~80-line dispatch boilerplate that this anchor is designed to replace."
         )
 
     # Compute results (deterministic from ctx, 덮어쓰기)
@@ -1968,6 +2009,7 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
     ctx["LEAD_SESSION_BLOCK"] = lead_session_block
     ctx["TEAM_CREATION_GATE"] = team_creation_gate_block
     ctx["WORKER_DISPATCH_GUIDANCE"] = worker_dispatch_guidance
+    ctx["OKSTRA_RUNTIME_RESOURCES"] = okstra_runtime_resources_block
     ctx["WORKER_RESULT_PATH_LINES"] = "\n".join(worker_result_lines)
     ctx["MODEL_ASSIGNMENT_LINES"] = "\n".join(model_assignment_lines)
     ctx["TEAM_ROLE_LINES"] = "\n".join(team_role_lines)
@@ -2001,9 +2043,21 @@ def apply_lead_prompt_defaults(ctx: dict) -> None:
     # Empty for non-final-verification runs; the final-verification prepare
     # path overwrites it with the resolved verification target block.
     ctx.setdefault("VERIFICATION_TARGET", "")
+    runtime_home = okstra_home()
     ctx.setdefault(
         "WORKER_PROMPT_PREAMBLE_PATH",
-        str(Path.home() / ".okstra" / "templates" / "worker-prompt-preamble.md"),
+        str(runtime_home / "templates" / "worker-prompt-preamble.md"),
+    )
+    # Lead resource paths the launch template references directly. paths.py
+    # seeds the production values; setdefault backfills callers that render the
+    # template without the full path ctx (mirrors WORKER_PROMPT_PREAMBLE_PATH).
+    ctx.setdefault(
+        "OKSTRA_LEAD_CONTRACT_PATH",
+        str(runtime_home / "prompts" / "lead" / "okstra-lead-contract.md"),
+    )
+    ctx.setdefault(
+        "OKSTRA_TEAM_CONTRACT_PATH",
+        str(runtime_home / "prompts" / "lead" / "team-contract.md"),
     )
     if "AVAILABLE_MCP_SERVERS" not in ctx:
         ctx["AVAILABLE_MCP_SERVERS"] = build_available_mcp_servers_block(

package/runtime/python/okstra_ctl/run.py

@@ -1067,7 +1067,7 @@ class _ResolvedAssets:
     prompt_template: Path
     task_index_template: Path
     final_report_template: Path
-    source_skill: Path
+    lead_contract: Path
     run_validator: Path
 
 
@@ -1090,19 +1090,19 @@ def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _Resolv
     final_report_template = (
         workspace_root / "templates" / "reports" / "final-report.template.md"
     )
-    source_skill = workspace_root / "agents" / "SKILL.md"
+    lead_contract = workspace_root / "prompts" / "lead" / "okstra-lead-contract.md"
     run_validator = workspace_root / "validators" / "validate-run.py"
-    for required in (task_index_template, final_report_template, run_validator, source_skill):
+    for required in (task_index_template, final_report_template, run_validator, lead_contract):
         if not required.is_file():
             raise PrepareError(
-                f"required okstra template or source skill missing: {required}.{_INSTALL_HINT}"
+                f"required okstra template or lead contract missing: {required}.{_INSTALL_HINT}"
             )
     return _ResolvedAssets(
         profile_file=profile_file,
         prompt_template=prompt_template,
         task_index_template=task_index_template,
         final_report_template=final_report_template,
-        source_skill=source_skill,
+        lead_contract=lead_contract,
         run_validator=run_validator,
     )