okstra 0.102.2 → 0.102.4

package/docs/superpowers/plans/2026-06-15-coding-preflight-pack-dispatch-path.md

@@ -1,504 +0,0 @@
-# Coding Preflight Pack Dispatch Path Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Ensure every implementation executor/verifier prompt receives the resolved `Coding preflight pack` path, so workers can read runtime prompt resources without relying on launch-only context or hardcoded `~/.okstra` paths.
-
-**Architecture:** `OKSTRA_CODING_PREFLIGHT_DIR` is already computed by `okstra_ctl.paths.compute_run_paths()` and rendered in the lead launch prompt. Promote that value into the machine-readable active-run-context as `runtimeResources.codingPreflightDir`, then include it as a worker prompt anchor header: `**Coding preflight pack:** <absolute-path>`. Deterministic dispatchers (`codex_dispatch.py`, `dispatch_core.py`) read the active context and inject the same header; prompt docs and tests treat this worker header as the source workers consume.
-
-**Tech Stack:** Python `okstra_ctl` render/dispatch modules, markdown prompt contracts, pytest for prompt/docs contracts, Node `node:test` for install/runtime surface checks, existing `npm run build` runtime sync.
-
----
-
-## Problem
-
-The previous migration removed hardcoded `~/.okstra/prompts/coding-preflight/` paths and made worker-facing text say to use the `Coding preflight pack:` path. That path currently appears in the lead launch prompt's `## Okstra Runtime Resources` block, but worker dispatch prompts do not reliably carry that block.
-
-Observed grounding:
-
-- Launch prompt resource block includes `Coding preflight pack`: `scripts/okstra_ctl/render.py` builds it from `OKSTRA_CODING_PREFLIGHT_DIR`.
-- Active-run-context currently has task/run/instruction/workers/errorLogs/executorWorktree/sourceArtifacts/lazyReadPlan, but no runtime resource paths.
-- Worker prompt anchor contract lists only seven headers, ending at `**Errors sidecar path:**`.
-- Codex/Gemini materialized prompts are produced by `scripts/okstra_ctl/codex_dispatch.py::_base_prompt_headers()` and currently omit the preflight pack path.
-- Generic `dispatch_core.py::_materialize_prompt_if_missing()` creates a minimal fallback prompt and also omits the preflight pack path.
-- `agents/workers/claude-worker.md` currently points the executor to the lead prompt's `## Okstra Runtime Resources`; workers do not necessarily receive that launch prompt.
-
-## Design decision
-
-Use a worker prompt anchor header, not prose-only forwarding.
-
-New invariant:
-
-```markdown
-**Coding preflight pack:** <absolute-path>
-```
-
-Placement:
-
-- Add it to every worker prompt anchor set after `**Worker Preamble Path:**` and before error-log headers.
-- Include it for all worker roles. Non-executor workers can ignore it; a uniform header avoids role-specific prompt shape drift.
-- The value must come from `active-run-context.runtimeResources.codingPreflightDir` when available.
-- Fallback for older active contexts: `okstra_home() / "prompts" / "coding-preflight"`, honoring `OKSTRA_HOME`.
-
-Why this design:
-
-- Workers already parse anchor headers (`Project Root`, `Result Path`, `Errors sidecar path`). This keeps path delivery in the existing mechanism.
-- Active-run-context is the machine-readable bridge from render-time computed paths to later deterministic dispatch.
-- Avoids reintroducing hidden skills or default-home literals.
-- Avoids inlining the whole preflight pack; workers still lazy-load only the resources selected by the router.
-
-## Task 1: Add runtime resource paths to active-run-context
-
-**Files:**
-- Modify: `scripts/okstra_ctl/render.py`
-- Modify: `tests/test_lead_runtime_marker.py` or a new focused pytest in `tests/test_docs_runtime_contract.py`
-
-- [ ] **Step 1: Add `_active_runtime_resources(ctx)`**
-
-In `scripts/okstra_ctl/render.py`, add a helper near `_active_error_logs` / `_active_executor_worktree`:
-
-```python
-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"),
-    }
-```
-
-Use only absolute paths. `OKSTRA_CODING_PREFLIGHT_DIR` is already computed by `paths.py` from `OKSTRA_HOME`, so this honors non-default runtime homes.
-
-- [ ] **Step 2: Persist it in `render_active_run_context`**
-
-Add the new field to the active context payload:
-
-```python
-payload = {
-    "schemaVersion": "1.0",
-    "kind": "active-run-context",
-    "task": _active_task(ctx),
-    "workflow": _active_workflow(ctx),
-    "run": _active_run(ctx),
-    "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(),
-}
-```
-
-Do not remove or rename existing active context fields.
-
-- [ ] **Step 3: Add active-context regression test**
-
-Add a focused test that renders a task bundle with custom `OKSTRA_HOME` and reads the generated active-run-context JSON.
-
-Expected assertions:
-
-```python
-active = json.loads(active_context_path.read_text(encoding="utf-8"))
-assert active["runtimeResources"]["codingPreflightDir"] == (
-    str(Path(os.environ["OKSTRA_HOME"]) / "prompts" / "coding-preflight")
-)
-```
-
-If an existing render test already locates `activeRunContextPath`, extend it rather than adding a parallel fixture.
-
-- [ ] **Step 4: Run focused Python test**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_lead_runtime_marker.py tests/test_docs_runtime_contract.py
-```
-
-Expected: all tests pass and the new active-context assertion confirms `OKSTRA_HOME` is honored.
-
-## Task 2: Add `Coding preflight pack` to the worker prompt contract
-
-**Files:**
-- Modify: `prompts/lead/team-contract.md`
-- Modify: `agents/workers/claude-worker.md`
-- Modify: `prompts/profiles/_coding-conventions-preflight.md`
-- Modify: `prompts/profiles/_implementation-verifier.md`
-- Modify: `tests/test_docs_runtime_contract.py`
-
-- [ ] **Step 1: Update anchor header list**
-
-In `prompts/lead/team-contract.md`, update `## Worker Prompt Composition` so the anchor list becomes:
-
-```markdown
-1. `**Project Root:** <absolute-path>` — absolute target project root (from `{{PROJECT_ROOT}}` in the lead's prompt). Required so the worker can self-anchor without relying on inherited cwd.
-2. `**Prompt History Path:** <project-relative-path>`
-3. `**Result Path:** <project-relative-path>` — canonical destination for the worker's result file. Workers resolve it to absolute against `**Project Root:**` and use it for the post-completion existence check (see CLI wrapper agents' step 8c, and Lead's redispatch policy below). The path identifies a single file; do NOT deliver a directory.
-4. `Assigned worker prompt history path: <absolute-path>` — same as the prompt-history path but resolved against `Project Root`. Codex/Gemini wrapper subagents extract this exact line.
-5. `**Worker Preamble Path:** <absolute-path>` — points to `~/.okstra/templates/worker-prompt-preamble.md` (canonical SSOT for Required Reading + Error Reporting + Anchor / Output sections). Workers Read this file end-to-end before producing any output. This anchor replaces the ~80 lines of inlined `[Required reading]` / `[Error reporting]` boilerplate that earlier versions injected into every dispatch.
-6. `**Coding preflight pack:** <absolute-path>` — points to the installed runtime resource pack under `<OKSTRA_HOME>/prompts/coding-preflight`. Implementation executors and verifiers use this to read `overview.md`, `clean-code.md`, and routed language/framework/architecture resources. Other worker roles may ignore it.
-7. `**Errors log path:** <absolute-path>` — run-level errors JSONL.
-8. `**Errors sidecar path:** <absolute-path>` — this worker's per-run sidecar JSON.
-```
-
-Update any local references that say headers #6 and #7 to #7 and #8.
-
-- [ ] **Step 2: Update worker-facing prose to consume the worker header**
-
-In `agents/workers/claude-worker.md`, replace `from the lead prompt's ## Okstra Runtime Resources block` with `from this worker prompt's **Coding preflight pack:** anchor header`.
-
-Expected sentence:
-
-```markdown
-Use this worker prompt's `**Coding preflight pack:**` anchor header; read that pack's `overview.md` and `clean-code.md`, then follow the routed pack's language → framework → architecture stages, iterating every rule and loading every matching resource.
-```
-
-- [ ] **Step 3: Update executor/verifier sidecars to consume the worker header**
-
-In `prompts/profiles/_coding-conventions-preflight.md`, replace launch-prompt wording:
-
-```markdown
-Use this worker prompt's `**Coding preflight pack:**` anchor header as the absolute path to the installed routed pack.
-```
-
-In `prompts/profiles/_implementation-verifier.md`, replace launch-prompt wording with the same worker-header wording.
-
-This matters because executor/verifier prompts are dispatched worker prompts, not the lead launch prompt.
-
-- [ ] **Step 4: Add docs contract checks**
-
-In `tests/test_docs_runtime_contract.py`, add or extend a test:
-
-```python
-def test_worker_prompt_contract_carries_coding_preflight_pack_anchor():
-    team_contract = _read_doc("prompts/lead/team-contract.md")
-    assert "`**Coding preflight pack:** <absolute-path>`" in team_contract
-    assert "**Worker Preamble Path:**" in team_contract
-    assert team_contract.index("**Worker Preamble Path:**") < team_contract.index("**Coding preflight pack:**")
-    assert team_contract.index("**Coding preflight pack:**") < team_contract.index("**Errors log path:**")
-
-    for relative_path in [
-        "agents/workers/claude-worker.md",
-        "prompts/profiles/_coding-conventions-preflight.md",
-        "prompts/profiles/_implementation-verifier.md",
-    ]:
-        text = _read_doc(relative_path)
-        assert "worker prompt's `**Coding preflight pack:**`" in text, relative_path
-        assert "lead prompt's `## Okstra Runtime Resources`" not in text, relative_path
-```
-
-- [ ] **Step 5: Run focused docs tests**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_docs_runtime_contract.py
-```
-
-Expected: all docs contract tests pass.
-
-## Task 3: Inject the header into deterministic worker prompt materialization
-
-**Files:**
-- Modify: `scripts/okstra_ctl/codex_dispatch.py`
-- Modify: `scripts/okstra_ctl/dispatch_core.py`
-- Modify: `tests/test_codex_dispatch.py`
-- Modify or add: dispatch-core pytest if one exists for `_materialize_prompt_if_missing`
-
-- [ ] **Step 1: Add a shared local resolver in `codex_dispatch.py`**
-
-In `scripts/okstra_ctl/codex_dispatch.py`, import `okstra_home` from `okstra_ctl.paths` if not already imported:
-
-```python
-from .paths import okstra_home
-```
-
-Add helper near `_base_prompt_headers`:
-
-```python
-def _coding_preflight_pack_path(active_context: Mapping[str, Any]) -> Path:
-    runtime_resources = active_context.get("runtimeResources")
-    if isinstance(runtime_resources, Mapping):
-        value = _string_value(runtime_resources.get("codingPreflightDir"))
-        if value:
-            return Path(value)
-    return okstra_home() / "prompts" / "coding-preflight"
-```
-
-- [ ] **Step 2: Add header to `_base_prompt_headers`**
-
-Insert the header after `Worker Preamble Path` and before error-log headers:
-
-```python
-return [
-    f"**Project Root:** {project_root}",
-    f"**Prompt History Path:** {prompt_rel}",
-    f"**Result Path:** {result_rel}",
-    f"Assigned worker prompt history path: {prompt_path}",
-    f"**Worker Preamble Path:** {WORKER_PREAMBLE_PATH}",
-    f"**Coding preflight pack:** {_coding_preflight_pack_path(active_context)}",
-    f"**Errors log path:** {_errors_log_path(project_root, manifest, active_context)}",
-    (
-        f"**Errors sidecar path:** "
-        f"{_worker_errors_sidecar_path(project_root, manifest, active_context, worker_id)}"
-    ),
-]
-```
-
-This covers Codex/Gemini materialized analysis, executor, and report-writer prompts.
-
-- [ ] **Step 3: Add the header to `dispatch_core.py` minimal fallback**
-
-`dispatch_core.py::_materialize_prompt_if_missing()` currently receives `active_context` at the caller level but not in the function. Thread it through:
-
-```python
-_materialize_prompt_if_missing(prompt_path, worker_id, result_path, project_root, active_context)
-```
-
-Change the function signature:
-
-```python
-def _materialize_prompt_if_missing(
-    prompt_path: Path,
-    worker_id: str,
-    result_path: Path,
-    project_root: Path,
-    active_context: Mapping[str, Any],
-) -> None:
-```
-
-Add a helper in `dispatch_core.py` mirroring the resolver:
-
-```python
-def _coding_preflight_pack_path(active_context: Mapping[str, Any]) -> Path:
-    runtime_resources = active_context.get("runtimeResources")
-    if isinstance(runtime_resources, Mapping):
-        value = _string_value(runtime_resources.get("codingPreflightDir"))
-        if value:
-            return Path(value)
-    return okstra_home() / "prompts" / "coding-preflight"
-```
-
-Import `okstra_home` from `.paths`.
-
-Include the header in the fallback prompt:
-
-```python
-prompt_path.write_text(
-    "\n".join([
-        f"# {worker_id} worker prompt",
-        f"**Project Root:** {project_root}",
-        f"**Result Path:** {result_path}",
-        f"**Coding preflight pack:** {_coding_preflight_pack_path(active_context)}",
-        "",
-    ]),
-    encoding="utf-8",
-)
-```
-
-This fallback prompt is still minimal by design, but it no longer violates the runtime-resource path contract.
-
-- [ ] **Step 4: Extend Codex dispatch test**
-
-In `tests/test_codex_dispatch.py::test_build_dispatch_plan_generates_executor_prompt_for_implementation`, set the active context runtime resource path before writing it:
-
-```python
-active_context["runtimeResources"] = {
-    "codingPreflightDir": "/tmp/okstra-runtime/prompts/coding-preflight"
-}
-```
-
-Add assertions:
-
-```python
-assert "**Coding preflight pack:** /tmp/okstra-runtime/prompts/coding-preflight" in prompt
-assert prompt.index("**Worker Preamble Path:**") < prompt.index("**Coding preflight pack:**")
-assert prompt.index("**Coding preflight pack:**") < prompt.index("**Errors log path:**")
-```
-
-Also add a report-writer or default worker materialization assertion if a nearby test already reads those prompt files. The header should be uniform across roles.
-
-- [ ] **Step 5: Add fallback test for old active contexts**
-
-Add a narrow test that omits `runtimeResources` from active context and sets `OKSTRA_HOME` with `monkeypatch`:
-
-```python
-monkeypatch.setenv("OKSTRA_HOME", str(tmp_path / "custom-okstra-home"))
-...
-assert f"**Coding preflight pack:** {tmp_path / 'custom-okstra-home' / 'prompts' / 'coding-preflight'}" in prompt
-```
-
-Use an existing dispatch test fixture to avoid duplicating manifest setup.
-
-- [ ] **Step 6: Run focused dispatch tests**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_codex_dispatch.py
-```
-
-Expected: all codex dispatch tests pass and materialized executor prompt includes the resolved `Coding preflight pack` header.
-
-## Task 4: Strengthen regression guards for old skill paths and untracked resources
-
-**Files:**
-- Modify: `tests/test_docs_runtime_contract.py`
-- Modify: `tests-js/skill-catalog.test.mjs` or add a small JS filesystem test if preferred
-
-- [ ] **Step 1: Forbid old internal skill paths in scanned live docs**
-
-Extend `forbidden_fragments` in `tests/test_docs_runtime_contract.py` with exact stale path fragments:
-
-```python
-"~/.claude/skills/okstra-coding-preflight",
-"~/.claude/skills/okstra-team-contract",
-"~/.claude/skills/okstra-convergence",
-"~/.claude/skills/okstra-report-writer",
-"skills/okstra-context-loader/SKILL.md",
-"skills/okstra-team-contract/SKILL.md",
-"skills/okstra-convergence/SKILL.md",
-"skills/okstra-report-writer/SKILL.md",
-"skills/okstra-coding-preflight/SKILL.md",
-```
-
-The scan should remain limited to live prompts/docs/templates, not dated historical plans.
-
-- [ ] **Step 2: Add source-resource existence test**
-
-Add a test that fails if required new source files are not present in the working tree. Python is simplest because the docs test already has `REPO_ROOT`:
-
-```python
-def test_internal_runtime_resource_sources_exist():
-    for relative_path in [
-        "src/skill-catalog.mjs",
-        "prompts/lead/okstra-lead-contract.md",
-        "prompts/lead/context-loader.md",
-        "prompts/lead/team-contract.md",
-        "prompts/lead/convergence.md",
-        "prompts/lead/report-writer.md",
-        "prompts/coding-preflight/overview.md",
-        "prompts/coding-preflight/clean-code.md",
-        "prompts/coding-preflight/languages/javascript-typescript.md",
-        "prompts/coding-preflight/languages/python.md",
-        "prompts/coding-preflight/languages/rust.md",
-        "prompts/coding-preflight/languages/java.md",
-        "prompts/coding-preflight/languages/kotlin.md",
-        "prompts/coding-preflight/languages/sql.md",
-        "prompts/coding-preflight/frameworks/node-server.md",
-        "prompts/coding-preflight/architectures/hexagonal.md",
-    ]:
-        assert (REPO_ROOT / relative_path).is_file(), relative_path
-```
-
-This does not prove git tracking by itself, but it catches clean-checkout omissions once CI runs on the branch.
-
-- [ ] **Step 3: Add manual git tracking gate before push**
-
-Before commit/push, run:
-
-```bash
-git status --short -- prompts/lead prompts/coding-preflight src/skill-catalog.mjs tests-js/skill-catalog.test.mjs
-```
-
-Expected: these paths appear as staged additions (`A`) or tracked modifications/deletions, not untracked (`??`). If any required runtime resource still shows `??`, stage it before pushing.
-
-## Task 5: Final verification
-
-**Files:**
-- Generated: `runtime/` via `npm run build`
-
-- [ ] **Step 1: Build runtime**
-
-Run:
-
-```bash
-npm run build
-```
-
-Expected: build exits 0 and syncs prompt/agent/source changes into `runtime/`.
-
-- [ ] **Step 2: Focused tests**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_docs_runtime_contract.py tests/test_codex_dispatch.py tests/test_lead_runtime_marker.py
-node --test tests-js/install-runtime.test.mjs tests-js/skill-catalog.test.mjs
-```
-
-Expected: all listed tests pass.
-
-- [ ] **Step 3: Materialized executor prompt smoke**
-
-Run or add a test equivalent to:
-
-```bash
-python3 -m pytest tests/test_codex_dispatch.py::test_build_dispatch_plan_generates_executor_prompt_for_implementation
-```
-
-Expected: generated executor prompt contains `**Coding preflight pack:** <resolved-path>` before `**Errors log path:**`.
-
-- [ ] **Step 4: Stale reference search**
-
-Run searches for live stale references:
-
-```text
-~/.okstra/prompts/coding-preflight
-~/.claude/skills/okstra-coding-preflight
-~/.claude/skills/okstra-team-contract
-skills/okstra-team-contract/SKILL.md
-skills/okstra-convergence/SKILL.md
-convergence skill
-schema in the convergence skill
-lead prompt's `## Okstra Runtime Resources`
-```
-
-Expected: no matches in live prompt resources, worker templates, README, architecture docs, CLI docs, source code, or tests except forbidden-fragment test literals. Historical plans may still contain old paths when clearly archival.
-
-- [ ] **Step 5: Full suite**
-
-Run:
-
-```bash
-npm run check
-```
-
-Expected: build, JS tests, Python tests, and workflow validator pass.
-
-- [ ] **Step 6: Runtime surface assertion**
-
-Run:
-
-```bash
-node --input-type=module -e "
-import assert from 'node:assert/strict';
-import { readdirSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { USER_SKILL_NAMES, OBSOLETE_INTERNAL_SKILL_NAMES } from './src/skill-catalog.mjs';
-const names = readdirSync('runtime/skills', { withFileTypes: true })
-  .filter((entry) => entry.isDirectory())
-  .map((entry) => entry.name)
-  .sort();
-assert.deepEqual(names, [...USER_SKILL_NAMES].sort());
-for (const name of OBSOLETE_INTERNAL_SKILL_NAMES) {
-  assert.equal(existsSync(join('runtime/skills', name)), false, name);
-}
-assert.equal(existsSync('runtime/prompts/lead/okstra-lead-contract.md'), true);
-assert.equal(existsSync('runtime/prompts/coding-preflight/overview.md'), true);
-assert.equal(existsSync('runtime/prompts/coding-preflight/languages/python.md'), true);
-console.log('runtime surface ok');
-"
-```
-
-Expected: exit code 0 and `runtime surface ok`.
-
-## Completion criteria
-
-The migration is complete only when:
-
-- Active-run-context persists `runtimeResources.codingPreflightDir` from the resolved runtime home.
-- Every materialized worker prompt carries `**Coding preflight pack:** <absolute-path>`.
-- Executor/verifier/worker prose consumes the worker prompt header, not the lead launch prompt.
-- No live prompt/doc/source path reintroduces hidden/internal skill locations.
-- Required new source/resource files are tracked before push.
-- Focused tests, dispatch prompt smoke, stale-reference search, `npm run check`, and runtime surface assertion pass freshly.