devflow-kit 3.10.0 → 3.11.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to Devflow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.11.0] - 2026-10-31
+
+### Upgrade notes — Files that devflow moves to a backup folder
+
+**What you must do:**
+- Nothing. If `devflow init` moves a file of yours, the output names the file and its new path.
+- To restore a moved file, copy it from the backup folder, `~/.devflow/install-backups/<UTC stamp>-<8 hex>/`, to one of its stable homes. Skills: `~/.devflow/skills/<name>/`. Rules: `~/.devflow/rules/`. Commands and agents: the top-level `commands/` and `agents/` folders of the Claude directory, outside the `devflow/` subfolders. A file that you put back into a devflow folder moves again on the next `devflow init`.
+
+**What to know:**
+- The backup is not encrypted. Devflow never prunes it. It stays until you delete it or run a full uninstall.
+- A file of yours with the same name as a shipped file is overwritten without a report.
+- Relative links in a moved folder can break.
+- Concurrent devflow runs are not supported.
+
+### Behaviour change
+
+- **Devflow now names the retired files that it removes, and it moves bare legacy skill folders instead of deleting them** ([#688](https://github.com/dean0x/devflow/issues/688)).
+  - `devflow init` and the toggles print each retired devflow file that they remove. Before, most of these removals printed nothing.
+  - A bare legacy skill folder, such as `skills/python` (a name from releases before v2), is now moved whole to the backup folder and named, but only when its `SKILL.md` is a copy that a release of devflow installed. Before, `devflow init` deleted every such folder. A skill of your own with such a name stays where it is. A folder that devflow cannot judge (no `SKILL.md`, or a link) also stays, and the output names it.
+  - A full `devflow uninstall` now removes a bare legacy skill folder, such as `skills/python`, only when its `SKILL.md` is a copy that a release of devflow installed. Before, it deleted every folder with such a name, without a backup, so a skill of your own with that name was lost. A skill of your own stays where it is. A folder that devflow cannot judge (no `SKILL.md`, or a link) also stays. The output names each folder that stays, and `--dry-run` lists the same folders. A `devflow:`-prefixed skill folder is removed as before.
+  - An interactive `devflow uninstall` where the install backups are the only user content in `~/.devflow` now asks before the full wipe. The prompt lists the backup folder, and a decline keeps the backups.
+
+### Fixed
+
+- **`devflow init` and the curation, compliance and rules toggles no longer delete files that devflow did not ship** ([#688](https://github.com/dean0x/devflow/issues/688)).
+  - A file that you keep in `commands/devflow/`, `agents/devflow/`, `rules/devflow/`, a `skills/devflow:*` folder or its `references/` folders is now moved to `~/.devflow/install-backups/<UTC stamp>-<8 hex>/`, and the output names it. Before, these commands deleted it. This holds for a full install, for a partial install (`--plugin`) and for the three toggles.
+  - A file that cannot move stays in place with its folder, and the output names it.
+
+---
+
 ## [3.10.0] - 2026-10-30
 
 ### Upgrade notes — Shadowed rules and skills
@@ -2338,6 +2368,7 @@ devflow init
 ---
 
 [Unreleased]: https://github.com/dean0x/devflow/compare/v3.8.0...HEAD
+[3.11.0]: https://github.com/dean0x/devflow/compare/v3.10.0...v3.11.0
 [3.10.0]: https://github.com/dean0x/devflow/compare/v3.9.0...v3.10.0
 [3.9.0]: https://github.com/dean0x/devflow/compare/v3.8.0...v3.9.0
 [3.8.0]: https://github.com/dean0x/devflow/compare/v3.7.0...v3.8.0

package/dist/cli/commands/backup-session.js

@@ -0,0 +1,131 @@
+/**
+ * The backup session of one command run: made once, before the command changes anything, and its
+ * record printed once when the command ends.
+ *
+ * `devflow init`, `devflow curation`, `devflow compliance` and `devflow rules` each make one
+ * session with {@link openBackupSession} and wrap the steps that may move or remove files in
+ * {@link runWithBackupReport}. The wrapper prints the record after the steps return or throw, so a
+ * run that moved a file and then failed still names where the file went.
+ */
+import { randomBytes } from 'crypto';
+import * as p from '@clack/prompts';
+import { WORKFLOW_FOLDERS } from '../../core/mds-variants.js';
+import { getPackageRoot } from '../../core/paths.js';
+import { retiredPathSet } from '../../core/retired-shipped-names.js';
+import { createBackupSession } from '../../targets/claude-code/install-backup.js';
+import { loadShippedSet } from '../../targets/claude-code/shipped-set.js';
+import { formatBackupSummary } from './install-report.js';
+/**
+ * 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.
+ */
+export 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;
+            }
+        }
+    }
+}
+/**
+ * Make the backup session of a command run, before the command changes anything.
+ *
+ * The shipped set comes from the full registries and the package source, never from what an
+ * earlier install left on disk. When it cannot be built the answer is a message and no session:
+ * a session with a smaller set would move devflow's own files aside. The caller prints the
+ * message, exits non-zero and changes nothing.
+ */
+export async function openBackupSession(options) {
+    const loaded = await loadShippedSet({
+        devflowDir: options.devflowDir,
+        packageRoot: options.packageRoot ?? getPackageRoot(),
+        workflowFolders: WORKFLOW_FOLDERS,
+    });
+    if (!loaded.ok) {
+        return {
+            ok: false,
+            message: `Could not list the files devflow ships, so nothing was changed: ${loaded.reason}`,
+        };
+    }
+    const session = createBackupSession({
+        shipped: loaded.shipped,
+        retired: retiredPathSet(),
+        claudeDir: options.claudeDir,
+        devflowDir: options.devflowDir,
+        now: () => new Date(),
+        bytes: size => randomBytes(size),
+    });
+    return { ok: true, session };
+}
+/**
+ * The session of a command that reports its failures through the exit code: the session, or null
+ * after one error line and exit code 1. The caller then returns without a change.
+ */
+export async function openBackupSessionOrFail(options) {
+    const opened = await openBackupSession(options);
+    if (opened.ok)
+        return opened.session;
+    p.log.error(opened.message);
+    process.exitCode = 1;
+    return null;
+}
+/**
+ * Run `fn`, which makes its session part-way through (it calls `begin`), and print the record of
+ * that session once: at its own `print` call, or else after `fn` returns or throws and before the
+ * caller returns or rethrows. A step that ends the process (`process.exit`) calls `print` first,
+ * since nothing after an exit runs. A throw from `fn` passes on unchanged, and a run that never
+ * calls `begin` prints nothing.
+ *
+ * @param emit - Where the lines go. Defaults to the clack log.
+ */
+export async function runWithLateBackupReport(fn, emit = logSummaryLines) {
+    let session = null;
+    let printed = false;
+    const report = {
+        begin: (opened) => { session = opened; },
+        print: () => {
+            if (printed || session === null)
+                return;
+            printed = true;
+            emit(formatBackupSummary(session.snapshot()));
+        },
+    };
+    try {
+        return await fn(report);
+    }
+    finally {
+        report.print();
+    }
+}
+/**
+ * Run `fn` and print the record of `session` once, after `fn` returns or throws and before the
+ * caller returns, rethrows or exits. A throw from `fn` passes on unchanged.
+ *
+ * `fn` receives `printBackups`, which prints the record at once and is a no-op afterwards: a step
+ * that ends the process (`process.exit`) calls it first, since nothing after an exit runs.
+ *
+ * @param emit - Where the lines go. Defaults to the clack log.
+ */
+export function runWithBackupReport(session, fn, emit = logSummaryLines) {
+    return runWithLateBackupReport(async (report) => {
+        report.begin(session);
+        return fn(report.print);
+    }, emit);
+}
+//# sourceMappingURL=backup-session.js.map

package/dist/cli/commands/compliance.js

@@ -21,6 +21,7 @@ import * as path from 'path';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
 import { COMPLIANCE_FRAMEWORKS, normalizeFrameworks, parseFrameworkList, } from '../../core/compliance.js';
+import { openBackupSessionOrFail, runWithBackupReport } from './backup-session.js';
 import { frameworkChoices, FRAMEWORK_SELECT_MESSAGE } from './compliance-prompts.js';
 import { COMPLIANCE_SKILL_TOKENS } from '../../core/compliance-compose.js';
 import { evidencePolicyStatusLine, evidencePolicySuggestion, formatEvidencePolicyUnavailable, loadEvidencePolicyModule, loadSettingsModule, repoComplianceStatusLines, } from '../../core/evidence-policy.js';
@@ -213,10 +214,15 @@ async function recordComplianceSwitch(devflowDir, nextState) {
  * A reference that the converge could not refresh, a linked folder for example, is an error that
  * names it, with exit 1, and the switch stays recorded as on.
  *
- * Returns a result and never throws; the caller prints the messages and sets the exit code.
+ * Returns a result and never throws; the caller prints the messages and sets the exit code. The
+ * record of the backup session prints once, as the change returns (an exit-1 result included),
+ * ahead of the messages.
  */
-export async function applyComplianceChange(opts) {
-    const { claudeDir, devflowDir, manifest, action, setFrameworks, runningVersion, packageRoot, warn } = opts;
+export function applyComplianceChange(opts) {
+    return runWithBackupReport(opts.backups, () => applyChange(opts));
+}
+async function applyChange(opts) {
+    const { claudeDir, devflowDir, manifest, action, setFrameworks, runningVersion, packageRoot, warn, backups } = opts;
     const resolved = resolveComplianceCliAction(manifest.features.compliance, action, setFrameworks);
     // normalizeFrameworks deduplicates (e.g. --set gdpr,GDPR → [gdpr]).
     const nextState = {
@@ -240,6 +246,7 @@ export async function applyComplianceChange(opts) {
         runningVersion,
         warn,
         packageRoot,
+        backups,
     });
     if (outcome.kind === 'skipped') {
         // The compliance skill and rule do not depend on the installed version, so they converge
@@ -249,6 +256,7 @@ export async function applyComplianceChange(opts) {
             devflowDir,
             manifest: { features: { compliance: nextState, rules: manifest.features.rules } },
             warn,
+            backups,
         });
         if (!nextState.enabled) {
             return { nextState, messages: [{ level: 'error', text: outcome.message }], exitCode: 1 };
@@ -422,6 +430,10 @@ export const complianceCommand = new Command('compliance')
     else {
         action = 'disable';
     }
+    // The session comes before the first change. Without a shipped set the command changes nothing.
+    const backups = await openBackupSessionOrFail({ claudeDir, devflowDir });
+    if (backups === null)
+        return;
     // Write the switch, converge both axes, record the installed variants (applyComplianceChange).
     const applied = await applyComplianceChange({
         claudeDir,
@@ -431,6 +443,7 @@ export const complianceCommand = new Command('compliance')
         setFrameworks,
         runningVersion: await readRunningVersion(),
         warn: (msg) => p.log.warn(msg),
+        backups,
     });
     // Emit messages
     for (const msg of applied.messages) {

package/dist/cli/commands/curation.js

@@ -9,6 +9,7 @@ import { loadShippedAgentDefaults } from '../../core/agent-models.js';
 import { readMachineFeature, writeMachineFeature } from '../../core/feature-switch.js';
 import { loadSettingsModule, narrowedSwitchLabel, personalConfigTrackedWarning } from '../../core/evidence-policy.js';
 import { getClaudeDirectory, getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
+import { openBackupSessionOrFail, runWithBackupReport } from './backup-session.js';
 import { applyVariantToggle, describeCurationConverge, describePostingLeft, installedScriptsSkew, readRunningVersion, } from '../../targets/claude-code/curation-install.js';
 import { getLedgerRoot } from '../../core/ledger-root.js';
 import { AREA_PAUSE_NOTICE } from '../../core/area-pause-notice.js';
@@ -657,16 +658,19 @@ async function handleClear() {
  * this CLI writes. The toggle moves the ledger folder only then: under version skew
  * (or when that could not be told) it moves nothing.
  */
-async function convergeInstalledVariants(enabled) {
+export async function convergeInstalledVariants(enabled, backups) {
     try {
-        const outcome = await applyVariantToggle({
+        // The record of the session prints when the toggle returns or throws, ahead of the warning
+        // below, so a file moved aside before a failure is still named.
+        const outcome = await runWithBackupReport(backups, async () => applyVariantToggle({
             claudeDir: getClaudeDirectory(),
             devflowDir: getDevFlowDirectory(),
             axis: 'curation',
             enabled,
             runningVersion: await readRunningVersion(),
             warn: (msg) => p.log.warn(msg),
-        });
+            backups,
+        }));
         if (outcome.kind === 'skipped') {
             p.log.warn(outcome.message);
             return 'not-converged';
@@ -721,13 +725,17 @@ async function tryMoveForToggle(ledgerRoot) {
  * tries the shared move with no wait. Only `--disable` drains, skew included.
  */
 async function handleToggle(enabled) {
+    // The session comes before the first change. Without a shipped set the toggle changes nothing.
+    const backups = await openBackupSessionOrFail({ claudeDir: getClaudeDirectory(), devflowDir: getDevFlowDirectory() });
+    if (backups === null)
+        return;
     const recorded = await writeMachineFeature(getDevFlowDirectory(), 'curation', enabled);
     if (!recorded.ok) {
         p.log.error(`Devflow is not installed on this machine — run ${color.cyan('devflow init')} first`);
         process.exitCode = 1;
         return;
     }
-    const converged = await convergeInstalledVariants(enabled);
+    const converged = await convergeInstalledVariants(enabled, backups);
     const ledgerRoot = await getLedgerRoot();
     const shownSkip = converged === 'converged' && ledgerRoot ? await tryMoveForToggle(ledgerRoot) : null;
     if (enabled) {

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