okstra 0.102.2 → 0.102.4

package/docs/superpowers/plans/2026-06-15-internal-skill-migration-remaining-fixups.md

@@ -1,387 +0,0 @@
-# Internal Skill Migration Remaining Fixups 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:** Close the remaining runtime-resource gaps after moving internal Okstra contracts out of agent skill discovery.
-
-**Architecture:** Keep the public skill surface fixed at the six user-facing skills. Treat `~/.okstra/prompts/` as a required installed runtime asset, not an optional doc tree. Runtime prompt text must point workers to the resolved coding-preflight pack path from the generated launch prompt, and internal prompt resources must describe themselves as contracts/resources, never hidden skills.
-
-**Tech Stack:** Node.js ES modules for install drift checks and JS tests, Python pytest contract tests for generated prompts/docs, markdown prompt resources, existing `npm run build` runtime sync.
-
----
-
-## Current status
-
-Already verified as passing:
-
-- `npm run build`
-- targeted JS/Python/workflow checks
-- `npm run check`
-- smoke: `install --link .` exposes prompt resources
-- smoke: generated prompts honor `OKSTRA_HOME` for lead contract paths
-- smoke: dangling obsolete internal skill symlink prune
-- runtime surface: `runtime/skills` contains only the six public skills and prompt resources exist under `runtime/prompts/`
-
-Still failing or incomplete:
-
-1. `okstra ensure-installed` reports OK when `~/.okstra/prompts/` is missing.
-2. implementation executor/verifier sidecars still hardcode `~/.okstra/prompts/coding-preflight/` instead of using the resolved `Coding preflight pack` path from the launch prompt.
-3. runtime prompt resources still describe internal contracts as “skill”.
-4. historical backlog references still point at removed internal skill paths; decide whether to update or explicitly mark them historical.
-
-## Task 1: Make `ensure-installed` verify prompt resources
-
-**Files:**
-- Modify: `src/install.mjs`
-- Modify: `tests-js/install-runtime.test.mjs`
-
-- [ ] **Step 1: Add required runtime prompt resource list**
-
-In `src/install.mjs`, near the other install constants, add an exact list of prompt files that must exist for any installed runtime:
-
-```js
-const REQUIRED_PROMPT_RESOURCE_FILES = Object.freeze([
-  ["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", "frameworks", "node-server.md"],
-  ["prompts", "coding-preflight", "architectures", "hexagonal.md"],
-]);
-```
-
-This is intentionally an allowlist, not a directory wildcard. The list catches the files the launch prompt and routed coding-preflight pack depend on.
-
-- [ ] **Step 2: Add a prompt drift helper**
-
-In `src/install.mjs`, near `skillTargetDriftReasons` / `agentDriftReasons`, add:
-
-```js
-async function promptResourceDriftReasons(paths) {
-  const reasons = [];
-  for (const parts of REQUIRED_PROMPT_RESOURCE_FILES) {
-    const path = join(paths.home, ...parts);
-    if (!(await fileExists(path))) reasons.push(`missing ${path}`);
-  }
-  return reasons;
-}
-```
-
-- [ ] **Step 3: Call prompt drift helper from `runEnsureInstalled`**
-
-In `runEnsureInstalled`, after the schema check and before skill target checks, add:
-
-```js
-for (const reason of await promptResourceDriftReasons(paths)) {
-  reasons.push(reason);
-}
-```
-
-Expected behavior: a version-current install with missing prompt resources must run `runInstall(...)` instead of returning `okstra runtime OK`.
-
-- [ ] **Step 4: Add regression test for missing prompt resources**
-
-Update the import in `tests-js/install-runtime.test.mjs` to include `rmSync`:
-
-```js
-import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
-```
-
-Add a test near the other install/ensure tests:
-
-```js
-test("ensure-installed repairs missing runtime prompt resources", () => {
-  const { root, env } = makeInstallEnv();
-  mkdirSync(join(root, ".claude"), { recursive: true });
-
-  const install = runCli(["install", "--quiet"], { ...env, OKSTRA_RUNTIME_HOST: "external" });
-  assert.equal(install.code, 0, install.stderr);
-
-  rmSync(join(root, ".okstra", "prompts"), { recursive: true, force: true });
-
-  const ensure = runCli(["ensure-installed"], { ...env, OKSTRA_RUNTIME_HOST: "external" });
-  assert.equal(ensure.code, 0, ensure.stderr);
-  assert.match(ensure.stderr, /okstra runtime needs install:/);
-  assert.equal(existsSync(join(root, ".okstra", "prompts", "lead", "okstra-lead-contract.md")), true);
-  assert.equal(existsSync(join(root, ".okstra", "prompts", "coding-preflight", "overview.md")), true);
-});
-```
-
-- [ ] **Step 5: Run focused JS test**
-
-Run:
-
-```bash
-node --test tests-js/install-runtime.test.mjs
-```
-
-Expected: all install-runtime subtests pass, including `ensure-installed repairs missing runtime prompt resources`.
-
-## Task 2: Remove hardcoded coding-preflight home paths from executor/verifier sidecars
-
-**Files:**
-- Modify: `prompts/profiles/_coding-conventions-preflight.md`
-- Modify: `prompts/profiles/_implementation-verifier.md`
-- Modify: `tests/test_docs_runtime_contract.py`
-
-- [ ] **Step 1: Update executor coding-preflight wording**
-
-Replace the hardcoded path wording in `prompts/profiles/_coding-conventions-preflight.md` with launch-resource wording:
-
-```markdown
-- **Resource selection — read the routed pack, never inline it here.** Use the `Coding preflight pack:` absolute path listed in the generated launch prompt's `## Okstra Runtime Resources` block. 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 layouts). In every stage, iterate all rules and accumulate every matching resource; do not stop after the first match.
-```
-
-Also update the graceful-degradation line to avoid `~/.okstra`:
-
-```markdown
-- **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.
-```
-
-- [ ] **Step 2: Update verifier coding-preflight wording**
-
-Replace the hardcoded path wording in `prompts/profiles/_implementation-verifier.md` with:
-
-```markdown
-- **Load the same conventions the executor used via the routed pack.** Use the `Coding preflight pack:` absolute path listed in the generated launch prompt's `## Okstra Runtime Resources` block. 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 into the prompt; it reads the same resource files the executor used.
-```
-
-- [ ] **Step 3: Add contract test for no hardcoded default preflight path**
-
-In `tests/test_docs_runtime_contract.py`, add:
-
-```python
-def test_profile_sidecars_use_resolved_coding_preflight_pack_path():
-    for relative_path in [
-        "prompts/profiles/_coding-conventions-preflight.md",
-        "prompts/profiles/_implementation-verifier.md",
-    ]:
-        text = _read_doc(relative_path)
-        assert "Coding preflight pack:" in text, relative_path
-        assert "~/.okstra/prompts/coding-preflight" not in text, relative_path
-```
-
-- [ ] **Step 4: Run focused Python contract test**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_docs_runtime_contract.py::test_profile_sidecars_use_resolved_coding_preflight_pack_path
-```
-
-Expected: the new test passes.
-
-## Task 3: Remove stale internal-skill wording from runtime prompt resources
-
-**Files:**
-- Modify: `prompts/lead/context-loader.md`
-- Modify: `prompts/lead/convergence.md`
-- Modify: `prompts/lead/report-writer.md`
-- Modify: `prompts/lead/team-contract.md`
-- Modify: `prompts/coding-preflight/overview.md`
-- Modify: `prompts/coding-preflight/languages/python.md`
-- Modify: `prompts/coding-preflight/languages/rust.md`
-- Modify: `tests/test_docs_runtime_contract.py`
-
-- [ ] **Step 1: Replace internal contract self-descriptions**
-
-Apply these exact terminology replacements where they refer to moved internal contracts/resources:
-
-```text
-okstra Skill Phase 1                         -> okstra lead Phase 1
-Information to be obtained after executing this skill -> Information produced after completing this contract
-This skill governs                           -> This contract governs
-this skill                                   -> this contract
-When the okstra skill Phase 5.5              -> When okstra lead Phase 5.5
-If `convergence.enabled: false`, this skill is skipped -> If `convergence.enabled: false`, this contract is skipped
-If you are reading this skill                -> If you are reading this contract
-During Phase 6 of the OKSTRA skill           -> During okstra lead Phase 6
-During Phase 7 of the OKSTRA skill           -> During okstra lead Phase 7
-During okstra Skill Phases 2–5               -> During okstra lead Phases 2–5
-Project rules override this skill on conflict -> Project rules override this resource pack on conflict
-project-level Python style skill             -> project-level Python style guide
-rust-guidelines skill                        -> `rust-guidelines` ruleset
-```
-
-Do not replace legitimate mentions of public user-facing skills such as `okstra-run`, `okstra-inspect`, or generic project review rule packs under `.claude/skills`.
-
-- [ ] **Step 2: Extend stale-wording test to runtime prompt resources**
-
-In `tests/test_docs_runtime_contract.py`, add these runtime resources to the scan list in `test_live_docs_do_not_describe_internal_contracts_as_skills`:
-
-```python
-"prompts/lead/context-loader.md",
-"prompts/lead/convergence.md",
-"prompts/lead/report-writer.md",
-"prompts/lead/team-contract.md",
-"prompts/coding-preflight/overview.md",
-"prompts/coding-preflight/languages/python.md",
-"prompts/coding-preflight/languages/rust.md",
-```
-
-Extend `forbidden_fragments` with targeted internal-contract phrases:
-
-```python
-"This skill governs",
-"this skill governs",
-"When this skill says",
-"Information to be obtained after executing this skill",
-"If you are reading this skill",
-"During Phase 6 of the OKSTRA skill",
-"During Phase 7 of the OKSTRA skill",
-"During okstra Skill Phases",
-"When the okstra skill Phase",
-"Project rules override this skill",
-"project-level Python style skill",
-"rust-guidelines skill",
-```
-
-- [ ] **Step 3: Run focused stale-wording test**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_docs_runtime_contract.py::test_live_docs_do_not_describe_internal_contracts_as_skills
-```
-
-Expected: test passes and scanned runtime resources no longer describe themselves as skills.
-
-## Task 4: Decide historical backlog wording
-
-**Files:**
-- Modify: `agents/TODO.md` or leave intentionally historical with a clarifying note.
-
-- [ ] **Step 1: Choose one policy for historical references**
-
-Use one of these two approaches:
-
-1. **Update historical paths to current resources** when the backlog item is still useful as maintenance guidance:
-
-```text
-agents/SKILL.md                              -> prompts/lead/okstra-lead-contract.md
-skills/okstra-context-loader/SKILL.md        -> prompts/lead/context-loader.md
-skills/okstra-team-contract/SKILL.md         -> prompts/lead/team-contract.md
-skills/okstra-convergence/SKILL.md           -> prompts/lead/convergence.md
-skills/okstra-report-writer/SKILL.md         -> prompts/lead/report-writer.md
-```
-
-2. **Keep historical paths** only if the section is intentionally archival; add one sentence at the top of the file:
-
-```markdown
-> Historical note: entries before 2026-06-15 may reference the former internal-skill layout; current lead contracts live under `prompts/lead/` and current coding-preflight resources live under `prompts/coding-preflight/`.
-```
-
-Recommended: update live-looking maintenance guidance and add the historical note only if old entries must remain untouched.
-
-- [ ] **Step 2: Verify old live paths are either gone or explicitly historical**
-
-Run:
-
-```bash
-python3 - <<'PY'
-from pathlib import Path
-text = Path('agents/TODO.md').read_text(encoding='utf-8')
-old = 'skills/okstra-team-contract/SKILL.md'
-if old in text:
-    assert 'Historical note:' in text
-PY
-```
-
-Expected: exit code 0.
-
-## Task 5: Final verification
-
-**Files:**
-- Generated: `runtime/` via `npm run build`
-
-- [ ] **Step 1: Run focused tests**
-
-Run:
-
-```bash
-node --test tests-js/install-runtime.test.mjs
-python3 -m pytest tests/test_docs_runtime_contract.py tests/test_lead_runtime_marker.py
-```
-
-Expected: all listed tests pass.
-
-- [ ] **Step 2: Re-run the failing ensure-installed smoke**
-
-Run:
-
-```bash
-TMP_HOME=$(mktemp -d)
-mkdir -p "$TMP_HOME/.claude"
-HOME="$TMP_HOME" OKSTRA_HOME="$TMP_HOME/.okstra" OKSTRA_RUNTIME_HOST=external node bin/okstra install --quiet
-node --input-type=module -e "import { rmSync } from 'node:fs'; import { join } from 'node:path'; rmSync(join(process.argv[1], '.okstra', 'prompts'), { recursive: true, force: true });" "$TMP_HOME"
-HOME="$TMP_HOME" OKSTRA_HOME="$TMP_HOME/.okstra" OKSTRA_RUNTIME_HOST=external node bin/okstra ensure-installed
-node --input-type=module -e "
-  import assert from 'node:assert/strict';
-  import { existsSync } from 'node:fs';
-  import { join } from 'node:path';
-  const home = process.argv[1];
-  assert.equal(existsSync(join(home, '.okstra', 'prompts', 'lead', 'okstra-lead-contract.md')), true);
-  assert.equal(existsSync(join(home, '.okstra', 'prompts', 'coding-preflight', 'overview.md')), true);
-" "$TMP_HOME"
-```
-
-Expected: `ensure-installed` detects missing prompt resources, reinstalls, and the final Node assertions pass.
-
-- [ ] **Step 3: Re-run previous smoke checks**
-
-Run the three smoke checks from `docs/superpowers/plans/2026-06-15-internal-skill-migration-fixups.md`:
-
-1. `install --link .` exposes prompt resources.
-2. generated prompt honors `OKSTRA_HOME` for lead resources.
-3. dangling obsolete internal skill symlink is pruned.
-
-Expected: all three pass.
-
-- [ ] **Step 4: Run full suite**
-
-Run:
-
-```bash
-npm run check
-```
-
-Expected: build, JS tests, Python tests, and workflow validator pass.
-
-- [ ] **Step 5: 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);
-console.log('runtime surface ok');
-"
-```
-
-Expected: exit code 0 and `runtime surface ok`.
-
-## Completion criteria
-
-The migration is complete only when:
-
-- `ensure-installed` restores missing prompt resources.
-- executor/verifier sidecars no longer hardcode `~/.okstra/prompts/coding-preflight/`.
-- runtime lead/coding-preflight resources do not describe internal contracts as skills.
-- public skill surface remains exactly the six plugin-listed user skills.
-- all focused tests, smoke checks, and `npm run check` pass freshly.