@haposoft/cafekit 0.18.1 → 0.18.3

package/bin/lib/migrate-plan.js

@@ -0,0 +1,419 @@
+'use strict';
+
+/**
+ * Plan which files of an npx install `migrate` removes and which it keeps.
+ *
+ * Pure planner: it reads the Claude and Codex install manifests and the files on
+ * disk and never writes. A file is removed only when every check below agrees it
+ * is CafeKit's untouched copy of something a plugin now ships; any doubt keeps it
+ * and names the reason, so the dry-run shows exactly what `--apply` will do.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { sha256, MANIFEST_FILE } = require('./manifest');
+const { isInside } = require('./path-safety');
+const { PLATFORMS } = require('./context');
+const { codexAgentName } = require('./codex-install');
+const { pluginSkills, pluginAgents } = require('./plugin-inventory');
+
+const MIGRATED_PLATFORMS = ['claude', 'codex'];
+const METADATA_FILES = ['cafekit.json', MANIFEST_FILE];
+// Written by the installer outside the manifest; the merged-file planner owns them.
+const MERGED_FILES = new Set(['.claude/settings.json', '.codex/hooks.json']);
+// Claude Code stores an /output-style choice in settings.local.json, which overrides settings.json.
+const STYLE_SETTINGS = ['.claude/settings.json', '.claude/settings.local.json'];
+const MAX_SCANNED_BYTES = 1024 * 1024;
+// Hook logs and dependency installs name runtime paths without depending on them.
+const UNSCANNED_DIRS = new Set(['.logs', '.privacy', 'session-state', 'agent-memory', 'worktrees', 'node_modules', '.venv', 'venv', '__pycache__']);
+// Created by the operating system, not by a user customizing a skill.
+const SYSTEM_FILES = new Set(['.DS_Store', 'Thumbs.db', 'desktop.ini']);
+
+const REASONS = {
+  merged: 'written outside the manifest, planned separately',
+  'outside-root': 'manifest key points outside the platform folders',
+  symlinked: 'path goes through a symlink',
+  modified: 'edited since install',
+  runtime: 'runtime configuration stays',
+  'npx-only': 'no plugin ships this skill or agent',
+  'group-kept': 'another file of the same skill or agent is kept',
+  'required-by-kept': 'a kept file names it',
+  'protects-kept': 'ignore rules still protect kept files',
+  missing: 'already gone',
+  untracked: 'not installed by CafeKit'
+};
+
+const toPosix = (value) => value.split(path.sep).join('/');
+
+function lstatOrNull(target) {
+  try {
+    return fs.lstatSync(target);
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
+    throw error;
+  }
+}
+
+/** True when any existing component of `rel` below `root` is a symlink. */
+function createSymlinkProbe(root) {
+  const cache = new Map();
+  return (rel) => {
+    let cursor = root;
+    for (const segment of rel.split('/').filter(Boolean)) {
+      cursor = path.join(cursor, segment);
+      if (!cache.has(cursor)) {
+        const stat = lstatOrNull(cursor);
+        cache.set(cursor, stat ? (stat.isSymbolicLink() ? 'link' : 'ok') : 'absent');
+      }
+      const state = cache.get(cursor);
+      if (state === 'link') return true;
+      if (state === 'absent') return false;
+    }
+    return false;
+  };
+}
+
+function readManifestRaw(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return { state: 'absent' };
+    return { state: 'corrupt' };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || !parsed.files || typeof parsed.files !== 'object' || Array.isArray(parsed.files)) {
+      return { state: 'corrupt' };
+    }
+    return { state: 'ok', files: parsed.files };
+  } catch {
+    return { state: 'corrupt' };
+  }
+}
+
+/** Skill folder or agent file an installed path belongs to; null for shared runtime files. */
+function groupOf(rel) {
+  let match = rel.match(/^(\.claude\/skills|\.agents\/skills)\/([^/]+)\//);
+  if (match) return { kind: 'skill', name: match[2], label: `${match[1]}/${match[2]}/` };
+  match = rel.match(/^\.claude\/agents\/([^/]+)\.md$/);
+  if (match) return { kind: 'agent', name: match[1], label: rel };
+  match = rel.match(/^\.codex\/agents\/([^/]+)\.toml$/);
+  if (match) return { kind: 'codex-agent', name: match[1], label: rel };
+  return null;
+}
+
+function createPluginShips() {
+  const skills = new Set(pluginSkills());
+  const agents = new Set(pluginAgents());
+  const codexAgents = new Set([...agents].map(codexAgentName));
+  return (group) => {
+    if (group.kind === 'skill') return skills.has(group.name);
+    if (group.kind === 'agent') return agents.has(group.name);
+    return codexAgents.has(group.name);
+  };
+}
+
+function platformFolders(key) {
+  return PLATFORMS[key].ownership?.allowedRoots || [PLATFORMS[key].folder];
+}
+
+function planEntry(root, platform, folders, recordRoot, key, record, isSymlinked) {
+  const norm = String(key).replace(/\\/g, '/');
+  const recorded = record && typeof record.sha256 === 'string' ? record.sha256 : null;
+  const base = { platform, key, sha256: recorded, group: null };
+  const outside = !norm || path.posix.isAbsolute(norm) || /^[A-Za-z]:/.test(norm) || norm.split('/').includes('..');
+  const abs = path.resolve(root, recordRoot, norm);
+  const rel = toPosix(path.relative(root, abs));
+  if (outside || !folders.some((folder) => {
+    const folderAbs = path.join(root, folder);
+    return abs !== folderAbs && isInside(folderAbs, abs);
+  })) {
+    return { ...base, path: rel, action: 'keep', reason: 'outside-root' };
+  }
+  const entry = { ...base, path: rel, group: groupOf(rel) };
+  if (MERGED_FILES.has(rel) || METADATA_FILES.some((name) => folders.some((folder) => rel === `${folder}/${name}`))) {
+    return { ...entry, action: 'keep', reason: 'merged' };
+  }
+  if (isSymlinked(rel)) return { ...entry, action: 'keep', reason: 'symlinked' };
+  const stat = lstatOrNull(abs);
+  if (!stat) return { ...entry, action: 'missing', reason: 'missing' };
+  if (!stat.isFile() || !recorded || sha256(fs.readFileSync(abs)) !== recorded) {
+    return { ...entry, action: 'keep', reason: 'modified' };
+  }
+  const folder = folders.find((name) => rel.startsWith(`${name}/`));
+  if (rel === `${folder}/runtime.json`) return { ...entry, action: 'keep', reason: 'runtime' };
+  if (rel === `${folder}/runtime.schema.json` && lstatOrNull(path.join(root, folder, 'runtime.json'))) {
+    return { ...entry, action: 'keep', reason: 'runtime' };
+  }
+  return { ...entry, action: 'remove', reason: null };
+}
+
+function planPlatform(root, platform, isSymlinked) {
+  const config = PLATFORMS[platform];
+  const folders = platformFolders(platform);
+  const result = { platform, name: config.name, folders, status: 'absent', reason: null, metadata: [], entries: [] };
+  if (!lstatOrNull(path.join(root, config.folder))) return result;
+  if (folders.some((folder) => lstatOrNull(path.join(root, folder))?.isSymbolicLink())) {
+    return { ...result, status: 'refused', reason: 'a platform folder is a symlink' };
+  }
+  result.metadata = METADATA_FILES
+    .map((name) => `${config.folder}/${name}`)
+    .filter((rel) => lstatOrNull(path.join(root, rel)));
+  const manifest = readManifestRaw(path.join(root, config.folder, MANIFEST_FILE));
+  if (manifest.state === 'absent') {
+    const managed = result.metadata.length > 0;
+    return { ...result, status: managed ? 'unmanaged' : 'absent', reason: managed ? 'cafekit.json without an install manifest' : null };
+  }
+  if (manifest.state === 'corrupt') return { ...result, status: 'refused', reason: 'the install manifest does not parse' };
+
+  const recordRoot = config.ownership?.recordRoot || config.folder;
+  result.entries = Object.entries(manifest.files)
+    .map(([key, record]) => planEntry(root, platform, folders, recordRoot, key, record, isSymlinked));
+  result.status = 'planned';
+  return result;
+}
+
+/** A symlink that points back into the repository keeps the files it reaches. */
+function keepSymlinkTargets(root, entries) {
+  const byPath = new Map(entries.map((entry) => [entry.path, entry]));
+  for (const entry of entries) {
+    if (entry.reason !== 'symlinked') continue;
+    let real;
+    try {
+      real = fs.realpathSync(path.join(root, entry.path));
+    } catch {
+      continue;
+    }
+    if (!isInside(root, real)) continue;
+    const target = byPath.get(toPosix(path.relative(root, real)));
+    if (target && target.action === 'remove') Object.assign(target, { action: 'keep', reason: 'symlinked' });
+  }
+}
+
+function applyGroupRules(entries, pluginShips, untracked) {
+  const groups = new Map();
+  for (const entry of entries) {
+    if (!entry.group) continue;
+    const id = `${entry.platform}:${entry.group.label}`;
+    if (!groups.has(id)) groups.set(id, []);
+    groups.get(id).push(entry);
+  }
+  for (const members of groups.values()) {
+    const { label } = members[0].group;
+    // A user file added inside a skill folder customizes that skill, so the skill stays whole.
+    const holdsUserFile = label.endsWith('/') && untracked.some((rel) => rel.startsWith(label)
+      && !SYSTEM_FILES.has(path.posix.basename(rel))
+      && !rel.split('/').some((segment) => UNSCANNED_DIRS.has(segment)));
+    const reason = !pluginShips(members[0].group) ? 'npx-only'
+      : members.some((entry) => entry.action === 'keep') || holdsUserFile ? 'group-kept' : null;
+    if (!reason) continue;
+    for (const entry of members) {
+      if (entry.action === 'remove') Object.assign(entry, { action: 'keep', reason });
+    }
+  }
+}
+
+function readText(abs, { follow = false } = {}) {
+  let stat;
+  try {
+    stat = follow ? fs.statSync(abs) : lstatOrNull(abs);
+  } catch {
+    return null;
+  }
+  if (!stat || !stat.isFile() || stat.size > MAX_SCANNED_BYTES) return null;
+  const buffer = fs.readFileSync(abs);
+  return buffer.includes(0) ? null : buffer.toString('utf8');
+}
+
+/** Installed paths a file names: `.claude/…`, `.codex/…`, `.agents/…`, and relative requires. */
+function referencedPaths(text, fromRel) {
+  const refs = new Set();
+  for (const match of text.matchAll(/\.(?:claude|codex|agents)[/\\][A-Za-z0-9._/\\-]+/g)) {
+    // JSON escapes a backslash as `\\`, so separators may arrive doubled.
+    refs.add(match[0].replace(/\\/g, '/').replace(/\/{2,}/g, '/').replace(/[./]+$/, ''));
+  }
+  for (const match of text.matchAll(/require\(\s*['"](\.{1,2}\/[^'"]+)['"]\s*\)/g)) {
+    const target = path.posix.normalize(path.posix.join(path.posix.dirname(fromRel), match[1]));
+    for (const suffix of ['', '.cjs', '.js', '/index.js']) refs.add(target + suffix);
+  }
+  return refs;
+}
+
+function selectedStyleNames(root) {
+  const names = new Set();
+  for (const rel of STYLE_SETTINGS) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(path.join(root, rel), 'utf8'));
+      if (typeof settings.outputStyle === 'string' && settings.outputStyle.trim()) names.add(settings.outputStyle.trim());
+    } catch {
+      // A missing or unparsable settings file selects nothing.
+    }
+  }
+  return names;
+}
+
+/** A style is named by its frontmatter `name:`, or by its file name when that is absent. */
+function styleName(text, rel) {
+  const frontmatter = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  const name = frontmatter && frontmatter[1].match(/^name:\s*(.+)$/m);
+  return name ? name[1].trim().replace(/^(['"])(.*)\1$/, '$2') : path.posix.basename(rel, '.md');
+}
+
+/**
+ * Text files of the untracked list, descending into collapsed folders. Symlinks are
+ * followed because reading a user's linked skill can only keep more files, never fewer.
+ */
+function untrackedFiles(root, untracked) {
+  const files = [];
+  const seen = new Set();
+  const visit = (rel) => {
+    if (rel.split('/').some((segment) => UNSCANNED_DIRS.has(segment))) return;
+    let real;
+    let stat;
+    try {
+      real = fs.realpathSync(path.join(root, rel));
+      stat = fs.statSync(real);
+    } catch {
+      return;
+    }
+    if (seen.has(real)) return;
+    seen.add(real);
+    if (stat.isDirectory()) {
+      for (const name of fs.readdirSync(real).sort()) visit(`${rel}/${name}`);
+    } else if (stat.isFile()) {
+      files.push(rel);
+    }
+  };
+  for (const rel of untracked) visit(rel.replace(/\/$/, ''));
+  return files;
+}
+
+/** Keep every shared file a kept or user file names, transitively, and the selected output styles. */
+function keepRequiredFiles(root, entries, untracked) {
+  const byPath = new Map(entries.map((entry) => [entry.path, entry]));
+  const readable = (entry) => !['outside-root', 'symlinked', 'merged'].includes(entry.reason);
+  const queue = [
+    ...entries.filter((entry) => entry.action === 'keep' && readable(entry)),
+    ...untrackedFiles(root, untracked).map((rel) => ({ path: rel, follow: true }))
+  ];
+  const keep = (entry) => {
+    if (entry.action !== 'remove') return;
+    Object.assign(entry, { action: 'keep', reason: 'required-by-kept' });
+    queue.push(entry);
+  };
+
+  const styles = selectedStyleNames(root);
+  if (styles.size > 0) {
+    for (const entry of entries) {
+      if (!/^\.claude\/output-styles\/[^/]+\.md$/.test(entry.path) || entry.action === 'missing') continue;
+      const text = readText(path.join(root, entry.path));
+      if (text && styles.has(styleName(text, entry.path))) keep(entry);
+    }
+  }
+
+  while (queue.length > 0) {
+    const entry = queue.pop();
+    const text = readText(path.join(root, entry.path), { follow: entry.follow === true });
+    if (!text) continue;
+    for (const ref of referencedPaths(text, entry.path)) {
+      const target = byPath.get(ref);
+      if (target && !target.group) keep(target);
+    }
+  }
+}
+
+/** Files in the platform folders that no manifest records, collapsing folders that hold none. */
+function listUntracked(root, platforms, entries) {
+  const managed = new Set(entries.map((entry) => entry.path));
+  const managedPrefixes = new Set();
+  for (const rel of managed) {
+    const parts = rel.split('/');
+    for (let i = 1; i < parts.length; i++) managedPrefixes.add(parts.slice(0, i).join('/'));
+  }
+  const skipped = new Set([...MERGED_FILES]);
+  for (const platform of platforms) for (const rel of platform.metadata) skipped.add(rel);
+
+  const untracked = [];
+  const visit = (rel) => {
+    if (managed.has(rel) || skipped.has(rel)) return;
+    const stat = lstatOrNull(path.join(root, rel));
+    if (!stat) return;
+    if (stat.isDirectory() && !stat.isSymbolicLink() && managedPrefixes.has(rel)) {
+      for (const name of fs.readdirSync(path.join(root, rel)).sort()) visit(`${rel}/${name}`);
+      return;
+    }
+    // A symlink that holds manifest keys is already reported as `symlinked`.
+    if (stat.isSymbolicLink() && managedPrefixes.has(rel)) return;
+    untracked.push(stat.isDirectory() ? `${rel}/` : rel);
+  };
+  for (const platform of platforms) {
+    if (platform.status !== 'planned') continue;
+    for (const folder of platform.folders) visit(folder);
+  }
+  return untracked;
+}
+
+/** A shared `.gitignore` stays while anything below its folder stays. */
+function keepIgnoreFiles(entries, untracked) {
+  for (const entry of entries) {
+    if (entry.group || entry.action !== 'remove' || path.posix.basename(entry.path) !== '.gitignore') continue;
+    const prefix = `${path.posix.dirname(entry.path)}/`;
+    const kept = entries.some((other) => other !== entry && other.action === 'keep' && other.path.startsWith(prefix))
+      || untracked.some((rel) => rel.startsWith(prefix));
+    if (kept) Object.assign(entry, { action: 'keep', reason: 'protects-kept' });
+  }
+}
+
+function planManifestFiles(projectRoot) {
+  const root = fs.realpathSync(projectRoot);
+  const isSymlinked = createSymlinkProbe(root);
+  const platforms = MIGRATED_PLATFORMS.map((platform) => planPlatform(root, platform, isSymlinked));
+  const entries = platforms.flatMap((platform) => platform.entries);
+  const untracked = listUntracked(root, platforms, entries);
+  keepSymlinkTargets(root, entries);
+  applyGroupRules(entries, createPluginShips(), untracked);
+  keepRequiredFiles(root, entries, untracked);
+  keepIgnoreFiles(entries, untracked);
+  return {
+    projectRoot: root,
+    platforms: Object.fromEntries(platforms.map(({ entries: _entries, ...platform }) => [platform.platform, platform])),
+    entries,
+    untracked
+  };
+}
+
+function renderManifestPlan(plan) {
+  const lines = [];
+  for (const platform of Object.values(plan.platforms)) {
+    if (platform.status === 'absent') continue;
+    const where = platform.folders.map((folder) => `${folder}/`).join(', ');
+    lines.push(`${platform.name} (${where}): ${platform.status}${platform.reason ? ` — ${platform.reason}` : ''}`);
+  }
+  const buckets = new Map();
+  for (const entry of plan.entries) {
+    const id = entry.action === 'remove' ? 'remove' : `${entry.action}:${entry.reason}`;
+    if (!buckets.has(id)) buckets.set(id, new Map());
+    const label = entry.group && entry.group.kind === 'skill' ? entry.group.label : entry.path;
+    const bucket = buckets.get(id);
+    bucket.set(label, (bucket.get(label) || 0) + 1);
+  }
+  const order = ['remove', ...Object.keys(REASONS).map((reason) => `${reason === 'missing' ? 'missing' : 'keep'}:${reason}`)];
+  for (const id of order) {
+    const bucket = buckets.get(id);
+    if (!bucket) continue;
+    const total = [...bucket.values()].reduce((sum, count) => sum + count, 0);
+    const reason = id.split(':')[1];
+    lines.push('', id === 'remove' ? `Remove (${total} files):` : `${id.startsWith('missing') ? 'Missing' : 'Keep'} — ${REASONS[reason]} (${total} files):`);
+    for (const [label, count] of [...bucket.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+      lines.push(`  ${label}${label.endsWith('/') ? ` (${count} files)` : ''}`);
+    }
+  }
+  if (plan.untracked.length > 0) {
+    lines.push('', `Keep — ${REASONS.untracked} (${plan.untracked.length}):`);
+    for (const rel of plan.untracked) lines.push(`  ${rel}`);
+  }
+  return lines.join('\n');
+}
+
+module.exports = { REASONS, planManifestFiles, renderManifestPlan, groupOf };

package/bin/lib/plugin-inventory.js

@@ -0,0 +1,33 @@
+'use strict';
+
+/**
+ * Which CafeKit skills and agents the Claude and Codex plugins ship.
+ *
+ * Lives under bin/ because the npm package ships bin and src but not scripts:
+ * the plugin build and the `migrate` command must agree on the same lists.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SOURCE = path.join(__dirname, '../../src/claude');
+
+// These need a Python venv, npm install or a browser binary, which a plugin has
+// no install step for; they stay on the npx path for now.
+const EXCLUDED_SKILLS = ['chrome-devtools', 'ui-ux', 'ui-ux-pro-max'];
+const EXCLUDED_AGENTS = ['ui-ux-designer'];
+
+function pluginSkills() {
+  const manifest = JSON.parse(fs.readFileSync(path.join(SOURCE, 'migration-manifest.json'), 'utf8'));
+  return manifest.skills.required.filter((name) => !EXCLUDED_SKILLS.includes(name));
+}
+
+function pluginAgents() {
+  return fs.readdirSync(path.join(SOURCE, 'agents'))
+    .filter((name) => name.endsWith('.md'))
+    .map((name) => name.slice(0, -3))
+    .filter((name) => !EXCLUDED_AGENTS.includes(name))
+    .sort();
+}
+
+module.exports = { EXCLUDED_SKILLS, EXCLUDED_AGENTS, pluginSkills, pluginAgents };

package/bin/phases/claude-runtime.js

@@ -16,6 +16,7 @@ const {
   getCopyOptions
 } = require('../lib/context');
 const { sha256 } = require('../lib/manifest');
+const { assertNoSymlinkPath } = require('../lib/path-safety');
 const { writeManagedFile, copyManagedTree } = require('../lib/managed-writer');
 const { report, treeAction } = require('./report');
 const {
@@ -164,30 +165,86 @@ function copyClaudeRuntimeFiles(ctx, platformKey) {
   });
 }
 
-/** Delete runtime files marked obsolete by the manifest. Claude only. */
-function removeObsoleteClaudeRuntimeFiles(ctx, platformKey) {
-  if (platformKey !== 'claude') return;
-
-  const obsoleteFiles = ctx.manifest?.obsolete?.runtimeFiles || [];
-  const targetBase = PLATFORMS.claude.folder;
-
-  obsoleteFiles.forEach((relPath) => {
-    const targetPath = path.join(targetBase, relPath);
-    if (!fs.existsSync(targetPath)) return;
-
-    const isDir = fs.statSync(targetPath).isDirectory();
-    if (!ctx.dryRun) {
-      fs.rmSync(targetPath, { force: true, recursive: isDir });
-      // Remove the entry from the manifest so it doesn't linger as a zombie.
-      if (ctx.trackers && ctx.trackers.claude) {
-        ctx.trackers.claude.prune(relPath);
-        // Directories: prune every tracked file underneath as well.
-        if (isDir) ctx.trackers.claude.prunePrefix(`${relPath}/`);
+/** Remove only obsolete runtime bytes proven unchanged by the ownership manifest. */
+function removeObsoleteRuntimeFiles(ctx, platformKey) {
+  const completed = (ctx.obsoleteRuntimeCleanedPlatforms ||= new Set());
+  if (completed.has(platformKey)) return;
+  completed.add(platformKey);
+  const preserved = new Set();
+  for (const key of [platformKey]) {
+    const platform = PLATFORMS[key];
+    const tracker = ctx.trackers?.[key];
+    const ownership = ctx.ownership?.[platform.folder] || { files: {} };
+    const obsoleteFiles = (ctx.manifest?.obsolete?.runtimeFiles || [])
+      // omp installs no skills: the shared .agents/skills directory belongs to the Codex install.
+      .filter(relative => key === 'omp' ? /^(?:hooks|scripts|extensions)\//.test(relative)
+        : key === 'claude' || /^(?:hooks|scripts|skills)\//.test(relative));
+    for (const relative of obsoleteFiles) {
+      const targetPath = key === 'codex' && relative.startsWith('skills/')
+        ? path.join(platform.skillsDir, relative.slice('skills/'.length))
+        : path.join(platform.folder, relative);
+      let stat;
+      try {
+        assertNoSymlinkPath(targetPath);
+        stat = fs.statSync(targetPath);
+      } catch (error) {
+        if (error.code === 'ENOENT') {
+          if ((key === 'codex' || key === 'omp') && tracker && !ctx.dryRun) tracker.prune(tracker.keyFor(targetPath));
+          continue;
+        }
+        preserved.add(targetPath);
+        continue;
+      }
+      try {
+        if (!tracker) throw new Error('Missing ownership tracker');
+        const trackedKeys = [];
+        const inspect = file => {
+          assertNoSymlinkPath(file);
+          const current = fs.statSync(file);
+          if (current.isDirectory()) {
+            for (const name of fs.readdirSync(file)) inspect(path.join(file, name));
+            return;
+          }
+          if (!current.isFile()) throw new Error('Unsupported obsolete file type');
+          const trackedKey = tracker.keyFor(file);
+          const recordedHash = ownership.files?.[trackedKey]?.sha256;
+          if (!recordedHash || recordedHash !== sha256(fs.readFileSync(file))) {
+            throw new Error('Obsolete file is not proven unchanged');
+          }
+          trackedKeys.push(trackedKey);
+        };
+        inspect(targetPath);
+        assertNoSymlinkPath(targetPath);
+        const targetKey = tracker.keyFor(targetPath);
+        if (!ctx.dryRun) {
+          fs.rmSync(targetPath, { force: true, recursive: stat.isDirectory() });
+          for (const trackedKey of trackedKeys) tracker.prune(trackedKey);
+          if (stat.isDirectory()) {
+            tracker.prune(targetKey);
+            tracker.prunePrefix(`${targetKey}/`);
+          }
+        }
+        ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed obsolete ${key} runtime: ${relative}`);
+        ctx.results.updated++;
+      } catch {
+        preserved.add(targetPath);
       }
     }
-    ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed obsolete runtime: ${relPath}`);
-    ctx.results.updated++;
-  });
+  }
+  if (preserved.size) {
+    ctx.results.preserved = (ctx.results.preserved || 0) + preserved.size;
+    (ctx.results.preservedFiles ||= []).push(...preserved);
+  }
+  const allPreserved = (ctx.obsoleteRuntimePreserved ||= new Set());
+  for (const target of preserved) allPreserved.add(target);
+  const selected = (ctx.platforms || [platformKey]).filter(key => ['claude', 'codex', 'omp'].includes(key));
+  if (selected.every(key => completed.has(key)) && allPreserved.size) {
+    ctx.ui.warn(`Preserved ${allPreserved.size} obsolete runtime item(s); review and remove manually if no longer needed: ${[...allPreserved].join(', ')}`);
+  }
+}
+
+function removeObsoleteClaudeRuntimeFiles(ctx, platformKey) {
+  if (platformKey === 'claude') removeObsoleteRuntimeFiles(ctx, platformKey);
 }
 
 /** Remove renamed agents only when ownership manifest proves pristine bytes. */
@@ -258,7 +315,7 @@ function copyClaudeMdFile(ctx, platformKey) {
 }
 
 /** Copy the rules/ tree (ownership-aware; no longer force-overwrites). */
-function copyRulesDirectory(ctx, platformKey) {
+function copyRulesDirectory(ctx, platformKey, excludedNames = new Set()) {
   if (!hasPlatformCapability(platformKey, 'rules')) return;
 
   const src = path.join(SRC, 'claude/rules');
@@ -270,9 +327,19 @@ function copyRulesDirectory(ctx, platformKey) {
   }
 
   const transform = getCopyOptions(platformKey, {}).transform;
-  const agg = copyManagedTree({
+  const options = {
     src, dest, platformFolder: PLATFORMS[platformKey].folder, ctx, tracker: ctx.trackers[platformKey], transform
-  });
+  };
+  let agg;
+  if (excludedNames.size === 0) agg = copyManagedTree(options);
+  else {
+    agg = { created: 0, updated: 0, unchanged: 0, preserved: 0, missing: 0 };
+    for (const name of fs.readdirSync(src)) {
+      if (excludedNames.has(name)) continue;
+      const child = copyManagedTree({ ...options, sourceRoot: src, src: path.join(src, name), dest: path.join(dest, name) });
+      for (const key of Object.keys(agg)) agg[key] += child[key];
+    }
+  }
   report(ctx, treeAction(agg), 'rules/ directory');
 }
 
@@ -303,6 +370,7 @@ module.exports = {
   copyOutputStylesDirectory,
   copyClaudeRuntimeFiles,
   removeObsoleteClaudeRuntimeFiles,
+  removeObsoleteRuntimeFiles,
   copyClaudeMdFile,
   copyClaudeAgentsMdFile,
   ensureSharedAgentsMdCore,

package/bin/phases/claude-settings.js

@@ -12,6 +12,26 @@ const { PLATFORMS } = require('../lib/context');
 
 const SRC_CLAUDE = path.join(__dirname, '../../src/claude');
 
+const FORMER_MATCHERS = new Set([
+  'Read|Write|Edit|MultiEdit|Bash|Glob',
+  'Read|Write|Edit|MultiEdit|Bash|Glob|Grep',
+]);
+
+function refreshManagedMatchers(settings, template, ctx) {
+  if (!Array.isArray(settings.hooks?.PreToolUse)) return settings;
+  const targets = template.hooks?.PreToolUse || [];
+  const entries = settings.hooks.PreToolUse.map(entry => {
+    if (!FORMER_MATCHERS.has(entry?.matcher) || !Array.isArray(entry.hooks) || !entry.hooks.length) return entry;
+    const candidates = targets.filter(target =>
+      entry.hooks.every(hook => target.hooks.some(managed => managed.command === hook?.command)));
+    if (candidates.length !== 1) return entry;
+    ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Settings: hook PreToolUse matcher updated`);
+    ctx.results.updated++;
+    return { ...entry, matcher: candidates[0].matcher };
+  });
+  return { ...settings, hooks: { ...settings.hooks, PreToolUse: entries } };
+}
+
 /**
  * Remove obsolete hook entries from a settings object whose command matches any
  * manifest-listed substring (e.g. a retired router hook). Returns a possibly
@@ -97,7 +117,8 @@ function mergeClaudeSettings(ctx, platformKey) {
     }
   }
 
-  const mergedSettings = pruneObsoleteSettingsHooks({ ...existingSettings }, ctx);
+  const mergedSettings = refreshManagedMatchers(
+    pruneObsoleteSettingsHooks({ ...existingSettings }, ctx), managedSettings, ctx);
 
   // statusLine: adopt managed value if upgrading, missing, or CafeKit-owned.
   if (managedSettings.statusLine) {