cairn-ai 0.2.6 → 0.2.7

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.
 

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>`.
 
@@ -72,8 +72,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

package/skills/cairn-review/SKILL.md

@@ -17,7 +17,7 @@ At the start and after compaction, restart, delegation, or handoff, restore cont
 
 When subagent tools are available, each agent may recursively delegate bounded review sub-tasks to subagents. Every child subagent reads project-root `MEMORY.md` when present and continues when absent, keeps the assigned scope, and preserves others' edits.
 
-Resolve any `cairn://...` resource through `references/cairn-runtime.json` next to this `SKILL.md` (or this skill's `../..` source root during development). Never look for Cairn runtime resources in the target repository.
+Resolve any `cairn://...` resource through `references/cairn-runtime.json` next to this `SKILL.md` (or this skill's `../..` source root during development). Never look for Cairn runtime resources in the target repository. 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.
 
 ## Procedure
 

package/skills/cairn-work/SKILL.md

@@ -29,7 +29,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 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 runtime files or derive the plugin root from the current working directory. Resolve `cairn://...` plan resources through this runtime and pass the target repository separately with `--root <repoRoot>`.
+Resolve Cairn's read-only runtime from `references/cairn-runtime.json` next to this `SKILL.md`. Its `pluginRoot` contains Cairn's scripts 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 runtime files or derive the plugin root from the current working directory. Resolve `cairn://...` plan resources through this runtime and pass the target repository separately with `--root <repoRoot>`. 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 the installed CLI for durable state. Important forms are:
 
@@ -46,7 +46,7 @@ node "<pluginRoot>/scripts/cairn.mjs" goal complete --quiet --root "<repoRoot>"
 
 `goal verify` executes the argv after `--` without a shell and records its exit code, bounded tool output, output digest, and watched-workspace fingerprint. The legacy `goal receipt` command imports declared evidence for compatibility; declared evidence does not satisfy a default tool-bound goal.
 
-Verification defaults to 600,000 ms (10 minutes), accepts a shorter `--timeout-ms`, and is capped at 3,600,000 ms (1 hour). The external command never holds the state lock. A receipt is committed only when the starting goal/task identity and the pre/post watched fingerprint still match. Choose the watch set and verification command at the semantic boundary that proves the claimed behavior.
+Verification defaults to 600,000 ms (10 minutes), accepts a shorter `--timeout-ms`, and is capped at 3,600,000 ms (1 hour). The external command never holds the state lock. A receipt is committed only when the starting goal/task identity and the pre/post watched fingerprint still match. Choose the watch set and verification command at the semantic boundary that proves the claimed behavior. With no explicit watch, Git-ignored files are excluded; pass each ignored artifact required by the claim with `--watch <path>` or explicitly watch its containing directory.
 
 Use `goal pause`, `goal block --reason "<concrete blocker>"`, or `goal cancel` when that is the truthful state. A task can be blocked with `goal task --task "<task-id>" --status blocked --reason "<concrete blocker>"`.
 
@@ -72,8 +72,8 @@ Any relevant mutation after a gate makes that result stale evidence. Rerun the a
 - 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 edits resume. Completed task profiles are preserved as audit history; incomplete task profiles are recalculated for the new path.
 
 ## Procedure