@haposoft/cafekit 0.16.0-rc.8 → 0.16.1

package/bin/phases/codex-hooks.js

@@ -0,0 +1,156 @@
+/**
+ * Phase helper: Codex hooks.json merge.
+ *
+ * `.codex/hooks.json` is a shared configuration file, not a CafeKit payload. It was
+ * previously copied verbatim, which made a single user-added hook turn the whole file
+ * into a user-modified artifact: a normal install then preserved CafeKit's stale hooks,
+ * and `--force-overwrite` destroyed the user's. Merging per command removes that choice.
+ *
+ * This mirrors how `.claude/settings.json` is handled, so hooks.json likewise stays
+ * outside the ownership model: CafeKit owns its own entries, the user owns theirs, and
+ * neither erases the other. Honors dry-run.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { PLATFORMS } = require('../lib/context');
+
+const CODEX_SRC = path.join(__dirname, '../../src/codex');
+const WINDOWS_HOOK_COMMAND = /^node "\.codex\/hooks\/([a-z0-9-]+\.cjs)"$/;
+
+/** The hook script a command runs, which is stable across installs and platforms. */
+function hookScript(command) {
+  if (typeof command !== 'string') return null;
+  const match = command.match(/[/\\]hooks[/\\]([a-z0-9-]+\.cjs)/i);
+  return match ? match[1] : null;
+}
+
+/**
+ * Rewrite a managed `commandWindows` into a path-encoded invocation. Absolute Windows
+ * paths cannot be quoted safely inside the Codex command string, so the path travels
+ * base64url and is decoded by the launcher.
+ */
+function materializeWindowsCommand(handler, projectRoot) {
+  if (typeof handler.commandWindows !== 'string') return handler;
+  const match = handler.commandWindows.match(WINDOWS_HOOK_COMMAND);
+  if (!match) throw new Error(`Unsupported Codex Windows hook command: ${handler.commandWindows}`);
+  const hookPath = path.join(fs.realpathSync(projectRoot), '.codex', 'hooks', match[1]);
+  const encoded = Buffer.from(hookPath, 'utf8').toString('base64url');
+  return {
+    ...handler,
+    commandWindows: 'node -e "process.argv[1]=Buffer.from(process.argv[1],\'base64url\').toString(\'utf8\');require(\'module\').runMain()" ' + encoded,
+  };
+}
+
+/** Drop CafeKit hooks the manifest has retired, leaving foreign entries untouched. */
+function pruneObsoleteCodexHooks(config, ctx) {
+  const obsolete = ctx.manifest?.obsolete?.settingsHookCommandSubstrings || [];
+  if (!config.hooks || obsolete.length === 0) return { config, removed: 0 };
+
+  let removed = 0;
+  const pruned = {};
+  for (const [eventName, groups] of Object.entries(config.hooks)) {
+    if (!Array.isArray(groups)) { pruned[eventName] = groups; continue; }
+    const keptGroups = [];
+    for (const group of groups) {
+      if (!Array.isArray(group?.hooks)) { keptGroups.push(group); continue; }
+      const keptHooks = group.hooks.filter((handler) => {
+        const command = handler?.command || '';
+        const isObsolete = obsolete.some((substring) => command.includes(substring));
+        if (isObsolete) removed += 1;
+        return !isObsolete;
+      });
+      if (keptHooks.length > 0) keptGroups.push({ ...group, hooks: keptHooks });
+    }
+    if (keptGroups.length > 0) pruned[eventName] = keptGroups;
+  }
+  return { config: removed > 0 ? { ...config, hooks: pruned } : config, removed };
+}
+
+/**
+ * Merge CafeKit-managed Codex hooks into the project's hooks.json, preserving every
+ * entry CafeKit did not author. Codex only.
+ */
+function mergeCodexHooks(ctx, platformKey, projectRoot = process.cwd()) {
+  if (platformKey !== 'codex') return;
+
+  const templatePath = path.join(CODEX_SRC, 'hooks.json');
+  if (!fs.existsSync(templatePath)) {
+    ctx.ui.warn('Codex hooks template not found: src/codex/hooks.json');
+    return;
+  }
+  const managed = JSON.parse(fs.readFileSync(templatePath, 'utf8'));
+  const targetPath = path.join(PLATFORMS.codex.folder, 'hooks.json');
+
+  let existing = {};
+  if (fs.existsSync(targetPath)) {
+    // A malformed hooks.json must not abort the install and must never be
+    // overwritten blind: skip the merge and say why.
+    try {
+      existing = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+    } catch (error) {
+      ctx.ui.warn(`Codex hooks: ${targetPath} is not valid JSON (${error.message}). `
+        + 'Skipping the hooks merge — fix the file and re-run the installer.');
+      ctx.results.errors++;
+      return;
+    }
+  }
+
+  const { config: base, removed } = pruneObsoleteCodexHooks({ ...existing }, ctx);
+  if (removed > 0) {
+    ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Codex hooks: removed ${removed} obsolete hook(s)`);
+    ctx.results.updated++;
+  }
+
+  const merged = { ...base };
+  if (typeof managed.description === 'string' && typeof merged.description !== 'string') {
+    merged.description = managed.description;
+  }
+  merged.hooks = { ...(base.hooks || {}) };
+
+  let added = 0;
+  for (const [eventName, managedGroups] of Object.entries(managed.hooks || {})) {
+    const groups = Array.isArray(merged.hooks[eventName]) ? [...merged.hooks[eventName]] : [];
+    // A script already registered anywhere under this event stays where the user put
+    // it. Matching on the script rather than the whole command survives the path
+    // differences between installs and platforms.
+    const registered = new Set(
+      groups.flatMap((group) => (group?.hooks || []).map((handler) => hookScript(handler?.command))).filter(Boolean),
+    );
+
+    for (const managedGroup of managedGroups) {
+      const wanted = (managedGroup.hooks || [])
+        .filter((handler) => {
+          const script = hookScript(handler?.command);
+          return script && !registered.has(script);
+        })
+        .map((handler) => materializeWindowsCommand(handler, projectRoot));
+      if (wanted.length === 0) continue;
+
+      const matcher = managedGroup.matcher || '';
+      const target = groups.find((group) => (group?.matcher || '') === matcher && Array.isArray(group?.hooks));
+      if (target) {
+        target.hooks = [...target.hooks, ...wanted];
+      } else {
+        groups.push({ ...managedGroup, hooks: wanted });
+      }
+      for (const handler of wanted) registered.add(hookScript(handler.command));
+      added += wanted.length;
+      ctx.ui.detail(`  ✓ ${ctx.dryRun ? '[dry-run] ' : ''}Codex hooks: ${eventName} merged (+${wanted.length})`);
+    }
+
+    merged.hooks[eventName] = groups;
+  }
+
+  if (added === 0 && removed === 0) {
+    ctx.ui.detail(`  → ${ctx.dryRun ? '[dry-run] ' : ''}Codex hooks: already registered`);
+    ctx.results.unchanged++;
+  }
+
+  if (!ctx.dryRun) {
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8');
+  }
+}
+
+module.exports = { mergeCodexHooks, pruneObsoleteCodexHooks, hookScript };

package/bin/phases/codex-runtime.js

@@ -5,57 +5,32 @@ const path = require('path');
 const { PLATFORMS } = require('../lib/context');
 const { writeManagedFile, copyManagedTree } = require('../lib/managed-writer');
 const { report, treeAction } = require('./report');
-const { copyRulesDirectory } = require('./claude-runtime');
+const { copyRulesDirectory, copyOutputStylesDirectory } = require('./claude-runtime');
 const {
   managedRange,
   upsertManagedCodexBlock
 } = require('../lib/codex-install');
+const { mergeCodexHooks } = require('./codex-hooks');
 
 const SRC = path.join(__dirname, '../../src');
 const CODEX_SRC = path.join(SRC, 'codex');
 
+// hooks.json is merged by `codex-hooks.js`, not copied: it is a shared config file
+// the user also writes to, so a verbatim copy would either preserve CafeKit's stale
+// hooks or destroy the user's.
 const CODEX_OWN_RUNTIME = [
   ['gitignore', '.gitignore'],
-  ['runtime.json', 'runtime.json'],
-  ['hooks.json', 'hooks.json']
+  ['runtime.json', 'runtime.json']
 ];
 
-const WINDOWS_HOOK_COMMAND = /^node "\.codex\/hooks\/([a-z0-9-]+\.cjs)"$/;
-
-function materializeWindowsHookCommands(content, projectRoot = process.cwd()) {
-  const config = JSON.parse(content);
-  const canonicalRoot = fs.realpathSync(projectRoot);
-
-  for (const groups of Object.values(config.hooks || {})) {
-    for (const group of groups) {
-      for (const handler of group.hooks || []) {
-        if (typeof handler.commandWindows !== 'string') continue;
-        const match = handler.commandWindows.match(WINDOWS_HOOK_COMMAND);
-        if (!match) {
-          throw new Error(`Unsupported Codex Windows hook command: ${handler.commandWindows}`);
-        }
-        const hookPath = path.join(canonicalRoot, '.codex', 'hooks', match[1]);
-        const encodedPath = Buffer.from(hookPath, 'utf8').toString('base64url');
-        handler.commandWindows = (
-          'node -e "process.argv[1]=Buffer.from(process.argv[1],\'base64url\').toString(\'utf8\');require(\'module\').runMain()" ' +
-          encodedPath
-        );
-      }
-    }
-  }
-
-  return `${JSON.stringify(config, null, 2)}\n`;
-}
-
-function writeSourceFile(ctx, platformKey, src, dest, label, transform) {
+function writeSourceFile(ctx, platformKey, src, dest, label) {
   const platform = PLATFORMS[platformKey];
   const { action } = writeManagedFile({
     src,
     dest,
     platformFolder: platform.folder,
     ctx,
-    tracker: ctx.trackers[platformKey],
-    transform
+    tracker: ctx.trackers[platformKey]
   });
   report(ctx, action, label);
 }
@@ -68,10 +43,7 @@ function installRuntimeFiles(ctx, platformKey) {
       platformKey,
       path.join(CODEX_SRC, sourceRel),
       path.join(platform.folder, targetRel),
-      `Codex runtime: ${targetRel}`,
-      sourceRel === 'hooks.json'
-        ? (content) => materializeWindowsHookCommands(content, process.cwd())
-        : undefined
+      `Codex runtime: ${targetRel}`
     );
   }
   writeSourceFile(
@@ -82,6 +54,8 @@ function installRuntimeFiles(ctx, platformKey) {
     'Codex skills: .agents/.gitignore'
   );
 
+  mergeCodexHooks(ctx, platformKey);
+
   const agg = copyManagedTree({
     src: path.join(CODEX_SRC, 'hooks'),
     dest: path.join(platform.folder, 'hooks'),
@@ -92,6 +66,15 @@ function installRuntimeFiles(ctx, platformKey) {
   report(ctx, treeAction(agg), 'Codex native hooks');
   // Keep one canonical command analyzer in the Claude source tree, then
   // materialize the same bytes into the installed Codex runtime.
+  // One canonical runtime schema lives in the Claude source tree; both installed
+  // runtimes reference it as ./runtime.schema.json beside their runtime.json.
+  writeSourceFile(
+    ctx,
+    platformKey,
+    path.join(SRC, 'claude', 'runtime.schema.json'),
+    path.join(platform.folder, 'runtime.schema.json'),
+    'Codex runtime schema'
+  );
   writeSourceFile(
     ctx,
     platformKey,
@@ -99,6 +82,13 @@ function installRuntimeFiles(ctx, platformKey) {
     path.join(platform.folder, 'hooks', 'lib', 'privacy-command-analysis.cjs'),
     'Codex privacy command analyzer'
   );
+  writeSourceFile(
+    ctx,
+    platformKey,
+    path.join(SRC, 'claude', 'hooks', 'lib', 'secret-keywords.cjs'),
+    path.join(platform.folder, 'hooks', 'lib', 'secret-keywords.cjs'),
+    'Codex secret keyword matcher'
+  );
   writeSourceFile(
     ctx,
     platformKey,
@@ -154,9 +144,10 @@ function installCodexRuntime(ctx, platformKey) {
   if (platformKey !== 'codex') return ctx;
   installRuntimeFiles(ctx, platformKey);
   copyRulesDirectory(ctx, platformKey);
+  copyOutputStylesDirectory(ctx, platformKey);
   installNativeRuleOverrides(ctx, platformKey);
   installManagedAgentsMd(ctx);
   return ctx;
 }
 
-module.exports = { installCodexRuntime, materializeWindowsHookCommands };
+module.exports = { installCodexRuntime };

package/bin/phases/copy-payload.js

@@ -127,12 +127,18 @@ function copyPlatformFiles(ctx, platformKey) {
       });
     }
 
-    // Additional required skills.
+    // Core skills plus the optional document bundle selected for this runtime.
     let requiredSkills = [];
     if (hasPlatformCapability(platformKey, 'skills')) {
       requiredSkills = ctx.manifest?.skills?.required || [];
+      if (ctx.documentSkills?.[platformKey]?.enabled) {
+        requiredSkills = [
+          ...requiredSkills,
+          ...(ctx.manifest?.skills?.bundles?.documentSkills || [])
+        ];
+      }
     }
-    requiredSkills
+    [...new Set(requiredSkills)]
       .filter((skillName) => skillName !== 'specs')
       .forEach((skillName) => {
         const skillSource = path.join(skillsSourceDir, skillName);
@@ -183,7 +189,14 @@ function copyPlatformFiles(ctx, platformKey) {
     } else {
       report(ctx, 'missing', `agents: ${platform.agentsDir}`);
     }
+  }
 
+  // ── Scripts ─────────────────────────────────────────────
+  // Gated on its own capability. This block used to sit inside the agents guard,
+  // so a platform with agents: false and scripts: true (omp) never received
+  // .omp/scripts/, and every Stop-time gate that requires ../scripts/*.cjs answered
+  // "Completion gate unavailable" on each session_stop.
+  if (hasPlatformCapability(platformKey, 'scripts')) {
     const scriptsSourceDir = path.join(SRC, 'claude/scripts');
     if (fs.existsSync(scriptsSourceDir)) {
       const scriptsDest = getRuntimeSupportTargetDir(platformKey, 'scripts');

package/bin/phases/omp-runtime.js

@@ -0,0 +1,140 @@
+'use strict';
+
+/**
+ * Phase: Oh My Pi runtime.
+ *
+ * omp discovers `.claude/skills` and `.agents/skills` on its own, so CafeKit copies no
+ * skill payload here. What omp does not have is CafeKit's enforcement chain, so this
+ * phase provisions what carries it:
+ *
+ *   .omp/hooks/           the gate scripts: the Claude set, with omp's overlay on top
+ *   .omp/extensions/      the bridge omp auto-loads, which dispatches those scripts
+ *   .omp/runtime.json     the hooks' configuration, beside the schema that describes it
+ *   .omp/rules/           the rules the hooks inject
+ *
+ * The hooks are portable: they derive their runtime directory from their own location,
+ * so the Claude bytes run unchanged under `.omp/`. Only the files that genuinely differ
+ * for omp live in `src/omp/hooks/` and are written over the Claude set afterwards, so a
+ * change to a shared hook reaches omp without anyone remembering to re-fork it.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { PLATFORMS } = require('../lib/context');
+const { writeManagedFile, copyManagedTree } = require('../lib/managed-writer');
+const { report, treeAction } = require('./report');
+const { copyRulesDirectory } = require('./claude-runtime');
+
+const SRC = path.join(__dirname, '../../src');
+const CLAUDE_SRC = path.join(SRC, 'claude');
+const OMP_SRC = path.join(SRC, 'omp');
+
+/** Files under `src/omp/hooks/` that replace their Claude counterpart, relative to the hooks dir. */
+function overlayFiles(dir = path.join(OMP_SRC, 'hooks'), prefix = '') {
+  if (!fs.existsSync(dir)) return [];
+  const found = [];
+  for (const name of fs.readdirSync(dir)) {
+    const rel = prefix ? `${prefix}/${name}` : name;
+    if (fs.statSync(path.join(dir, name)).isDirectory()) found.push(...overlayFiles(path.join(dir, name), rel));
+    else found.push(rel);
+  }
+  return found.sort();
+}
+
+/**
+ * The Claude hook set is the list the migration manifest ships to `.claude/`, not a
+ * directory walk: the source tree also holds `__tests__/`, which must never install.
+ */
+function claudeHookFiles(ctx) {
+  const files = ctx.manifest?.runtime?.files || [];
+  return files.filter((rel) => rel.startsWith('hooks/')).map((rel) => rel.slice('hooks/'.length));
+}
+
+function writeSourceFile(ctx, platformKey, src, dest, label) {
+  const platform = PLATFORMS[platformKey];
+  const { action } = writeManagedFile({
+    src,
+    dest,
+    platformFolder: platform.folder,
+    ctx,
+    tracker: ctx.trackers[platformKey]
+  });
+  report(ctx, action, label);
+}
+
+function installHooks(ctx, platformKey) {
+  const platform = PLATFORMS[platformKey];
+  const overlay = new Set(overlayFiles());
+  // Claude set first, skipping anything the overlay is about to replace so a file is
+  // written once and the manifest records the bytes that actually land.
+  for (const rel of claudeHookFiles(ctx)) {
+    if (overlay.has(rel)) continue;
+    writeSourceFile(
+      ctx,
+      platformKey,
+      path.join(CLAUDE_SRC, 'hooks', rel),
+      path.join(platform.folder, 'hooks', rel),
+      `omp hooks: ${rel}`
+    );
+  }
+  for (const rel of overlay) {
+    writeSourceFile(
+      ctx,
+      platformKey,
+      path.join(OMP_SRC, 'hooks', rel),
+      path.join(platform.folder, 'hooks', rel),
+      `omp hooks (overlay): ${rel}`
+    );
+  }
+}
+
+function installRuntimeFiles(ctx, platformKey) {
+  const platform = PLATFORMS[platformKey];
+  writeSourceFile(
+    ctx,
+    platformKey,
+    path.join(OMP_SRC, 'runtime.json'),
+    path.join(platform.folder, 'runtime.json'),
+    'omp runtime: runtime.json'
+  );
+  // One canonical runtime schema lives in the Claude source tree; every installed
+  // runtime references it as ./runtime.schema.json beside its runtime.json.
+  writeSourceFile(
+    ctx,
+    platformKey,
+    path.join(CLAUDE_SRC, 'runtime.schema.json'),
+    path.join(platform.folder, 'runtime.schema.json'),
+    'omp runtime schema'
+  );
+}
+
+function installBridge(ctx, platformKey) {
+  const platform = PLATFORMS[platformKey];
+  const bridgeSource = path.join(OMP_SRC, 'extensions');
+  const bridgeDest = path.join(platform.folder, 'extensions');
+  if (fs.existsSync(bridgeSource)) {
+    const bridge = copyManagedTree({
+      src: bridgeSource,
+      dest: bridgeDest,
+      platformFolder: platform.folder,
+      ctx,
+      tracker: ctx.trackers[platformKey]
+    });
+    report(ctx, treeAction(bridge), 'omp bridge extension');
+  } else if (!ctx.dryRun) {
+    // A half-provisioned install is visibly empty rather than silently absent.
+    fs.mkdirSync(bridgeDest, { recursive: true });
+    ctx.ui.detail('  ✓ omp extensions directory created (bridge not present)');
+  }
+}
+
+function installOmpRuntime(ctx, platformKey) {
+  if (platformKey !== 'omp') return;
+  installHooks(ctx, platformKey);
+  installRuntimeFiles(ctx, platformKey);
+  installBridge(ctx, platformKey);
+  copyRulesDirectory(ctx, platformKey);
+  return ctx;
+}
+
+module.exports = { installOmpRuntime, overlayFiles, claudeHookFiles };

package/bin/phases/root-config.js

@@ -110,6 +110,9 @@ function ensureGitignore(ctx) {
     // Local runtime payload — reinstall with npx; keep out of git
     '.claude/',
     '.codex/',
+    // omp auto-executes every file in .omp/extensions/, so a committed copy
+    // would run arbitrary code on clone. Keep it out of git like the rest.
+    '.omp/',
     '.agents/'
   ];
   const prefix = ctx.dryRun ? '[dry-run] ' : '';

package/bin/phases/select-platform.js

@@ -11,7 +11,8 @@ const path = require('path');
 const {
   PLATFORMS,
   detectPlatforms,
-  getPlatformKeys
+  getPlatformKeys,
+  resolvePlatformAliases
 } = require('../lib/context');
 const { SUPPORTED, LANGUAGE_LABELS, OTHER_LABEL } = require('../lib/i18n');
 
@@ -36,7 +37,25 @@ function getInstalledLocale(platformKeys = getPlatformKeys()) {
 }
 
 /** First step: pick the installer/UI language (interactive only). */
+/**
+ * Resolve host aliases on the requested platform list, once, before anything reads it.
+ *
+ * selectLanguage() filters this list through PLATFORMS to decide which installed runtime
+ * to take a saved locale from, so an unresolved alias would empty that list and fall back
+ * to scanning every platform folder — `--platform grok` in a project that also has
+ * `.codex/` would then silently take Codex's language.
+ */
+function applyPlatformAliases(ctx) {
+  const requested = ctx.options.platforms || [];
+  if (requested.length === 0) return ctx;
+  const { platforms, aliased } = resolvePlatformAliases(requested);
+  ctx.options.platforms = platforms;
+  ctx.aliasedHost = aliased;
+  return ctx;
+}
+
 async function selectLanguage(ctx) {
+  applyPlatformAliases(ctx);
   // Restore the saved locale BEFORE the interactivity check: a non-interactive
   // upgrade (--yes) must not forget the configured language. Skipping this left
   // ctx at the 'en' default, and patchRuntimeLocale then clobbered the user's
@@ -161,6 +180,7 @@ async function resolvePlatforms(ctx) {
     ctx.ui.info(ctx.t('installingFor', {
       names: platformNames(requested)
     }));
+    if (ctx.aliasedHost) ctx.ui.info(ctx.t('grokCompatNotice'));
     reportInstallMode(ctx);
     return ctx;
   }
@@ -244,6 +264,7 @@ function getInstalledPlatform() {
 
 module.exports = {
   selectLanguage,
+  applyPlatformAliases,
   promptPlatformSelection,
   resolvePlatforms,
   getInstalledPlatform,

package/bin/phases/select-skill-bundles.js

@@ -0,0 +1,96 @@
+/** Resolve the optional document-skills bundle for each selected runtime. */
+
+const fs = require('fs');
+const path = require('path');
+const { PLATFORMS } = require('../lib/context');
+
+function readMetadata(platformKey) {
+  const target = path.join(PLATFORMS[platformKey].folder, 'cafekit.json');
+  if (!fs.existsSync(target)) return { state: 'absent', target, metadata: null };
+  try {
+    const metadata = JSON.parse(fs.readFileSync(target, 'utf8'));
+    if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+      return { state: 'invalid', target, metadata: null, reason: 'expected a JSON object' };
+    }
+    return { state: 'valid', target, metadata };
+  } catch (error) {
+    return { state: 'invalid', target, metadata: null, reason: error.message };
+  }
+}
+
+function explicitSelection(options) {
+  if (options.withDocumentSkills) {
+    return { enabled: true, selectionSource: 'cli-opt-in' };
+  }
+  if (options.withoutDocumentSkills) {
+    return { enabled: false, selectionSource: 'cli-opt-out' };
+  }
+  return null;
+}
+
+async function selectDocumentSkills(ctx) {
+  const explicit = explicitSelection(ctx.options);
+  const unresolvedFresh = [];
+
+  for (const platformKey of ctx.platforms) {
+    if (explicit) {
+      ctx.documentSkills[platformKey] = { ...explicit };
+      continue;
+    }
+
+    const metadataResult = readMetadata(platformKey);
+    const metadata = metadataResult.metadata;
+    if (metadata?.schemaVersion >= 2 && typeof metadata.documentSkills?.enabled === 'boolean') {
+      ctx.documentSkills[platformKey] = {
+        enabled: metadata.documentSkills.enabled,
+        selectionSource: metadata.documentSkills.selectionSource || 'persisted'
+      };
+    } else if (metadataResult.state === 'valid') {
+      ctx.documentSkills[platformKey] = {
+        enabled: true,
+        selectionSource: 'legacy-upgrade'
+      };
+    } else if (metadataResult.state === 'invalid') {
+      ctx.documentSkills[platformKey] = {
+        enabled: true,
+        selectionSource: 'metadata-recovery'
+      };
+      ctx.ui.warn(ctx.t('documentSkillsMetadataRecovery', {
+        path: metadataResult.target
+      }));
+    } else if (fs.existsSync(path.join(PLATFORMS[platformKey].folder, 'cafekit-manifest.json'))) {
+      ctx.documentSkills[platformKey] = {
+        enabled: true,
+        selectionSource: 'legacy-upgrade'
+      };
+    } else {
+      unresolvedFresh.push(platformKey);
+    }
+  }
+
+  let freshEnabled = false;
+  let source = 'default-fresh';
+  if (unresolvedFresh.length > 0 && ctx.interactive) {
+    const answer = await ctx.ui.confirm(
+      { message: ctx.t('documentSkillsConfirm'), initialValue: false },
+      false
+    );
+    if (ctx.ui.isCancel(answer)) {
+      ctx.cancelled = true;
+      return ctx;
+    }
+    freshEnabled = Boolean(answer);
+    source = 'interactive';
+  }
+
+  for (const platformKey of unresolvedFresh) {
+    ctx.documentSkills[platformKey] = {
+      enabled: freshEnabled,
+      selectionSource: source
+    };
+  }
+
+  return ctx;
+}
+
+module.exports = { readMetadata, explicitSelection, selectDocumentSkills };

package/bin/phases/skill-inventory.js

@@ -0,0 +1,71 @@
+/** Ownership-aware removal for retired and deselected skill directories. */
+
+const fs = require('fs');
+const path = require('path');
+const { PLATFORMS } = require('../lib/context');
+const { hashFile } = require('../lib/manifest');
+
+function listTreeEntries(root) {
+  const entries = [];
+  const visit = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const target = path.join(current, entry.name);
+      entries.push({ target, entry });
+      if (entry.isDirectory() && !entry.isSymbolicLink()) visit(target);
+    }
+  };
+  visit(root);
+  return entries;
+}
+
+function classifySkillTree(ctx, platformKey, skillName) {
+  const platform = PLATFORMS[platformKey];
+  const tracker = ctx.trackers[platformKey];
+  const target = path.join(platform.skillsDir, skillName);
+  if (!fs.existsSync(target)) return { target, removable: false, absent: true };
+  if (!fs.lstatSync(target).isDirectory()) {
+    return { target, removable: false, absent: false };
+  }
+
+  const entries = listTreeEntries(target);
+  const ownership = ctx.ownership?.[platform.folder]?.files || {};
+  const unsafe = entries.some(({ target: item, entry }) => {
+    if (!entry.isFile() || entry.isSymbolicLink()) return !entry.isDirectory();
+    const key = tracker.keyFor(item);
+    return ownership[key]?.sha256 !== hashFile(item);
+  });
+  return { target, removable: entries.length > 0 && !unsafe, absent: false };
+}
+
+function removeSkill(ctx, platformKey, skillName) {
+  const tracker = ctx.trackers[platformKey];
+  const classified = classifySkillTree(ctx, platformKey, skillName);
+  if (classified.absent) return;
+
+  if (!classified.removable) {
+    ctx.ui.warn(`Preserved user-owned skill: ${classified.target}`);
+    ctx.results.preserved++;
+    ctx.results.preservedFiles.push(classified.target);
+    return;
+  }
+
+  const prefix = `${tracker.keyFor(classified.target).replace(/\/$/, '')}/`;
+  if (!ctx.dryRun) {
+    fs.rmSync(classified.target, { recursive: true, force: true });
+    tracker.prunePrefix(prefix);
+  }
+  ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed skill: ${classified.target}`);
+  ctx.results.updated++;
+}
+
+function reconcileSkillInventory(ctx, platformKey) {
+  const retired = ctx.manifest?.obsolete?.skills || [];
+  for (const skillName of retired) removeSkill(ctx, platformKey, skillName);
+
+  if (!ctx.documentSkills?.[platformKey]?.enabled) {
+    const optional = ctx.manifest?.skills?.bundles?.documentSkills || [];
+    for (const skillName of optional) removeSkill(ctx, platformKey, skillName);
+  }
+}
+
+module.exports = { listTreeEntries, classifySkillTree, removeSkill, reconcileSkillInventory };