devflow-kit 3.10.0 → 3.12.0

package/dist/cli/commands/init.js

@@ -15,9 +15,11 @@ import { describeMoveText, describeOutcome, runInitCurationMove, shownSkipAt } f
 import { realGlobalTuningMoveIO, realProjectLedgerMoveIO } from './curation-move-io.js';
 import { describeEchoedValue } from '../../core/echo-value.js';
 import { installViaFileCopy, installScripts } from '../../targets/claude-code/installer.js';
-import { formatLinksSummary, formatOverlaySummary, formatSkillScopeSummary, formatTrackerAssetSummary, isPluginListUnchanged } from './install-report.js';
+import { logSummaryLines, openBackupSession, runWithLateBackupReport } from './backup-session.js';
+import { formatKeptLegacySkills, formatLinksSummary, formatOverlaySummary, formatSkillScopeSummary, formatTrackerAssetSummary, isPluginListUnchanged } from './install-report.js';
 import { mergeLinkReports, newLinkReport } from '../../targets/claude-code/linked-folder.js';
-import { sweepLegacyDevflowFiles } from './legacy-sweep.js';
+import { sweepLegacyDevflowFiles, sweepLegacySkillFolders } from './legacy-sweep.js';
+import { removeRulesFolder, rulesFolderRefusedMessage } from '../../targets/claude-code/rules-folder.js';
 import { convergeTrackerArtifacts } from '../../targets/claude-code/tracker-install.js';
 import { installSettings, installManagedSettings, installClaudeignore, hasClaudeignore, discoverProjectGitRoots, ensureDevflowGitignore, applyUserSecurityDenyList, detectDenyState, resolveSecurityAction, assertHistoricalDenySuperset, loadTemplateDenyEntries, stripUserSecurityDenyList, } from '../../targets/claude-code/post-install.js';
 import { DEVFLOW_PLUGINS, registeredPluginNames, buildAssetMaps, buildScopedSkillsMap, buildRulesMap, partitionSelectablePlugins, WORKFLOW_ORDER, parsePluginSelection, resolveFeatureRedirect } from '../../core/plugins.js';
@@ -119,34 +121,6 @@ export function formatSweepSummary(report) {
     }
     return lines;
 }
-/**
- * Log each summary line at the severity it carries — the one dispatch every
- * `SummaryLine[]` renderer shares.
- *
- * Exhaustive over `SummaryLine['level']` rather than an `if/else`: a level added
- * to the interface has to be routed here, at compile time, instead of silently
- * degrading to `info` at every call site.
- */
-function logSummaryLines(lines) {
-    for (const line of lines) {
-        switch (line.level) {
-            case 'success':
-                p.log.success(line.message);
-                break;
-            case 'info':
-                p.log.info(line.message);
-                break;
-            case 'warn':
-                p.log.warn(line.message);
-                break;
-            default: {
-                const _exhaustive = line.level;
-                void _exhaustive;
-                break;
-            }
-        }
-    }
-}
 /**
  * Converge the installed agents onto the saved model and effort assignments, after the file copy
  * wrote the shipped defaults. Per-item failures are non-fatal.
@@ -766,7 +740,7 @@ export const initCommand = new Command('init')
     .option('--recommended', 'Apply recommended defaults after plugin selection (skip advanced prompts)')
     .option('--advanced', 'Show all configuration prompts')
     .option('--reset', 'Factory reset — restore all defaults, ignoring prior installation state')
-    .action(async (options) => {
+    .action((options) => runWithLateBackupReport(async (backupReport) => {
     // Get package version
     const packageJsonPath = path.join(getPackageRoot(), 'package.json');
     let version = '';
@@ -1822,6 +1796,17 @@ export const initCommand = new Command('init')
     const { agentsMap } = buildAssetMaps(pluginsToInstall);
     // Rules: install only from selected plugins (plugin-scoped, not universal)
     const rulesMap = rulesEnabled ? buildRulesMap(pluginsToInstall) : new Map();
+    // The one backup session of this run, made before any change. The install and the converge
+    // after it share it, so the run makes at most one backup folder. When the shipped set cannot
+    // be built, init changes nothing.
+    const openedBackups = await openBackupSession({ claudeDir, devflowDir });
+    if (!openedBackups.ok) {
+        s.stop('Installation failed');
+        p.log.error(openedBackups.message);
+        process.exit(1);
+    }
+    const backups = openedBackups.session;
+    backupReport.begin(backups);
     // D32/D35: Apply one-time migrations (global + per-project) tracked at ~/.devflow/migrations.json.
     // Migrations clean up ~/.devflow runtime data and never touch the installer's copy
     // targets, so their position relative to installViaFileCopy carries no dependency.
@@ -1878,11 +1863,14 @@ export const initCommand = new Command('init')
             // generated reference tree, mode-normalisation failures) reach the user rather
             // than the void. Collected now, emitted after the spinner stops.
             warn: (msg) => { installWarnings.push(msg); },
+            backups,
         });
     }
     catch (error) {
         s.stop('Installation failed');
         p.log.error(`${error}`);
+        // A file the install moved aside before it failed is named now: nothing runs after the exit.
+        backupReport.print();
         process.exit(1);
     }
     // The one converge for both switches (D-LEARNING-VARIANT-INSTALL, AC-27): the file copy
@@ -1906,6 +1894,7 @@ export const initCommand = new Command('init')
         },
         plugins: effectivePlugins,
         warn: (msg) => installWarnings.push(msg),
+        backups,
     });
     if (verbose && variantConverge.converged) {
         p.log.info(`Curation ${curationEnabled ? 'on' : 'off'}, compliance ${complianceEnabled ? 'on' : 'off'} variants: ` +
@@ -1943,29 +1932,22 @@ export const initCommand = new Command('init')
     if (behaviorEnabled && !rulesEnabled) {
         p.log.info('Behavior rule is on but rules are disabled, so it is not installed — run `devflow rules --enable`.');
     }
-    // Clean up stale skills from previous installations
+    // Stale skill folders from previous installations move whole to the backup folder and are named,
+    // but a bare folder moves only when its SKILL.md is a copy that a release of devflow installed.
+    // A bare folder that the check cannot judge stays where it is, and is named here.
     s.message('Cleaning up');
-    const skillsDir = path.join(claudeDir, 'skills');
-    const skillRemoveResults = await Promise.allSettled(LEGACY_SKILL_NAMES.map(legacy => fs.rm(path.join(skillsDir, legacy), { recursive: true })));
-    const staleRemoved = skillRemoveResults.filter(r => r.status === 'fulfilled').length;
-    if (staleRemoved > 0 && verbose) {
-        p.log.info(`Cleaned up ${staleRemoved} legacy skill(s)`);
-    }
+    const legacySkills = await sweepLegacySkillFolders({ claudeDir, backups, legacySkills: LEGACY_SKILL_NAMES });
+    logSummaryLines(formatKeptLegacySkills(legacySkills.kept));
     // Clean up stale commands (e.g., /review → /code-review) and rules from previous installations.
     // A folder the install refused, or that is a link, is not swept: nothing is read or removed through it.
-    const { staleCommandsRemoved, staleRulesRemoved } = await sweepLegacyDevflowFiles({ claudeDir, report: installReport });
-    if (staleCommandsRemoved > 0 && verbose) {
-        p.log.info(`Cleaned up ${staleCommandsRemoved} legacy command(s)`);
-    }
-    if (staleRulesRemoved > 0 && verbose) {
-        p.log.info(`Cleaned up ${staleRulesRemoved} legacy rule(s)`);
-    }
-    // Disable rules directory if rules not enabled
+    // Each removed file is named on the retired line of the backup record.
+    await sweepLegacyDevflowFiles({ claudeDir, report: installReport, backups });
+    // Disable rules directory if rules not enabled: the files devflow did not ship move aside first.
     if (!rulesEnabled) {
-        try {
-            await fs.rm(path.join(claudeDir, 'rules', 'devflow'), { recursive: true, force: true });
+        const rulesFolder = path.join(claudeDir, 'rules', 'devflow');
+        if ((await removeRulesFolder(rulesFolder, backups)) === 'refused') {
+            p.log.warn(rulesFolderRefusedMessage(rulesFolder));
         }
-        catch { /* ignore */ }
     }
     // Clean up legacy hook scripts and lib files left by prior installs
     // (paths relative to hooksDir; copyDirectory is additive, so stale files
@@ -2007,12 +1989,11 @@ export const initCommand = new Command('init')
     ];
     const hooksDir = path.join(devflowDir, 'scripts', 'hooks');
     for (const legacy of LEGACY_HOOK_FILES) {
-        const legacyPath = path.join(hooksDir, legacy);
-        try {
-            await fs.rm(legacyPath);
-        }
-        catch { /* doesn't exist */ }
+        await backups.removeExact(path.join(hooksDir, legacy));
     }
+    // Every step that moves or removes files in devflow's folders has run: name what the session
+    // moved aside, ahead of the summary below. A throw before this point prints it on the way out.
+    backupReport.print();
     // The curation move (#529): after the legacy sweep, before the manifest persist and
     // the disabled-feature drain below, so the drain sees the moved folder. Its lines
     // and its one notice print with the install warnings, after the spinner stops.
@@ -2611,5 +2592,5 @@ export const initCommand = new Command('init')
         p.log.info(`External model routing: ${color.green('enabled')} — takes effect in new Claude Code sessions`);
     }
     p.outro(color.green('Ready! Run any command in Claude Code to get started.'));
-});
+}));
 //# sourceMappingURL=init.js.map

package/dist/cli/commands/install-report.js

@@ -9,6 +9,7 @@
  */
 import color from 'picocolors';
 import { overlayUnitLabel } from '../../targets/claude-code/installer.js';
+import { escapeName, formatCappedList } from '../../targets/claude-code/install-backup.js';
 import { refusedFolderMessage, replacedLinkMessage } from '../../targets/claude-code/linked-folder.js';
 import { SKILL_REFS_SKILL_NAME } from '../../core/mds-variants.js';
 import { prefixSkillName } from '../../core/plugins.js';
@@ -231,4 +232,98 @@ export function formatSkillScopeSummary(report, pluginListUnchanged) {
     }
     return lines;
 }
+const BACKUP_SHOWN_UNITS = 5;
+/** One moved unit as `original -> backup`; a folder carries a trailing slash. */
+function movedUnitLabel(unit) {
+    const slash = unit.kind === 'directory' ? '/' : '';
+    return `${unit.original}${slash} -> ${unit.backup}${slash}`;
+}
+function failureLine(failure) {
+    const where = escapeName(failure.path);
+    const reason = escapeName(failure.reason);
+    switch (failure.action) {
+        case 'move':
+            return { level: 'warn', message: `Could not move ${where} to the backup folder (${reason}) — it stays where it is` };
+        case 'scan':
+            return { level: 'warn', message: `Could not scan ${where} (${reason}) — nothing in it was moved or removed` };
+        case 'remove':
+            return { level: 'warn', message: `Could not remove ${where} (${reason}) — it stays where it is` };
+        default: {
+            const _exhaustive = failure.action;
+            void _exhaustive;
+            return { level: 'warn', message: `Could not finish a step on ${where} (${reason})` };
+        }
+    }
+}
+/**
+ * The lines for the bare legacy skill folders that init kept because it could not tell if devflow
+ * made them (`sweepLegacySkillFolders`): one line per folder for the first five, then one line that
+ * counts the rest. A run that kept none gives no lines. Every printed path goes through `escapeName`.
+ */
+export function formatKeptLegacySkills(kept) {
+    const lines = kept.slice(0, BACKUP_SHOWN_UNITS).map((folder) => ({
+        level: 'info',
+        message: `Kept ${escapeName(folder)}: devflow could not tell if it made this folder`,
+    }));
+    if (kept.length > BACKUP_SHOWN_UNITS) {
+        lines.push({ level: 'info', message: `Kept ${kept.length - BACKUP_SHOWN_UNITS} more folder(s) for the same reason` });
+    }
+    return lines;
+}
+/**
+ * Turn the backup session's record into summary lines: what moved aside, what stayed because it
+ * could not move, and which retired files were removed. An empty snapshot gives no lines, so a
+ * clean run prints nothing.
+ *
+ * A move is not a removal. The moved line has its own wording and counts only moved units (a moved
+ * folder is one), and it never feeds the "Removed N orphaned asset(s)" line of `formatSweepSummary`.
+ * One removed name prints on one line only, by the kind of removal:
+ *
+ *   - the retired line below lists the retired files the session removed itself, with
+ *     `BackupSession.removeListed` (the earlier releases' commands, agents, rules and skill files)
+ *     or `BackupSession.removeExact` (the legacy sweep's command and rule names, and the legacy
+ *     hook scripts);
+ *   - `formatSweepSummary` lists the names the registry-diff sweeps removed, which the install
+ *     report records in `sweptOrphans`. A sweep removes a name only after the session has not,
+ *     and the session removes no name that a sweep records.
+ *
+ * Every printed name goes through `escapeName`. Pure function — returns lines, logs nothing.
+ */
+export function formatBackupSummary(snapshot) {
+    const lines = [];
+    if (snapshot.moved.length > 0) {
+        lines.push({
+            level: 'info',
+            message: `Moved ${snapshot.moved.length} item(s) that devflow does not ship out of its folders: ` +
+                formatCappedList(snapshot.moved.map(movedUnitLabel), BACKUP_SHOWN_UNITS),
+        });
+        if (snapshot.runFolder !== null) {
+            lines.push({ level: 'info', message: `Backup folder: ${escapeName(snapshot.runFolder)}` });
+        }
+    }
+    if (snapshot.retiredRemoved.length > 0) {
+        lines.push({
+            level: 'info',
+            message: `Removed ${snapshot.retiredRemoved.length} retired devflow file(s): ` +
+                formatCappedList(snapshot.retiredRemoved, BACKUP_SHOWN_UNITS),
+        });
+    }
+    for (const failure of snapshot.failures)
+        lines.push(failureLine(failure));
+    for (const hit of snapshot.capHits) {
+        lines.push({
+            level: 'warn',
+            message: `${escapeName(hit.folder)} holds ${hit.entries} entries, more than the limit of ${hit.cap} — ` +
+                'devflow left it whole and moved nothing out of it',
+        });
+    }
+    if (snapshot.rootRefusal !== null) {
+        lines.push({
+            level: 'warn',
+            message: `Could not use the backup folder ${escapeName(snapshot.rootRefusal.path)} ` +
+                `(${escapeName(snapshot.rootRefusal.reason)}) — nothing was moved aside in this run`,
+        });
+    }
+    return lines;
+}
 //# sourceMappingURL=install-report.js.map

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 = [];