okstra 0.82.0 → 0.83.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,12 +78,13 @@ 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
   ${"$HOME"}/.omp/agent/skills/<name> <- skills fallback when Claude/Codex homes are absent
   ${"$HOME"}/.claude/agents/<worker>.md <- worker agents when ${"$HOME"}/.claude exists
-  ${"$HOME"}/.okstra/installed-runtimes.json <- manifest of installed runtime adapters
+  ${"$HOME"}/.okstra/installed-runtimes.json <- install request/resolution manifest
   ${"$HOME"}/.okstra/installed-skills.json   <- target-aware manifest of installed skills
   ${"$HOME"}/.okstra/installed-agents.json   <- manifest of installed workers
   ${"$HOME"}/.okstra/version       <- installed package version stamp
@@ -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
@@ -86,6 +109,9 @@ worker wrapper scripts without modifying the user's global settings.
 Worker agent definitions are installed into ${"$HOME"}/.claude/agents/ only
 when ${"$HOME"}/.claude exists, so Claude Code's subagent discovery can pick
 them up. Codex/OMP skill targets receive skill markdown only.
+
+Default auto runtime installation does not require host detection; it still
+installs shared runtime files and any agent-home skill targets it finds.
 `;
 
 const ENSURE_USAGE = `okstra ensure-installed — idempotent install check
@@ -125,6 +151,31 @@ export function validateInstallRuntime(value) {
   return runtime;
 }
 
+function resolveInstallRuntime(runtime, command) {
+  const resolution = resolveRuntime({
+    requestedRuntime: runtime,
+    command,
+    env: process.env,
+    capabilities: { tmuxAvailable: Boolean(process.env.TMUX) },
+  });
+  if (resolution.ok || runtime !== "auto") return resolution;
+  return {
+    ok: false,
+    requestedRuntime: "auto",
+    resolvedRuntime: null,
+    host: "unknown",
+    confidence: "none",
+    reason: resolution.reason,
+    fallbackFrom: null,
+    warnings: [resolution.reason],
+  };
+}
+
+function formatInstallRuntimeLabel(runtime, resolution) {
+  if (resolution.resolvedRuntime) return `${runtime} -> ${resolution.resolvedRuntime}`;
+  return `${runtime} (host unresolved; installing target assets)`;
+}
+
 async function hashFile(path) {
   const buf = await fs.readFile(path);
   return createHash("sha256").update(buf).digest("hex");
@@ -139,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 {
@@ -209,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 {
@@ -313,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 });
@@ -348,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() {
@@ -584,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),
@@ -601,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) {
@@ -725,17 +738,11 @@ export async function runInstall(args) {
   const pkgRoot = getPackageRoot();
   const runtimeRoot = join(pkgRoot, "runtime");
   const paths = await resolvePaths();
-  const runtimeResolution = resolveRuntime({
-    requestedRuntime: opts.runtime,
-    command: "install",
-    env: process.env,
-    capabilities: { tmuxAvailable: Boolean(process.env.TMUX) },
-  });
-  if (!runtimeResolution.ok) {
+  const runtimeResolution = resolveInstallRuntime(opts.runtime, "install");
+  if (!runtimeResolution.ok && opts.runtime !== "auto") {
     process.stderr.write(`error: ${runtimeResolution.reason}\n`);
     return 2;
   }
-  const resolvedRuntime = runtimeResolution.resolvedRuntime;
 
   if (!opts.dryRun) {
     await fs.mkdir(paths.home, { recursive: true });
@@ -754,7 +761,7 @@ export async function runInstall(args) {
 
   if (!opts.quiet) {
     process.stdout.write(`installing okstra runtime (package ${paths.package})\n`);
-    process.stdout.write(`  runtime: ${opts.runtime} -> ${resolvedRuntime}\n`);
+    process.stdout.write(`  runtime: ${formatInstallRuntimeLabel(opts.runtime, runtimeResolution)}\n`);
     process.stdout.write(`  source: ${runtimeRoot}\n`);
     process.stdout.write(`  home:   ${paths.home}\n`);
   }
@@ -806,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);
@@ -813,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) {
@@ -835,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);
@@ -873,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}`);
@@ -883,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");
@@ -949,13 +982,8 @@ export async function runEnsureInstalled(args) {
     return 2;
   }
   const paths = await resolvePaths();
-  const runtimeResolution = resolveRuntime({
-    requestedRuntime: opts.runtime,
-    command: "ensure-installed",
-    env: process.env,
-    capabilities: { tmuxAvailable: Boolean(process.env.TMUX) },
-  });
-  if (!runtimeResolution.ok) {
+  const runtimeResolution = resolveInstallRuntime(opts.runtime, "ensure-installed");
+  if (!runtimeResolution.ok && opts.runtime !== "auto") {
     process.stderr.write(`error: ${runtimeResolution.reason}\n`);
     return 2;
   }
@@ -970,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.