claude-dev-env 1.94.0 → 1.95.0

package/bin/install.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, copyFileSync, unlinkSync, rmSync, realpathSync } from 'node:fs';
-import { join, dirname, resolve, relative } from 'node:path';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, copyFileSync, unlinkSync, rmSync, renameSync, realpathSync } from 'node:fs';
+import { join, dirname, resolve, relative, basename } from 'node:path';
 import { homedir } from 'node:os';
 import { execSync, execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -9,6 +9,7 @@ import { createRequire } from 'node:module';
 import { installAllGitHooks } from './git_hooks_installer.mjs';
 import { installMypyIniForClaudeHooks } from './install_mypy_ini.mjs';
 import { expandHomeDirectoryTokensInSettings } from './expand_home_directory_tokens.mjs';
+import { EVER_SHIPPED_SKILL_NAMES } from './ever-shipped-skills.mjs';
 
 const CLAUDE_HOME = join(homedir(), '.claude');
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -19,6 +20,10 @@ const packageRequire = createRequire(import.meta.url);
 
 export const CONTENT_DIRECTORIES = ['rules', 'docs', 'commands', 'agents', 'system-prompts', 'scripts', '_shared', 'audit-rubrics'];
 
+const SKILL_MANIFEST_FILENAME = 'SKILL.md';
+const NEVER_PRUNED_SKILL_DIRECTORIES = new Set(['_shared']);
+const PRUNED_SKILLS_BACKUP_DIRECTORY_NAME = '.claude-dev-env-pruned';
+
 export const CORE_INCLUDE_DIRECTORIES = [
     'rules', 'docs', 'commands', 'agents', 'audit-rubrics', '_shared', 'scripts',
 ];
@@ -94,17 +99,33 @@ function resolveDependencyPackageRoot(dependencyPackageName) {
     return dirname(dependencyPackageJsonPath);
 }
 
+/**
+ * Discovers the install groups contributed by resolvable dependency packages and
+ * the names of the declared dependencies that failed to resolve.
+ *
+ * A dependency that cannot be resolved contributes no group, so its skills never
+ * enter the installed set. The retired-skill prune subtracts the installed set
+ * from the ever-shipped set, so an unresolved dependency whose skills migrated
+ * out of the main package would leave those live skills looking retired. The
+ * returned unresolved-name list lets the caller skip the prune in that degraded
+ * mode rather than delete a live skill.
+ *
+ * @returns {{groups: object, unresolvedDependencyNames: string[]}} The resolvable
+ *   dependency groups keyed by group name, and the names that failed to resolve.
+ */
 function discoverDependencyGroups() {
     const ownPackageJsonPath = join(PACKAGE_ROOT, 'package.json');
     const ownPackageJson = JSON.parse(readFileSync(ownPackageJsonPath, 'utf8'));
     const dependencies = ownPackageJson.dependencies || {};
     const discoveredGroups = {};
+    const unresolvedDependencyNames = [];
     for (const dependencyName of Object.keys(dependencies)) {
         let dependencyRoot;
         try {
             dependencyRoot = resolveDependencyPackageRoot(dependencyName);
         } catch {
             console.error(`  WARNING: Could not resolve dependency ${dependencyName}, skipping`);
+            unresolvedDependencyNames.push(dependencyName);
             continue;
         }
         const dependencyPackageJson = JSON.parse(
@@ -145,9 +166,12 @@ function discoverDependencyGroups() {
         }
         discoveredGroups[groupName] = group;
     }
-    return discoveredGroups;
+    return { groups: discoveredGroups, unresolvedDependencyNames };
 }
 
+const dependencyDiscovery = discoverDependencyGroups();
+const UNRESOLVED_DEPENDENCY_NAMES = dependencyDiscovery.unresolvedDependencyNames;
+
 const INSTALL_GROUPS = {
     core: {
         description: 'Development standards, hooks, agents, commands',
@@ -164,7 +188,7 @@ const INSTALL_GROUPS = {
         description: 'Session logging and memory',
         skills: ['session-log', 'session-tidy'],
     },
-    ...discoverDependencyGroups(),
+    ...dependencyDiscovery.groups,
 };
 
 /**
@@ -606,11 +630,99 @@ function mergeHooks(hooksSourceRoot, pythonCommand) {
     return groupCount;
 }
 
-function writeManifest(installedFiles) {
+function writeManifest(installedFiles, skillNames) {
     const manifest = { package: PACKAGE_NAME, version: PACKAGE_VERSION, installedAt: new Date().toISOString(), files: installedFiles };
+    if (skillNames) {
+        manifest.skills = skillNames;
+    }
     writeFileSync(MANIFEST_FILE, JSON.stringify(manifest, null, 2) + '\n');
 }
 
+/**
+ * Read the skill directory names the previous install recorded.
+ *
+ * Returns null when no manifest exists or the manifest predates the skills key,
+ * so a caller can treat "unknown prior skills" the same in both cases and lean
+ * on the ever-shipped set to find retired skills.
+ *
+ * @returns {string[]|null} The prior manifest's skill names, or null when absent.
+ */
+function readPriorManifestSkills() {
+    if (!existsSync(MANIFEST_FILE)) return null;
+    try {
+        const priorManifest = JSON.parse(readFileSync(MANIFEST_FILE, 'utf8'));
+        return Array.isArray(priorManifest.skills) ? priorManifest.skills : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Move retired skill directories a prior install left under ~/.claude/skills into
+ * a timestamped backup directory rather than deleting them.
+ *
+ * A directory is pruned only when the package no longer ships it and either the
+ * prior manifest recorded it or the package once shipped it. Subtracting the
+ * just-installed set from the ever-shipped set at call time means restoring a
+ * skill to the package protects it — it re-enters the installed set and never
+ * counts as retired. Matching is by directory name alone, so a personal
+ * directory a user authored under a name that collides with a retired skill
+ * (for example `code`, `implement`, `refine`, `gotcha`, `caveman`) is treated as
+ * that retired skill and moved to backup; only a name in neither set, and
+ * ~/.claude/skills/_shared, are left in place.
+ *
+ * Each pruned directory is renamed to
+ * ~/.claude/.claude-dev-env-pruned/<timestamp>/<skill-name>/ — a backup root
+ * outside ~/.claude/skills, so a moved directory is never re-discovered as a
+ * skill — under one shared timestamp per run. A backup is never cleaned up, so a
+ * user can recover a wrongly-matched directory. One directory whose rename fails
+ * (for example a read-only file or a cross-device move) is logged and left in
+ * place, never deleted, so a prune failure costs at most a cosmetic leftover.
+ *
+ * @param {Set<string>} installedSkillNames Skill names this install just wrote.
+ * @param {string[]|null} priorManifestSkills The prior manifest's skill names, or null.
+ */
+function pruneRetiredSkills(installedSkillNames, priorManifestSkills) {
+    const skillsDirectory = join(CLAUDE_HOME, 'skills');
+    if (!existsSync(skillsDirectory)) return;
+    const retiredSkillNames = new Set(
+        [...EVER_SHIPPED_SKILL_NAMES].filter(skillName => !installedSkillNames.has(skillName))
+    );
+    const priorSkillNames = new Set(priorManifestSkills || []);
+    const runTimestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupRoot = join(CLAUDE_HOME, PRUNED_SKILLS_BACKUP_DIRECTORY_NAME, runTimestamp);
+    const existingSkillDirs = readdirSync(skillsDirectory, { withFileTypes: true })
+        .filter(entry => entry.isDirectory());
+    for (const skillDir of existingSkillDirs) {
+        const skillName = skillDir.name;
+        if (NEVER_PRUNED_SKILL_DIRECTORIES.has(skillName)) continue;
+        if (installedSkillNames.has(skillName)) continue;
+        const isPruneCandidate = priorSkillNames.has(skillName) || retiredSkillNames.has(skillName);
+        if (!isPruneCandidate) continue;
+        moveRetiredSkillToBackup(skillsDirectory, backupRoot, skillName);
+    }
+}
+
+/**
+ * Move one retired skill directory into the run's backup root, leaving it in
+ * place when the move fails.
+ *
+ * @param {string} skillsDirectory The ~/.claude/skills directory holding the skill.
+ * @param {string} backupRoot The run's timestamped backup directory.
+ * @param {string} skillName The retired skill directory name to move.
+ */
+function moveRetiredSkillToBackup(skillsDirectory, backupRoot, skillName) {
+    const skillPath = join(skillsDirectory, skillName);
+    const backupPath = join(backupRoot, skillName);
+    try {
+        mkdirSync(backupRoot, { recursive: true });
+        renameSync(skillPath, backupPath);
+        console.log(`  ✗ ${join('skills', skillName)} (retired — moved to ${join(PRUNED_SKILLS_BACKUP_DIRECTORY_NAME, basename(backupRoot), skillName)})`);
+    } catch (moveError) {
+        console.warn(`  Warning: could not move retired ${join('skills', skillName)} to backup, leaving in place (${moveError.message})`);
+    }
+}
+
 function install(selectedGroups, options = {}) {
     const isUpdateRefresh = Boolean(options.isUpdateRefresh);
     if (isUpdateRefresh && !selectedGroups && existsSync(MANIFEST_FILE)) {
@@ -708,6 +820,7 @@ function install(selectedGroups, options = {}) {
     let skillsCreated = 0;
     let skillsUpdated = 0;
     const skillPaths = [];
+    const installedSkillNames = new Set();
     for (const sourceRoot of allSourceRoots) {
         const skillsSource = join(sourceRoot, 'skills');
         if (!existsSync(skillsSource)) continue;
@@ -718,6 +831,9 @@ function install(selectedGroups, options = {}) {
             skillsCreated += stats.created;
             skillsUpdated += stats.updated;
             skillPaths.push(...stats.paths);
+            if (existsSync(join(skillsSource, skillDir.name, SKILL_MANIFEST_FILENAME))) {
+                installedSkillNames.add(skillDir.name);
+            }
         }
     }
     summary.skills = { created: skillsCreated, updated: skillsUpdated, paths: skillPaths };
@@ -804,7 +920,21 @@ function install(selectedGroups, options = {}) {
         allInstalledFiles.push(claudeHubDest);
         console.log(`  \u2713 ${relative(CLAUDE_HOME, claudeHubDest)} (hub)`);
     }
-    writeManifest(allInstalledFiles);
+    const isFullInstall = !selectedGroups;
+    const priorManifestSkills = readPriorManifestSkills();
+    let manifestSkillNames = priorManifestSkills;
+    if (isFullInstall) {
+        if (UNRESOLVED_DEPENDENCY_NAMES.length > 0) {
+            console.log(
+                `  Skipping retired-skill prune — unresolved dependency group(s): ${UNRESOLVED_DEPENDENCY_NAMES.join(', ')}. `
+                + 'A skill that migrated to a dependency package would look retired and be moved to backup, so the prune is held until every dependency resolves.',
+            );
+        } else {
+            pruneRetiredSkills(installedSkillNames, priorManifestSkills);
+        }
+        manifestSkillNames = [...installedSkillNames].sort();
+    }
+    writeManifest(allInstalledFiles, manifestSkillNames);
     console.log(`\nInstalled ${PACKAGE_NAME}:`);
     for (const directory of CONTENT_DIRECTORIES) {
         if (summary[directory]) {

package/bin/install.prune.test.mjs

@@ -0,0 +1,457 @@
+import { test, after } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import {
+    mkdtempSync,
+    mkdirSync,
+    writeFileSync,
+    existsSync,
+    readFileSync,
+    readdirSync,
+    rmSync,
+    cpSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const THIS_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const INSTALLER_PATH = join(THIS_DIRECTORY, 'install.mjs');
+const PACKAGE_DIRECTORY = dirname(THIS_DIRECTORY);
+const EXCLUDED_PACKAGE_COPY_DIRECTORY = 'node_modules';
+
+const RETIRED_SKILL_DIRECTORIES = [
+    'findbugs',
+    'fixbugs',
+    'pr-scope-resolve',
+    'post-audit-findings',
+    'pr-consistency-audit',
+    'bdd-protocol',
+];
+const PERSONAL_SKILL_DIRECTORIES = ['balatro', 'midjourney-sref', 'credit-card-picker'];
+const SHIPPED_SKILL_DIRECTORY = 'autoconverge';
+const PRUNED_BACKUP_DIRECTORY_NAME = '.claude-dev-env-pruned';
+const SKIP_PRUNE_NOTICE_MARKER = 'Skipping retired-skill prune';
+const DEPENDENCY_STUB_PACKAGE_SEGMENTS = ['@jl-cmd', 'prompt-generator'];
+
+/**
+ * Create a stub node_modules tree the installer can resolve the declared
+ * dependency package from, and return its root for the child's NODE_PATH.
+ *
+ * The installer resolves `@jl-cmd/prompt-generator/package.json`; a lone
+ * package.json at that path is enough for `createRequire.resolve` to succeed.
+ * The stub makes the dependency resolvable inside the sandbox so a full install
+ * exercises the real prune path. It does not prove the real private package
+ * resolves in a real install — CI cannot host that package — only that the
+ * resolved-dependency branch prunes as designed.
+ *
+ * @param {string} homeDirectory The sandbox home the stub is nested under.
+ * @returns {string} The stub modules root to place on the child's NODE_PATH.
+ */
+let isolatedInstallerPath = null;
+let isolatedPackageCopyRoot = null;
+
+/**
+ * Copy the package into a temp directory without node_modules and return the
+ * copy's installer path.
+ *
+ * The installer resolves its declared dependencies with Node's regular
+ * node_modules walk starting at its own file, so the real installer under the
+ * repo always finds `@jl-cmd/prompt-generator` once `npm install` has run —
+ * removing NODE_PATH from the child cannot make the dependency unresolvable
+ * there. Running the copy makes resolution genuinely fail through the
+ * installer's own catch path: no node_modules sits in the copy's ancestry and
+ * the child gets no NODE_PATH. The copy is created once and shared by every
+ * unresolved-dependency install; installs write only into their sandbox HOME.
+ *
+ * @returns {string} The path to `bin/install.mjs` inside the package copy.
+ */
+function ensureIsolatedInstallerPath() {
+    if (isolatedInstallerPath !== null) return isolatedInstallerPath;
+    isolatedPackageCopyRoot = mkdtempSync(join(tmpdir(), 'cdev-prune-package-'));
+    cpSync(PACKAGE_DIRECTORY, isolatedPackageCopyRoot, {
+        recursive: true,
+        filter: sourcePath => basename(sourcePath) !== EXCLUDED_PACKAGE_COPY_DIRECTORY,
+    });
+    isolatedInstallerPath = join(isolatedPackageCopyRoot, 'bin', 'install.mjs');
+    return isolatedInstallerPath;
+}
+
+after(() => {
+    if (isolatedPackageCopyRoot !== null) {
+        rmSync(isolatedPackageCopyRoot, { recursive: true, force: true });
+    }
+});
+
+function ensureDependencyStub(homeDirectory) {
+    const stubModulesRoot = join(homeDirectory, 'dependency-stub-modules');
+    const stubPackageDirectory = join(stubModulesRoot, ...DEPENDENCY_STUB_PACKAGE_SEGMENTS);
+    mkdirSync(stubPackageDirectory, { recursive: true });
+    writeFileSync(
+        join(stubPackageDirectory, 'package.json'),
+        JSON.stringify({
+            name: DEPENDENCY_STUB_PACKAGE_SEGMENTS.join('/'),
+            version: '1.0.0',
+            description: 'sandbox dependency stub',
+        }) + '\n',
+    );
+    return stubModulesRoot;
+}
+
+/**
+ * Report whether a retired skill directory landed under the prune backup root.
+ *
+ * @param {string} claudeDirectory The sandbox ~/.claude directory.
+ * @param {string} skillName The retired skill directory name to look for.
+ * @returns {boolean} True when a timestamped backup holds the skill directory.
+ */
+function prunedBackupContains(claudeDirectory, skillName) {
+    const backupRoot = join(claudeDirectory, PRUNED_BACKUP_DIRECTORY_NAME);
+    if (!existsSync(backupRoot)) return false;
+    return readdirSync(backupRoot, { withFileTypes: true })
+        .filter(entry => entry.isDirectory())
+        .some(timestampDir => existsSync(join(backupRoot, timestampDir.name, skillName)));
+}
+
+/**
+ * Create an isolated ~/.claude sandbox and return the paths a prune test reads.
+ *
+ * The returned home directory becomes the installer's HOME, so every file the
+ * install writes and every skill directory the prune inspects stays inside the
+ * temp tree and never touches the machine's real ~/.claude.
+ *
+ * @returns {{homeDirectory: string, claudeDirectory: string, skillsDirectory: string, manifestPath: string}}
+ */
+function createSandbox() {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-prune-home-'));
+    const claudeDirectory = join(homeDirectory, '.claude');
+    const skillsDirectory = join(claudeDirectory, 'skills');
+    mkdirSync(skillsDirectory, { recursive: true });
+    const manifestPath = join(claudeDirectory, '.claude-dev-env-manifest.json');
+    return { homeDirectory, claudeDirectory, skillsDirectory, manifestPath };
+}
+
+/**
+ * Plant a skill directory under the sandbox with a single marker file.
+ *
+ * A personal directory is planted with no ``SKILL.md`` so it never looks like a
+ * shipped skill; a retired directory is planted with a ``SKILL.md`` so it mirrors
+ * a real skill the package once installed and later dropped.
+ *
+ * @param {string} skillsDirectory The sandbox skills directory.
+ * @param {string} skillName The directory name to plant.
+ * @param {boolean} withSkillManifest Whether to write a ``SKILL.md`` marker.
+ */
+function plantSkillDirectory(skillsDirectory, skillName, withSkillManifest) {
+    const skillDirectory = join(skillsDirectory, skillName);
+    mkdirSync(skillDirectory, { recursive: true });
+    const markerName = withSkillManifest ? 'SKILL.md' : 'notes.md';
+    writeFileSync(join(skillDirectory, markerName), `seeded ${skillName}\n`);
+}
+
+/**
+ * Run the real installer against the sandbox home and return its stdout.
+ *
+ * The declared dependency package is resolvable by default: the child's
+ * NODE_PATH points at a sandbox stub so `createRequire.resolve` finds it and the
+ * full-install prune runs. Passing ``{ dependencyResolvable: false }`` runs the
+ * installer from an isolated package copy with no node_modules in its ancestry
+ * and no NODE_PATH, so the dependency fails to resolve and the installer skips
+ * the prune.
+ *
+ * @param {string} homeDirectory The sandbox home the installer writes into.
+ * @param {string[]} extraArguments Installer arguments (for example ``['--only', 'core']``).
+ * @param {{dependencyResolvable?: boolean}} options Whether the dependency resolves.
+ * @returns {string} The installer's stdout.
+ */
+function runInstaller(homeDirectory, extraArguments, options = {}) {
+    const dependencyResolvable = options.dependencyResolvable !== false;
+    const childEnvironment = {
+        ...process.env,
+        HOME: homeDirectory,
+        USERPROFILE: homeDirectory,
+        GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+    };
+    let installerPath;
+    if (dependencyResolvable) {
+        childEnvironment.NODE_PATH = ensureDependencyStub(homeDirectory);
+        installerPath = INSTALLER_PATH;
+    } else {
+        delete childEnvironment.NODE_PATH;
+        installerPath = ensureIsolatedInstallerPath();
+    }
+    return execFileSync('node', [installerPath, ...extraArguments], {
+        cwd: dirname(installerPath),
+        encoding: 'utf8',
+        env: childEnvironment,
+    });
+}
+
+function readManifest(manifestPath) {
+    return JSON.parse(readFileSync(manifestPath, 'utf8'));
+}
+
+test('a full reinstall over a pre-manifest dirty tree prunes retired skills and keeps personal ones', () => {
+    const sandbox = createSandbox();
+    try {
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            plantSkillDirectory(sandbox.skillsDirectory, retiredSkill, true);
+        }
+        for (const personalSkill of PERSONAL_SKILL_DIRECTORIES) {
+            plantSkillDirectory(sandbox.skillsDirectory, personalSkill, false);
+        }
+        assert.equal(existsSync(sandbox.manifestPath), false, 'sandbox starts with no manifest');
+
+        const installerOutput = runInstaller(sandbox.homeDirectory, []);
+
+        assert.equal(
+            installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
+            false,
+            'the resolvable-dependency install runs the prune rather than skipping it',
+        );
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            assert.equal(
+                existsSync(join(sandbox.skillsDirectory, retiredSkill)),
+                false,
+                `retired skill ${retiredSkill} should be pruned`,
+            );
+            assert.equal(
+                prunedBackupContains(sandbox.claudeDirectory, retiredSkill),
+                true,
+                `retired skill ${retiredSkill} should be moved to the prune backup`,
+            );
+        }
+        for (const personalSkill of PERSONAL_SKILL_DIRECTORIES) {
+            assert.equal(
+                existsSync(join(sandbox.skillsDirectory, personalSkill)),
+                true,
+                `personal skill ${personalSkill} should survive`,
+            );
+        }
+        assert.equal(
+            existsSync(join(sandbox.skillsDirectory, SHIPPED_SKILL_DIRECTORY)),
+            true,
+            'shipped skills should install',
+        );
+        const manifest = readManifest(sandbox.manifestPath);
+        assert.ok(Array.isArray(manifest.skills), 'manifest gains a skills array');
+        assert.ok(manifest.skills.includes(SHIPPED_SKILL_DIRECTORY), 'manifest skills lists shipped skills');
+        assert.equal(manifest.skills.includes('_shared'), false, 'manifest skills omits _shared');
+        assert.equal(manifest.skills.includes('__pycache__'), false, 'manifest skills omits __pycache__');
+    } finally {
+        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a full reinstall over an old-format manifest without a skills key still prunes via the ever-shipped fallback', () => {
+    const sandbox = createSandbox();
+    try {
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            plantSkillDirectory(sandbox.skillsDirectory, retiredSkill, true);
+        }
+        writeFileSync(
+            sandbox.manifestPath,
+            JSON.stringify({
+                package: 'claude-dev-env',
+                version: '0.0.0',
+                installedAt: new Date().toISOString(),
+                files: [join(sandbox.skillsDirectory, 'findbugs', 'SKILL.md')],
+            }, null, 2) + '\n',
+        );
+
+        const installerOutput = runInstaller(sandbox.homeDirectory, []);
+
+        assert.equal(
+            installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
+            false,
+            'the resolvable-dependency install runs the prune rather than skipping it',
+        );
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            assert.equal(
+                existsSync(join(sandbox.skillsDirectory, retiredSkill)),
+                false,
+                `retired skill ${retiredSkill} should be pruned via the ever-shipped fallback`,
+            );
+            assert.equal(
+                prunedBackupContains(sandbox.claudeDirectory, retiredSkill),
+                true,
+                `retired skill ${retiredSkill} should be moved to the prune backup`,
+            );
+        }
+        const manifest = readManifest(sandbox.manifestPath);
+        assert.ok(Array.isArray(manifest.skills), 'the reinstall writes the skills key onto the old-format manifest');
+    } finally {
+        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a full reinstall prunes a manifest-recorded skill absent from the package and keeps a personal directory', () => {
+    const sandbox = createSandbox();
+    try {
+        const retiredManifestSkill = 'ghost-skill';
+        const personalSkill = 'balatro';
+        plantSkillDirectory(sandbox.skillsDirectory, retiredManifestSkill, true);
+        plantSkillDirectory(sandbox.skillsDirectory, personalSkill, false);
+        writeFileSync(
+            sandbox.manifestPath,
+            JSON.stringify({
+                package: 'claude-dev-env',
+                version: '0.0.0',
+                installedAt: new Date().toISOString(),
+                files: [],
+                skills: [SHIPPED_SKILL_DIRECTORY, retiredManifestSkill],
+            }, null, 2) + '\n',
+        );
+
+        const installerOutput = runInstaller(sandbox.homeDirectory, []);
+
+        assert.equal(
+            installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
+            false,
+            'the resolvable-dependency install runs the prune rather than skipping it',
+        );
+        assert.equal(
+            existsSync(join(sandbox.skillsDirectory, retiredManifestSkill)),
+            false,
+            'a skill the prior manifest recorded but the package no longer ships is pruned',
+        );
+        assert.equal(
+            prunedBackupContains(sandbox.claudeDirectory, retiredManifestSkill),
+            true,
+            'the manifest-recorded retired skill is moved to the prune backup',
+        );
+        assert.equal(
+            existsSync(join(sandbox.skillsDirectory, personalSkill)),
+            true,
+            'a personal directory in neither the manifest nor the ever-shipped set survives',
+        );
+    } finally {
+        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a scoped --only install leaves retired skills in place because prune runs on full installs only', () => {
+    const sandbox = createSandbox();
+    try {
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            plantSkillDirectory(sandbox.skillsDirectory, retiredSkill, true);
+        }
+
+        runInstaller(sandbox.homeDirectory, ['--only', 'core']);
+
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            assert.equal(
+                existsSync(join(sandbox.skillsDirectory, retiredSkill)),
+                true,
+                `retired skill ${retiredSkill} should survive a scoped install`,
+            );
+            assert.equal(
+                prunedBackupContains(sandbox.claudeDirectory, retiredSkill),
+                false,
+                `retired skill ${retiredSkill} should not be moved to backup by a scoped install`,
+            );
+        }
+    } finally {
+        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a full reinstall keeps pr-fix-protocol because the package ships it again', () => {
+    const sandbox = createSandbox();
+    try {
+        plantSkillDirectory(sandbox.skillsDirectory, 'pr-fix-protocol', true);
+        writeFileSync(join(sandbox.skillsDirectory, 'pr-fix-protocol', 'SKILL.md'), 'stale seeded copy\n');
+
+        const installerOutput = runInstaller(sandbox.homeDirectory, []);
+
+        assert.equal(
+            installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
+            false,
+            'the resolvable-dependency install runs the prune rather than skipping it',
+        );
+        const restoredSkillPath = join(sandbox.skillsDirectory, 'pr-fix-protocol', 'SKILL.md');
+        assert.equal(existsSync(restoredSkillPath), true, 'pr-fix-protocol survives and is reinstalled');
+        assert.notEqual(
+            readFileSync(restoredSkillPath, 'utf8'),
+            'stale seeded copy\n',
+            'the shipped pr-fix-protocol overwrites the stale seeded copy',
+        );
+    } finally {
+        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a full reinstall with an unresolved dependency skips the prune and leaves retired skills untouched', () => {
+    const sandbox = createSandbox();
+    try {
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            plantSkillDirectory(sandbox.skillsDirectory, retiredSkill, true);
+        }
+
+        const installerOutput = runInstaller(sandbox.homeDirectory, [], { dependencyResolvable: false });
+
+        assert.equal(
+            installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
+            true,
+            'the installer logs a notice that it is skipping the prune',
+        );
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            assert.equal(
+                existsSync(join(sandbox.skillsDirectory, retiredSkill)),
+                true,
+                `retired skill ${retiredSkill} should survive when a dependency is unresolved`,
+            );
+            assert.equal(
+                prunedBackupContains(sandbox.claudeDirectory, retiredSkill),
+                false,
+                `retired skill ${retiredSkill} should not be moved to backup when the prune is skipped`,
+            );
+        }
+    } finally {
+        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('the prune skip is scoped: once the dependency resolves a later full install prunes normally', () => {
+    const sandbox = createSandbox();
+    try {
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            plantSkillDirectory(sandbox.skillsDirectory, retiredSkill, true);
+        }
+
+        const skippedOutput = runInstaller(sandbox.homeDirectory, [], { dependencyResolvable: false });
+        assert.equal(
+            skippedOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
+            true,
+            'the unresolved-dependency install skips the prune',
+        );
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            assert.equal(
+                existsSync(join(sandbox.skillsDirectory, retiredSkill)),
+                true,
+                `retired skill ${retiredSkill} should still be present after the skipped prune`,
+            );
+        }
+
+        const resolvedOutput = runInstaller(sandbox.homeDirectory, [], { dependencyResolvable: true });
+        assert.equal(
+            resolvedOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
+            false,
+            'the resolved-dependency install runs the prune, proving the skip is not a permanent disable',
+        );
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            assert.equal(
+                existsSync(join(sandbox.skillsDirectory, retiredSkill)),
+                false,
+                `retired skill ${retiredSkill} should be pruned once the dependency resolves`,
+            );
+            assert.equal(
+                prunedBackupContains(sandbox.claudeDirectory, retiredSkill),
+                true,
+                `retired skill ${retiredSkill} should be moved to the prune backup on the resolved install`,
+            );
+        }
+    } finally {
+        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
+    }
+});