okstra 0.102.2 → 0.102.4

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

@@ -1,749 +0,0 @@
-# Internal Skill Resource Migration 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:** Only user-facing Okstra skills are installed into agent skill homes; former internal skills become Okstra runtime resources under the project/runtime tree.
-
-**Architecture:** `skills/` becomes the public skill surface and contains only the six user-facing skill directories already listed by `.claude-plugin/plugin.json`. Lead-only operating contracts move to shipped runtime prompt resources (`prompts/lead/`), and generated launch prompts load them by explicit file paths. Coding preflight moves as a routed resource pack (`prompts/coding-preflight/`): the router checks language, framework, then architecture stages; each stage iterates a list of rules and selects every matching resource. The installer copies only public skills and prunes package-owned internal skill directories from prior installs.
-
-**Tech Stack:** Node.js ES modules for install/uninstall/runtime tests, Python `okstra_ctl` renderer and pytest contract tests, markdown prompt resources, existing `npm run build` runtime sync.
-
----
-
-## Grounding
-
-Current facts to preserve or change:
-
-- Public plugin skill list is six skills: `okstra-setup`, `okstra-brief`, `okstra-run`, `okstra-memory`, `okstra-inspect`, `okstra-schedule` (`.claude-plugin/plugin.json`).
-- Current installer copies every directory under `runtime/skills` and then copies `runtime/agents/SKILL.md` as the extra `okstra` skill.
-- Current lead contract (`agents/SKILL.md`) references internal skill files by skill paths and tells the lead to invoke them.
-- Current Claude launch prompt says `Invoke the okstra skill now`; Codex launch prompt explicitly says not to invoke Claude Code skills.
-- `tools/build.mjs` already ships `prompts/`, `agents/`, `templates/`, and `skills/` into `runtime/`, so prompt resources under `prompts/` are installable without adding a new build channel.
-
-## Target File Structure
-
-### Public user skills retained under `skills/`
-
-- `skills/okstra-setup/`
-- `skills/okstra-brief/`
-- `skills/okstra-run/`
-- `skills/okstra-memory/`
-- `skills/okstra-inspect/`
-- `skills/okstra-schedule/`
-
-### Internal resources moved out of `skills/`
-
-- `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`
-- `skills/okstra-coding-preflight/SKILL.md` -> `prompts/coding-preflight/overview.md`
-- `skills/okstra-coding-preflight/clean-code.md` -> `prompts/coding-preflight/clean-code.md`
-- `skills/okstra-coding-preflight/languages/*` -> `prompts/coding-preflight/languages/*`
-- `skills/okstra-coding-preflight/languages/nodejs.md` -> `prompts/coding-preflight/frameworks/node-server.md`
-- `skills/okstra-coding-preflight/architecture/*` -> `prompts/coding-preflight/architectures/*`
-
-Delete the old internal directories after references are migrated:
-
-- `agents/SKILL.md`
-- `skills/okstra-context-loader/`
-- `skills/okstra-team-contract/`
-- `skills/okstra-convergence/`
-- `skills/okstra-report-writer/`
-- `skills/okstra-coding-preflight/`
-
-
-`prompts/coding-preflight/` is a routed resource pack, not a single always-read contract. Default selection is `overview.md` + `clean-code.md`, then 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. The router never stops at the first match inside a stage because one diff can touch multiple languages/frameworks/architectures.
-
-1. **Language stage** — iterate all language rules:
-   - `languages/javascript-typescript.md` when any touched file is `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`, or a JS package manifest implies JS/TS work.
-   - `languages/python.md` when any touched file is `.py` or manifests include `pyproject.toml`, `requirements.txt`, `setup.py`, or `setup.cfg`.
-   - `languages/rust.md` when any touched file is `.rs` or `Cargo.toml` exists in scope.
-   - `languages/java.md` when any touched file is `.java` or manifests include `pom.xml` / `build.gradle`.
-   - `languages/kotlin.md` when any touched file is `.kt` / `.kts` or manifests include `build.gradle.kts`.
-   - `languages/sql.md` when any touched file is `.sql`, migration paths are touched, `prisma/schema.prisma` is touched, or embedded query strings / ORM query builders are changed.
-2. **Framework stage** — iterate all framework/runtime rules:
-   - `frameworks/node-server.md` when `package.json` or dependencies/scripts show server-side Node work (`express`, `fastify`, `nestjs`, server entrypoints, API routes, CLI services), or when touched files are Node runtime modules.
-3. **Architecture stage** — iterate all architecture rules:
-   - `architectures/hexagonal.md` when the project has ports-and-adapters / hexagonal signals (`domain/` + `ports/` + `adapters/`, `core/` + `infrastructure/` + `application/`, `*.port.*`, NestJS hex split, domain-boundary abstract classes).
-
-Unknown or unlisted language with no matching reference: stop before editing and ask the user for the canonical style guide; do not invent a default. No launch prompt should inline or require reading every preflight file.
-
-## Task 1: Add a Public Skill Catalog
-
-**Files:**
-- Create: `src/skill-catalog.mjs`
-- Modify: `src/install.mjs`
-- Test: `tests-js/skill-catalog.test.mjs`
-
-- [ ] **Step 1: Add the catalog module**
-
-Create `src/skill-catalog.mjs`:
-
-```js
-export const USER_SKILL_NAMES = Object.freeze([
-  "okstra-setup",
-  "okstra-brief",
-  "okstra-run",
-  "okstra-memory",
-  "okstra-inspect",
-  "okstra-schedule",
-]);
-
-export const OBSOLETE_INTERNAL_SKILL_NAMES = Object.freeze([
-  "okstra",
-  "okstra-context-loader",
-  "okstra-team-contract",
-  "okstra-convergence",
-  "okstra-report-writer",
-  "okstra-coding-preflight",
-]);
-
-export function userSkillNames() {
-  return [...USER_SKILL_NAMES];
-}
-
-export function obsoleteInternalSkillNames() {
-  return [...OBSOLETE_INTERNAL_SKILL_NAMES];
-}
-```
-
-- [ ] **Step 2: Write catalog/plugin sync test**
-
-Create `tests-js/skill-catalog.test.mjs`:
-
-```js
-import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import test from "node:test";
-import { USER_SKILL_NAMES, OBSOLETE_INTERNAL_SKILL_NAMES } from "../src/skill-catalog.mjs";
-
-function readJson(path) {
-  return JSON.parse(readFileSync(path, "utf8"));
-}
-
-test("public skill catalog matches Claude plugin manifest", () => {
-  const plugin = readJson(".claude-plugin/plugin.json");
-  const pluginNames = plugin.skills.map((entry) => entry.replace("./skills/", ""));
-  assert.deepEqual(pluginNames, USER_SKILL_NAMES);
-});
-
-test("obsolete internal skill names do not overlap public skills", () => {
-  for (const name of OBSOLETE_INTERNAL_SKILL_NAMES) {
-    assert.equal(USER_SKILL_NAMES.includes(name), false, name);
-  }
-});
-```
-
-- [ ] **Step 3: Run the new test and verify it passes before install changes**
-
-Run:
-
-```bash
-node --test tests-js/skill-catalog.test.mjs
-```
-
-Expected: both subtests pass.
-
-- [ ] **Step 4: Import the catalog in `src/install.mjs`**
-
-At the top of `src/install.mjs`, import the catalog:
-
-```js
-import { OBSOLETE_INTERNAL_SKILL_NAMES, USER_SKILL_NAMES } from "./skill-catalog.mjs";
-```
-
-Keep the existing import ordering style: built-in imports first, local imports after them.
-
-## Task 2: Install Only Public Skills and Prune Old Internal Skill Installs
-
-**Files:**
-- Modify: `src/install.mjs`
-- Modify: `tests-js/install-runtime.test.mjs`
-- Modify: `tests-js/uninstall-runtime.test.mjs`
-
-- [ ] **Step 1: Replace `listSkillDirs()` usage for install with the catalog**
-
-In `installSkillsCopy(runtimeRoot, target, opts)`, stop using every directory under `runtime/skills`. Use `USER_SKILL_NAMES` as the exact install list.
-
-Implementation shape:
-
-```js
-async function installSkillsCopy(runtimeRoot, target, opts) {
-  const { refresh, dryRun, quiet } = opts;
-  const srcRoot = join(runtimeRoot, "skills");
-  const names = USER_SKILL_NAMES;
-  let copied = 0;
-  let skipped = 0;
-  for (const name of names) {
-    const r = await copyTreeIfChanged(join(srcRoot, name), join(target.skillsDir, name), {
-      refresh,
-      dryRun,
-      mode: 0o644,
-    });
-    copied += r.copied;
-    skipped += r.skipped;
-  }
-  const pruned = await pruneObsoleteInternalSkills(target, opts);
-  if (!quiet) {
-    process.stdout.write(
-      `  ${target.provider} skills: copied=${copied} skipped=${skipped} pruned=${pruned} -> ${target.skillsDir}/ (${names.length} skills)\n`,
-    );
-  }
-  return { ...target, installed: [...names] };
-}
-```
-
-- [ ] **Step 2: Apply the same public-list behavior to link mode**
-
-In `installSkillsLink(repoAbs, target, opts)`, use `USER_SKILL_NAMES`, remove the lead-skill link call, and call the same prune helper.
-
-Implementation shape:
-
-```js
-async function installSkillsLink(repoAbs, target, opts) {
-  const { dryRun, quiet } = opts;
-  const srcRoot = join(repoAbs, "skills");
-  const names = USER_SKILL_NAMES;
-  if (!dryRun) await fs.mkdir(target.skillsDir, { recursive: true });
-  for (const name of names) {
-    const src = join(srcRoot, name);
-    const dst = join(target.skillsDir, name);
-    const action = await ensureSymlink(src, dst, { dryRun });
-    if (!quiet) process.stdout.write(`  ${target.provider} skills/${name}: ${action}\n`);
-  }
-  const pruned = await pruneObsoleteInternalSkills(target, opts);
-  if (!quiet && pruned > 0) {
-    process.stdout.write(`  ${target.provider} obsolete internal skills: pruned=${pruned}\n`);
-  }
-  return { ...target, installed: [...names] };
-}
-```
-
-- [ ] **Step 3: Add the prune helper**
-
-Add near the skill install helpers:
-
-```js
-async function pruneObsoleteInternalSkills(target, opts) {
-  let pruned = 0;
-  for (const name of OBSOLETE_INTERNAL_SKILL_NAMES) {
-    const path = join(target.skillsDir, name);
-    if (!(await pathExists(path))) continue;
-    pruned += 1;
-    if (!opts.dryRun) {
-      await fs.rm(path, { recursive: true, force: true });
-    }
-  }
-  return pruned;
-}
-```
-
-This deliberately prunes only Okstra-owned exact names; no wildcard deletion.
-
-- [ ] **Step 4: Delete the lead skill install functions**
-
-Remove these obsolete pieces from `src/install.mjs`:
-
-```js
-const LEAD_SKILL_NAME = "okstra";
-async function installLeadSkillCopy(...) { ... }
-async function installLeadSkillLink(...) { ... }
-```
-
-No compatibility shim. The generated launch prompt will load the lead contract from `prompts/lead/` instead.
-
-- [ ] **Step 5: Update install tests to assert only public skills are installed**
-
-In `tests-js/install-runtime.test.mjs`, replace assertions that expect `okstra-team-contract` and `okstra` under provider skill homes.
-
-Expected assertion shape:
-
-```js
-for (const providerRoot of [join(root, ".claude", "skills"), join(root, ".agent", "skills")]) {
-  assert.equal(existsSync(join(providerRoot, "okstra-run", "SKILL.md")), true);
-  assert.equal(existsSync(join(providerRoot, "okstra-setup", "SKILL.md")), true);
-  assert.equal(existsSync(join(providerRoot, "okstra-team-contract", "SKILL.md")), false);
-  assert.equal(existsSync(join(providerRoot, "okstra", "SKILL.md")), false);
-}
-```
-
-Manifest assertions must compare against `USER_SKILL_NAMES`, not internal names.
-
-- [ ] **Step 6: Add stale-install prune coverage**
-
-Add a test to `tests-js/install-runtime.test.mjs`:
-
-```js
-test("install prunes obsolete internal skill directories from prior installs", () => {
-  const { root, env } = makeInstallEnv();
-  const claudeSkills = join(root, ".claude", "skills");
-  mkdirSync(join(claudeSkills, "okstra-team-contract"), { recursive: true });
-  writeFileSync(join(claudeSkills, "okstra-team-contract", "SKILL.md"), "old\n");
-  mkdirSync(join(claudeSkills, "okstra"), { recursive: true });
-  writeFileSync(join(claudeSkills, "okstra", "SKILL.md"), "old\n");
-
-  const install = runCli(["install"], { ...env, OKSTRA_RUNTIME_HOST: "external" });
-  assert.equal(install.code, 0, install.stderr);
-
-  assert.equal(existsSync(join(claudeSkills, "okstra-run", "SKILL.md")), true);
-  assert.equal(existsSync(join(claudeSkills, "okstra-team-contract")), false);
-  assert.equal(existsSync(join(claudeSkills, "okstra")), false);
-});
-```
-
-- [ ] **Step 7: Remove legacy fallback skill target test**
-
-Remove the obsolete fallback-target test; supported skill homes are Claude and Agent only.
-
-- [ ] **Step 8: Run targeted install/uninstall tests**
-
-Run:
-
-```bash
-node --test tests-js/skill-catalog.test.mjs tests-js/install-runtime.test.mjs tests-js/uninstall-runtime.test.mjs
-```
-
-Expected: all listed JS tests pass.
-
-## Task 3: Move Internal Markdown Contracts to Runtime Prompt Resources
-
-**Files:**
-- Create: `prompts/lead/okstra-lead-contract.md`
-- Create: `prompts/lead/context-loader.md`
-- Create: `prompts/lead/team-contract.md`
-- Create: `prompts/lead/convergence.md`
-- Create: `prompts/lead/report-writer.md`
-- Create: `prompts/coding-preflight/overview.md`
-- Move: `skills/okstra-coding-preflight/clean-code.md` -> `prompts/coding-preflight/clean-code.md`
-- Move: `skills/okstra-coding-preflight/languages/*` -> `prompts/coding-preflight/languages/*`
-- Move: `skills/okstra-coding-preflight/languages/nodejs.md` -> `prompts/coding-preflight/frameworks/node-server.md`
-- Move: `skills/okstra-coding-preflight/architecture/*` -> `prompts/coding-preflight/architectures/*`
-- Delete: `agents/SKILL.md`
-- Delete: old internal skill directories under `skills/`
-
-- [ ] **Step 1: Move lead contract content**
-
-Copy the body of `agents/SKILL.md` into `prompts/lead/okstra-lead-contract.md`, removing only skill frontmatter:
-
-```markdown
-# Okstra Lead Contract
-
-## Overview
-...
-```
-
-Replace wording that says `SKILL.md`, `sub-skill`, or `Invoke skill` with file-resource language:
-
-```markdown
-## Support contract index
-
-| Contract | Scope |
-|---|---|
-| [context-loader](./context-loader.md) | Phase 1 task-bundle discovery, manifest fields, run-directory layout |
-| [team-contract](./team-contract.md) | Phase 2–5 worker roster, model assignment rules, prompt composition, worker output contract, terminal statuses, usage tracking |
-| [convergence](./convergence.md) | Phase 5.5 finding convergence loop and implementation-planning plan-body verification mode |
-| [report-writer](./report-writer.md) | Phase 6 final-report authorship, dispatch template, resume-safe dispatch, shared-graph integrity check, Phase 7 token-usage collector |
-```
-
-- [ ] **Step 2: Move internal skill bodies into lead contracts**
-
-For each source `SKILL.md`, remove the frontmatter block and write the remaining body to the matching target:
-
-```text
-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
-skills/okstra-coding-preflight/SKILL.md    -> prompts/coding-preflight/overview.md
-```
-
-Use title names that are resources, not skills:
-
-```markdown
-# Okstra Context Loader Contract
-# Okstra Team Contract
-# Okstra Convergence Contract
-# Okstra Report Writer Contract
-# Okstra Coding Preflight
-```
-
-- [ ] **Step 3: Move coding preflight resource files**
-
-Preserve the router semantics from `skills/okstra-coding-preflight/SKILL.md`: moving the files changes their namespace only, not when they are read. `overview.md` must define three ordered stages — language, framework, architecture. Each stage contains a list of rules; each rule can have multiple conditions; matching is list-iteration with accumulation, not first-match branching. Executors read only resources selected by touched files, project manifests, dependencies/scripts, and detected architecture.
-
-Move these files without content changes first:
-
-```text
-skills/okstra-coding-preflight/clean-code.md              -> prompts/coding-preflight/clean-code.md
-skills/okstra-coding-preflight/languages/python.md        -> prompts/coding-preflight/languages/python.md
-skills/okstra-coding-preflight/languages/rust.md          -> prompts/coding-preflight/languages/rust.md
-skills/okstra-coding-preflight/languages/sql.md           -> prompts/coding-preflight/languages/sql.md
-skills/okstra-coding-preflight/languages/java.md          -> prompts/coding-preflight/languages/java.md
-skills/okstra-coding-preflight/languages/javascript-typescript.md -> prompts/coding-preflight/languages/javascript-typescript.md
-skills/okstra-coding-preflight/languages/kotlin.md        -> prompts/coding-preflight/languages/kotlin.md
-skills/okstra-coding-preflight/languages/nodejs.md        -> prompts/coding-preflight/frameworks/node-server.md
-skills/okstra-coding-preflight/architecture/hexagonal.md  -> prompts/coding-preflight/architectures/hexagonal.md
-```
-
-- [ ] **Step 4: Rewrite internal links inside moved files**
-
-Replace old skill-relative links:
-
-```text
-../okstra-team-contract/SKILL.md -> ./team-contract.md
-../okstra-convergence/SKILL.md   -> ./convergence.md
-../okstra-report-writer/SKILL.md -> ./report-writer.md
-../okstra-context-loader/SKILL.md -> ./context-loader.md
-```
-
-Replace prose references like `okstra-team-contract skill` with `team-contract resource` or `prompts/lead/team-contract.md`, whichever is clearer in context.
-
-- [ ] **Step 5: Delete old internal skill sources**
-
-Delete only these exact paths:
-
-```text
-agents/SKILL.md
-skills/okstra-context-loader/
-skills/okstra-team-contract/
-skills/okstra-convergence/
-skills/okstra-report-writer/
-skills/okstra-coding-preflight/
-```
-
-Do not delete the six public skill directories.
-
-## Task 4: Make Generated Lead Prompts Load Internal Resources by Path
-
-**Files:**
-- Modify: `scripts/okstra_ctl/render.py`
-- Modify: `prompts/launch.template.md`
-- Modify: `prompts/profiles/_coding-conventions-preflight.md`
-- Modify: `agents/workers/claude-worker.md`
-- Modify: `agents/workers/_cli-wrapper-template.md`
-- Modify: `agents/workers/report-writer-worker.md`
-- Modify: `scripts/lib/okstra/globals.sh`
-- Modify: `scripts/okstra_ctl/context_cost.py`
-- Modify: `scripts/okstra_token_usage/claude.py`
-- Modify: `scripts/okstra_token_usage/collect.py`
-
-- [ ] **Step 1: Add runtime resource path helpers in `render.py`**
-
-Add helper functions near the existing lead-runtime helpers:
-
-```python
-def _runtime_resource_root() -> Path:
-    okstra_home = os.environ.get("OKSTRA_HOME", "").strip()
-    if okstra_home:
-        return Path(okstra_home)
-    return Path.home() / ".okstra"
-
-
-def _runtime_resource_path(*parts: str) -> str:
-    return str(_runtime_resource_root().joinpath(*parts))
-```
-
-- [ ] **Step 2: Generate explicit lead resource paths**
-
-Inside the launch prompt rendering context, compute these paths:
-
-```python
-lead_contract_path = _runtime_resource_path("prompts", "lead", "okstra-lead-contract.md")
-context_loader_path = _runtime_resource_path("prompts", "lead", "context-loader.md")
-team_contract_path = _runtime_resource_path("prompts", "lead", "team-contract.md")
-convergence_path = _runtime_resource_path("prompts", "lead", "convergence.md")
-report_writer_path = _runtime_resource_path("prompts", "lead", "report-writer.md")
-coding_preflight_root = _runtime_resource_path("prompts", "coding-preflight")
-```
-
-- [ ] **Step 3: Replace Claude skill bootstrap**
-
-Replace the Claude branch text currently shaped like `Invoke the okstra skill now` with file loading:
-
-```python
-lead_bootstrap_instruction = (
-    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."
-)
-```
-
-For Codex and external runtime branches, add the same path as a resource, without mentioning Claude skills.
-
-- [ ] **Step 4: Add a compact resource block to the generated prompt**
-
-Add a block after the session block:
-
-```markdown
-## Okstra Runtime Resources
-
-- Lead contract: `<lead_contract_path>`
-- Context loader: `<context_loader_path>`
-- Team contract: `<team_contract_path>`
-- Convergence contract: `<convergence_path>`
-- Report writer contract: `<report_writer_path>`
-- Coding preflight root: `<coding_preflight_root>`
-```
-
-This gives every lead runtime the same path-based contract surface.
-
-- [ ] **Step 5: Update `prompts/launch.template.md` references**
-
-Replace `agents/SKILL.md` and `okstra skill` references with the new contract names.
-
-Expected wording:
-
-```markdown
-Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at every checkpoint enumerated in the lead contract (`prompts/lead/okstra-lead-contract.md` → "Progress reporting (BLOCKING)").
-```
-
-```markdown
-See `Lifecycle Phase Boundaries` in the lead contract (`prompts/lead/okstra-lead-contract.md`) for the canonical rules and the phase-transition checklist.
-```
-
-- [ ] **Step 6: Update coding preflight path references**
-
-In `prompts/profiles/_coding-conventions-preflight.md`, replace the old Claude skill path with installed runtime resource paths:
-
-```markdown
-Detect applicable coding-conventions resources with three ordered stages: language, framework, architecture. Always read `overview.md` and `clean-code.md` first. For each stage, iterate every rule in the stage's list; each rule may have multiple conditions, and a rule matches when any condition is true. Accumulate every matched resource; do not stop at the first match. Language examples: JS/TS files or JS package manifests -> `languages/javascript-typescript.md`; Python files/manifests -> `languages/python.md`; Rust files/manifests -> `languages/rust.md`; Java/Kotlin/SQL triggers -> matching language files. Framework examples: server-side Node evidence (`express`, `fastify`, `nestjs`, API routes, CLI services, Node runtime modules) -> `frameworks/node-server.md`. Architecture examples: ports-and-adapters / NestJS-hex signals -> `architectures/hexagonal.md`. If no listed language matches, stop before editing and ask for the canonical style guide.
-```
-
-Also update the graceful-degradation line to say `resource-unavailable`, not `skill-unavailable`.
-
-- [ ] **Step 7: Update worker docs and scripts that cite old skill paths**
-
-Use exact replacements:
-
-```text
-skills/okstra-team-contract/SKILL.md -> prompts/lead/team-contract.md
-okstra-team-contract skill -> team-contract resource
-okstra-convergence skill -> convergence resource
-okstra-report-writer skill -> report-writer resource
-agents/SKILL.md -> prompts/lead/okstra-lead-contract.md
-```
-
-Apply these in worker agent files, wrapper templates, token usage comments, and context-cost hot path names.
-
-- [ ] **Step 8: Remove obsolete globals entry**
-
-In `scripts/lib/okstra/globals.sh`, remove or rename `SOURCE_CLAUDE_OKSTRA_SKILL`. If no runtime code reads it, delete it. If a shell path still needs the lead contract, replace it with:
-
-```bash
-SOURCE_OKSTRA_LEAD_CONTRACT="$WORKSPACE_ROOT/prompts/lead/okstra-lead-contract.md"
-```
-
-## Task 5: Update Contract Tests and Docs
-
-**Files:**
-- Modify: `tests/test_docs_runtime_contract.py`
-- Modify: `tests/test_lead_runtime_marker.py`
-- Modify: `tests-js/doctor-runtime.test.mjs` if expected install assets mention hidden skills
-- Modify: `docs/kr/architecture.md`
-- Modify: `docs/kr/cli.md`
-- Modify: `docs/project-structure-overview.md`
-- Modify: `README.md`
-- Modify: `README.kr.md`
-- Modify: `CHANGES.md`
-
-- [ ] **Step 1: Replace internal-skill frontmatter test**
-
-In `tests/test_docs_runtime_contract.py`, remove assertions that internal resources contain `user-invocable: false`. Replace them with a resource-location assertion:
-
-```python
-def test_internal_okstra_contracts_are_runtime_resources_not_skills():
-    for relative_path in [
-        "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",
-    ]:
-        text = _read_doc(relative_path)
-        assert "user-invocable:" not in text, relative_path
-        assert "hide:" not in text, relative_path
-
-    for relative_path in [
-        "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",
-        "agents/SKILL.md",
-    ]:
-        assert not (ROOT / relative_path).exists(), relative_path
-```
-
-- [ ] **Step 2: Add generated-prompt guard test**
-
-Update the lead runtime marker tests so generated Claude prompts contain the lead contract path and do not contain `Invoke the okstra skill now`.
-
-Expected assertions:
-
-```python
-assert "prompts/lead/okstra-lead-contract.md" in prompt_text
-assert "Invoke the `okstra` skill now" not in prompt_text
-assert "do not invoke hidden/internal skills" in prompt_text
-```
-
-- [ ] **Step 3: Update JS install expectations**
-
-Where JS tests inspect runtime manifests, assert:
-
-```js
-assert.deepEqual(target.skills, USER_SKILL_NAMES);
-assert.equal(manifest.installedAssets.claudeSkills, true);
-assert.equal(manifest.installedAssets.claudeAgents, true);
-```
-
-`claudeSkills` remains true when public skills install; it no longer implies internal lead resources were installed as skills.
-
-- [ ] **Step 4: Update architecture docs**
-
-In `docs/kr/architecture.md`, document the new boundary:
-
-```markdown
-- 사용자 호출 가능 스킬: `skills/okstra-{setup,brief,run,memory,inspect,schedule}` 만 agent skill home 으로 복사된다.
-- Lead/internal 운영 계약: `prompts/lead/*.md` 와 `prompts/coding-preflight/*` 로 설치되며, generated launch prompt 가 절대 경로를 제공한다. 이 파일들은 skill discovery 대상이 아니다.
-- 과거 `okstra-context-loader`, `okstra-team-contract`, `okstra-convergence`, `okstra-report-writer`, `okstra-coding-preflight`, `okstra` skill 디렉터리는 install 시 exact-name prune 대상이다.
-```
-
-- [ ] **Step 5: Update CLI docs and READMEs**
-
-Change install behavior docs:
-
-```markdown
-`okstra install` copies only user-facing Okstra skills to detected agent homes. Internal lead contracts are installed under `~/.okstra/prompts/` and loaded by generated prompts; they do not appear in the agent skill list.
-```
-
-- [ ] **Step 6: Add `CHANGES.md` entry**
-
-Add a new dated entry:
-
-```markdown
-## 2026-06-15
-
-- `okstra install` now exposes only user-facing Okstra skills in agent skill lists. Lead-only contracts moved into the Okstra runtime resource tree and old internal skill directories are pruned on reinstall.
-  - 사용자 영향: `/skills` / skill discovery views no longer show `okstra-team-contract`, `okstra-convergence`, `okstra-report-writer`, `okstra-context-loader`, `okstra-coding-preflight`, or hidden `okstra`; existing Okstra runs still load the same contracts through generated prompt paths.
-```
-
-## Task 6: Consistency Search and Runtime Build Verification
-
-**Files:**
-- Generated: `runtime/` via `npm run build`
-
-- [ ] **Step 1: Search for old internal skill paths**
-
-Run repository searches for these strings and update every live reference outside historical changelog entries and this plan:
-
-```text
-skills/okstra-context-loader
-skills/okstra-team-contract
-skills/okstra-convergence
-skills/okstra-report-writer
-skills/okstra-coding-preflight
-agents/SKILL.md
-Invoke the `okstra` skill now
-okstra-team-contract skill
-okstra-convergence skill
-okstra-report-writer skill
-```
-
-Expected: no live runtime, prompt, test, or docs reference requires the old skill namespace.
-
-- [ ] **Step 2: Build runtime**
-
-Run:
-
-```bash
-npm run build
-```
-
-Expected: `runtime/prompts/lead/*.md`, `runtime/prompts/coding-preflight/*`, and only the six public `runtime/skills/okstra-*` skill directories are present.
-
-- [ ] **Step 3: Verify no internal skills in runtime skills tree**
-
-Use a Node assertion script instead of shell globbing:
-
-```bash
-node - <<'NODE'
-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/clean-code.md'), true);
-NODE
-```
-
-Expected: exit code 0.
-
-## Task 7: End-to-End Install Smoke Tests
-
-**Files:**
-- No source changes expected after Task 6.
-
-- [ ] **Step 1: Run targeted automated suites**
-
-Run:
-
-```bash
-node --test tests-js/skill-catalog.test.mjs tests-js/install-runtime.test.mjs tests-js/uninstall-runtime.test.mjs tests-js/doctor-runtime.test.mjs
-python3 -m pytest tests/test_docs_runtime_contract.py tests/test_lead_runtime_marker.py
-bash validators/validate-workflow.sh
-```
-
-Expected: all commands pass.
-
-- [ ] **Step 2: Smoke-test install into a fake Claude home**
-
-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
-node - <<'NODE' "$TMP_HOME"
-import assert from 'node:assert/strict';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { USER_SKILL_NAMES, OBSOLETE_INTERNAL_SKILL_NAMES } from './src/skill-catalog.mjs';
-const home = process.argv[2];
-for (const name of USER_SKILL_NAMES) {
-  assert.equal(existsSync(join(home, '.claude', 'skills', name, 'SKILL.md')), true, name);
-}
-for (const name of OBSOLETE_INTERNAL_SKILL_NAMES) {
-  assert.equal(existsSync(join(home, '.claude', 'skills', name)), false, name);
-}
-assert.equal(existsSync(join(home, '.okstra', 'prompts', 'lead', 'okstra-lead-contract.md')), true);
-assert.equal(existsSync(join(home, '.okstra', 'prompts', 'coding-preflight', 'clean-code.md')), true);
-NODE
-```
-
-Expected: install exits 0; Node assertions exit 0.
-
-- [ ] **Step 3: Run full check**
-
-Run:
-
-```bash
-npm run check
-```
-
-Expected: build, JS tests, Python tests, and workflow validator pass.
-
-## Rollback Plan
-
-If generated lead prompts cannot reliably read `~/.okstra/prompts/lead/okstra-lead-contract.md`, revert only the render/bootstrap change and keep the moved resources staged. Do not reintroduce hidden skills as the default install surface. The fallback must be explicit prompt inlining from `prompts/lead/okstra-lead-contract.md`, not copying internal files back to `~/.claude/skills`.