@cuewright/skills 0.1.1 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuewright/skills",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "CLI installer for the Cuewright skills framework",
   "type": "module",
   "engines": {

package/src/commands/doctor.js

@@ -1,8 +1,9 @@
 import chalk from 'chalk';
-import { access, readFile, lstat } from 'fs/promises';
+import { access, readFile, lstat } from 'fs/promises'; // lstat used in checks 3-4
 import { join } from 'path';
 import { cwd } from 'process';
 import { readManifest, listSkills, getVersion } from '../utils/manifest.js';
+import { inventorySkillsDir } from '../utils/symlink.js';
 import { getSkillsDir, getFrameworkDir } from '../adapters/claude.js';
 
 export async function doctor() {
@@ -63,7 +64,7 @@ export async function doctor() {
   }
 
   if (brokenLinks.length === 0) {
-    checks.push(pass(`${wiredCount}/${skills.length} skills wired`));
+    checks.push(pass(`${wiredCount}/${skills.length} skills wired (cw- prefix)`));
   } else {
     allPassed = false;
     checks.push(fail(
@@ -75,6 +76,29 @@ export async function doctor() {
     }
   }
 
+  // 4b. Inventory skills directory — detect legacy and orphaned entries
+  const { legacy: legacyFound, orphaned: orphanedFound } = await inventorySkillsDir(skillsDir, skills);
+
+  if (legacyFound.length > 0) {
+    allPassed = false;
+    checks.push(fail(
+      `${legacyFound.length} legacy skill director${legacyFound.length === 1 ? 'y' : 'ies'} found (pre-v0.15.0 install)`,
+      'Run `cuewright update` to clean up automatically.'
+    ));
+    for (const name of legacyFound) {
+      checks.push(fail(`  .claude/skills/${name}/`, null));
+    }
+  }
+
+  if (orphanedFound.length > 0) {
+    checks.push(warn(
+      `${orphanedFound.length} unknown director${orphanedFound.length === 1 ? 'y' : 'ies'} in .claude/skills/ (third-party or project-local — no action needed)`
+    ));
+    for (const name of orphanedFound) {
+      checks.push(warn(`  .claude/skills/${name}/`));
+    }
+  }
+
   // 5. arch/project-config.md exists
   const configPath = join(projectRoot, '.claude', 'skills', 'arch', 'project-config.md');
   if (!await exists(configPath)) {
@@ -107,6 +131,14 @@ export async function doctor() {
     }
   }
 
+  // 6b. arch/references/ exists
+  const referencesDir = join(projectRoot, '.claude', 'skills', 'arch', 'references');
+  if (!await exists(referencesDir)) {
+    checks.push(warn('arch/references/ not found — skill reference files have no home. Run `cuewright update` to scaffold it.'));
+  } else {
+    checks.push(pass('arch/references/ found'));
+  }
+
   // 7. Baseline compatibility check (if baseline present)
   const baselineDir = join(projectRoot, '.claude', 'skills', '_baseline');
   if (await exists(baselineDir)) {

package/src/commands/init.js

@@ -4,7 +4,7 @@ import { join } from 'path';
 import { cwd } from 'process';
 import { readManifest, listSkills, getVersion } from '../utils/manifest.js';
 import { syncSymlinks, syncCopies, platformSupportsSymlinks } from '../utils/symlink.js';
-import { addSubmodule } from '../storage/submodule.js';
+import { addSubmodule, configureSparseCheckout } from '../storage/submodule.js';
 import { cloneFramework } from '../storage/copy.js';
 import { getSkillsDir, getFrameworkDir, getSubmodulePath } from '../adapters/claude.js';
 
@@ -76,6 +76,7 @@ async function freshInstall(projectRoot, frameworkDir, skillsDir, options) {
   if (useSubmodule) {
     console.log('Adding git submodule...');
     await addSubmodule(projectRoot, getSubmodulePath(), tag);
+    await configureSparseCheckout(frameworkDir);
   } else {
     console.log('Cloning framework (copy mode)...');
     await cloneFramework(frameworkDir, tag);
@@ -96,6 +97,7 @@ async function freshInstall(projectRoot, frameworkDir, skillsDir, options) {
   }
 
   await scaffoldConfigIfMissing(projectRoot, frameworkDir);
+  await scaffoldArchDirectories(projectRoot);
 
   console.log(chalk.green(`\nDone.`));
   console.log(`  Framework:  v${version}`);
@@ -127,6 +129,18 @@ async function scaffoldConfigIfMissing(projectRoot, frameworkDir) {
   console.log('  Scaffolded arch/project-config.md');
 }
 
+/**
+ * Scaffold arch/references/ and arch/templates/ subdirectories if they don't exist.
+ * These are the project customization roots under the cw- prefix model.
+ */
+async function scaffoldArchDirectories(projectRoot) {
+  const archDir = join(projectRoot, '.claude', 'skills', 'arch');
+  await mkdir(join(archDir, 'references'), { recursive: true });
+  await mkdir(join(archDir, 'templates', 'page'), { recursive: true });
+  await mkdir(join(archDir, 'templates', 'component'), { recursive: true });
+  await mkdir(join(archDir, 'templates', 'guide'), { recursive: true });
+}
+
 async function exists(path) {
   try {
     await access(path);

package/src/commands/update.js

@@ -1,12 +1,13 @@
 import chalk from 'chalk';
-import { access, readFile, unlink } from 'fs/promises';
+import { access, readFile, unlink, mkdir } from 'fs/promises';
 import { join } from 'path';
 import { cwd } from 'process';
 import { readManifest, listSkills, getVersion } from '../utils/manifest.js';
-import { syncSymlinks, syncCopies, platformSupportsSymlinks, buildHeader } from '../utils/symlink.js';
-import { updateSubmodule, getLatestTag } from '../storage/submodule.js';
+import { syncSymlinks, syncCopies, platformSupportsSymlinks, cleanupLegacyDirectories } from '../utils/symlink.js';
+import { updateSubmodule, fetchTags, getLatestTag, getLatestTagFromRemote, configureSparseCheckout } from '../storage/submodule.js';
 import { cloneFramework } from '../storage/copy.js';
 import { getSkillsDir, getFrameworkDir } from '../adapters/claude.js';
+import { updateProjectConfigVersion } from '../utils/project-config.js';
 import simpleGit from 'simple-git';
 
 export async function update(options) {
@@ -29,11 +30,21 @@ export async function update(options) {
   const isSubmodule = await exists(join(projectRoot, '.gitmodules'))
     && await isSubmoduleInstall(projectRoot, frameworkDir);
 
+  // Fetch remote tags before resolving latest — ensures local tag list is current
+  if (isSubmodule && !options.to) {
+    try {
+      await fetchTags(frameworkDir);
+    } catch {
+      // Non-fatal — fallback to remote query below
+    }
+  }
+
   // Determine target version — always bare (no leading v)
-  const targetVersion = ((options.to || await resolveLatestTag(frameworkDir))).replace(/^v/, '');
+  const targetVersion = (options.to || await resolveLatestTag(frameworkDir, isSubmodule)).replace(/^v/, '');
 
   if (targetVersion === oldVersion) {
-    console.log(chalk.cyan(`Already at v${oldVersion} (latest). Nothing to update.`));
+    console.log(chalk.cyan(`Already at v${oldVersion} (latest).`));
+    await runCleanup(skillsDir, listSkills(oldManifest), projectRoot, dryRun);
     return;
   }
 
@@ -46,6 +57,7 @@ export async function update(options) {
   if (!dryRun) {
     if (isSubmodule) {
       await updateSubmodule(projectRoot, '.claude/skills/_framework', targetVersion);
+      await configureSparseCheckout(frameworkDir);
     } else {
       await cloneFramework(frameworkDir, targetVersion);
     }
@@ -63,11 +75,10 @@ export async function update(options) {
     console.log(`New skills: ${added.join(', ')}`);
     if (!dryRun) {
       const useCopies = !platformSupportsSymlinks();
-      if (useCopies) {
-        await syncCopies(frameworkDir, skillsDir, added, targetVersion);
-      } else {
-        await syncSymlinks(frameworkDir, skillsDir, added);
-      }
+      const { errors: syncErrors } = useCopies
+        ? await syncCopies(frameworkDir, skillsDir, added, targetVersion)
+        : await syncSymlinks(frameworkDir, skillsDir, added);
+      for (const e of syncErrors) console.log(chalk.yellow(`  warning: ${e}`));
     }
   }
 
@@ -75,20 +86,32 @@ export async function update(options) {
     for (const name of removed) {
       const skillPath = join(skillsDir, name);
       if (await exists(skillPath)) {
-        const isOverride = await isRealDirectory(skillPath);
-        if (isOverride) {
-          console.log(chalk.yellow(`  warning: skill '${name}' was removed from the framework but you have a local override at .claude/skills/${name}/. It has been left in place.`));
-        } else {
-          // It's a symlink to a now-missing target — clean it up
+        const isRealDir = await isRealDirectory(skillPath);
+        if (!isRealDir) {
+          // Symlink to now-missing target — clean it up
           if (!dryRun) {
             await unlink(skillPath);
           }
-          console.log(`  Removed broken symlink: ${name}`);
+          console.log(`  Removed stale symlink: ${name}`);
+        } else {
+          console.log(chalk.yellow(`  warning: '${name}' removed from framework. Local directory at .claude/skills/${name}/ left in place.`));
         }
       }
     }
   }
 
+  // Always run legacy cleanup — catches dirs that survived the diff-based migration
+  await runCleanup(skillsDir, [...newSkills], projectRoot, dryRun);
+
+  // Scaffold arch/references/ and arch/templates/ if missing
+  if (!dryRun) {
+    const archDir = join(projectRoot, '.claude', 'skills', 'arch');
+    await mkdir(join(archDir, 'references'), { recursive: true });
+    await mkdir(join(archDir, 'templates', 'page'), { recursive: true });
+    await mkdir(join(archDir, 'templates', 'component'), { recursive: true });
+    await mkdir(join(archDir, 'templates', 'guide'), { recursive: true });
+  }
+
   // Print changelog for the updated range
   const changelogPath = join(frameworkDir, 'CHANGELOG.md');
   if (await exists(changelogPath)) {
@@ -100,6 +123,12 @@ export async function update(options) {
     }
   }
 
+  // Update version in project-config.md
+  if (!dryRun) {
+    const configPath = join(projectRoot, '.claude', 'skills', 'arch', 'project-config.md');
+    await updateProjectConfigVersion(configPath, targetVersion);
+  }
+
   if (!dryRun) {
     console.log(chalk.green(`\nUpdated to v${targetVersion}.`));
   } else {
@@ -107,15 +136,28 @@ export async function update(options) {
   }
 }
 
+async function runCleanup(skillsDir, manifestSkillNames, projectRoot, dryRun) {
+  const { cleaned, errors } = await cleanupLegacyDirectories(skillsDir, manifestSkillNames, projectRoot, { dryRun });
+  if (cleaned.length > 0) {
+    console.log(chalk.green(`  Cleaned up ${cleaned.length} legacy director${cleaned.length === 1 ? 'y' : 'ies'}: ${cleaned.join(', ')}`));
+  }
+  for (const e of errors) console.log(chalk.yellow(`  warning: ${e}`));
+}
+
 /**
- * Resolve the latest semver tag from the installed framework's git history.
+ * Resolve the latest semver tag from the installed framework.
  */
-async function resolveLatestTag(frameworkDir) {
+async function resolveLatestTag(frameworkDir, isSubmodule) {
   try {
     const git = simpleGit(frameworkDir);
     return await getLatestTag(git);
   } catch {
-    throw new Error('Could not determine latest framework version. Use --to <version> to specify one.');
+    // Shallow clone or no local tags — query remote directly
+    try {
+      return await getLatestTagFromRemote();
+    } catch {
+      throw new Error('Could not determine latest framework version. Use --to <version> to specify one.');
+    }
   }
 }
 

package/src/storage/copy.js

@@ -14,5 +14,6 @@ export async function cloneFramework(targetDir, tag) {
   await mkdir(targetDir, { recursive: true });
 
   const git = simpleGit();
-  await git.clone(FRAMEWORK_REPO, targetDir, ['--depth', '1', ...(tag ? ['--branch', tag] : [])]);
+  const gitTag = tag ? (tag.startsWith('v') ? tag : `v${tag}`) : undefined;
+  await git.clone(FRAMEWORK_REPO, targetDir, ['--depth', '1', ...(gitTag ? ['--branch', gitTag] : [])]);
 }

package/src/storage/submodule.js

@@ -5,7 +5,7 @@ const FRAMEWORK_REPO = 'https://github.com/scriswell/cuewright';
 /**
  * Add the framework as a git submodule.
  * If tag is provided, checks out that tag after adding.
- * Tag may be bare (0.14.33) or prefixed (v0.14.33) — normalized internally.
+ * Tag may be bare (0.15.0) or prefixed (v0.15.0) — normalized internally.
  */
 export async function addSubmodule(projectRoot, submodulePath, tag) {
   const git = simpleGit(projectRoot);
@@ -23,20 +23,27 @@ export async function addSubmodule(projectRoot, submodulePath, tag) {
 
 /**
  * Update an existing submodule to a specific tag (or latest if no tag given).
- * "Latest" means the most recent semver tag on the remote.
+ * Caller is responsible for fetching tags before calling this.
  */
 export async function updateSubmodule(projectRoot, submodulePath, tag) {
   const subGit = simpleGit(`${projectRoot}/${submodulePath}`);
-
-  await subGit.fetch(['--tags']);
-
   const gitTag = tag ? toGitTag(tag) : toGitTag(await getLatestTag(subGit));
   await subGit.checkout(gitTag);
 }
 
+/**
+ * Fetch all tags from the remote into the submodule's local repo.
+ * Call this before resolveLatestTag to ensure local tags are current.
+ */
+export async function fetchTags(frameworkDir) {
+  const git = simpleGit(frameworkDir);
+  await git.fetch(['--tags']);
+}
+
 /**
  * Return the latest semver tag as a bare version string (no leading v).
- * e.g. "0.14.33" not "v0.14.33"
+ * e.g. "0.15.0" not "v0.15.0"
+ * Uses local tags — call fetchTags() first if stale.
  */
 export async function getLatestTag(git) {
   const result = await git.tags(['--sort=-version:refname']);
@@ -47,9 +54,42 @@ export async function getLatestTag(git) {
   return semverTags[0].replace(/^v/, '');
 }
 
+/**
+ * Resolve the latest semver tag directly from the remote.
+ * Fallback for copy-mode installs where local tags are unavailable.
+ */
+export async function getLatestTagFromRemote() {
+  const git = simpleGit();
+  const result = await git.listRemote(['--tags', '--sort=-version:refname', FRAMEWORK_REPO]);
+  const tags = result.split('\n')
+    .map(line => line.match(/refs\/tags\/(v\d+\.\d+\.\d+)$/))
+    .filter(Boolean)
+    .map(m => m[1]);
+  if (tags.length === 0) throw new Error('No semver tags found on remote');
+  return tags[0].replace(/^v/, '');
+}
+
+/**
+ * Configure sparse checkout on a submodule to include only the directories
+ * that consuming projects need: skills/, targets/, core/, plus key root files.
+ * Excludes docs/, .github/, CHANGELOG.md, etc.
+ */
+export async function configureSparseCheckout(submoduleAbsPath) {
+  const git = simpleGit(submoduleAbsPath);
+  await git.raw(['sparse-checkout', 'init', '--no-cone']);
+  await git.raw(['sparse-checkout', 'set',
+    'skills/',
+    'targets/',
+    'core/',
+    'manifest.json',
+    'LICENSE',
+    'README.md',
+  ]);
+}
+
 /**
  * Normalize a version string to a git tag with v prefix.
- * "0.14.33" → "v0.14.33", "v0.14.33" → "v0.14.33"
+ * "0.15.0" → "v0.15.0", "v0.15.0" → "v0.15.0"
  */
 function toGitTag(version) {
   return version.startsWith('v') ? version : `v${version}`;

package/src/utils/project-config.js

@@ -0,0 +1,25 @@
+import { readFile, writeFile, access } from 'fs/promises';
+
+/**
+ * Update the Framework Version line in arch/project-config.md.
+ * Looks for a markdown table row like: | Framework Version | v0.8.0 |
+ * Updates the version value in place. No-ops if the file doesn't exist
+ * or doesn't contain a recognizable version line.
+ */
+export async function updateProjectConfigVersion(configPath, newVersion) {
+  try {
+    await access(configPath);
+  } catch {
+    return; // No project-config — nothing to update
+  }
+
+  const content = await readFile(configPath, 'utf8');
+  const updated = content.replace(
+    /^(\|\s*(?:Framework\s+Version|framework_version)\s*\|\s*)v?\d+\.\d+\.\d+(\s*\|)/im,
+    `$1v${newVersion}$2`
+  );
+
+  if (updated !== content) {
+    await writeFile(configPath, updated, 'utf8');
+  }
+}

package/src/utils/symlink.js

@@ -1,15 +1,13 @@
-import { symlink, mkdir, access, lstat, readFile, writeFile } from 'fs/promises';
+import { symlink, mkdir, access, lstat, readFile, writeFile, readdir, unlink, rename } from 'fs/promises';
 import { join } from 'path';
 
 /**
  * Ensure all skills in the manifest are wired into the skills discovery dir
  * using directory symlinks.
  *
- * For each skill name:
- *   - If a real directory already exists at <skillsDir>/<name>: skip (override preserved).
- *   - If a valid symlink already exists: skip.
- *   - If a broken symlink exists: re-create it.
- *   - Otherwise: create a directory symlink pointing to <frameworkDir>/skills/<name>.
+ * Framework skills use the cw- prefix and are always symlinks — no local
+ * directory overrides. If a real directory is found at a cw-* path, a warning
+ * is emitted and the entry is skipped.
  *
  * Returns a summary: { wired: string[], skipped: string[], errors: string[] }
  */
@@ -36,7 +34,8 @@ export async function syncSymlinks(frameworkDir, skillsDir, skillNames) {
           wired.push(name);
         }
       } else if (stat.isDirectory()) {
-        skipped.push(name); // real directory override — never touch
+        // Real directory at a cw-* path — should not exist
+        errors.push(`${name}: real directory found — framework skills cannot be overridden locally. Remove .claude/skills/${name}/ to restore the framework version.`);
       } else {
         errors.push(`${name}: unexpected file at ${linkPath}`);
       }
@@ -56,10 +55,9 @@ export async function syncSymlinks(frameworkDir, skillsDir, skillNames) {
  * Copies <frameworkDir>/skills/<name>/SKILL.md → <skillsDir>/<name>/SKILL.md,
  * prepending an auto-generated header so consumers know not to edit the file directly.
  *
- * For each skill name:
- *   - If a real directory exists at <skillsDir>/<name> WITHOUT the auto-gen header: skip (override).
- *   - If a copy with the header already exists: skip (already wired).
- *   - Otherwise: create <skillsDir>/<name>/ and write SKILL.md with header.
+ * Framework skills (cw-* prefix) are always auto-generated copies. If a copy
+ * already exists with the auto-generated header, it is refreshed. If a real
+ * override without the header is found, an error is emitted.
  *
  * Returns a summary: { wired: string[], skipped: string[], errors: string[] }
  */
@@ -78,20 +76,19 @@ export async function syncCopies(frameworkDir, skillsDir, skillNames, version) {
     try {
       const stat = await lstat(destDir);
       if (stat.isDirectory()) {
-        // Check if it's an auto-generated copy or a real override
         let existingContent = '';
         try {
           existingContent = await readFile(destFile, 'utf8');
         } catch {
-          // No SKILL.md — treat as override directory
-          skipped.push(name);
+          // No SKILL.md in a cw-* dir — unexpected
+          errors.push(`${name}: real directory without SKILL.md — framework skills cannot be overridden locally.`);
           continue;
         }
 
         if (existingContent.startsWith('<!-- AUTO-GENERATED')) {
           skipped.push(name); // already wired as a copy
         } else {
-          skipped.push(name); // real override — never touch
+          errors.push(`${name}: real directory with custom SKILL.md found — framework skills cannot be overridden locally. Remove .claude/skills/${name}/ to restore the framework version.`);
         }
         continue;
       }
@@ -120,7 +117,6 @@ export function buildHeader(skillName, version) {
   return [
     `<!-- AUTO-GENERATED: Copied from _framework/skills/${skillName}/SKILL.md (v${version}) -->`,
     `<!-- Do not edit directly. Run \`npx @cuewright/skills update\` to refresh. -->`,
-    `<!-- To override: delete this file and create your own SKILL.md in this directory. -->`,
     '',
     '',
   ].join('\n');
@@ -133,3 +129,143 @@ export function buildHeader(skillName, version) {
 export function platformSupportsSymlinks() {
   return process.platform !== 'win32';
 }
+
+/**
+ * Remove old unprefixed skill directories that correspond to cw-* framework skills.
+ *
+ * This runs independently of the manifest diff, so it catches directories that
+ * survived the initial migration (e.g., rmdir failed due to non-empty content)
+ * as well as directories from even older installs that were never in a manifest.
+ *
+ * For each cw-* skill in manifestSkillNames, checks for a real directory or
+ * symlink at skillsDir/<unprefixed-name>/ and cleans it up:
+ * - Symlink: unlinked (was an old framework pointer)
+ * - Real directory: reference files moved to arch/references/<name>/, SKILL.md
+ *   removed, directory rmdir'd
+ *
+ * Returns { cleaned: string[], errors: string[] }
+ */
+export async function cleanupLegacyDirectories(skillsDir, manifestSkillNames, projectRoot, { dryRun = false } = {}) {
+  const cleaned = [];
+  const errors = [];
+  const { join } = await import('path');
+  const { rmdir } = await import('fs/promises');
+
+  for (const cwName of manifestSkillNames) {
+    if (!cwName.startsWith('cw-')) continue;
+    const unprefixed = cwName.slice(3);
+    const legacyPath = join(skillsDir, unprefixed);
+
+    let stat;
+    try {
+      stat = await lstat(legacyPath);
+    } catch {
+      continue; // Does not exist — nothing to do
+    }
+
+    if (stat.isSymbolicLink()) {
+      if (!dryRun) {
+        try {
+          await unlink(legacyPath);
+        } catch (err) {
+          errors.push(`${unprefixed}: could not remove symlink — ${err.message}`);
+          continue;
+        }
+      }
+      cleaned.push(unprefixed);
+      continue;
+    }
+
+    if (!stat.isDirectory()) continue;
+
+    // Real directory — migrate reference files, then remove
+    let entries;
+    try {
+      entries = await readdir(legacyPath);
+    } catch (err) {
+      errors.push(`${unprefixed}: could not read directory — ${err.message}`);
+      continue;
+    }
+
+    const referenceFiles = entries.filter(e => e !== 'SKILL.md');
+
+    if (referenceFiles.length > 0 && !dryRun) {
+      const refDir = join(projectRoot, '.claude', 'skills', 'arch', 'references', unprefixed);
+      try {
+        await mkdir(refDir, { recursive: true });
+        for (const file of referenceFiles) {
+          await rename(join(legacyPath, file), join(refDir, file));
+        }
+      } catch (err) {
+        errors.push(`${unprefixed}: could not migrate reference files — ${err.message}`);
+        continue;
+      }
+    }
+
+    if (!dryRun) {
+      try {
+        await unlink(join(legacyPath, 'SKILL.md'));
+      } catch {
+        // Already gone or never existed — fine
+      }
+
+      try {
+        await rmdir(legacyPath);
+      } catch {
+        errors.push(`${unprefixed}: directory not empty after migration — remove .claude/skills/${unprefixed}/ manually`);
+        continue;
+      }
+    }
+
+    cleaned.push(unprefixed);
+  }
+
+  return { cleaned, errors };
+}
+
+/**
+ * Scan skillsDir and categorize every entry.
+ *
+ * Returns:
+ * {
+ *   legacy: string[],    // unprefixed dirs matching a cw-* manifest skill
+ *   orphaned: string[],  // dirs that don't match any manifest skill or reserved name
+ * }
+ *
+ * Reserved names (skipped): _framework, _baseline, arch, worktrees
+ * Framework skills (cw-*) are not included in the return — they're already
+ * checked by the main doctor health checks.
+ */
+export async function inventorySkillsDir(skillsDir, manifestSkillNames) {
+  const { join } = await import('path');
+  const legacy = [];
+  const orphaned = [];
+
+  const RESERVED = new Set(['_framework', '_baseline', 'arch', 'worktrees']);
+  const unprefixedNames = new Set(
+    manifestSkillNames.filter(n => n.startsWith('cw-')).map(n => n.slice(3))
+  );
+  const cwNames = new Set(manifestSkillNames);
+
+  let entries;
+  try {
+    entries = await readdir(skillsDir, { withFileTypes: true });
+  } catch {
+    return { legacy, orphaned };
+  }
+
+  for (const entry of entries) {
+    const name = entry.name;
+    if (RESERVED.has(name)) continue;
+    if (cwNames.has(name)) continue; // framework skill — handled by main checks
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+
+    if (unprefixedNames.has(name)) {
+      legacy.push(name);
+    } else {
+      orphaned.push(name);
+    }
+  }
+
+  return { legacy, orphaned };
+}