devflow-kit 3.10.0 → 3.11.0

package/dist/cli/commands/legacy-sweep.js

@@ -1,64 +1,159 @@
+import { createHash } from 'crypto';
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import { LEGACY_COMMAND_NAMES, LEGACY_RULE_NAMES } from '../../core/plugins.js';
-import { isUnrealFolder } from '../../targets/claude-code/linked-folder.js';
+import { RETIRED_SHIPPED } from '../../core/retired-shipped-names.js';
+import { LEGACY_SKILL_NAMES } from '../../targets/claude-code/legacy.js';
+import { BARE_LEGACY_SKILL_HASHES } from '../../targets/claude-code/legacy-skill-hashes.js';
+import { directoryState, isUnrealFolder } from '../../targets/claude-code/linked-folder.js';
+/** The prefix of a skill folder in devflow's own namespace. A folder without it is bare. */
+const NAMESPACE_PREFIX = 'devflow:';
 /**
- * Whether the sweep may remove files from `dir`: the install did not refuse it, and `lstat` shows a
- * real folder or nothing. `readdir` and `rm` of a path below a link act on the folder it points to.
+ * Whether the sweep may remove files from `dir`: the install did not refuse it, nothing in it stays
+ * because a move failed or the folder was too large to scan, and `lstat` shows a real folder or
+ * nothing. `readdir` and `rm` of a path below a link act on the folder it points to.
  */
-async function mayRemoveFrom(report, dir) {
-    return !report.refusedFolders.includes(dir) && !(await isUnrealFolder(dir));
+async function mayRemoveFrom(report, backups, dir) {
+    return !report.refusedFolders.includes(dir) && !backups.isKept(dir) && !(await isUnrealFolder(dir));
+}
+/** Each name once, in the order given. */
+const uniqueNames = (...lists) => [...new Set(lists.flat())];
+/**
+ * Remove `<folder>/<name>.md` for each name, by exact name. A name that is shipped today is never
+ * removed, and a file that stays is left for the session's record.
+ */
+async function removeRetiredMarkdown(folder, names, backups) {
+    const removed = [];
+    for (const name of names) {
+        const file = path.join(folder, `${name}.md`);
+        if (backups.classifyAt(file, 'file') === 'shipped')
+            continue;
+        if ((await backups.removeExact(file)).status === 'removed')
+            removed.push(file);
+    }
+    return removed;
 }
 /**
  * Remove the files that earlier releases installed into `commands/devflow` and `rules/devflow` and
- * that no release installs now: the legacy command and rule names, and every `*-teams.md` command.
- * Runs on every install shape, since the full install's pre-clean covers only a full install.
+ * that no release installs now: the retired command and rule names and the legacy lists, each by its
+ * exact name. Runs on every install shape, since the full install's pre-clean covers only a full
+ * install. A file whose name only looks like a retired one (a `*-teams.md` of the user's) is not
+ * matched here: the install's pre-pass moves it aside and names it.
  *
- * A folder the install refused (`report.refusedFolders`) or that is a link now is skipped whole: the
- * sweep reads and removes nothing there, and the folder it points to is left as it is. Never throws.
+ * A folder the install refused (`report.refusedFolders`), that the session could not scan, or that
+ * is a link now is skipped whole: the sweep reads and removes nothing there, and the folder a link
+ * points to is left as it is. Every removal goes through `backups`, so each removed file is named
+ * once, on the retired line of its record. Never throws.
  *
- * @param opts.legacyCommands - Legacy command names; defaults to the registry list.
- * @param opts.legacyRules - Legacy rule names; defaults to the registry list.
+ * @param opts.legacyCommands - Legacy command names; added to the retired commands.
+ * @param opts.legacyRules - Legacy rule names; added to the retired rules.
  */
 export async function sweepLegacyDevflowFiles(opts) {
-    const { claudeDir, report } = opts;
-    const legacyCommands = opts.legacyCommands ?? LEGACY_COMMAND_NAMES;
-    const legacyRules = opts.legacyRules ?? LEGACY_RULE_NAMES;
-    const result = { staleCommandsRemoved: 0, staleRulesRemoved: 0 };
+    const { claudeDir, report, backups } = opts;
+    const commands = uniqueNames(RETIRED_SHIPPED.commands, opts.legacyCommands ?? LEGACY_COMMAND_NAMES);
+    const rules = uniqueNames(RETIRED_SHIPPED.rules, opts.legacyRules ?? LEGACY_RULE_NAMES);
+    const removed = [];
     const commandsDir = path.join(claudeDir, 'commands', 'devflow');
-    if (await mayRemoveFrom(report, commandsDir)) {
-        for (const legacy of legacyCommands) {
-            try {
-                await fs.rm(path.join(commandsDir, `${legacy}.md`));
-                result.staleCommandsRemoved++;
-            }
-            catch { /* absent — expected for most entries */ }
-        }
-        // Orphaned *-teams.md workflow command variants left by the Agent Teams refactor. None is ever
-        // re-installed, so a blanket sweep is safe on any install type.
-        try {
-            for (const entry of await fs.readdir(commandsDir)) {
-                if (!entry.endsWith('-teams.md'))
-                    continue;
-                try {
-                    await fs.rm(path.join(commandsDir, entry));
-                    result.staleCommandsRemoved++;
-                }
-                catch { /* already gone */ }
-            }
-        }
-        catch { /* commands folder absent — nothing to sweep */ }
+    if (await mayRemoveFrom(report, backups, commandsDir)) {
+        removed.push(...await removeRetiredMarkdown(commandsDir, commands, backups));
     }
     const rulesDir = path.join(claudeDir, 'rules', 'devflow');
-    if (await mayRemoveFrom(report, rulesDir)) {
-        for (const legacy of legacyRules) {
-            try {
-                await fs.rm(path.join(rulesDir, `${legacy}.md`));
-                result.staleRulesRemoved++;
-            }
-            catch { /* absent — expected for most entries */ }
+    if (await mayRemoveFrom(report, backups, rulesDir)) {
+        removed.push(...await removeRetiredMarkdown(rulesDir, rules, backups));
+    }
+    return { removed };
+}
+/** The most bytes of a `SKILL.md` the check reads. Every released copy is far smaller, so a larger file is not one. */
+const MAX_SKILL_FILE_BYTES = 1024 * 1024;
+/**
+ * Who made a bare legacy skill folder, judged from its `SKILL.md` alone:
+ *   - `devflow`: the file is a regular file whose SHA-256 is one of `released`;
+ *   - `other`: the file reads and is not one of them, or is larger than any release copy;
+ *   - `unknown`: the check cannot decide. There is no `SKILL.md`, it is not a regular file, the
+ *     folder or the file is a link, or a read fails.
+ * An `absent` folder needs no answer. Reads one file at most. Never throws.
+ */
+async function judgeBareSkillFolder(folder, released) {
+    const state = await directoryState(folder);
+    if (state === 'absent')
+        return 'absent';
+    if (state !== 'real')
+        return 'unknown';
+    try {
+        const skillFile = path.join(folder, 'SKILL.md');
+        const stat = await fs.lstat(skillFile);
+        if (!stat.isFile())
+            return 'unknown';
+        if (stat.size > MAX_SKILL_FILE_BYTES)
+            return 'other';
+        const digest = createHash('sha256').update(await fs.readFile(skillFile)).digest('hex');
+        return released.includes(digest) ? 'devflow' : 'other';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * {@link judgeBareSkillFolder} for the bare legacy skill `name`, against the released copies of that
+ * name. A name with no entry in `released` was never installed bare by a release, so a folder of
+ * that name is `other`. The one check that `devflow init` and `devflow uninstall` share.
+ *
+ * @param folder - The folder of the skill, `<skills folder>/<name>`.
+ * @param released - SHA-256 hashes of the released `SKILL.md` copies by bare name; defaults to the frozen table.
+ */
+export function judgeBareLegacySkill(folder, name, released = BARE_LEGACY_SKILL_HASHES) {
+    return judgeBareSkillFolder(folder, Object.hasOwn(released, name) ? released[name] : []);
+}
+/**
+ * Deal with the skill folders that earlier installs left under the legacy names: every name of the
+ * legacy skill list, bare and `devflow:`-prefixed.
+ *
+ * A `devflow:`-prefixed folder that no release listed moves whole, with one rename and no walk, and
+ * is named; it is never deleted. A bare folder lives in the skills folder that Claude Code and other
+ * tools share, so its name proves nothing (`python`, `plan` and `review` are names of a user's own
+ * skills too). It moves only when its `SKILL.md` is a copy that a release of devflow installed
+ * (`released`). A bare folder whose `SKILL.md` is any other file stays where it is, and nothing is
+ * said. A bare folder that the check cannot judge stays, is never deleted, and is returned in
+ * `kept`, so the caller names it. A name with a listing in `retiredFiles` (the files a release
+ * shipped in that folder) goes by the listing instead: the listed files are removed, the rest of
+ * the folder moves, and a plain `rmdir` removes the folder only when it is empty. A move that fails
+ * leaves the folder and its files where they are, and the session records it. A name that is shipped
+ * today, or that an earlier step could not move, is skipped, and so is every name when the skills
+ * folder is a link or not a folder: nothing is moved through a link. Nothing here removes a folder
+ * with recursion. Never throws.
+ *
+ * @param opts.legacySkills - Folder names to deal with; defaults to the legacy skill list.
+ * @param opts.retiredFiles - Released file listings by folder name; defaults to the retired registry.
+ * @param opts.released - SHA-256 hashes of the released `SKILL.md` copies by bare name; defaults to the frozen table.
+ */
+export async function sweepLegacySkillFolders(opts) {
+    const { backups } = opts;
+    const retiredFiles = opts.retiredFiles ?? RETIRED_SHIPPED.skillFiles;
+    const released = opts.released ?? BARE_LEGACY_SKILL_HASHES;
+    const kept = [];
+    const skillsDir = path.join(opts.claudeDir, 'skills');
+    if ((await directoryState(skillsDir)) !== 'real')
+        return { kept };
+    for (const name of opts.legacySkills ?? LEGACY_SKILL_NAMES) {
+        const folder = path.join(skillsDir, name);
+        if (backups.isKept(folder) || backups.classifyAt(folder, 'directory') === 'shipped')
+            continue;
+        const listed = Object.hasOwn(retiredFiles, name) && retiredFiles[name].length > 0;
+        if (listed && (await directoryState(folder)) === 'real') {
+            await backups.prepass([folder]);
+            await backups.removeListed(folder);
+        }
+        else if (name.startsWith(NAMESPACE_PREFIX)) {
+            await backups.moveWhole(folder);
+        }
+        else {
+            const verdict = await judgeBareLegacySkill(folder, name, released);
+            if (verdict === 'devflow')
+                await backups.moveWhole(folder);
+            else if (verdict === 'unknown')
+                kept.push(folder);
         }
     }
-    return result;
+    return { kept };
 }
 //# sourceMappingURL=legacy-sweep.js.map

package/dist/cli/commands/rules.js

@@ -10,7 +10,9 @@ import { rulesDir } from '../../core/assets.js';
 import { installAllRules, validateRuleShadow } from '../../targets/claude-code/installer.js';
 import { convergeFromManifest } from '../../targets/claude-code/compliance-install.js';
 import { convergeBehaviorFromManifest } from '../../targets/claude-code/behavior-install.js';
-import { newLinkReport, refuseUnrealFolder, refusedFolderMessage, removeReportingLink } from '../../targets/claude-code/linked-folder.js';
+import { newLinkReport, refuseUnrealFolder, refusedFolderMessage } from '../../targets/claude-code/linked-folder.js';
+import { removeRulesFolder, rulesFolderRefusedMessage } from '../../targets/claude-code/rules-folder.js';
+import { openBackupSessionOrFail, runWithBackupReport } from './backup-session.js';
 import { formatLinksSummary } from './install-report.js';
 /**
  * Check whether a rule has a user shadow file at ~/.devflow/rules/{name}.md.
@@ -205,20 +207,29 @@ async function handleRuleUnshadow(name, allRules, devflowDir) {
  *
  * Warn-not-throw on per-item compliance convergence failure, so a convergence
  * failure never undoes the rules install.
+ *
+ * The record of `backups` prints once, as the enable returns or throws.
  */
-export async function runRulesEnable(claudeDir, devflowDir) {
+export function runRulesEnable(claudeDir, devflowDir, backups) {
+    return runWithBackupReport(backups, printBackups => enableRules(claudeDir, devflowDir, backups, printBackups));
+}
+async function enableRules(claudeDir, devflowDir, backups, printBackups) {
     const rulesTarget = path.join(claudeDir, 'rules', 'devflow');
     const manifest = await readManifest(devflowDir);
     if (!manifest) {
         p.log.error('No manifest found. Run devflow init first.');
+        printBackups();
         process.exit(1);
     }
     const installedPlugins = DEVFLOW_PLUGINS.filter(pl => manifest.plugins.includes(pl.name));
     const rulesMap = buildRulesMap(installedPlugins);
-    // Wipe stale rules from previously uninstalled plugins before re-installing. A rules folder that is
-    // a link is unlinked and replaced by a real folder, never emptied through, and the link is reported.
+    // Clear stale rules from previously uninstalled plugins before re-installing: the files devflow did
+    // not ship move to the backup folder, and the rest of the folder is removed by the session's list.
+    // A rules folder that is a link is unlinked and replaced by a real folder, never emptied through,
+    // and the link is reported. Something that is not a folder stays and is refused below.
     const links = newLinkReport();
-    links.replacedLinks.push(...await removeReportingLink(rulesTarget));
+    if ((await removeRulesFolder(rulesTarget, backups)) === 'unlinked')
+        links.replacedLinks.push(rulesTarget);
     // A link that could not be removed is still there, and `mkdir` and every rule write would follow it.
     // Prove the folder first; a refused folder gets no rule, no manifest write and one refusal line.
     const rulesFolderRefused = await refuseUnrealFolder(links, rulesTarget);
@@ -268,6 +279,7 @@ export async function runRulesEnable(claudeDir, devflowDir) {
             manifest,
             warn: warnConverge,
             rulesEnabledOverride: !installFailed,
+            backups,
         });
     }
     catch (err) {
@@ -325,17 +337,42 @@ export const rulesCommand = new Command('rules')
     }
     // No positional action — fall through to flag-based handling
     if (options.enable) {
-        await runRulesEnable(claudeDir, devflowDir);
+        const backups = await openBackupSessionOrFail({ claudeDir, devflowDir });
+        if (backups === null)
+            return;
+        await runRulesEnable(claudeDir, devflowDir, backups);
     }
     else if (options.disable) {
-        await fs.rm(rulesTarget, { recursive: true, force: true });
-        const manifest = await readManifest(devflowDir);
-        if (manifest) {
-            manifest.features.rules = false;
-            manifest.updatedAt = new Date().toISOString();
-            await writeManifest(devflowDir, manifest);
+        const backups = await openBackupSessionOrFail({ claudeDir, devflowDir });
+        if (backups === null)
+            return;
+        const removal = await runWithBackupReport(backups, async () => {
+            const outcome = await removeRulesFolder(rulesTarget, backups);
+            const manifest = await readManifest(devflowDir);
+            if (manifest) {
+                manifest.features.rules = false;
+                manifest.updatedAt = new Date().toISOString();
+                await writeManifest(devflowDir, manifest);
+            }
+            return outcome;
+        });
+        switch (removal) {
+            case 'kept':
+                p.log.warn(`Rules disabled — ${rulesTarget} stays, because it still holds files that devflow did not remove`);
+                break;
+            case 'refused':
+                p.log.warn(`Rules disabled. ${rulesFolderRefusedMessage(rulesTarget)}`);
+                break;
+            case 'absent':
+            case 'removed':
+            case 'unlinked':
+                p.log.success('Rules disabled — removed rules directory');
+                break;
+            default: {
+                const unreachable = removal;
+                void unreachable;
+            }
         }
-        p.log.success('Rules disabled — removed rules directory');
     }
     else if (options.status) {
         let installedFiles = [];

package/dist/cli/commands/uninstall.js

@@ -37,8 +37,10 @@ import { probeTrackedArea } from '../../core/tracked-areas.js';
 import { restampInstalledCommands } from '../../targets/claude-code/language-stamp.js';
 import { installRenderedCharter, removeHandoffSentinel } from '../../targets/claude-code/charter-render.js';
 import { installCommandsAndAgents } from '../../targets/claude-code/installer.js';
+import { BACKUP_ROOT_NAME, escapeName } from '../../targets/claude-code/install-backup.js';
 import { isUnrealFolder, newLinkReport, refuseUnrealFolder, refusedFolderStatement } from '../../targets/claude-code/linked-folder.js';
 import { formatReplacedLinksSummary } from './install-report.js';
+import { judgeBareLegacySkill } from './legacy-sweep.js';
 /**
  * Where a retired repo-local install lives: `<gitRoot>/.claude` and `<gitRoot>/.devflow`.
  *
@@ -654,6 +656,9 @@ export function userContentPaths(devflowDir) {
         { relPath: 'skills', isDir: true, label: `skill shadows (${path.join(devflowDir, 'skills')})` },
         // Rule shadow overrides (~/.devflow/rules/{name}.md)
         { relPath: 'rules', isDir: true, label: `rule shadows (${path.join(devflowDir, 'rules')})` },
+        // The files an install moved out of the devflow folders because devflow did not ship them.
+        // They are the user's own files, so only a confirmed full wipe removes them.
+        { relPath: BACKUP_ROOT_NAME, isDir: true, label: `install backups (${path.join(devflowDir, BACKUP_ROOT_NAME)})` },
         // preference-profile.md — user-curated decision-preference profile
         { relPath: 'preference-profile.md', label: 'preference-profile.md' },
         // tracker/ — the inferred, hand-editable issue-tracker conventions, one file
@@ -921,7 +926,7 @@ export function installArtifactPaths(devflowDir) {
  * This function runs on the decline, cancel, non-interactive AND --keep-docs paths,
  * so an entry here is deleted even when the user answers "no" to the full wipe.
  * User-authored state (everything in `userContentPaths`: skill/rule shadows,
- * preference-profile.md, the tracker conventions with the legacy tracker.md and
+ * the install backups, preference-profile.md, the tracker conventions with the legacy tracker.md and
  * its backups, the global tuning file under both names, hud.json) is removed only by
  * the confirmed full-dir rm.
  * agent-models.json is an INSTALL ARTIFACT (stale per-agent overrides silently
@@ -1012,6 +1017,35 @@ export async function isDevFlowInstalled(claudeDir) {
     catch { /* skills dir absent or unreadable */ }
     return false;
 }
+/** Why a bare legacy skill folder stays: its `SKILL.md` is a file that no release of devflow installed. */
+const KEPT_NOT_MADE = 'devflow did not make this folder';
+/** Why a bare legacy skill folder stays: there is no regular `SKILL.md`, the folder or file is a link, or a read failed. */
+const KEPT_UNDECIDED = 'devflow could not tell if it made this folder';
+/**
+ * Sort the bare legacy skill folders that exist in `skillsDir` into those a full uninstall removes
+ * and those it keeps. The skills folder is shared with Claude Code and other tools, so a bare name
+ * (`python`, `plan`) does not prove that devflow made the folder. It is removed only when the check
+ * `devflow init` uses finds a `SKILL.md` that a release installed (`judgeBareLegacySkill`). The dry
+ * run and the removal both take this one list. A `devflow:` name is in the namespace of devflow, and
+ * the prefixed pass removes it. Reads one file per folder at most. Never throws.
+ */
+async function planBareLegacySkills(skillsDir) {
+    const remove = [];
+    const keep = [];
+    for (const name of new Set(LEGACY_SKILL_NAMES)) {
+        if (name.startsWith(SKILL_NAMESPACE))
+            continue;
+        const folder = path.join(skillsDir, name);
+        const verdict = await judgeBareLegacySkill(folder, name);
+        if (verdict === 'devflow')
+            remove.push(folder);
+        else if (verdict === 'other')
+            keep.push({ folder, reason: KEPT_NOT_MADE });
+        else if (verdict === 'unknown')
+            keep.push({ folder, reason: KEPT_UNDECIDED });
+    }
+    return { remove, keep };
+}
 // ---------------------------------------------------------------------------
 // Phase runners — extracted from the action function for readability and
 // independent testability.  Each covers one logical stage of the uninstall.
@@ -1029,9 +1063,10 @@ export async function isDevFlowInstalled(claudeDir) {
  *      and the scripts directory inside devflowDir.
  *   2. ALL skill removal candidates (existence-filtered):
  *      - Prefixed (devflow:name): live registry ∪ LEGACY_SKILL_NAMES.
- *      - Bare (name or devflow-name legacy): LEGACY_SKILL_NAMES ONLY.
- *        ~/.claude/skills/ is shared; bare dirs for live-registry skill names
- *        are by construction foreign to Devflow.
+ *      - Bare (name or devflow-name legacy): LEGACY_SKILL_NAMES ONLY, and only a
+ *        folder that devflow made (planBareLegacySkills). ~/.claude/skills/ is
+ *        shared; bare dirs for live-registry skill names are by construction
+ *        foreign to Devflow. A bare folder that stays is listed as `(kept: <reason>)`.
  *   3. manifest.json (removed separately in removeDevFlowInstallArtifacts).
  *   4. Every artifact path from installArtifactPaths(devflowDir) — the single
  *      source of truth shared with the real removal loop.
@@ -1057,8 +1092,8 @@ export async function enumerateDryRunExtras(claudeDir, devflowDir, folderWorkflo
     // 2. Skills: enumerate ALL removal candidates that exist on disk.
     // Mirrors removeAllDevFlow's split-pass approach:
     //   Prefixed: live registry ∪ LEGACY_SKILL_NAMES ∪ FEATURE_OWNED_SKILLS
-    //   Bare: LEGACY_SKILL_NAMES only — shared skills/ dir; live-registry bare
-    //         dirs are by construction foreign to Devflow.
+    //   Bare: LEGACY_SKILL_NAMES only, and only a folder that devflow made — shared
+    //         skills/ dir; live-registry bare dirs are by construction foreign to Devflow.
     // FEATURE_OWNED_SKILLS (compliance) is included so full uninstall removes
     // devflow:compliance even though it left the plugin registry (step 1.5).
     // The workflow skill folders (D-WORKFLOW-FOLDER-INSTALL) join through getAllSkillNames.
@@ -1072,14 +1107,10 @@ export async function enumerateDryRunExtras(claudeDir, devflowDir, folderWorkflo
         }
         catch { /* absent */ }
     }
-    for (const skillName of LEGACY_SKILL_NAMES) {
-        const barePath = path.join(skillsDir, skillName);
-        try {
-            await fs.access(barePath);
-            extras.push(barePath);
-        }
-        catch { /* absent */ }
-    }
+    const bareSkills = await planBareLegacySkills(skillsDir);
+    extras.push(...bareSkills.remove);
+    for (const { folder, reason } of bareSkills.keep)
+        extras.push(`${escapeName(folder)} (kept: ${reason})`);
     // 3. manifest.json — removed separately by removeDevFlowInstallArtifacts
     //    (NOT in installArtifactPaths). List it here so the preview is complete.
     const manifestPath = path.join(devflowDir, 'manifest.json');
@@ -1422,9 +1453,11 @@ export async function runSelectivePhaseForScope(opts) {
  * @param opts.isTTY            - Whether the session is interactive. Injected rather than
  *   read from process.stdin so the prompt gate is an explicit input (matching
  *   resolveDevflowDirCleanup) instead of an ambient global a test cannot control.
+ * @param opts.confirm          - The prompt for the full-dir wipe (default `p.confirm`).
  */
 export async function runFullPhaseForScope(opts) {
     const { scope, claudeDir, devflowDir, devflowScriptsDir, verbose, keepDocs, isTTY } = opts;
+    const confirm = opts.confirm ?? p.confirm;
     // D-CLI-NO-SYMLINK: a legacy local install's removals and rewrites pass this first.
     const mayChange = scopeChangeGuard(scope, { claudeDir, devflowDir });
     // Revert GPT agent frontmatter before removing agents — ensures no orphaned
@@ -1482,7 +1515,7 @@ export async function runFullPhaseForScope(opts) {
             for (const item of userContent) {
                 p.log.info(`  ${item}`);
             }
-            const confirmFullCleanup = await p.confirm({
+            const confirmFullCleanup = await confirm({
                 message: `Remove entire ${devflowDir}? (includes the items listed above, plus logs and install metadata)`,
                 initialValue: false,
             });
@@ -2005,10 +2038,11 @@ export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose, ma
     //     prefixSkillName() is idempotent for already-prefixed legacy entries.
     //     FEATURE_OWNED_SKILLS (compliance) is included so full uninstall removes
     //     devflow:compliance even though it left the plugin registry (step 1.5).
-    //   Bare pass (name or devflow-name legacy): LEGACY_SKILL_NAMES ONLY.
-    //     A bare dir whose name matches a live-registry skill is by construction
-    //     foreign to Devflow (the devflow: namespace shipped in dcecda3, 2026-03-30).
-    //     A bare 'compliance/' dir is also foreign (not in LEGACY_SKILL_NAMES).
+    //   Bare pass (name or devflow-name legacy): LEGACY_SKILL_NAMES ONLY, and only a folder
+    //     whose SKILL.md is a copy that a release of devflow installed (planBareLegacySkills).
+    //     Any other bare folder stays and is named. A bare dir whose name matches a
+    //     live-registry skill is by construction foreign to Devflow (the devflow: namespace
+    //     shipped in dcecda3, 2026-03-30). A bare 'compliance/' dir is also foreign (not in LEGACY_SKILL_NAMES).
     //   The workflow skill folders (D-WORKFLOW-FOLDER-INSTALL) are in getAllSkillNames, so the folder is removed.
     const prefixedSkillNames = new Set([...getAllSkillNames(folderWorkflows), ...LEGACY_SKILL_NAMES, ...FEATURE_OWNED_SKILLS]);
     const skillsDir = path.join(claudeDir, 'skills');
@@ -2025,17 +2059,21 @@ export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose, ma
         }
         catch { /* Skill doesn't exist */ }
     }
-    for (const skillName of LEGACY_SKILL_NAMES) {
-        // Remove bare variant — frozen legacy list only, never the live registry
-        const barePath = path.join(skillsDir, skillName);
+    // Bare variant: frozen legacy list only, never the live registry, and only a folder that devflow made.
+    const bareSkills = await planBareLegacySkills(skillsDir);
+    for (const barePath of bareSkills.remove) {
         try {
-            await fs.stat(barePath);
             if (!(await mayChange(barePath)))
                 continue;
             await fs.rm(barePath, { recursive: true, force: true });
             skillsRemoved++;
         }
-        catch { /* Skill doesn't exist */ }
+        catch (error) {
+            p.log.warn(`Could not remove ${escapeName(barePath)}: ${error}`);
+        }
+    }
+    for (const { folder, reason } of bareSkills.keep) {
+        p.log.info(`Kept ${escapeName(folder)}: ${reason}`);
     }
     if (skillsRemoved > 0 && verbose) {
         p.log.success(`Removed ${skillsRemoved} Devflow skill directories`);

package/dist/core/compliance.js

@@ -31,6 +31,20 @@ export const COMPLIANCE_RULE_PLACEHOLDER = '${DEVFLOW_COMPLIANCE_FRAMEWORKS}';
  * definition. Adding a third always-present ref requires only one change here.
  */
 export const ALWAYS_PRESENT_REFS = ['detection.md', 'sources.md'];
+/**
+ * Every file the installed compliance skill folder holds, as POSIX paths below it: `SKILL.md`, the
+ * always-present references, and one `references/{id}.md` per registry framework. The install
+ * writes all of them on every machine whatever the selection (D-COMPLIANCE-INSTALL-ALWAYS), so
+ * this is also the set a scan treats as shipped. The skill source holds more (the framework
+ * fragments), which the install does not copy.
+ */
+export function complianceSkillFiles() {
+    return [
+        'SKILL.md',
+        ...ALWAYS_PRESENT_REFS.map(ref => `references/${ref}`),
+        ...COMPLIANCE_FRAMEWORKS.map(fw => `references/${fw.id}.md`),
+    ];
+}
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------

package/dist/core/fs-atomic.js

@@ -10,6 +10,10 @@ import { promises as fs } from 'fs';
  * intentionally remains a separate implementation — same semantics, different module
  * system. Any change to the retry logic here MUST be mirrored there.
  */
+/** The sibling `filePath` is written to before the rename: `<file>.tmp.<pid>`. */
+export function atomicTempPath(filePath) {
+    return `${filePath}.tmp.${process.pid}`;
+}
 /**
  * Atomically write `filePath` by writing to a sibling `.tmp` then renaming.
  *
@@ -38,7 +42,7 @@ export async function writeFileAtomicExclusive(filePath, data, createMode) {
     // (e.g., two Claude Code sessions) never collide on the same .tmp path.
     // mirrors proxy-log.ts rotation at src/core/proxy-log.ts which PID-scopes
     // for the same reason.
-    const tmp = `${filePath}.tmp.${process.pid}`;
+    const tmp = atomicTempPath(filePath);
     const options = { encoding: 'utf-8', flag: 'wx', ...(createMode === undefined ? {} : { mode: createMode }) };
     try {
         await fs.writeFile(tmp, data, options);

package/dist/core/orphan-sweep.js

@@ -59,6 +59,10 @@ export function mdEntryName(entry) {
  *   that `dir` is a real folder before the call, because the sweep reads and
  *   removes inside whatever `dir` names.
  *
+ * @param removal - How an admitted orphan is removed ({@link SweepRemoval}). Defaults to
+ *   `recursive`. With `unlink`, an entry that has become a folder since the check stays and is
+ *   recorded in `failed`; an entry that has vanished since the check counts as removed.
+ *
  * @returns A {@link SweepResult} reporting how many entries were scanned, which
  *   registry names were removed, and which removals failed.
  *   `scanned` is the count matched by the predicate (not the removed count) —
@@ -70,7 +74,7 @@ export function mdEntryName(entry) {
  * individual removal is recorded in `failed` without aborting the sweep.
  * Never writes, only removes — no delete-then-write window.
  */
-export async function sweepOrphanedAssets(dir, knownNames, extractRegistryName, mayRemove) {
+export async function sweepOrphanedAssets(dir, knownNames, extractRegistryName, mayRemove, removal = 'recursive') {
     const removed = [];
     const failed = [];
     let scanned = 0;
@@ -86,7 +90,7 @@ export async function sweepOrphanedAssets(dir, knownNames, extractRegistryName,
                 try {
                     if (mayRemove !== undefined && !(await mayRemove(entryPath)))
                         continue;
-                    await fs.rm(entryPath, { recursive: true, force: true });
+                    await removeEntry(entryPath, removal);
                     removed.push(registryName);
                 }
                 catch (err) {
@@ -98,4 +102,18 @@ export async function sweepOrphanedAssets(dir, knownNames, extractRegistryName,
     catch { /* directory absent or unreadable — not an error */ }
     return { scanned, removed, failed };
 }
+/** Remove one orphan as `removal` says. An absent entry is already removed, as `fs.rm` with `force` treats it. */
+async function removeEntry(entryPath, removal) {
+    if (removal === 'recursive') {
+        await fs.rm(entryPath, { recursive: true, force: true });
+        return;
+    }
+    try {
+        await fs.unlink(entryPath);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+}
 //# sourceMappingURL=orphan-sweep.js.map

package/dist/core/path-set.js

@@ -0,0 +1,15 @@
+/** Build a {@link PathSet} from file paths: the folder prefixes are computed once. */
+export function createPathSet(files) {
+    const all = new Set(files);
+    const folders = new Set();
+    for (const file of all) {
+        for (let cut = file.indexOf('/'); cut !== -1; cut = file.indexOf('/', cut + 1)) {
+            folders.add(file.slice(0, cut));
+        }
+    }
+    return Object.freeze({
+        files: all,
+        holds: (folder) => all.has(folder) || folders.has(folder),
+    });
+}
+//# sourceMappingURL=path-set.js.map

package/dist/core/plugins.js

@@ -640,11 +640,12 @@ export function parsePluginSelection(input, validPlugins) {
 /**
  * Deprecated command names from old installations.
  * Used during init to clean up stale command files on upgrade.
+ *
+ * Each name is a command file that a release installed. The cleanup removes such a file with no
+ * backup, so a name that no release shipped does not belong here.
  */
 export const LEGACY_COMMAND_NAMES = [
-    'review',
     'specify',
-    'specify-teams',
 ];
 /** A command entry of a plugin without its leading `/`. */
 function commandName(cmd) {