okstra 0.82.1 → 0.84.0

package/src/install.mjs

@@ -7,6 +7,7 @@ import { resolvePaths } from "./paths.mjs";
 import { fileExists } from "./_proc.mjs";
 import { buildRuntimeManifest, RUNTIMES_MANIFEST_REL } from "./runtime-manifest.mjs";
 import { normalizeRuntimeRequest, resolveRuntime } from "./runtime-resolver.mjs";
+import { OBSOLETE_INTERNAL_SKILL_NAMES, USER_SKILL_NAMES } from "./skill-catalog.mjs";
 
 const SKILLS_MANIFEST_REL = "installed-skills.json";
 const AGENTS_MANIFEST_REL = "installed-agents.json";
@@ -41,6 +42,26 @@ const BIN_ENTRYPOINTS = [
   "okstra-spawn-followups.py",
 ];
 
+// Runtime prompt resources the launch prompt and routed coding-preflight pack
+// depend on. Intentionally an exact allowlist, not a directory wildcard.
+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", "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"],
+]);
+
 const INSTALL_USAGE = `okstra install — install runtime into ~/.okstra
 
 Usage:
@@ -57,6 +78,7 @@ Effect (copy mode):
   ${"$HOME"}/.okstra/lib/validators <- runtime/validators  (stage/report structure validators)
   ${"$HOME"}/.okstra/bin           <- runtime/bin
   ${"$HOME"}/.okstra/templates     <- runtime/templates  (report.css / report.js / *.template.md)
+  ${"$HOME"}/.okstra/prompts       <- runtime/prompts  (lead contracts + coding-preflight pack)
   ${"$HOME"}/.okstra/templates/settings.local.json <- runtime/templates/reports/settings.template.json
   ${"$HOME"}/.claude/skills/<name> <- skills when ${"$HOME"}/.claude exists
   ${"$HOME"}/.codex/skills/<name>  <- skills when ${"$HOME"}/.codex exists
@@ -70,6 +92,7 @@ Effect (copy mode):
 Effect (link mode):
   ${"$HOME"}/.okstra/lib/python/<pkg> -> <repo>/scripts/<pkg>   (symlink)
   ${"$HOME"}/.okstra/bin/<name>.sh    -> <repo>/scripts/<name>.sh
+  ${"$HOME"}/.okstra/prompts          -> <repo>/prompts
   ${"$HOME"}/.okstra/templates/settings.local.json -> <repo>/templates/reports/settings.template.json
   ${"$HOME"}/.claude/skills/<name>    -> <repo>/skills/<name> when ${"$HOME"}/.claude exists
   ${"$HOME"}/.codex/skills/<name>     -> <repo>/skills/<name> when ${"$HOME"}/.codex exists
@@ -167,6 +190,16 @@ async function dirExists(path) {
   }
 }
 
+async function pathEntryExists(path) {
+  try {
+    await fs.lstat(path);
+    return true;
+  } catch (err) {
+    if (err.code === "ENOENT") return false;
+    throw err;
+  }
+}
+
 async function* walkFiles(root) {
   let entries;
   try {
@@ -237,34 +270,6 @@ async function copyTreeIfChanged(srcRoot, dstRoot, opts) {
   return { copied, skipped, missingSource };
 }
 
-// Single-file variant of copyTreeIfChanged, used for the lead `okstra` skill
-// whose source is one file (agents/SKILL.md) rather than a skill directory.
-async function copyFileIfChanged(src, dst, opts) {
-  const { refresh = false, dryRun = false, mode } = opts ?? {};
-  let srcBuf;
-  try {
-    srcBuf = await fs.readFile(src);
-  } catch {
-    return { copied: 0, skipped: 0, missingSource: true };
-  }
-  let needsCopy = refresh;
-  if (!needsCopy) {
-    try {
-      const [srcHash, dstHash] = await Promise.all([hashFile(src), hashFile(dst)]);
-      needsCopy = srcHash !== dstHash;
-    } catch {
-      needsCopy = true;
-    }
-  }
-  if (!needsCopy) return { copied: 0, skipped: 1, missingSource: false };
-  if (dryRun) {
-    process.stdout.write(`[dry-run] copy ${src} -> ${dst}\n`);
-    return { copied: 1, skipped: 0, missingSource: false };
-  }
-  await writeFileAtomic(dst, srcBuf, mode);
-  return { copied: 1, skipped: 0, missingSource: false };
-}
-
 async function ensureSymlink(target, linkPath, opts) {
   const { dryRun = false } = opts ?? {};
   try {
@@ -341,6 +346,15 @@ async function installLinkMode(repoPath, paths, opts) {
     const action = await ensureSymlink(src, dst, { dryRun });
     if (!quiet) process.stdout.write(`  bin/${name}: ${action}\n`);
   }
+  const promptsSrc = join(repoAbs, "prompts");
+  const promptsDst = join(paths.home, "prompts");
+  if (await dirExists(promptsSrc)) {
+    const action = await ensureSymlink(promptsSrc, promptsDst, { dryRun });
+    if (!quiet) process.stdout.write(`  prompts: ${action}\n`);
+  } else if (!quiet) {
+    process.stdout.write("  prompts: missing in repo — skipped\n");
+  }
+
 
   const skillTargets = await detectSkillTargets();
   const installedSkillTargets = await installSkillTargetsLink(repoAbs, skillTargets, { dryRun, quiet });
@@ -376,16 +390,7 @@ async function installLinkMode(repoPath, paths, opts) {
     );
   }
   return 0;
-}
 
-async function listSkillDirs(skillsRoot) {
-  try {
-    const entries = await fs.readdir(skillsRoot, { withFileTypes: true });
-    return entries.filter((e) => e.isDirectory()).map((e) => e.name);
-  } catch (err) {
-    if (err.code === "ENOENT") return [];
-    throw err;
-  }
 }
 
 async function detectSkillTargets() {
@@ -612,15 +617,12 @@ const SETTINGS_TEMPLATE_DESCRIPTOR = {
   label: "settings template",
 };
 
-const LEAD_SKILL_NAME = "okstra";
-
 async function installSkillsCopy(runtimeRoot, target, opts) {
   const { refresh, dryRun, quiet } = opts;
   const srcRoot = join(runtimeRoot, "skills");
-  const names = await listSkillDirs(srcRoot);
   let copied = 0;
   let skipped = 0;
-  for (const name of names) {
+  for (const name of USER_SKILL_NAMES) {
     const r = await copyTreeIfChanged(
       join(srcRoot, name),
       join(target.skillsDir, name),
@@ -629,65 +631,48 @@ async function installSkillsCopy(runtimeRoot, target, opts) {
     copied += r.copied;
     skipped += r.skipped;
   }
-  const lead = await installLeadSkillCopy(runtimeRoot, target, opts);
+  const pruned = await pruneObsoleteInternalSkills(target, opts);
   if (!quiet) {
-    const totalCopied = copied + lead.copied;
-    const totalSkipped = skipped + lead.skipped;
-    const totalSkills = names.length + lead.installed.length;
     process.stdout.write(
-      `  ${target.provider} skills: copied=${totalCopied} skipped=${totalSkipped} -> ${target.skillsDir}/ (${totalSkills} skills)\n`,
+      `  ${target.provider} skills: copied=${copied} skipped=${skipped} pruned=${pruned} -> ${target.skillsDir}/ (${USER_SKILL_NAMES.length} skills)\n`,
     );
   }
-  return { ...target, installed: [...names, ...lead.installed] };
+  return { ...target, installed: [...USER_SKILL_NAMES] };
 }
 
 async function installSkillsLink(repoAbs, target, opts) {
   const { dryRun, quiet } = opts;
   const srcRoot = join(repoAbs, "skills");
-  const names = await listSkillDirs(srcRoot);
   if (!dryRun) await fs.mkdir(target.skillsDir, { recursive: true });
-  for (const name of names) {
+  for (const name of USER_SKILL_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 lead = await installLeadSkillLink(repoAbs, target, opts);
-  return { ...target, installed: [...names, ...lead] };
-}
-
-async function installLeadSkillCopy(runtimeRoot, target, opts) {
-  const { refresh, dryRun, quiet } = opts;
-  const src = join(runtimeRoot, "agents", "SKILL.md");
-  const dst = join(target.skillsDir, LEAD_SKILL_NAME, "SKILL.md");
-  const r = await copyFileIfChanged(src, dst, { refresh, dryRun, mode: 0o644 });
-  if (r.missingSource) {
-    if (!quiet) {
-      process.stdout.write(
-        `  ${target.provider} skills/okstra: runtime/agents/SKILL.md missing — skipped\n`,
-      );
-    }
-    return { installed: [], copied: 0, skipped: 0 };
+  const pruned = await pruneObsoleteInternalSkills(target, opts);
+  if (!quiet && pruned > 0) {
+    process.stdout.write(`  ${target.provider} obsolete internal skills: pruned=${pruned}\n`);
   }
-  return { installed: [LEAD_SKILL_NAME], copied: r.copied, skipped: r.skipped };
+  return { ...target, installed: [...USER_SKILL_NAMES] };
 }
 
-async function installLeadSkillLink(repoAbs, target, opts) {
-  const { dryRun, quiet } = opts;
-  const src = join(repoAbs, "agents", "SKILL.md");
-  if (!(await fileExists(src))) {
-    if (!quiet) {
-      process.stdout.write(
-        `  ${target.provider} skills/okstra: <repo>/agents/SKILL.md missing — skipped\n`,
-      );
+// Remove former internal skill directories left by older installs. Exact-name
+// only (OBSOLETE_INTERNAL_SKILL_NAMES) — those contracts now ship as runtime
+// resources under ~/.okstra/prompts/, not as agent skills.
+async function pruneObsoleteInternalSkills(target, opts) {
+  let pruned = 0;
+  for (const name of OBSOLETE_INTERNAL_SKILL_NAMES) {
+    const path = join(target.skillsDir, name);
+    if (!(await pathEntryExists(path))) continue;
+    pruned += 1;
+    if (opts.dryRun) {
+      process.stdout.write(`[dry-run] rm ${path}\n`);
+      continue;
     }
-    return [];
+    await fs.rm(path, { recursive: true, force: true });
   }
-  const dst = join(target.skillsDir, LEAD_SKILL_NAME, "SKILL.md");
-  if (!dryRun) await fs.mkdir(join(target.skillsDir, LEAD_SKILL_NAME), { recursive: true });
-  const action = await ensureSymlink(src, dst, { dryRun });
-  if (!quiet) process.stdout.write(`  ${target.provider} skills/okstra/SKILL.md: ${action}\n`);
-  return [LEAD_SKILL_NAME];
+  return pruned;
 }
 
 async function installSkillTargetsCopy(runtimeRoot, targets, opts) {
@@ -828,6 +813,17 @@ export async function runInstall(args) {
     join(paths.home, "lib", "validators"),
     { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o755 },
   );
+  // prompts/ tree — lead/internal operating contracts (prompts/lead/*.md) and
+  // the coding-preflight resource pack (prompts/coding-preflight/*) are read at
+  // runtime by the lead and executor via absolute ~/.okstra/prompts/ paths
+  // (paths.py OKSTRA_LEAD_CONTRACT_PATH / OKSTRA_CODING_PREFLIGHT_DIR). Run-prep
+  // reads prompts/profiles + launch.template from the package runtime dir, but
+  // the lead's runtime Read needs them under the home tree like templates.
+  const promptsResult = await copyTreeIfChanged(
+    join(runtimeRoot, "prompts"),
+    join(paths.home, "prompts"),
+    { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o644 },
+  );
 
   if (!opts.quiet) {
     summarise("python", pythonResult, paths.pythonpath);
@@ -835,6 +831,7 @@ export async function runInstall(args) {
     summarise("templates", templatesResult, join(paths.home, "templates"));
     summarise("schemas", schemasResult, join(paths.home, "schemas"));
     summarise("validators", validatorsResult, join(paths.home, "lib", "validators"));
+    summarise("prompts", promptsResult, join(paths.home, "prompts"));
   }
 
   if (pythonResult.missingSource && binResult.missingSource) {
@@ -857,6 +854,11 @@ export async function runInstall(args) {
       "warning: runtime/validators is empty. stage-structure / report validation will use stale or missing validators — re-run the build step.\n",
     );
   }
+  if (promptsResult.missingSource) {
+    process.stderr.write(
+      "warning: runtime/prompts is empty. lead contracts + coding-preflight resources will be missing — re-run the build step.\n",
+    );
+  }
 
   const skillTargets = await detectSkillTargets();
   const installedSkillTargets = await installSkillTargetsCopy(runtimeRoot, skillTargets, opts);
@@ -895,7 +897,7 @@ export async function runInstall(args) {
 async function skillTargetDriftReasons(targets) {
   const reasons = [];
   for (const target of targets) {
-    for (const name of ["okstra-run", LEAD_SKILL_NAME]) {
+    for (const name of USER_SKILL_NAMES) {
       const skillPath = join(target.skillsDir, name, "SKILL.md");
       if (!(await fileExists(skillPath))) {
         reasons.push(`missing ${skillPath}`);
@@ -905,6 +907,15 @@ async function skillTargetDriftReasons(targets) {
   return reasons;
 }
 
+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;
+}
+
 async function agentDriftReasons(paths) {
   const reasons = [];
   const workersDir = join(paths.agents, "workers");
@@ -987,6 +998,9 @@ export async function runEnsureInstalled(args) {
   if (!(await fileExists(join(paths.home, "schemas", "final-report-v1.0.schema.json")))) {
     reasons.push(`missing ${join(paths.home, "schemas", "final-report-v1.0.schema.json")}`);
   }
+  for (const reason of await promptResourceDriftReasons(paths)) {
+    reasons.push(reason);
+  }
   const skillTargets = await detectSkillTargets();
   for (const reason of await skillTargetDriftReasons(skillTargets)) {
     reasons.push(reason);

package/src/skill-catalog.mjs

@@ -0,0 +1,35 @@
+// Single source of truth for which okstra skills are user-facing and which
+// former internal skill directories must be pruned from agent skill homes on
+// (re)install. The Claude plugin manifest (.claude-plugin/plugin.json) and the
+// installer both derive their skill list from here, so the public surface
+// cannot drift between discovery and install.
+
+export const USER_SKILL_NAMES = Object.freeze([
+  "okstra-setup",
+  "okstra-brief",
+  "okstra-run",
+  "okstra-memory",
+  "okstra-inspect",
+  "okstra-schedule",
+]);
+
+// Names okstra used to install as skills before lead/internal contracts moved
+// into the runtime resource tree (~/.okstra/prompts/). Install prunes these
+// exact directories from each target skill home so upgrades do not leave the
+// old internal skills behind. Exact-name only — never wildcard.
+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];
+}

package/src/uninstall.mjs

@@ -206,6 +206,11 @@ export async function runUninstall(args) {
   // never removed it, leaving a stale final-report schema behind.
   await removePath(join(paths.home, "schemas"), opts);
 
+  // prompts/ tree — installed by copy mode (runtime/prompts): lead contracts
+  // + coding-preflight resource pack. Remove so an upgrade never serves stale
+  // operating contracts.
+  await removePath(join(paths.home, "prompts"), opts);
+
   // Remove the skills we own. Manifest v2 records every target root; legacy
   // manifests fall back to Claude-only names when the runtime manifest says
   // Claude assets may have been installed.