clckernel 1.2.18 → 2.0.0

package/src/updater.js

@@ -1,18 +1,198 @@
 /**
  * CLC Kernel — Non-Destructive Harness Updater
- * Safely updates core AST tools, skills, playbooks, and IDE symlinks in an existing
+ * Safely updates core guard tools, skills, playbooks, and IDE symlinks in an existing
  * project while guaranteeing 100% preservation of:
  * - Local specifications (sdds/)
- * - Custom AST guards (tools/guards/)
- * - Project configuration and custom thresholds (.clckernel.yaml / .clc-forge.yaml)
+ * - Project guards (tools/guards/, and guard files in tools/ the kernel does not ship)
+ * - Project configuration and custom thresholds (.clckernel.yaml, or an older config name)
  * - Application source code and domain models
  */
 
 const fs = require('fs');
 const path = require('path');
 const { autoDetectStack } = require('./detector');
-const { generateHarness } = require('./generator');
+const { generateHarness, manifestGuardNames } = require('./generator');
+const { createIO, runWithIO, currentIO, sha256, NEW_SUFFIX } = require('./io');
+const { CONFIG_NAMES, readProjectConfig, globMatcher } = require('./config');
 
+// Artifacts written by releases that still used the old project name.
+const SKILLS_REL = path.join('.agents', 'skills');
+const LEGACY_SKILL = 'clc_forge_cli';
+const CURRENT_SKILL = 'clckernel_cli';
+const LEGACY_CURSOR_RULE = '.cursor/rules/clc_forge_context.mdc';
+const LEGACY_RESOLVED_JSON = '.clc-forge.resolved.json';
+const BUNDLED_SKILL_DIR = path.join(__dirname, '..', SKILLS_REL, CURRENT_SKILL);
+
+// Guard file names the audit orchestrators discover at the top of tools/
+// (sdds/unified-discovery): check_*, scan_*, verify_* or *_guard, .js or .py.
+const GUARD_FILE_RE = /^tools\/(?:(?:check|scan|verify)_[^/]*|[^/]*_guard)\.(?:js|py)$/;
+
+/**
+ * Read every regular file under `dir` into a map of relative path -> bytes.
+ * Anything that is not a directory or a regular file (e.g. a symlink) is
+ * recorded under `others`, since it cannot have come from us.
+ */
+function snapshotFiles(dir) {
+  const files = new Map();
+  const others = [];
+  if (!fs.existsSync(dir)) return { files, others };
+  const walk = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name);
+      const rel = path.relative(dir, full).split(path.sep).join('/');
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) files.set(rel, fs.readFileSync(full));
+      else others.push(rel);
+    }
+  };
+  walk(dir);
+  return { files, others };
+}
+
+/**
+ * Why the legacy skill dir is not provably ours, or null when it is: every
+ * file must be byte-identical to the same file in the bundled skill or in the
+ * project's clckernel_cli as it was before this update (older releases wrote
+ * both directories with the same bytes).
+ */
+function legacySkillMismatch(legacyDir, references) {
+  const { files, others } = snapshotFiles(legacyDir);
+  if (others.length) return `not a regular file: ${others[0]}`;
+  for (const [rel, bytes] of files) {
+    const known = references.some((ref) => ref.has(rel) && ref.get(rel).equals(bytes));
+    if (!known) {
+      const listed = references.some((ref) => ref.has(rel));
+      return listed ? `modified file: ${rel}` : `unknown file: ${rel}`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Remove artifacts left by releases that used the old name, only when they
+ * are provably generated by us. Anything else is kept and reported.
+ * @param {string} dir - Project root
+ * @param {Map<string, Buffer>} previousSkill - clckernel_cli files before this update
+ * @returns {{ removed: string[], kept: {path: string, reason: string}[] }}
+ */
+function cleanupLegacyArtifacts(dir, previousSkill) {
+  const removed = [];
+  const kept = [];
+  const lstat = (p) => {
+    try { return fs.lstatSync(p); } catch { return null; }
+  };
+
+  const skillDir = path.join(dir, SKILLS_REL, LEGACY_SKILL);
+  const skillLabel = `.agents/skills/${LEGACY_SKILL}/`;
+  const skillStat = lstat(skillDir);
+  if (skillStat) {
+    if (!skillStat.isDirectory()) {
+      kept.push({ path: skillLabel, reason: 'not a directory' });
+    } else {
+      const bundled = snapshotFiles(BUNDLED_SKILL_DIR).files;
+      const mismatch = legacySkillMismatch(skillDir, [bundled, previousSkill]);
+      if (mismatch) {
+        kept.push({ path: skillLabel, reason: mismatch });
+      } else if (currentIO(dir).remove(skillDir) === 'excluded') {
+        kept.push({ path: skillLabel, reason: 'excluded by config (update.exclude)' });
+      } else {
+        removed.push(skillLabel);
+      }
+    }
+  }
+
+  const rulePath = path.join(dir, LEGACY_CURSOR_RULE);
+  const ruleStat = lstat(rulePath);
+  if (ruleStat) {
+    const pointsToAgents =
+      ruleStat.isSymbolicLink() &&
+      path.resolve(path.dirname(rulePath), fs.readlinkSync(rulePath)) === path.join(dir, 'AGENTS.md');
+    if (pointsToAgents && currentIO(dir).remove(rulePath) === 'excluded') {
+      kept.push({ path: LEGACY_CURSOR_RULE, reason: 'excluded by config (update.exclude)' });
+    } else if (pointsToAgents) {
+      removed.push(LEGACY_CURSOR_RULE);
+    } else {
+      kept.push({
+        path: LEGACY_CURSOR_RULE,
+        reason: ruleStat.isSymbolicLink() ? 'symlink does not point to AGENTS.md' : 'not a symlink to AGENTS.md',
+      });
+    }
+  }
+
+  const jsonPath = path.join(dir, LEGACY_RESOLVED_JSON);
+  const jsonStat = lstat(jsonPath);
+  if (jsonStat) {
+    if (jsonStat.isFile() && currentIO(dir).remove(jsonPath) === 'excluded') {
+      kept.push({ path: LEGACY_RESOLVED_JSON, reason: 'excluded by config (update.exclude)' });
+    } else if (jsonStat.isFile()) {
+      removed.push(LEGACY_RESOLVED_JSON);
+    } else {
+      kept.push({ path: LEGACY_RESOLVED_JSON, reason: 'not a regular file' });
+    }
+  }
+
+  return { removed, kept };
+}
+
+/**
+ * Kernel guards this update retired (sdds/unified-discovery, decision 6): a
+ * guard file in tools/ that the kernel wrote before — listed in the prior
+ * registry, or byte-identical to a version it published — and that this run
+ * did not write because the current manifest no longer ships it. Nothing is
+ * moved or deleted: the file stays where it is (siblings it requires keep
+ * resolving), leaves the registry (rebuilt from what this run wrote), and the
+ * audit orchestrators keep running it as a project guard.
+ * @param {object} io - The update's io session (after generateHarness)
+ * @param {string} dir - Project root
+ * @param {object} knownHashes - { path: [sha256] } of published versions
+ * @returns {string[]} Root-relative paths, sorted
+ */
+function retiredKernelGuards(io, dir, knownHashes) {
+  const plan = io.plan();
+  const decided = new Set([
+    ...io.managedEntries().map((entry) => entry.path),
+    ...plan.protected.map((entry) => entry.path),
+    ...plan.excluded,
+  ]);
+  const candidates = new Set([...io.registry.paths, ...Object.keys(knownHashes)]);
+  const retired = [];
+  for (const rel of candidates) {
+    if (!GUARD_FILE_RE.test(rel) || decided.has(rel)) continue;
+    const bytes = io.read(path.join(dir, rel));
+    if (!bytes) continue;
+    const ours = io.registry.paths.includes(rel) || (knownHashes[rel] || []).includes(sha256(bytes));
+    if (ours) retired.push(rel);
+  }
+  return retired.sort();
+}
+
+/**
+ * Checks --add-guards against the stack's manifest.
+ * @param {string[]|'all'|undefined} requested - Guard names, or 'all'
+ * @param {string[]} offered - Guard names of the stack's manifest
+ * @returns {string[]|'all'} The guards to add
+ * @throws {Error} When a name is not a guard of this stack
+ */
+function validateAddGuards(requested, offered) {
+  if (requested === undefined || requested === null) return [];
+  if (requested === 'all') return 'all';
+  const unknown = requested.filter((name) => !offered.includes(name));
+  if (unknown.length > 0) {
+    throw new Error(
+      `Unknown guard(s) for --add-guards: ${unknown.join(', ')}. ` +
+        `This stack offers: ${offered.join(', ') || '(none)'}. Nothing was written.`
+    );
+  }
+  return [...requested];
+}
+
+/**
+ * Refreshes the harness of an installed project. It updates what the project
+ * has and never adds guards or mirrors it does not have
+ * (sdds/update-no-additions); options.addGuards opts guards in.
+ * @param {string} [targetDir] - Project root
+ * @param {{ dryRun?: boolean, addGuards?: string[]|'all', knownHashes?: object }} [options]
+ */
 function updateHarness(targetDir = process.cwd(), options = {}) {
   const resolvedDir = path.resolve(targetDir);
 
@@ -20,44 +200,57 @@ function updateHarness(targetDir = process.cwd(), options = {}) {
     throw new Error(`Target directory "${resolvedDir}" does not exist.`);
   }
 
+  // The project config is read before anything is written: an invalid one
+  // throws its ConfigError and the update writes nothing (sdds/config-foundation).
+  const projectConfig = readProjectConfig(resolvedDir);
+
   // 1. Detect Stack
   const detected = autoDetectStack(resolvedDir);
 
+  // --add-guards is checked before anything is written: an unknown name
+  // fails the whole update (sdds/update-no-additions, decision 1).
+  const addGuards = validateAddGuards(options.addGuards, manifestGuardNames(resolvedDir, detected));
+
   // 2. Identify existing preserved assets
   const preserved = {
     sdds: fs.existsSync(path.join(resolvedDir, 'sdds')),
     customGuards: fs.existsSync(path.join(resolvedDir, 'tools', 'guards')),
-    configYaml: fs.existsSync(path.join(resolvedDir, '.clckernel.yaml')) || fs.existsSync(path.join(resolvedDir, '.clc-forge.yaml')),
+    configYaml: CONFIG_NAMES.some((name) => fs.existsSync(path.join(resolvedDir, name))),
   };
 
   // 3. Run harness generation (refreshes tools, hooks, skills, and symlinks)
-  generateHarness(resolvedDir, detected);
-
-  // 4. Ensure AGENTS.md documents the update command in its command table.
-  // Non-destructive: only inject into a file that already carries the CLC
-  // Kernel command table, and only when the row is missing (idempotent).
-  // A project-customized AGENTS.md without that structure is left untouched.
-  const agentsPath = path.join(resolvedDir, 'AGENTS.md');
-  if (fs.existsSync(agentsPath)) {
-    let agentsContent = fs.readFileSync(agentsPath, 'utf-8');
-    if (!agentsContent.includes('clckernel update')) {
-      if (agentsContent.includes('| `clckernel start`')) {
-        agentsContent = agentsContent.replace(
-          '| `clckernel start`',
-          '| `clckernel update` | Maintenance | Non-destructive update: refresh core tools, playbooks & symlinks (preserves SDDs & custom guards). |\n| `clckernel start`'
-        );
-        fs.writeFileSync(agentsPath, agentsContent, 'utf-8');
-      } else if (agentsContent.includes('## 3. Universal Command Interface')) {
-        agentsContent += '\n| `clckernel update` | Maintenance | Non-destructive update: refresh core tools, playbooks & symlinks (preserves SDDs & custom guards). |\n';
-        fs.writeFileSync(agentsPath, agentsContent, 'utf-8');
-      }
-    }
-  }
+  // inside one io session (sdds/safe-update): every write follows the
+  // ownership rule, and a dry run only records the plan.
+  const { loadKnownHashes } = require('./io');
+  const knownHashes = options.knownHashes || loadKnownHashes();
+  const io = createIO({
+    root: resolvedDir,
+    dryRun: !!options.dryRun,
+    knownHashes,
+    mode: 'update',
+    exclude: globMatcher(projectConfig.config.update.exclude),
+  });
+  const { retiredGuards, legacyCleanup } = runWithIO(io, () => {
+    // Snapshot the installed skill first: the legacy copy is compared against it.
+    const previousSkill = snapshotFiles(path.join(resolvedDir, SKILLS_REL, CURRENT_SKILL)).files;
+    generateHarness(resolvedDir, detected, { addGuards, projectConfig });
+    const retired = retiredKernelGuards(io, resolvedDir, knownHashes);
+    const cleanup = cleanupLegacyArtifacts(resolvedDir, previousSkill);
+    const { ensureGitignoreEntries } = require('./gitignore');
+    ensureGitignoreEntries(resolvedDir);
+    injectUpdateRow(io, resolvedDir);
+    return { retiredGuards: retired, legacyCleanup: cleanup };
+  });
 
   return {
     success: true,
     targetDir: resolvedDir,
+    dryRun: io.dryRun,
     preserved,
+    configWarnings: projectConfig.warnings,
+    legacyCleanup,
+    retiredGuards,
+    plan: io.plan(),
     refreshed: {
       tools: true,
       skills: true,
@@ -67,24 +260,66 @@ function updateHarness(targetDir = process.cwd(), options = {}) {
   };
 }
 
-async function runUpdate(targetDir = process.cwd()) {
-  const { colors, printBanner } = require('./ui');
+/**
+ * Ensures AGENTS.md documents the update command in its command table.
+ * Non-destructive: only inject into a file that already carries the CLC
+ * Kernel command table, and only when the row is missing (idempotent).
+ * A project-customized AGENTS.md without that structure is left untouched.
+ */
+function injectUpdateRow(io, resolvedDir) {
+  const agentsPath = path.join(resolvedDir, 'AGENTS.md');
+  const current = io.read(agentsPath);
+  if (!current) return;
+  let agentsContent = current.toString('utf-8');
+  if (agentsContent.includes('clckernel update')) return;
+  if (agentsContent.includes('| `clckernel start`')) {
+    agentsContent = agentsContent.replace(
+      '| `clckernel start`',
+      '| `clckernel update` | Maintenance | Non-destructive update: run `npx clckernel update [dir]` (`--dry-run` previews, `--add-guards <a,b\\|all>` adds guards); refreshes kernel tools, hook, playbooks & symlinks (preserves SDDs, project guards, edited files & `.clckernel.yaml`). |\n| `clckernel start`'
+    );
+    io.writeFile(agentsPath, agentsContent);
+  } else if (agentsContent.includes('## 3. Universal Command Interface')) {
+    agentsContent += '\n| `clckernel update` | Maintenance | Non-destructive update: run `npx clckernel update [dir]` (`--dry-run` previews, `--add-guards <a,b\\|all>` adds guards); refreshes kernel tools, hook, playbooks & symlinks (preserves SDDs, project guards, edited files & `.clckernel.yaml`). |\n';
+    io.writeFile(agentsPath, agentsContent);
+  }
+}
+
+async function runUpdate(targetDir = process.cwd(), options = {}) {
+  const { colors, printBanner, printPlan } = require('./ui');
+  const dryRun = !!options.dryRun;
   printBanner();
 
-  console.log(`\n${colors.cyan}🔄 Actualizando CLC Kernel en:${colors.reset} ${targetDir}\n`);
+  console.log(`\n${colors.cyan}🔄 Actualizando CLC Kernel en:${colors.reset} ${targetDir}${dryRun ? ' (dry run)' : ''}\n`);
 
   try {
-    const result = updateHarness(targetDir);
+    const result = updateHarness(targetDir, { dryRun, addGuards: options.addGuards });
 
-    console.log(`${colors.green}✔ Salvaguardas estándar actualizadas en tools/${colors.reset}`);
-    console.log(`${colors.green}✔ Playbooks y Skills agénticos actualizados en .agents/skills/${colors.reset}`);
-    console.log(`${colors.green}✔ Enlaces simbióticos de IDEs actualizados (Cursor, Claude, Copilot, Antigravity)${colors.reset}`);
-    console.log(`${colors.green}✔ Hooks de git sincronizados${colors.reset}`);
+    for (const warning of result.configWarnings) {
+      console.log(`${colors.amber}⚠ ${warning}${colors.reset}`);
+    }
+    for (const retiredPath of result.retiredGuards) {
+      console.log(`${colors.amber}⚠ ${retiredPath}: retired kernel guard kept as project guard (the kernel no longer ships it; the hook and the audit still run it)${colors.reset}`);
+    }
+    for (const { path: keptPath, reason } of result.legacyCleanup.kept) {
+      console.log(`${colors.amber}⚠ Kept legacy artifact ${keptPath} (${reason}); review and remove it manually${colors.reset}`);
+    }
+    console.log('');
+    printPlan(result.plan, { dryRun });
     console.log(`\n${colors.bold}🔒 ACTIVOS PRESERVADOS AL 100%:${colors.reset}`);
     console.log(`   • ${colors.emerald}sdds/${colors.reset} (Especificaciones locales intactas)`);
     console.log(`   • ${colors.emerald}tools/guards/${colors.reset} (Reglas y salvaguardas personalizadas intactas)`);
     console.log(`   • ${colors.emerald}.clckernel.yaml${colors.reset} (Configuraciones de equipo intactas)\n`);
-    console.log(`${colors.green}✨ ¡Proyecto actualizado con éxito a la última versión de CLC Kernel!${colors.reset}\n`);
+    if (dryRun) {
+      console.log(`${colors.cyan}Dry run complete. Run without --dry-run to apply this plan.${colors.reset}\n`);
+    } else if (result.plan.protected.length > 0) {
+      console.log(`${colors.amber}✨ Proyecto actualizado, con ${result.plan.protected.length} archivo(s) protegido(s) para revisar (*${NEW_SUFFIX}).${colors.reset}\n`);
+    } else {
+      console.log(`${colors.emerald}✨ ¡Proyecto actualizado con éxito a la última versión de CLC Kernel!${colors.reset}\n`);
+    }
+    // sdds/onboarding: a short Next steps block, only when something needs attention.
+    const { updateNextStepsLines } = require('./ui');
+    const steps = dryRun ? [] : updateNextStepsLines(result.plan);
+    if (steps.length > 0) console.log(`${steps.join('\n')}\n`);
     return result;
   } catch (err) {
     console.error(`\n❌ Error actualizando el arnés: ${err.message}`);

package/tools/_changes.js

@@ -0,0 +1,279 @@
+/**
+ * Snapshot helpers shared by the diff-based guards (twin of _changes.py).
+ *
+ * A guard evaluates exactly the snapshot being verified:
+ *   - 'staged':      something is staged (a pre-commit) -> the index
+ *   - 'last-commit': nothing staged (a manual run)      -> HEAD, diffed against HEAD~1
+ *                    (a root commit lists every file of HEAD)
+ *   - null:          no git repository / git unavailable
+ * File content always comes from that snapshot, never from the working copy.
+ *
+ * Files the harness installed itself are listed in tools/.clckernel-managed.json
+ * (written by `clckernel` install/update). changedFiles drops every listed path,
+ * so no guard evaluates the harness's own code, unless the guard passes
+ * `includeManaged` (check_hitl: the kernel's own skill must obey its rules).
+ * Without a registry (e.g. the clckernel repository, where tools/ is source
+ * code) nothing is excluded.
+ *
+ * The project's `exclude_paths` (.clckernel.yaml) are dropped too, for every
+ * guard. The config is read through the sibling _config.js, which install
+ * ships next to this file; an older install without it fails closed when a
+ * config file appears (run `clckernel update`). An invalid config
+ * throws its ConfigError: a guard never runs on a config it cannot read.
+ *
+ * Self-contained: uses only Node.js built-ins. Git runs with argument arrays,
+ * never through a shell; paths are read NUL-separated (-z), so spaces and
+ * non-ASCII names survive.
+ */
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const BINARY_PROBE_BYTES = 8000;
+const MANAGED_REGISTRY = 'tools/.clckernel-managed.json';
+const MAX_BUFFER = 512 * 1024 * 1024;
+const CONFIG_NAMES = ['.clckernel.yaml', '.clckernel.yml', '.clc-forge.yaml', '.clc-forge.yml'];
+
+/**
+ * The project's validated config (defaults filled in), or null when the
+ * project has no config file. Deprecation warnings go to stderr once.
+ * @param {string} [dir] - Project root (default: cwd)
+ * @returns {object|null}
+ * @throws {Error} ConfigError on an invalid config; a plain Error when
+ *   tools/_config.js is missing
+ */
+function projectConfig(dir) {
+  const root = dir || process.cwd();
+  if (!CONFIG_NAMES.some(name => fs.existsSync(path.join(root, name)))) return null;
+  let configModule;
+  try {
+    configModule = require('./_config.js');
+  } catch (err) {
+    if (err && err.code === 'MODULE_NOT_FOUND') {
+      throw new Error(`The project config needs tools/_config.js and tools/yaml.js (${err.message.split('\n')[0]}): run \`clckernel update\` so the guards can read it`);
+    }
+    throw err;
+  }
+  const loaded = configModule.loadConfig(root);
+  configModule.reportWarnings(loaded);
+  return loaded.config;
+}
+
+/**
+ * A predicate for root-relative paths matching one of the globs (false for
+ * every path when there are none).
+ * @param {string[]} globs
+ * @returns {(rel: string) => boolean}
+ */
+function globMatcher(globs) {
+  if (!Array.isArray(globs) || globs.length === 0) return () => false;
+  return require('./_config.js').globMatcher(globs);
+}
+
+/** Runs git in dir; stdout Buffer on success, null on any failure. */
+function git(dir, args) {
+  const res = spawnSync('git', args, { cwd: dir, maxBuffer: MAX_BUFFER, stdio: ['ignore', 'pipe', 'pipe'] });
+  if (res.error || res.status !== 0) return null;
+  return res.stdout;
+}
+
+function splitNul(buffer) {
+  return buffer.toString('utf-8').split('\0').filter(Boolean);
+}
+
+function hasCommit(dir, rev) {
+  return git(dir, ['rev-parse', '--verify', '--quiet', `${rev}^{commit}`]) !== null;
+}
+
+/**
+ * Lists the files added, copied, modified or renamed in the snapshot, minus
+ * the registry-listed files and the config's exclude_paths.
+ * @param {string} dir - Directory inside the repository
+ * @param {{ extensions?: string[], includeManaged?: boolean }} [options] - Keep only
+ *   paths ending in one of `extensions`; `includeManaged` keeps registry-listed paths too
+ * @returns {{ mode: 'staged'|'last-commit'|null, files: string[] }}
+ */
+function changedFiles(dir, { extensions, includeManaged = false } = {}) {
+  const cwd = dir || process.cwd();
+  const anyStaged = git(cwd, ['diff', '--cached', '--name-only', '-z']);
+  if (anyStaged === null) return { mode: null, files: [] };
+
+  let mode;
+  let out;
+  if (anyStaged.length > 0) {
+    mode = 'staged';
+    out = git(cwd, ['diff', '--cached', '--name-only', '-z', '--diff-filter=ACMR']);
+  } else if (!hasCommit(cwd, 'HEAD')) {
+    // No commits and nothing staged: the index holds nothing to evaluate.
+    return { mode: 'staged', files: [] };
+  } else {
+    mode = 'last-commit';
+    out = hasCommit(cwd, 'HEAD~1')
+      ? git(cwd, ['diff', '--name-only', '-z', '--diff-filter=ACMR', 'HEAD~1', 'HEAD'])
+      : git(cwd, ['ls-tree', '-r', '-z', '--name-only', '--full-tree', 'HEAD']);
+  }
+  if (out === null) return { mode: null, files: [] };
+
+  const managed = includeManaged ? new Set() : managedFiles(cwd, mode);
+  const config = projectConfig(cwd);
+  const excluded = globMatcher(config ? config.exclude_paths : []);
+  let files = splitNul(out).filter(f => !managed.has(f) && !excluded(f));
+  if (Array.isArray(extensions) && extensions.length > 0) {
+    files = files.filter(f => extensions.some(ext => f.endsWith(ext)));
+  }
+  return { mode, files };
+}
+
+/**
+ * New paths of the PURE renames in the snapshot: files whose content is
+ * identical to a file removed in the same change (same blob, git R100). The
+ * pair compared is the one changedFiles uses: HEAD -> index when staged,
+ * HEAD~1 -> HEAD in last-commit mode; a root commit (or an index with no HEAD)
+ * has no renames. A rename with any content change is not listed.
+ * @param {string} dir - Directory inside the repository
+ * @param {'staged'|'last-commit'|null} mode - Snapshot (from changedFiles)
+ * @returns {Set<string>}
+ */
+function pureRenames(dir, mode) {
+  const cwd = dir || process.cwd();
+  const raw = ['--raw', '-z', '--no-abbrev', '-M', '--diff-filter=R'];
+  let out = null;
+  if (mode === 'staged' && hasCommit(cwd, 'HEAD')) {
+    out = git(cwd, ['diff', '--cached', ...raw, 'HEAD']);
+  } else if (mode === 'last-commit' && hasCommit(cwd, 'HEAD~1')) {
+    out = git(cwd, ['diff', ...raw, 'HEAD~1', 'HEAD']);
+  }
+  const renamed = new Set();
+  if (out === null) return renamed;
+  // Each record: ":<src mode> <dst mode> <src blob> <dst blob> R<score>" NUL old NUL new NUL.
+  const parts = splitNul(out);
+  for (let i = 0; i + 2 < parts.length; i += 3) {
+    const fields = parts[i].replace(/^:/, '').split(' ');
+    if (fields.length === 5 && fields[2] === fields[3]) renamed.add(parts[i + 2]);
+  }
+  return renamed;
+}
+
+/**
+ * Paths listed in the harness registry: read from the snapshot being evaluated,
+ * falling back to the working copy at the repository root. A missing or
+ * malformed registry excludes nothing.
+ * @returns {Set<string>}
+ */
+function managedFiles(cwd, mode) {
+  let text = readFile(cwd, MANAGED_REGISTRY, mode);
+  if (text === null && mode !== null) {
+    const top = git(cwd, ['rev-parse', '--show-toplevel']);
+    text = readFile(top ? top.toString('utf-8').trim() : cwd, MANAGED_REGISTRY, null);
+  }
+  if (text === null) return new Set();
+  try {
+    const data = JSON.parse(text);
+    // Older installs wrote a list of paths; current ones { kernelVersion, files: [{ path, sha256 }] }.
+    if (Array.isArray(data)) return new Set(data.filter(f => typeof f === 'string'));
+    if (data && Array.isArray(data.files)) {
+      const paths = data.files.map(f => f && f.path).filter(f => typeof f === 'string');
+      return new Set([...paths, MANAGED_REGISTRY]);
+    }
+  } catch {
+    // Malformed registry: exclude nothing.
+  }
+  return new Set();
+}
+
+/** Object name of a path in the snapshot (paths are relative to the repo root). */
+function objectName(file, mode) {
+  return mode === 'staged' ? `:0:${file}` : `HEAD:${file}`;
+}
+
+/**
+ * Reads a file from the snapshot.
+ * With mode null (no git) the working copy is the only source there is.
+ * @returns {string|null} UTF-8 content; null when missing or binary
+ */
+function readFile(dir, file, mode) {
+  const cwd = dir || process.cwd();
+  let buffer;
+  if (mode === null || mode === undefined) {
+    try {
+      buffer = fs.readFileSync(path.join(cwd, file));
+    } catch {
+      return null;
+    }
+  } else {
+    buffer = git(cwd, ['cat-file', 'blob', objectName(file, mode)]);
+    if (buffer === null) return null;
+  }
+  if (buffer.subarray(0, BINARY_PROBE_BYTES).includes(0)) return null;
+  return buffer.toString('utf-8');
+}
+
+/**
+ * True when the path exists in the snapshot (the working copy when mode is null).
+ * @returns {boolean}
+ */
+function exists(dir, file, mode) {
+  const cwd = dir || process.cwd();
+  if (mode === null || mode === undefined) return fs.existsSync(path.join(cwd, file));
+  return git(cwd, ['cat-file', '-e', objectName(file, mode)]) !== null;
+}
+
+/**
+ * Lists every file of the snapshot, for whole-repository facts (e.g. a name
+ * that must be unique, a link target that must exist): the index in staged
+ * mode, HEAD in last-commit mode. Paths are relative to the repository root
+ * and sorted; nothing is excluded. With mode null (no git) nothing is listed.
+ * @param {string} dir - Directory inside the repository
+ * @param {'staged'|'last-commit'|null} mode - Snapshot (from changedFiles)
+ * @returns {string[]}
+ */
+function listFiles(dir, mode) {
+  const cwd = dir || process.cwd();
+  if (mode !== 'staged' && mode !== 'last-commit') return [];
+  const out = mode === 'staged'
+    ? git(cwd, ['ls-files', '-z', '--cached', '--full-name', '--', ':/'])
+    : git(cwd, ['ls-tree', '-r', '-z', '--name-only', '--full-tree', 'HEAD']);
+  if (out === null) return [];
+  return [...new Set(splitNul(out))].sort();
+}
+
+/**
+ * Dependencies of the nearest package.json of a repository path, read from the
+ * snapshot: the file's directory, then each parent up to the repository root
+ * (a monorepo part's own package.json wins over the root one). Results are
+ * memoized per directory in `cache` when one is passed.
+ * @param {string} dir - Directory inside the repository
+ * @param {string} file - Path relative to the repository root
+ * @param {'staged'|'last-commit'|null} mode - Snapshot (from changedFiles)
+ * @param {Map<string, object|null>} [cache] - Directory -> dependencies
+ * @returns {object|null} dependencies + devDependencies; null without a package.json
+ */
+function nearestPackageDeps(dir, file, mode, cache = new Map()) {
+  const visited = [];
+  let current = path.posix.dirname(file);
+  let deps = null;
+  for (;;) {
+    const key = current === '.' ? '' : current;
+    if (cache.has(key)) {
+      deps = cache.get(key);
+      break;
+    }
+    visited.push(key);
+    const raw = readFile(dir, key ? `${key}/package.json` : 'package.json', mode);
+    if (raw !== null) {
+      try {
+        const pkg = JSON.parse(raw);
+        deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      } catch {
+        deps = {};
+      }
+      break;
+    }
+    if (!key) break;
+    current = path.posix.dirname(key);
+  }
+  for (const key of visited) cache.set(key, deps);
+  return deps;
+}
+
+module.exports = { changedFiles, pureRenames, readFile, exists, listFiles, nearestPackageDeps, projectConfig, globMatcher };