cairn-ai 0.2.6 → 0.2.8

package/scripts/cairn-toolcheck.mjs

@@ -1,26 +1,69 @@
 #!/usr/bin/env node
-import { accessSync, constants, realpathSync, statSync } from "node:fs";
-import { lstat, readdir } from "node:fs/promises";
-import { delimiter, isAbsolute, join, posix, relative, resolve, sep, win32 } from "node:path";
-import { spawnSync } from "node:child_process";
+import { readFileSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-
-export const DEFAULT_TIMEOUT_MS = 10_000;
+import {
+  DEFAULT_TIMEOUT_MS,
+  commandOk,
+  execute,
+  inspectCommand,
+  localExecutableAvailable,
+  run,
+} from "./cairn-toolcheck-runtime.mjs";
+import { buildRequirements, collectEntries, detectStacks } from "./cairn-toolcheck-detect.mjs";
+
+export {
+  commandCandidates,
+  commandOk,
+  DEFAULT_TIMEOUT_MS,
+  inspectCommand,
+  isWithin,
+  localExecutableAvailable,
+  run,
+  shouldUseShell,
+  systemCommandCandidates,
+} from "./cairn-toolcheck-runtime.mjs";
+export {
+  addJvmBuildToolRequirements,
+  addJvmRequirements,
+  buildRequirements,
+  collectEntries,
+  composerInstall,
+  detectStacks,
+  installDev,
+  jdtlsInstall,
+  packageManager,
+  packageManagerSource,
+  pushUnique,
+  pythonInstall,
+  req,
+  unsafeReq,
+} from "./cairn-toolcheck-detect.mjs";
+
+const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const usage = "Usage: cairn toolcheck [--root PATH] [--json] [--install --yes]";
 
 if (isCliEntry()) {
+  const args = process.argv.slice(2);
   try {
-    const options = parseCliArgs(process.argv.slice(2));
-    const report = await createReport(options);
-
-    if (options.json) {
-      console.log(JSON.stringify(report, null, 2));
+    const options = parseCliArgs(args);
+    if (options.action === "help") {
+      console.log(usage);
+    } else if (options.action === "version") {
+      console.log(`cairn ${version}`);
     } else {
-      printReport(report);
+      const report = await createReport(options);
+      if (options.json) console.log(JSON.stringify(report, null, 2));
+      else printReport(report);
+      if (report.install.refused || report.results.some((result) => !result.ok)) process.exitCode = 1;
     }
-
-    if (report.install.refused || report.results.some((result) => !result.ok)) process.exitCode = 1;
   } catch (error) {
-    console.error(`Cairn toolcheck error: ${error instanceof Error ? error.message : String(error)}`);
+    const message = error instanceof Error ? error.message : String(error);
+    if (args.includes("--json")) {
+      console.log(JSON.stringify({ schemaVersion: 1, error: { code: "CLI_USAGE", message } }, null, 2));
+    } else {
+      console.error(`Cairn toolcheck error: ${message}`);
+    }
     process.exitCode = 2;
   }
 }
@@ -30,25 +73,35 @@ export function parseCliArgs(args, cwd = process.cwd()) {
   let install = false;
   let yes = false;
   let json = false;
+  let action = "check";
+  const provided = new Set();
 
   for (let index = 0; index < args.length; index += 1) {
     const argument = args[index];
-    if (argument === "--install") install = true;
-    else if (argument === "--yes") yes = true;
-    else if (argument === "--json") json = true;
-    else if (argument === "--root") {
-      const value = args[index + 1];
+    if (["--help", "--version", "--install", "--yes", "--json"].includes(argument)) {
+      if (provided.has(argument)) throw new Error(`${argument} may only be provided once`);
+      provided.add(argument);
+      if (argument === "--help") action = "help";
+      else if (argument === "--version") action = "version";
+      else if (argument === "--install") install = true;
+      else if (argument === "--yes") yes = true;
+      else json = true;
+    } else if (argument === "--root" || argument.startsWith("--root=")) {
+      if (provided.has("--root")) throw new Error("--root may only be provided once");
+      provided.add("--root");
+      const value = argument === "--root" ? args[index + 1] : argument.slice("--root=".length);
       if (!value || value.startsWith("--")) throw new Error("--root requires a path");
       root = value;
-      index += 1;
-    } else if (argument.startsWith("--root=")) {
-      const value = argument.slice("--root=".length);
-      if (!value) throw new Error("--root requires a path");
-      root = value;
+      if (argument === "--root") index += 1;
+    } else {
+      throw new Error(`unknown option: ${argument}`);
     }
   }
 
-  return { root: resolve(cwd, root), install, yes, json };
+  if (provided.has("--help") && provided.has("--version")) {
+    throw new Error("--help and --version cannot be used together");
+  }
+  return { root: resolve(cwd, root), install, yes, json, action };
 }
 
 export async function createReport({
@@ -140,333 +193,6 @@ export async function createReport({
   };
 }
 
-export async function collectEntries(base) {
-  const output = [];
-  async function walk(dir) {
-    for (const entry of await readdir(dir)) {
-      if ([".git", ".cairn", "node_modules", "vendor", "target", ".venv", "__pycache__"].includes(entry)) continue;
-      const path = join(dir, entry);
-      const relativePath = normalizePath(relative(base, path));
-      if (relativePath === "test/fixtures" || relativePath.startsWith("test/fixtures/")) continue;
-      const info = await lstat(path);
-      if (info.isSymbolicLink()) continue;
-      if (info.isDirectory()) await walk(path);
-      else output.push(relativePath);
-    }
-  }
-  await walk(base);
-  return output;
-}
-
-export function detectStacks(paths) {
-  const stacks = new Set();
-  if (hasBasename(paths, "package.json")) stacks.add("javascript");
-  if (hasBasename(paths, "tsconfig.json") || paths.some((path) => path.endsWith(".ts") || path.endsWith(".tsx"))) stacks.add("typescript");
-  if (hasBasename(paths, "pyproject.toml") || paths.some((path) => path.endsWith(".py"))) stacks.add("python");
-  if (hasBasename(paths, "composer.json") || paths.some((path) => path.endsWith(".php"))) stacks.add("php");
-  if (hasBasename(paths, "pom.xml", "build.gradle", "build.gradle.kts") || paths.some((path) => path.endsWith(".java"))) stacks.add("java");
-  if (paths.some((path) => path.endsWith(".kt") || path.endsWith(".kts"))) stacks.add("kotlin");
-  if (hasBasename(paths, "Package.swift") || paths.some((path) => hasPathSegmentWithSuffix(path, ".xcodeproj", ".xcworkspace") || path.endsWith(".swift"))) stacks.add("swift");
-  if (hasBasename(paths, "go.mod") || paths.some((path) => path.endsWith(".go"))) stacks.add("go");
-  if (hasBasename(paths, "Cargo.toml") || paths.some((path) => path.endsWith(".rs"))) stacks.add("rust");
-  return [...stacks];
-}
-
-export function buildRequirements(stacks, entries = [], _commandAvailable = commandOk, platform = process.platform) {
-  const requirements = [];
-  if (stacks.includes("javascript")) {
-    requirements.push(unsafeReq("node", ["--version"], "JavaScript runtime for package scripts and CLI checks", "automatic runtime installation is unavailable"));
-    const manager = packageManager(entries);
-    requirements.push(unsafeReq(manager, ["--version"], `JavaScript package manager selected from ${packageManagerSource(entries)}`, "automatic package-manager installation is unavailable"));
-  }
-  if (stacks.includes("typescript")) {
-    requirements.push(unsafeReq("typescript-language-server", ["--version"], "TypeScript LSP server", "automatic package installation is disabled without pinned package versions"));
-    requirements.push(unsafeReq("tsc", ["--version"], "TypeScript compiler verification", "automatic package installation is disabled without pinned package versions"));
-  }
-  if (stacks.includes("python")) {
-    requirements.push(unsafeReq("basedpyright", ["--version"], "Python LSP/type checker", "automatic Python package installation is disabled without pinned package versions"));
-    requirements.push(unsafeReq("ruff", ["--version"], "Python lint and format checker", "automatic Python package installation is disabled without pinned package versions"));
-  }
-  if (stacks.includes("php")) {
-    const composerProject = hasBasename(entries, "composer.json");
-    requirements.push(req("php", ["--version"], "PHP runtime for Composer scripts and CLI checks"));
-    if (composerProject) requirements.push(req("composer", ["--version"], "PHP package manager for project-local tool installation"));
-    requirements.push(unsafeReq("phpactor", ["--version"], "PHP LSP server", "automatic Composer package installation is disabled without pinned package versions"));
-    requirements.push(unsafeReq("phpstan", ["--version"], "PHP static analysis verification", "automatic Composer package installation is disabled without pinned package versions"));
-    requirements.push(unsafeReq("php-cs-fixer", ["--version"], "PHP formatting verification", "automatic Composer package installation is disabled without pinned package versions"));
-  }
-  if (stacks.includes("java")) {
-    addJvmRequirements(requirements);
-    requirements.push(unsafeReq("jdtls", ["--version"], "Java LSP server", "checksum-free JDTLS latest downloads are disabled"));
-    addJvmBuildToolRequirements(requirements, entries);
-  }
-  if (stacks.includes("kotlin")) {
-    addJvmRequirements(requirements);
-    requirements.push(req("kotlin-lsp.sh", ["--help"], "Kotlin LSP server"));
-    requirements.push(req("kotlinc", ["-version"], "Kotlin compiler verification"));
-    addJvmBuildToolRequirements(requirements, entries);
-  }
-  if (stacks.includes("swift")) {
-    requirements.push(req("swift", ["--version"], "Swift toolchain for build and test commands"));
-    requirements.push(req("sourcekit-lsp", ["--version"], "Swift LSP server"));
-    if (entries.some((path) => hasPathSegmentWithSuffix(path, ".xcodeproj", ".xcworkspace"))) {
-      requirements.push(req("xcodebuild", ["-version"], "Xcode build verification"));
-    }
-  }
-  if (stacks.includes("go")) {
-    requirements.push(unsafeReq("gopls", ["version"], "Go LSP server", "unpinned go install targets are disabled"));
-    requirements.push(unsafeReq("golangci-lint", ["--version"], "Go lint verification", "unpinned go install targets are disabled"));
-  }
-  if (stacks.includes("rust")) {
-    requirements.push(unsafeReq("rust-analyzer", ["--version"], "Rust LSP server", "automatic rustup changes are disabled without a pinned toolchain manifest"));
-    requirements.push(unsafeReq("cargo", ["clippy", "--version"], "Rust clippy verification", "automatic rustup changes are disabled without a pinned toolchain manifest"));
-  }
-  return requirements;
-}
-
-export function addJvmRequirements(requirements) {
-  if (!requirements.some((requirement) => requirement.name === "java")) {
-    requirements.push(req("java", ["--version"], "JVM runtime for build and test commands"));
-  }
-  if (!requirements.some((requirement) => requirement.name === "javac")) {
-    requirements.push(req("javac", ["--version"], "JVM compiler verification"));
-  }
-}
-
-export function addJvmBuildToolRequirements(requirements, entries = []) {
-  const gradleWindows = findBasename(entries, "gradlew.bat");
-  const gradleUnix = findBasename(entries, "gradlew");
-  if (gradleWindows) pushUnique(requirements, req(repositoryCommand(gradleWindows), ["--version"], "Gradle wrapper availability", null, { localOnly: true }));
-  else if (gradleUnix) pushUnique(requirements, req(repositoryCommand(gradleUnix), ["--version"], "Gradle wrapper availability", null, { localOnly: true }));
-  else if (hasBasename(entries, "build.gradle", "build.gradle.kts")) pushUnique(requirements, req("gradle", ["--version"], "Gradle availability"));
-  const mavenWindows = findBasename(entries, "mvnw.cmd", "mvnw.bat");
-  const mavenUnix = findBasename(entries, "mvnw");
-  if (mavenWindows) pushUnique(requirements, req(repositoryCommand(mavenWindows), ["--version"], "Maven wrapper availability", null, { localOnly: true }));
-  else if (mavenUnix) pushUnique(requirements, req(repositoryCommand(mavenUnix), ["--version"], "Maven wrapper availability", null, { localOnly: true }));
-  else if (hasBasename(entries, "pom.xml")) pushUnique(requirements, req("mvn", ["--version"], "Maven availability"));
-}
-
-export function pushUnique(requirements, requirement) {
-  if (!requirements.some((candidate) => candidate.name === requirement.name)) requirements.push(requirement);
-}
-
-// Kept for API compatibility. Callers may show these commands, but buildRequirements
-// no longer attaches an unpinned command to an automatically executable requirement.
-export function composerInstall(packages) {
-  return { command: "composer", args: ["require", "--dev", ...packages] };
-}
-
-export function pythonInstall(uv, project, tool, platform = process.platform) {
-  if (uv && project) return { command: "uv", args: ["add", "--dev", tool] };
-  if (uv) return { command: "uv", args: ["tool", "install", tool] };
-  if (platform === "win32") return { command: "py", args: ["-3", "-m", "pip", "install", "--user", tool] };
-  return { command: "python3", args: ["-m", "pip", "install", "--user", tool] };
-}
-
-export function jdtlsInstall(_platform = process.platform) {
-  return null;
-}
-
-export function req(command, args, reason, installCommand = null, options = {}) {
-  return {
-    name: command,
-    command,
-    args,
-    reason,
-    install: installCommand,
-    installUnavailableReason: options.installUnavailableReason ?? null,
-    localOnly: options.localOnly ?? false,
-  };
-}
-
-export function unsafeReq(command, args, reason, installUnavailableReason) {
-  return req(command, args, reason, null, { installUnavailableReason });
-}
-
-export function packageManager(entries = []) {
-  return selectPackageManager(entries).manager;
-}
-
-export function packageManagerSource(entries = []) {
-  const selected = selectPackageManager(entries);
-  return selected.path ?? "the npm default (no lockfile found)";
-}
-
-export function installDev(pm, packages) {
-  if (pm === "bun") return { command: "bun", args: ["add", "-d", ...packages] };
-  if (pm === "pnpm") return { command: "pnpm", args: ["add", "-D", ...packages] };
-  if (pm === "yarn") return { command: "yarn", args: ["add", "-D", ...packages] };
-  return { command: "npm", args: ["install", "--save-dev", ...packages] };
-}
-
-export function inspectCommand(requirement, {
-  root = process.cwd(),
-  runner = run,
-  timeoutMs = DEFAULT_TIMEOUT_MS,
-  localChecker = localExecutableAvailable,
-  platform = process.platform,
-} = {}) {
-  const candidates = commandCandidates(requirement.command, root, platform);
-  const localOnly = requirement.localOnly || isRepositoryCommand(requirement.command, root);
-
-  if (!localOnly) {
-    let diagnostic = null;
-    for (const candidate of systemCommandCandidates(requirement.command, platform)) {
-      diagnostic = execute(candidate, requirement.args, { root, runner, timeoutMs });
-      if (diagnostic.status === 0) {
-        return {
-          ok: true,
-          availability: "verified",
-          source: "system",
-          candidate,
-          diagnostic,
-        };
-      }
-    }
-
-    for (const candidate of candidates.slice(1)) {
-      if (localChecker(candidate)) {
-        return {
-          ok: true,
-          availability: "discovered",
-          source: "repository",
-          candidate,
-          diagnostic,
-        };
-      }
-    }
-
-    return {
-      ok: false,
-      availability: diagnostic?.timedOut ? "timeout" : "missing",
-      source: null,
-      candidate: null,
-      diagnostic,
-    };
-  }
-
-  for (const candidate of repositoryCandidates(requirement.command, root)) {
-    if (localChecker(candidate)) {
-      return {
-        ok: true,
-        availability: "discovered",
-        source: "repository",
-        candidate,
-        diagnostic: null,
-      };
-    }
-  }
-
-  return {
-    ok: false,
-    availability: "missing",
-    source: null,
-    candidate: null,
-    diagnostic: null,
-  };
-}
-
-export function commandOk(command, args, root = process.cwd(), runner = run) {
-  return inspectCommand(req(command, args, "tool availability"), { root, runner }).ok;
-}
-
-export function commandCandidates(command, root = process.cwd(), platform = process.platform) {
-  const candidates = isRepositoryCommand(command, root)
-    ? repositoryCandidates(command, root)
-    : [
-        command,
-        join(root, "node_modules", ".bin", command),
-        join(root, "vendor", "bin", command),
-        join(root, ".cairn", "tools", "bin", command),
-      ];
-  if (platform !== "win32") return [...new Set(candidates)];
-  const extensions = [".cmd", ".bat", ".exe"];
-  return [...new Set(candidates.flatMap((candidate) => hasWindowsExecutableExtension(candidate) ? [candidate] : [candidate, ...extensions.map((extension) => `${candidate}${extension}`)]))];
-}
-
-export function systemCommandCandidates(command, platform = process.platform) {
-  if (platform !== "win32" || hasWindowsExecutableExtension(command) || isAbsolute(command)) return [command];
-  return [command, `${command}.cmd`, `${command}.bat`, `${command}.exe`];
-}
-
-export function localExecutableAvailable(command, platform = process.platform) {
-  try {
-    const info = statSync(command);
-    if (!info.isFile()) return false;
-    accessSync(command, platform === "win32" ? constants.F_OK : constants.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export function run(command, args, { cwd = process.cwd(), timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
-  const startedAt = Date.now();
-  const result = spawnSync(command, args, {
-    cwd,
-    stdio: "ignore",
-    encoding: "utf8",
-    shell: shouldUseShell(command),
-    timeout: timeoutMs,
-    env: safeEnvironment(cwd),
-  });
-  return { ...result, durationMs: Date.now() - startedAt };
-}
-
-export function shouldUseShell(command, platform = process.platform) {
-  return platform === "win32" && /\.(cmd|bat)$/i.test(command);
-}
-
-function execute(command, args, { root, runner, timeoutMs }) {
-  const startedAt = Date.now();
-  try {
-    const result = runner(command, args, { cwd: root, timeoutMs });
-    return {
-      status: Number.isInteger(result?.status) ? result.status : null,
-      signal: result?.signal ?? null,
-      errorCode: result?.error?.code ?? null,
-      timedOut: result?.error?.code === "ETIMEDOUT",
-      durationMs: Number.isFinite(result?.durationMs) ? result.durationMs : Date.now() - startedAt,
-    };
-  } catch (error) {
-    return {
-      status: null,
-      signal: null,
-      errorCode: error && typeof error === "object" && "code" in error ? String(error.code) : "RUNNER_ERROR",
-      timedOut: false,
-      durationMs: Date.now() - startedAt,
-    };
-  }
-}
-
-function repositoryCandidates(command, root) {
-  const normalizedCommand = command.replace(/^\.\//, "");
-  const direct = isAbsolute(command) ? command : resolve(root, normalizedCommand);
-  return [...new Set([direct])];
-}
-
-function isRepositoryCommand(command, root) {
-  if (/^(?:\.\.?[\\/])/.test(command)) return true;
-  if (/^(?:gradlew|gradlew\.bat|mvnw|mvnw\.cmd|mvnw\.bat)$/i.test(command)) return true;
-  return isAbsolute(command) && isWithin(root, command);
-}
-
-export function isWithin(root, candidate, platform = process.platform) {
-  const pathApi = platform === "win32" ? win32 : posix;
-  const path = pathApi.relative(pathApi.resolve(root), pathApi.resolve(candidate));
-  return path === "" || (!pathApi.isAbsolute(path) && !path.startsWith(`..${pathApi.sep}`) && path !== "..");
-}
-
-function safeEnvironment(root) {
-  const pathKey = Object.keys(process.env).find((key) => key.toLowerCase() === "path") ?? "PATH";
-  const safePath = (process.env[pathKey] ?? "")
-    .split(delimiter)
-    .filter(Boolean)
-    .filter((entry) => isAbsolute(entry) && !isWithin(root, entry))
-    .join(delimiter);
-  return { ...process.env, [pathKey]: safePath };
-}
-
 function printReport(report) {
   console.log(`Cairn toolcheck: ${report.root}`);
   console.log(`Detected stacks: ${report.detected.length > 0 ? report.detected.join(", ") : "none"}`);
@@ -493,74 +219,3 @@ function isCliEntry() {
     return import.meta.url === pathToFileURL(process.argv[1]).href;
   }
 }
-
-function normalizePath(path) {
-  return path.split(sep).join("/");
-}
-
-function pathBasename(path) {
-  const normalized = normalizePath(path);
-  return normalized.slice(normalized.lastIndexOf("/") + 1);
-}
-
-function hasBasename(paths, ...names) {
-  const expected = new Set(names);
-  return paths.some((path) => expected.has(pathBasename(path)));
-}
-
-function findBasename(paths, ...names) {
-  const expected = new Set(names);
-  return [...paths]
-    .filter((path) => expected.has(pathBasename(path)))
-    .sort(compareRepositoryPaths)[0] ?? null;
-}
-
-function hasPathSegmentWithSuffix(path, ...suffixes) {
-  return normalizePath(path)
-    .split("/")
-    .some((segment) => suffixes.some((suffix) => segment.endsWith(suffix)));
-}
-
-function repositoryCommand(path) {
-  const normalized = normalizePath(path);
-  return normalized.startsWith("./") ? normalized : `./${normalized}`;
-}
-
-function selectPackageManager(entries) {
-  const lockfiles = [
-    { manager: "bun", names: new Set(["bun.lock", "bun.lockb"]), priority: 0 },
-    { manager: "pnpm", names: new Set(["pnpm-lock.yaml"]), priority: 1 },
-    { manager: "yarn", names: new Set(["yarn.lock"]), priority: 2 },
-    { manager: "npm", names: new Set(["package-lock.json", "npm-shrinkwrap.json"]), priority: 3 },
-  ];
-  const candidates = [];
-
-  for (const path of entries) {
-    const normalized = normalizePath(path);
-    const name = pathBasename(normalized);
-    const match = lockfiles.find(({ names }) => names.has(name));
-    if (!match) continue;
-    candidates.push({
-      manager: match.manager,
-      path: normalized,
-      depth: normalized.split("/").length - 1,
-      priority: match.priority,
-    });
-  }
-
-  candidates.sort((left, right) => left.depth - right.depth
-    || left.priority - right.priority
-    || left.path.localeCompare(right.path));
-  return candidates[0] ?? { manager: "npm", path: null };
-}
-
-function compareRepositoryPaths(left, right) {
-  const leftPath = normalizePath(left);
-  const rightPath = normalizePath(right);
-  const depth = leftPath.split("/").length - rightPath.split("/").length;
-  return depth || leftPath.localeCompare(rightPath);
-}
-
-function hasWindowsExecutableExtension(command) {
-  return /\.(cmd|bat|exe)$/i.test(command);
-}

package/scripts/cairn.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { realpathSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { spawnSync } from "node:child_process";
@@ -8,8 +8,17 @@ import { parseRootArgs, resolvePluginRoot } from "./cairn-paths.mjs";
 
 const pluginRoot = resolvePluginRoot(import.meta.url);
 const scriptDir = join(pluginRoot, "scripts");
+const version = JSON.parse(readFileSync(join(pluginRoot, "package.json"), "utf8")).version;
 
 export async function main(command = "help", args = [], { runner = spawnSync } = {}) {
+  if (command === "help" || command === "--help") {
+    console.log(message("usage"));
+    return;
+  }
+  if (command === "version" || command === "--version") {
+    console.log(`cairn ${version}`);
+    return;
+  }
   if (["install", "upgrade", "doctor", "uninstall"].includes(command)) {
     const result = runner(process.execPath, [join(scriptDir, "cairn-lifecycle.mjs"), command, ...args], { stdio: "inherit" });
     process.exitCode = result.status ?? 1;
@@ -40,7 +49,7 @@ export async function main(command = "help", args = [], { runner = spawnSync } =
     console.log(message(command));
     return;
   }
-  console.log(message("usage"));
+  throw new Error(`unknown command: ${command}`);
 }
 
 export function message(key, locale = localeValue()) {
@@ -140,5 +149,10 @@ const messages = {
 
 if (isCliEntry()) {
   const [command = "help", ...args] = process.argv.slice(2);
-  await main(command, args);
+  try {
+    await main(command, args);
+  } catch (error) {
+    console.error(`Cairn error: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 2;
+  }
 }

package/skills/cairn-memory/SKILL.md

@@ -17,7 +17,7 @@ When subagent tools are available, each agent may recursively delegate bounded s
 
 ## Runtime Location
 
-Resolve Cairn's read-only runtime from `references/cairn-runtime.json` next to this `SKILL.md`. Its `pluginRoot` contains Cairn's `scripts/`, `templates/`, commands, agents, and model guidance. In a source checkout where the locator does not exist, resolve the plugin root from this `SKILL.md` location (`../..`). Never look for Cairn runtime files in the target repository or derive the plugin root from the current working directory.
+Resolve Cairn's read-only runtime from `references/cairn-runtime.json` next to this `SKILL.md`. Its `pluginRoot` contains Cairn's `scripts/`, `templates/`, commands, agents, and model guidance. In a source checkout where the locator does not exist, resolve the plugin root from this `SKILL.md` location (`../..`). Never look for Cairn runtime files in the target repository or derive the plugin root from the current working directory. If the shared runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror and recover from the published/global package with `cairn doctor` followed by `cairn upgrade`; do not use another mirror as a repair source.
 
 Keep the target repository root separate. Pass it explicitly with `--root <repoRoot>` when invoking the installed runtime. Repository artifacts include `MEMORY.md`, `PLAN.md`, `docs/memory/`, and `docs/plan/`; runtime goal state lives only under the user-home Cairn directory.
 
@@ -31,7 +31,8 @@ Keep the target repository root separate. Pass it explicitly with `--root <repoR
    - Recursive subagent delegation is allowed only for bounded sub-tasks when the current surface supports it.
 4. Write detailed facts to `docs/memory/<domain>.md`.
 5. Keep only one-line links and summaries in `MEMORY.md`.
-6. Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.
+6. When a lesson or correction recurs and is machine-checkable, encode it as a test, lint rule, script, or hook instead of more prose; memory keeps judgment rules and a pointer to the enforcing check.
+7. Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.
 
 ## Delegation Prompt Format
 

package/skills/cairn-plan/SKILL.md

@@ -23,7 +23,7 @@ At the start and after compaction, restart, or handoff, restore context in this
 
 ## Runtime Location
 
-Resolve Cairn's read-only runtime from `references/cairn-runtime.json` next to this `SKILL.md`. Its `pluginRoot` contains Cairn's `scripts/`, `templates/`, commands, agents, and model guidance. In a source checkout where the locator does not exist, resolve the plugin root from this `SKILL.md` location (`../..`). Never search the target repository for Cairn scripts, templates, or model guidance, and never derive the plugin root from the current working directory.
+Resolve Cairn's read-only runtime from `references/cairn-runtime.json` next to this `SKILL.md`. Its `pluginRoot` contains Cairn's `scripts/`, `templates/`, commands, agents, and model guidance. In a source checkout where the locator does not exist, resolve the plugin root from this `SKILL.md` location (`../..`). Never search the target repository for Cairn scripts, templates, or model guidance, and never derive the plugin root from the current working directory. If the shared runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror and recover from the published/global package with `cairn doctor` followed by `cairn upgrade`; do not use another mirror as a repair source.
 
 Use logical resource IDs such as `cairn://templates/work-plan.md` and `cairn://docs/model-guidance/codex.md` in repository plans. Resolve those IDs through `pluginRoot` only while executing. Keep `repoRoot` separate and pass it explicitly as `--root <repoRoot>`.
 
@@ -33,7 +33,10 @@ For a non-trivial implementation request or continuation of already planned work
 node "<pluginRoot>/scripts/cairn.mjs" goal start --root "<repoRoot>" --goal "<objective>" --plan "docs/plan/<topic>.md" --tasks '[{"id":"triage-plan","title":"Run planned triage and finalize the plan","requiredEvidence":["planArtifact","triageDecision"]},{"id":"implement","title":"Implement the finalized plan"},{"id":"verify","title":"Verify and review the result"}]' --criteria "<completion criterion>" --session "<current session_id>"
 ```
 
-Use the current Codex hook `session_id` when it is available. If the surface does not expose a stable session ID, omit `--session` and record that the goal is repository-scoped. If Codex UI plan/goal tools are unavailable, record that limitation and continue with the repository plan and goal; never claim UI synchronization that did not occur.
+Pass `--session` only with a session ID the surface actually exposes to the model; never guess or invent one, because a mismatched owner makes every later hook treat the goal as foreign. If no stable session ID is exposed, omit `--session` and record that the goal is repository-scoped.
+
+If an unfinished repository goal already exists when a new implementation request, steer, or drift arrives, do not cancel it to start another. Fold the new work into it with `goal replan` (completed tasks and their evidence are preserved; resume a paused or blocked goal first), synchronize the plan artifact and native UI roadmap, and keep advancing until goal final review. Start a separate goal only when the user explicitly switches work. When a hook reports that another session owns the goal and this session continues that same work, take ownership with `goal claim --session <id>` using the ID shown by the hook.
+ If Codex UI plan/goal tools are unavailable, record that limitation and continue with the repository plan and goal; never claim UI synchronization that did not occur.
 
 ## Procedure
 
@@ -72,8 +75,8 @@ Use the current Codex hook `session_id` when it is available. If the surface doe
 - Models always inherit the host/user default; never configure or override them.
 - Light Path planning, implementation, and verification request `medium`.
 - Heavy Path planning, review, and implementation request `high`; final verification and review request `xhigh`.
-- Every module task records `Requested reasoning effort` and `Effective reasoning effort` in `docs/plan/<topic>.md`.
-- Pass requested effort only when dispatching a new task/worker and the host exposes a reasoning-effort option or host-native equivalent. Omit model overrides. For an unsupported host or value, record effective reasoning effort `inherited` with the reason and leave model/global config unchanged.
+- Every module task records `Requested reasoning effort` and `Effective reasoning effort` in `docs/plan/<topic>.md`. Requested is Cairn's desired profile; Effective is what the dispatch result confirms.
+- Pass requested effort only when dispatching a new task/worker and the host exposes a reasoning-effort option or host-native equivalent. Omit model overrides. Effective `inherited` means no task-level override was confirmed, not proof of missing host capability. Describe capability only from the exposed interface or dispatch response, distinguish Cairn non-integration from host non-support, and leave model/global config unchanged.
 - On every route change, synchronize the plan artifact, repository goal task roadmap through `goal replan`, native UI plan, and reasoning effort profile before mutation. Completed task profiles are preserved as audit history; incomplete task profiles are recalculated for the new path.
 
 ## Complexity Triage