devflow-kit 3.8.0 → 3.10.0

package/dist/cli/commands/uninstall.js

@@ -7,8 +7,8 @@ import color from 'picocolors';
 import { getInstallationPaths, getClaudeDirectory, getHomeDirectory, getManagedSettingsPath } from '../../targets/claude-code/claude-paths.js';
 import { getGitRoot } from '../../core/git.js';
 import { isSameLocation } from '../../core/same-location.js';
-import { DEVFLOW_PLUGINS, SKILL_NAMESPACE, buildAssetMaps, getAllSkillNames, getAllAgentNames, getAllCommandNames, parsePluginSelection, resolveFeatureRedirect, prefixSkillName, unprefixSkillName, skillsOf, FEATURE_OWNED_SKILLS } from '../../core/plugins.js';
-import { readManifest, removeManifestPlugins } from '../../core/manifest.js';
+import { DEVFLOW_PLUGINS, SKILL_NAMESPACE, WORKFLOW_FOLDER_NAMES, registeredPluginNames, buildAssetMaps, getAllSkillNames, getAllAgentNames, getAllCommandNames, parsePluginSelection, resolveFeatureRedirect, prefixSkillName, unprefixSkillName, skillsOf, selectedWorkflowFolders, FEATURE_OWNED_SKILLS } from '../../core/plugins.js';
+import { readManifest, readManifestPlugins, removeManifestPlugins } from '../../core/manifest.js';
 import { sweepOrphanedAssets, mdFileName, mdEntryName } from '../../core/orphan-sweep.js';
 import { LEGACY_SKILL_NAMES } from '../../targets/claude-code/legacy.js';
 import { removeAmbientHook } from './ambient.js';
@@ -32,9 +32,13 @@ import { stripDevflowTeammateModeFromJson } from '../../core/teammate-mode-clean
 import { getPackageRoot, isContainedIn } from '../../core/paths.js';
 import { firstSymbolicLink } from '../../core/linked-path.js';
 import { MANIFEST_LOCK_NAME, MANIFEST_LOCK_STALE_MARK } from '../../core/manifest-lock.js';
-import { CURATION_TUNING_FILE_NAME, LEGACY_NAMES, MOVE_JOURNAL_SUFFIX, MOVE_LOCK_PREFIX, MOVE_LOCK_SUFFIX } from '../../core/project-paths.js';
+import { CURATION_DIR_NAME, CURATION_TUNING_FILE_NAME, LEGACY_NAMES, MOVE_JOURNAL_SUFFIX, MOVE_LOCK_PREFIX, MOVE_LOCK_SUFFIX, getMemoryDir } from '../../core/project-paths.js';
+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 { isUnrealFolder, newLinkReport, refuseUnrealFolder, refusedFolderStatement } from '../../targets/claude-code/linked-folder.js';
+import { formatReplacedLinksSummary } from './install-report.js';
 /**
  * Where a retired repo-local install lives: `<gitRoot>/.claude` and `<gitRoot>/.devflow`.
  *
@@ -75,10 +79,121 @@ async function scopeInstallPaths(scope, gitRoot) {
     return gitRoot === null ? null : legacyLocalInstallPaths(gitRoot);
 }
 /**
- * The user scope's guard, which passes everything: `~/.claude` and `~/.devflow` are
- * the user's own, so a symbolic link there is the user's choice.
+ * The user scope's guard for a path that is not inside a Devflow install folder, and for the removal
+ * of a whole entry. It passes everything: `~/.claude` and `~/.devflow` and their other folders, the
+ * manifest and `settings.json` are the user's own, so a symbolic link there is followed. `fs.rm` of an
+ * entry that is a link removes the link and never what it points to, so a full uninstall removes a
+ * linked Devflow folder as it removes a real one.
+ *
+ * A read, write or removal inside a Devflow install folder never uses this guard: it uses
+ * {@link devflowFolderGuard}, which refuses a link.
  */
-const changeAnything = async () => true;
+const changeUserOwned = async () => true;
+/** The folders directly under `~/.claude` that hold a `devflow` folder of Devflow's own. */
+const DEVFLOW_FILE_FOLDERS = ['commands', 'agents', 'rules'];
+/**
+ * The Devflow install folder that holds `target` and every folder below it down to the parent of
+ * `target`, outermost first; null for a target outside every Devflow install folder. A target that is
+ * itself a Devflow install folder (a `skills/devflow:*` folder) gives that folder alone. PURE.
+ *
+ * The Devflow install folders are `commands/devflow`, `agents/devflow`, `rules/devflow` and each
+ * `skills/devflow:*` folder. `~/.claude`, `~/.claude/skills` and the other folders above them are
+ * not among them.
+ */
+function devflowFolderChain(claudeDir, target) {
+    const rel = path.relative(claudeDir, target);
+    if (rel === '' || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel))
+        return null;
+    const parts = rel.split(path.sep);
+    const inFileFolder = DEVFLOW_FILE_FOLDERS.includes(parts[0]) && parts[1] === 'devflow';
+    const inSkillFolder = parts[0] === 'skills' && parts[1] !== undefined && parts[1].startsWith(SKILL_NAMESPACE);
+    if (!inFileFolder && !inSkillFolder)
+        return null;
+    const chain = [path.join(claudeDir, parts[0], parts[1])];
+    for (let depth = 2; depth < parts.length - 1; depth++) {
+        chain.push(path.join(chain[chain.length - 1], parts[depth]));
+    }
+    return chain;
+}
+/**
+ * The guard for a change inside the Devflow install folders of `claudeDir`.
+ *
+ * Devflow never reads, writes or removes through a link at or below its own install folders. A
+ * target is let through only when each Devflow folder on the way to it is a real folder or absent;
+ * a folder that is a link, or not a folder, refuses the target. The refusal is recorded once in
+ * `report.refusedFolders` and the link is left as it was. A target outside every Devflow install
+ * folder passes, and a link to a file that is the target itself is not followed (`fs.rm` removes
+ * the link). Never throws.
+ */
+function devflowFolderGuard(claudeDir, report) {
+    return async (target) => {
+        const chain = devflowFolderChain(claudeDir, target);
+        if (chain === null)
+            return true;
+        for (const folder of chain) {
+            if (report.refusedFolders.includes(folder))
+                return false;
+            if (await refuseUnrealFolder(report, folder))
+                return false;
+        }
+        return true;
+    };
+}
+/**
+ * Turn the refused-folder half of an uninstall into summary lines, one per folder.
+ *
+ * An uninstall removes and changes nothing at a path that is a link, or not a folder where it needs
+ * one, and leaves the entry as it was. That looks the same on disk as an uninstall that found nothing
+ * to remove, so the line says what was skipped and what to do about it.
+ *
+ * Pure function — returns lines, logs nothing.
+ */
+export function formatUninstallRefusedSummary(report) {
+    return report.refusedFolders.map(folder => ({
+        level: 'warn',
+        message: `${refusedFolderStatement(folder)} Devflow removed and changed nothing there. ` +
+            `Remove the link or replace it with a real folder, then run the uninstall again.`,
+    }));
+}
+/** How many folders an uninstall left as they are, in a sentence that agrees with the count. */
+function leftAsTheyAre(count) {
+    return count === 1 ? '1 folder was left as it is' : `${count} folders were left as they are`;
+}
+/**
+ * The line for one scope's removal. With no refused folder the plugin is removed. With any, the
+ * removal is partial: the line says so and counts the folders left as they are, because a refused
+ * folder looks the same on disk as a folder that had nothing to remove.
+ *
+ * @param pluginLabel - Empty, or the selected plugin names as ` (a, b)`.
+ *
+ * Pure function — returns the line, logs nothing.
+ */
+export function formatPluginRemovedLine(pluginLabel, refusedCount) {
+    if (refusedCount === 0)
+        return { level: 'success', message: `Plugin removed${pluginLabel}` };
+    return { level: 'warn', message: `Plugin removed in part${pluginLabel}: ${leftAsTheyAre(refusedCount)}.` };
+}
+/**
+ * The last line of an uninstall. It says success only when no folder was refused in any scope;
+ * otherwise it says the uninstall was done in part and counts the folders left as they are.
+ *
+ * Pure function — returns the line, logs nothing.
+ */
+export function formatUninstallOutro(refusedCount) {
+    if (refusedCount === 0) {
+        return `${color.green('Devflow uninstalled successfully')}${color.dim('  Reinstall: npx devflow-kit init')}`;
+    }
+    return color.yellow(`Devflow uninstalled in part: ${leftAsTheyAre(refusedCount)}.`);
+}
+/** Print the links an uninstall replaced or refused, one line each, once per path. */
+function logLinkReport(report) {
+    const lines = [
+        ...formatReplacedLinksSummary({ replacedLinks: [...new Set(report.replacedLinks)] }),
+        ...formatUninstallRefusedSummary({ refusedFolders: [...new Set(report.refusedFolders)] }),
+    ];
+    for (const line of lines)
+        p.log[line.level](line.message);
+}
 /**
  * `folder` and every path below it down to `target`, the target included, outermost
  * first, for whichever of the two folders holds `target`; null for a target in
@@ -139,11 +254,17 @@ function legacyLocalChangeGuard(folders, skipped) {
         return false;
     };
 }
-/** The guard for one scope's full or selective phase: checked for a legacy local install, open for the user's. */
-function scopeChangeGuard(scope, folders) {
-    return scope === 'local'
-        ? legacyLocalChangeGuard(folders, 'Legacy local install not fully removed')
-        : changeAnything;
+/**
+ * The guard for one scope's full or selective phase.
+ *
+ * A legacy local install is checked for a link anywhere on the way to a target. In the user scope the
+ * full phase removes whole entries and passes ({@link changeUserOwned}). The selective phase gives
+ * its `links` report and gets {@link devflowFolderGuard}, which refuses a linked Devflow folder.
+ */
+function scopeChangeGuard(scope, folders, links) {
+    if (scope === 'local')
+        return legacyLocalChangeGuard(folders, 'Legacy local install not fully removed');
+    return links === undefined ? changeUserOwned : devflowFolderGuard(folders.claudeDir, links);
 }
 /**
  * The plugins the manifest records as installed, as registry definitions.
@@ -163,6 +284,24 @@ export async function resolveInstalledPlugins(devflowDir) {
     const resolved = DEVFLOW_PLUGINS.filter(plugin => names.has(plugin.name));
     return resolved.length === 0 ? DEVFLOW_PLUGINS : resolved;
 }
+/**
+ * The plugin names the orchestrator charter is re-rendered for after `uninstall --plugin`, or null when there
+ * is no manifest record to render from. Pure.
+ *
+ * D-CHARTER-INSTALL-RENDER: the set is the manifest record (`readManifestPlugins`) minus the plugins being
+ * removed, with a legacy name mapped and only names this registry has kept ({@link registeredPluginNames}).
+ * It is deliberately NOT {@link resolveInstalledPlugins}: that falls back to the whole registry when the
+ * manifest is missing or names nothing, which is the safe direction for retaining assets, and the wrong one
+ * here. The registry would render a charter that routes to every workflow on a machine that installed none
+ * of them. With no record the caller leaves the installed charter as it is and takes only the sentinel away.
+ * A record that lists no plugin is a record of nothing installed, so it yields the empty set rather than null.
+ */
+export function charterPluginsAfterRemoval(recordedPlugins, removedPluginNames) {
+    if (recordedPlugins === null)
+        return null;
+    const removed = new Set(removedPluginNames);
+    return registeredPluginNames(recordedPlugins).filter(name => !removed.has(name));
+}
 /**
  * Compute which assets should be removed during selective plugin uninstall.
  * Skills and agents shared by remaining plugins are retained.
@@ -182,8 +321,11 @@ export async function resolveInstalledPlugins(devflowDir) {
  *   registry only when there is no manifest to read, and the dry-run and the
  *   real removal must always be given the SAME list or they describe different
  *   outcomes.
+ * @param folderWorkflows - The target-layer set (D-WORKFLOW-FOLDER-INSTALL). A folder
+ *   workflow of a selected plugin is a skill to remove, unless a remaining plugin
+ *   owns it too, and never a command: it has no command file.
  */
-export function computeAssetsToRemove(selectedPlugins, installedPlugins) {
+export function computeAssetsToRemove(selectedPlugins, installedPlugins, folderWorkflows = WORKFLOW_FOLDER_NAMES) {
     const selectedNames = new Set(selectedPlugins.map(p => p.name));
     const remainingPlugins = installedPlugins.filter(p => !selectedNames.has(p.name));
     const retainedSkills = skillsOf(remainingPlugins);
@@ -203,6 +345,11 @@ export function computeAssetsToRemove(selectedPlugins, installedPlugins) {
         if (!retainedSkills.has(skill))
             skills.push(skill);
     }
+    const retainedFolders = selectedWorkflowFolders(remainingPlugins, folderWorkflows);
+    for (const name of selectedWorkflowFolders(selectedPlugins, folderWorkflows)) {
+        if (!retainedFolders.has(name))
+            skills.push(name);
+    }
     for (const plugin of selectedPlugins) {
         for (const agent of plugin.agents) {
             if (!retainedAgents.has(agent))
@@ -212,7 +359,7 @@ export function computeAssetsToRemove(selectedPlugins, installedPlugins) {
             if (!retainedRules.has(rule))
                 rules.push(rule);
         }
-        commands.push(...plugin.commands);
+        commands.push(...plugin.commands.filter(cmd => !folderWorkflows.has(cmd.replace(/^\//, ''))));
     }
     return { skills, agents, commands, rules };
 }
@@ -285,20 +432,66 @@ const TRACKED_ENTRIES = DEVFLOW_TRACKED_PATHS.map((tracked) => ({
     name: tracked.replace(/\/$/, ''),
     isDir: tracked.endsWith('/'),
 }));
+/** The memory folder's name under `.devflow/`, by the name the path helper gives it. */
+const MEMORY_FOLDER_NAME = path.basename(getMemoryDir(path.sep));
+/**
+ * The data area an entry under `.devflow/` belongs to, or null. The curation area holds the
+ * curation folder, the old ledger folder and the backup folders; the memory area holds the
+ * memory folder. Decided by name alone, whatever the kind of entry, and without regard to
+ * ASCII letter case, as the tracked-areas check matches them.
+ */
+function projectDataAreaOf(name) {
+    const lower = name.toLowerCase();
+    if (lower === CURATION_DIR_NAME || lower === LEGACY_NAMES.folder || lower.startsWith(LEGACY_NAMES.backupPrefix))
+        return 'curation';
+    if (lower === MEMORY_FOLDER_NAME)
+        return 'memory';
+    return null;
+}
 /**
  * Split the entries under a repository's `.devflow/` into what a confirmed cleanup
  * removes and what it keeps (D-UNINSTALL-CARVE-OUT). An entry is kept only when both
  * its name and its kind match a tracked path, so a stray FILE named `features` is
- * not mistaken for the tracked directory. PURE — both lists sorted by name.
+ * not mistaken for the tracked directory. An entry of a paused data area (`pausedAreas`:
+ * git tracks files in the area's folders, or did not answer) is kept too, in
+ * `keepPaused`. PURE — all three lists sorted by name.
  */
-export function partitionProjectData(entries) {
+export function partitionProjectData(entries, pausedAreas = new Set()) {
     const isTracked = (entry) => TRACKED_ENTRIES.some((t) => t.name === entry.name && t.isDir === entry.isDir);
+    const isPaused = (entry) => {
+        const area = projectDataAreaOf(entry.name);
+        return area !== null && pausedAreas.has(area);
+    };
     const byName = (a, b) => a.name.localeCompare(b.name);
     return {
-        remove: entries.filter((e) => !isTracked(e)).sort(byName),
+        remove: entries.filter((e) => !isTracked(e) && !isPaused(e)).sort(byName),
         keep: entries.filter(isTracked).sort(byName),
+        keepPaused: entries.filter((e) => !isTracked(e) && isPaused(e)).sort(byName),
     };
 }
+/** The check's own answer, from the package's own copy of it. */
+const probeProjectDataArea = async (root, area) => (await probeTrackedArea(root, area)).answer;
+/**
+ * The data areas that hold an entry in `entries` and are paused at `gitRoot`: git tracks
+ * files in the area's folders, or a `.git` entry stands and git did not answer. An area
+ * with no entry is not asked, and a root with no `.git` entry makes no git call. A probe
+ * that fails to answer counts as `unknown`, so the area is kept.
+ */
+async function pausedProjectDataAreas(gitRoot, entries, probe) {
+    const present = new Set(entries.flatMap((entry) => {
+        const area = projectDataAreaOf(entry.name);
+        return area === null ? [] : [area];
+    }));
+    const answers = await Promise.all([...present].map(async (area) => {
+        try {
+            return [area, await probe(gitRoot, area)];
+        }
+        catch {
+            return [area, 'unknown'];
+        }
+    }));
+    return new Set(answers.flatMap(([area, answer]) => (answer === 'untracked' ? [] : [area])));
+}
 /**
  * Resolve the project-data step's target: `<gitRoot>/.devflow`, partitioned.
  *
@@ -312,6 +505,12 @@ export function partitionProjectData(entries) {
  * A `.devflow` that is a symbolic link to anywhere else is skipped too, and never
  * followed: its target is a directory devflow cannot prove it wrote, so a
  * confirmed cleanup must not empty it — nor unlink a link the user made.
+ *
+ * A folder that git tracks is the repository's content, not devflow's data. The
+ * curation area (the curation folder, the old ledger folder and the backup folders)
+ * and the memory area (the memory folder) are each asked of the tracked-areas check at
+ * the git root, when an entry of the area stands. An area that git tracks files in, or
+ * that git did not answer for, moves its entries from the removal list to `keepPaused`.
  */
 export async function resolveProjectDataPlan(opts) {
     if (opts.gitRoot === null)
@@ -335,8 +534,10 @@ export async function resolveProjectDataPlan(opts) {
     catch {
         return { kind: 'skip', reason: 'absent' };
     }
-    const { remove, keep } = partitionProjectData(dirents.map((d) => ({ name: d.name, isDir: d.isDirectory() })));
-    return { kind: 'plan', plan: { dir, remove, keep } };
+    const entries = dirents.map((d) => ({ name: d.name, isDir: d.isDirectory() }));
+    const paused = await pausedProjectDataAreas(opts.gitRoot, entries, opts.probe ?? probeProjectDataArea);
+    const { remove, keep, keepPaused } = partitionProjectData(entries, paused);
+    return { kind: 'plan', plan: { dir, remove, keep, keepPaused } };
 }
 /**
  * The line that tells the user why the project-data step was skipped, or null
@@ -366,15 +567,21 @@ function entryLabel(entry) {
 function entryList(entries) {
     return entries.length === 0 ? '(none)' : entries.map(entryLabel).join(', ');
 }
+/** Why the entries of a data area stay, said beside a list of them. */
+const KEEP_PAUSED_REASON = 'git tracks them, or git did not answer';
+/** Why one entry of a data area stays, said beside it. */
+const KEEP_PAUSED_REASON_ONE = 'git tracks it, or git did not answer';
 /**
  * The lines shown before the project-data confirm: what is removed and what is
- * kept. PURE.
+ * kept, and, only where there are such entries, what is kept because git tracks them
+ * or did not answer. PURE.
  */
 export function formatProjectDataPlan(plan) {
     return [
         `Project data in ${plan.dir}/:`,
         `  Remove: ${entryList(plan.remove)}`,
         `  Keep (shared via git): ${entryList(plan.keep)}`,
+        ...(plan.keepPaused.length === 0 ? [] : [`  Keep (${KEEP_PAUSED_REASON}): ${entryList(plan.keepPaused)}`]),
     ];
 }
 /**
@@ -724,7 +931,7 @@ export function installArtifactPaths(devflowDir) {
  * Each removal passes `mayChange` first, which skips one a symbolic link would
  * redirect in a legacy local install (D-CLI-NO-SYMLINK, legacyLocalChangeGuard).
  */
-export async function removeDevFlowInstallArtifacts(devflowDir, verbose, mayChange = changeAnything) {
+export async function removeDevFlowInstallArtifacts(devflowDir, verbose, mayChange = changeUserOwned) {
     const manifestPath = path.join(devflowDir, 'manifest.json');
     if (await mayChange(manifestPath)) {
         try {
@@ -832,7 +1039,7 @@ export async function isDevFlowInstalled(claudeDir) {
  * @param claudeDir  - Target Claude Code directory (e.g. ~/.claude)
  * @param devflowDir - Devflow data directory (e.g. ~/.devflow)
  */
-export async function enumerateDryRunExtras(claudeDir, devflowDir) {
+export async function enumerateDryRunExtras(claudeDir, devflowDir, folderWorkflows = WORKFLOW_FOLDER_NAMES) {
     const extras = [];
     // 1. Whole directories removed by removeAllDevFlow
     for (const dir of [
@@ -854,7 +1061,8 @@ export async function enumerateDryRunExtras(claudeDir, devflowDir) {
     //         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).
-    const prefixedSkillNames = new Set([...getAllSkillNames(), ...LEGACY_SKILL_NAMES, ...FEATURE_OWNED_SKILLS]);
+    // The workflow skill folders (D-WORKFLOW-FOLDER-INSTALL) join through getAllSkillNames.
+    const prefixedSkillNames = new Set([...getAllSkillNames(folderWorkflows), ...LEGACY_SKILL_NAMES, ...FEATURE_OWNED_SKILLS]);
     const skillsDir = path.join(claudeDir, 'skills');
     for (const skillName of prefixedSkillNames) {
         const prefixedPath = path.join(skillsDir, prefixSkillName(skillName));
@@ -946,6 +1154,9 @@ export async function runDryRunPhase(opts) {
             for (const entry of projectData.plan.remove) {
                 extras.push(`${path.join(projectData.plan.dir, entryLabel(entry))} (if confirmed)`);
             }
+            for (const entry of projectData.plan.keepPaused) {
+                extras.push(`${path.join(projectData.plan.dir, entryLabel(entry))} (kept: ${KEEP_PAUSED_REASON_ONE})`);
+            }
         }
         else {
             const skipped = formatProjectDataSkip(projectData.reason, projectRoot);
@@ -972,13 +1183,17 @@ export async function runDryRunPhase(opts) {
  * settings.json, so the notice tells the user to run `devflow init` for those.
  *
  * Never runs in a legacy local scope (D-CLI-NO-SYMLINK): a repository can commit a command
- * file as a symbolic link, and the copy writes through it. The folder guard below does not
- * check files. `devflow init` can not update a legacy local install either, so the warning
- * tells the user to remove it in full.
+ * file as a symbolic link, and the copy writes through it. `devflow init` can not update a
+ * legacy local install either, so the warning tells the user to remove it in full.
+ *
+ * In the user scope the copy writes into neither folder when either is a link or not a folder,
+ * whatever the caller's guard says: writing only one folder would pair old commands with new
+ * agents. The refused folder is recorded in `links`. A command or agent file that is a link is
+ * replaced by a real file and recorded in `links` too; what it pointed to is left as it was.
  *
  * Skipped, with a warning, when there is no readable manifest or it lists no known plugin (the
- * retained set would be a guess), or when a folder is behind a link the caller's guard
- * refuses. Those warnings name `devflow init` as the remedy. When the copy fails, it stops
+ * retained set would be a guess), or when a folder is a link, not a folder, or behind a link the
+ * caller's guard refuses. Those warnings name `devflow init` as the remedy. When the copy fails, it stops
  * at the first failure: files it wrote before then stay, and the warning names the same
  * remedy. Never throws: an uninstall must finish.
  * Agent model lines are reverted again after the copy, as the selective phase does before
@@ -989,7 +1204,8 @@ export async function refreshRetainedCommandsAndAgents(opts) {
     const { claudeDir, devflowDir, retained, retiredAgents } = opts;
     const scope = opts.scope ?? 'user';
     const verbose = opts.verbose ?? false;
-    const mayChange = opts.mayChange ?? changeAnything;
+    const mayChange = opts.mayChange ?? changeUserOwned;
+    const links = opts.links ?? newLinkReport();
     const agentsDir = path.join(claudeDir, 'agents', 'devflow');
     const commandsDir = path.join(claudeDir, 'commands', 'devflow');
     const retired = `Removed the agent file(s) of an older Devflow release: ${retiredAgents.join(', ')}.`;
@@ -1016,7 +1232,14 @@ export async function refreshRetainedCommandsAndAgents(opts) {
         p.log.warn(`${retired} The manifest lists no known plugin, so Devflow did not rewrite the remaining files. ${remedy}`);
         return;
     }
-    if (!(await mayChange(agentsDir)) || !(await mayChange(commandsDir))) {
+    let blocked = !(await mayChange(agentsDir)) || !(await mayChange(commandsDir));
+    if (!blocked) {
+        // The caller's guard may pass everything. Neither folder is written when it is a link or not a folder.
+        const agentsRefused = await refuseUnrealFolder(links, agentsDir);
+        const commandsRefused = await refuseUnrealFolder(links, commandsDir);
+        blocked = agentsRefused || commandsRefused;
+    }
+    if (blocked) {
         p.log.warn(`${retired} A linked folder blocks the rewrite. ${remedy}`);
         return;
     }
@@ -1026,7 +1249,9 @@ export async function refreshRetainedCommandsAndAgents(opts) {
             agentsMap: buildAssetMaps(retained).agentsMap,
             claudeDir,
             curation: manifest.features.curation,
+            compliance: manifest.features.compliance.enabled,
             trackerServers: effectiveTrackerServers(manifest.features.tracker),
+            links,
             warn: (msg) => p.log.warn(msg),
         });
     }
@@ -1041,6 +1266,30 @@ export async function refreshRetainedCommandsAndAgents(opts) {
     catch { /* the revert is best effort, as in the selective phase */ }
     p.log.info(`${retired} Devflow wrote the current commands and agents of the plugins that stay installed. Run \`devflow init\` to update the hooks and scripts.`);
 }
+/**
+ * Re-render the installed orchestrator charter for the plugins that stay after a selective removal, so it
+ * stops routing to a workflow whose skill was just removed, and take the implement sentinel away when
+ * implement is among the removed.
+ *
+ * D-CHARTER-INSTALL-RENDER: the set comes from the MANIFEST record, read without a heal so the file stays
+ * byte-identical, which still lists the removed plugins until the caller drops the record, never from the
+ * registry fallback of {@link resolveInstalledPlugins}. The record is read only where the change guard lets
+ * a change through. With no usable record there is nothing to render from and the installed charter stays
+ * as it is, but the sentinel needs no record and goes when implement is among the removed. An uninstall
+ * never creates a file, so a machine whose charter is not installed gets none. A failure is a warning,
+ * never a failure of the uninstall.
+ */
+async function rerenderCharterAfterRemoval(devflowDir, removedPluginNames, mayChange) {
+    const scriptsDir = path.join(devflowDir, 'scripts');
+    const warn = (msg) => p.log.warn(msg);
+    const recorded = (await mayChange(path.join(devflowDir, 'manifest.json'))) ? await readManifestPlugins(devflowDir) : null;
+    const retained = charterPluginsAfterRemoval(recorded, removedPluginNames);
+    if (retained === null) {
+        await removeHandoffSentinel({ scriptsDir, removedPlugins: removedPluginNames, warn, mayChange });
+        return;
+    }
+    await installRenderedCharter({ scriptsDir, plugins: retained, warn, mayChange, mode: 'uninstall' });
+}
 /**
  * SELECTIVE PHASE (per scope): revert agent model overrides, remove the
  * selected plugins' assets, and clean up the ambient hook if the ambient
@@ -1050,13 +1299,19 @@ export async function refreshRetainedCommandsAndAgents(opts) {
  * @param opts.devflowDir  - Devflow data directory for this scope.
  * @param opts.selectedPlugins - Plugin subset to remove.
  * @param opts.verbose     - Whether to emit verbose log lines.
+ *
+ * Nothing is read, written or removed through a link at or below a Devflow install folder. A
+ * Devflow folder that is a link, or not a folder, is left as it was; the phase prints one line for
+ * each and returns them, with the file links it replaced, in the {@link LinkReport}.
  */
 export async function runSelectivePhaseForScope(opts) {
     const { claudeDir, devflowDir, selectedPlugins, verbose } = opts;
     const scope = opts.scope ?? 'user';
     const installedPlugins = opts.installedPlugins ?? DEVFLOW_PLUGINS;
-    // D-CLI-NO-SYMLINK: a legacy local install's removals and rewrites pass this first.
-    const mayChange = scopeChangeGuard(scope, { claudeDir, devflowDir });
+    const links = newLinkReport();
+    // D-CLI-NO-SYMLINK: a legacy local install's removals and rewrites pass this first. In the user
+    // scope the guard refuses a linked Devflow folder and records it in `links`.
+    const mayChange = scopeChangeGuard(scope, { claudeDir, devflowDir }, links);
     // Revert GPT agent frontmatter BEFORE removing agent files — strips GPT model
     // lines from installed agent frontmatter while the files are still present.
     // Non-fatal: tolerate missing agents dir or revert errors.
@@ -1075,7 +1330,9 @@ export async function runSelectivePhaseForScope(opts) {
         }
         catch { /* agents dir absent or revert failed — non-fatal */ }
     }
-    const sweeps = await removeSelectedPlugins(claudeDir, selectedPlugins, verbose, installedPlugins, mayChange);
+    // In the user scope the removal builds its own guard over the same report, which also checks each
+    // orphan it sweeps; a legacy local install keeps the guard above.
+    const sweeps = await removeSelectedPlugins(claudeDir, selectedPlugins, verbose, installedPlugins, scope === 'local' ? mayChange : undefined, links);
     // A retired agent file means the install is from an older release, and the commands of the
     // plugins that stay installed still spawn the name that was just removed. Write their
     // current commands and agents so the install stays whole. Runs before the language stamp
@@ -1090,6 +1347,7 @@ export async function runSelectivePhaseForScope(opts) {
             scope,
             verbose,
             mayChange,
+            links,
         });
     }
     // D-LANGUAGE-FOCUS-STAMP: re-stamp the installed /code-review from the selection that REMAINS.
@@ -1108,6 +1366,9 @@ export async function runSelectivePhaseForScope(opts) {
             mayChange,
         });
     }
+    // D-CHARTER-INSTALL-RENDER: the charter stops routing to the removed workflows. It reads the manifest
+    // record, so it runs before the record is dropped below.
+    await rerenderCharterAfterRemoval(devflowDir, selectedPlugins.map(sp => sp.name), mayChange);
     // D-UNINSTALL-DROPS-PLUGIN: the manifest is the install record `devflow init` seeds its plugin
     // selection from (a re-init keeps the prior selection), so a plugin removed here but still listed
     // would be installed again by the next plain init. Take the selected names off the list;
@@ -1140,6 +1401,8 @@ export async function runSelectivePhaseForScope(opts) {
         }
         catch { /* settings.json may not exist */ }
     }
+    logLinkReport(links);
+    return links;
 }
 /**
  * FULL PHASE (per scope): revert agent model overrides, remove all Devflow
@@ -1167,11 +1430,13 @@ export async function runFullPhaseForScope(opts) {
     // Revert GPT agent frontmatter before removing agents — ensures no orphaned
     // GPT model lines remain if agents dir is preserved by a later partial flow.
     // Non-fatal: tolerate missing agents dir or revert errors.
+    // The revert rewrites the files in the folder, so a folder that is a link is not reverted: the
+    // removal below takes the link away whole and the files it led to stay as they are.
     {
         const agentsInstallDir = path.join(claudeDir, 'agents', 'devflow');
         try {
             await fs.access(agentsInstallDir);
-            if (await mayChange(agentsInstallDir)) {
+            if (await mayChange(agentsInstallDir) && !(await isUnrealFolder(agentsInstallDir))) {
                 await revertExternalAgents({
                     installDir: agentsInstallDir,
                     devflowDir,
@@ -1251,7 +1516,9 @@ export async function runFullPhaseForScope(opts) {
 async function runProjectDataStep(plan, gates) {
     const shown = `${plan.dir}/`;
     if (plan.remove.length === 0) {
-        p.log.info(`${shown} preserved (holds only files shared via git)`);
+        p.log.info(plan.keepPaused.length === 0
+            ? `${shown} preserved (holds only files shared via git)`
+            : `${shown} preserved (holds only files shared via git, and ${entryList(plan.keepPaused)}, which stay: ${KEEP_PAUSED_REASON})`);
         return;
     }
     if (gates.keepDocs) {
@@ -1287,7 +1554,7 @@ async function runProjectDataStep(plan, gates) {
             failed.push(`${entryLabel(entry)} (${err.code ?? err.message})`);
         }
     }
-    if (plan.keep.length === 0 && failed.length === 0) {
+    if (plan.keep.length === 0 && plan.keepPaused.length === 0 && failed.length === 0) {
         // Nothing tracked was there: drop the now-empty directory. rmdir refuses a
         // directory something wrote into meanwhile, which is then left in place.
         await fs.rmdir(plan.dir).catch(() => undefined);
@@ -1298,6 +1565,8 @@ async function runProjectDataStep(plan, gates) {
         p.log.warn(`Could not remove from ${shown}: ${failed.join(', ')}`);
     if (plan.keep.length > 0)
         p.log.info(`Kept: ${entryList(plan.keep)}`);
+    if (plan.keepPaused.length > 0)
+        p.log.info(`Kept: ${entryList(plan.keepPaused)} (${KEEP_PAUSED_REASON})`);
 }
 /**
  * CLEANUP PHASE: post-loop extras run only on full uninstall.
@@ -1413,7 +1682,7 @@ export async function runCleanupPhase(opts) {
             // where no symbolic link leads it out of `<gitRoot>/.claude`.
             const mayChange = scope === 'local'
                 ? legacyLocalChangeGuard(paths, 'settings.json not edited')
-                : changeAnything;
+                : changeUserOwned;
             if (settingsContent !== originalContent && await mayChange(settingsPath)) {
                 await writeSettingsFileAtomic(settingsPath, settingsContent);
                 if (verbose) {
@@ -1654,7 +1923,10 @@ export const uninstallCommand = new Command('uninstall')
             catch { /* non-fatal */ }
         }
     }
-    // Uninstall from each scope
+    // Uninstall from each scope. The folders a selective uninstall refused are counted across the
+    // scopes, so the last line can say the removal was done in part. A refusal is reported, not a
+    // failure: the exit status stays 0, as it does for a legacy install whose links were skipped.
+    const refusedFolders = new Set();
     for (const scope of scopesToUninstall) {
         const paths = await scopeInstallPaths(scope, gitRoot);
         if (paths === null) {
@@ -1669,8 +1941,9 @@ export const uninstallCommand = new Command('uninstall')
         else {
             p.log.step('Uninstalling legacy local scope (git-root/.claude/)');
         }
+        const scopeRefused = new Set();
         if (isSelectiveUninstall) {
-            await runSelectivePhaseForScope({
+            const links = await runSelectivePhaseForScope({
                 claudeDir,
                 devflowDir,
                 selectedPlugins,
@@ -1678,6 +1951,10 @@ export const uninstallCommand = new Command('uninstall')
                 installedPlugins: await resolveInstalledPlugins(devflowDir),
                 scope,
             });
+            for (const folder of links.refusedFolders) {
+                scopeRefused.add(folder);
+                refusedFolders.add(folder);
+            }
         }
         else {
             await runFullPhaseForScope({ scope, claudeDir, devflowDir, devflowScriptsDir, verbose, keepDocs: !!options.keepDocs, isTTY: !!process.stdin.isTTY });
@@ -1685,14 +1962,14 @@ export const uninstallCommand = new Command('uninstall')
         const pluginLabel = isSelectiveUninstall
             ? ` (${selectedPluginNames.join(', ')})`
             : '';
-        p.log.success(`Plugin removed${pluginLabel}`);
+        const removed = formatPluginRemovedLine(pluginLabel, scopeRefused.size);
+        p.log[removed.level](removed.message);
     }
     // === CLEANUP EXTRAS (only for full uninstall) ===
     if (!isSelectiveUninstall) {
         await runCleanupPhase({ scopesToUninstall, keepDocs: !!options.keepDocs, verbose, cwd: process.cwd(), isTTY: !!process.stdin.isTTY, managedProxyPorts });
     }
-    const status = color.green('Devflow uninstalled successfully');
-    p.outro(`${status}${color.dim('  Reinstall: npx devflow-kit init')}`);
+    p.outro(formatUninstallOutro(refusedFolders.size));
 });
 /**
  * Remove all Devflow assets (full uninstall).
@@ -1700,7 +1977,7 @@ export const uninstallCommand = new Command('uninstall')
  * Each removal passes `mayChange` first, which skips one a symbolic link would
  * redirect in a legacy local install (D-CLI-NO-SYMLINK, legacyLocalChangeGuard).
  */
-export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose, mayChange = changeAnything) {
+export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose, mayChange = changeUserOwned, folderWorkflows = WORKFLOW_FOLDER_NAMES) {
     const devflowDirectories = [
         { path: path.join(claudeDir, 'commands', 'devflow'), name: 'commands' },
         { path: path.join(claudeDir, 'agents', 'devflow'), name: 'agents' },
@@ -1732,7 +2009,8 @@ export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose, ma
     //     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).
-    const prefixedSkillNames = new Set([...getAllSkillNames(), ...LEGACY_SKILL_NAMES, ...FEATURE_OWNED_SKILLS]);
+    //   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');
     let skillsRemoved = 0;
     for (const skillName of prefixedSkillNames) {
@@ -1777,7 +2055,7 @@ export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose, ma
     // registry (retired, renamed, or deleted). The loop above walks the static
     // registry + LEGACY list; this sweep walks the actual directory, so orphaned
     // dirs from older versions are also cleaned up. (F9)
-    await sweepDevflowNamespaces(claudeDir, verbose, mayChange);
+    await sweepDevflowNamespaces(claudeDir, verbose, mayChange, undefined, folderWorkflows);
 }
 /**
  * Registry-diff sweep of all Devflow-owned namespaces in `claudeDir`:
@@ -1797,25 +2075,38 @@ export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose, ma
  * and the user has no other signal that it is still there.
  *
  * A folder `mayChange` refuses is not swept at all (D-CLI-NO-SYMLINK,
- * legacyLocalChangeGuard). An entry in a swept folder that is itself a link is
- * only unlinked: `fs.rm` never follows the link it is given.
+ * legacyLocalChangeGuard). The agents and commands folders are swept only when each is a real folder
+ * or absent, whatever `mayChange` says, because the sweep reads and removes inside whatever the
+ * folder names; a folder that is a link or not a folder is recorded in `links` and left as it was.
+ *
+ * With no `mayChange`, the sweep uses the Devflow folder guard, which also refuses each orphan that
+ * is a link (a linked `skills/devflow:*` folder): the orphan stays and is recorded in `links`. With a
+ * `mayChange` given, an orphan that is itself a link is only unlinked: `fs.rm` never follows the
+ * link it is given.
  *
  * Returns what each sweep removed and failed to remove, so a caller can tell that
  * a retired agent was removed (see {@link refreshRetainedCommandsAndAgents}).
  */
-export async function sweepDevflowNamespaces(claudeDir, verbose, mayChange = changeAnything) {
+export async function sweepDevflowNamespaces(claudeDir, verbose, mayChange, links = { refusedFolders: [] }, folderWorkflows = WORKFLOW_FOLDER_NAMES) {
     const agentsDir = path.join(claudeDir, 'agents', 'devflow');
     const commandsDir = path.join(claudeDir, 'commands', 'devflow');
     const skillsDir = path.join(claudeDir, 'skills');
     const noSweep = { scanned: 0, removed: [], failed: [] };
-    const sweep = async (...args) => (await mayChange(args[0])) ? sweepOrphanedAssets(...args) : noSweep;
-    const agentsSweep = await sweep(agentsDir, new Set(getAllAgentNames()), mdEntryName);
-    const commandsSweep = await sweep(commandsDir, new Set(getAllCommandNames()), mdEntryName);
+    const guard = mayChange ?? devflowFolderGuard(claudeDir, links);
+    const mayRemove = mayChange === undefined ? guard : undefined;
+    const sweep = async (...args) => (await guard(args[0])) ? sweepOrphanedAssets(args[0], args[1], args[2], mayRemove) : noSweep;
+    const sweepDevflowFolder = async (...args) => (await guard(args[0])) && !(await refuseUnrealFolder(links, args[0]))
+        ? sweepOrphanedAssets(args[0], args[1], args[2], mayRemove)
+        : noSweep;
+    const agentsSweep = await sweepDevflowFolder(agentsDir, new Set(getAllAgentNames()), mdEntryName);
+    const commandsSweep = await sweepDevflowFolder(commandsDir, new Set(getAllCommandNames(folderWorkflows)), mdEntryName);
     // FEATURE_OWNED_SKILLS (compliance) unioned into knownNames so a selective
     // uninstall of another plugin does not sweep devflow:compliance — nothing
     // converges after selective uninstall (only installViaFileCopy + convergeComplianceArtifacts
     // on full/partial init re-materialize it). D-FO-1 applies.
-    const skillsSweep = await sweep(skillsDir, new Set([...getAllSkillNames(), ...FEATURE_OWNED_SKILLS]), (entry) => entry.startsWith(SKILL_NAMESPACE) ? unprefixSkillName(entry) : null);
+    // D-WORKFLOW-FOLDER-INSTALL: a workflow skill folder is a known skill, so a selective uninstall of
+    // another plugin keeps it, and a stale command file of a folder workflow is an orphan here.
+    const skillsSweep = await sweep(skillsDir, new Set([...getAllSkillNames(folderWorkflows), ...FEATURE_OWNED_SKILLS]), (entry) => entry.startsWith(SKILL_NAMESPACE) ? unprefixSkillName(entry) : null);
     const byKind = [
         { kind: 'agent', sweep: agentsSweep },
         { kind: 'command', sweep: commandsSweep },
@@ -1839,17 +2130,20 @@ export async function sweepDevflowNamespaces(claudeDir, verbose, mayChange = cha
  * sweep the install directory for any orphaned assets whose names left the
  * registry (retired agents/commands survive indefinitely without the sweep).
  * For skills: only remove skills that are NOT used by any remaining plugin.
- * Each removal passes `mayChange` first, which skips one a symbolic link would
- * redirect in a legacy local install (D-CLI-NO-SYMLINK, legacyLocalChangeGuard).
+ * Each removal passes the guard first. A legacy local install passes `mayChange`
+ * (D-CLI-NO-SYMLINK, legacyLocalChangeGuard). With none given, the removal uses the
+ * Devflow folder guard: nothing is removed in or from a Devflow folder that is a link or
+ * not a folder, and each such folder is recorded in `links` and left as it was.
  *
  * Returns what the closing registry-diff sweep removed.
  */
-export async function removeSelectedPlugins(claudeDir, plugins, verbose, installedPlugins = DEVFLOW_PLUGINS, mayChange = changeAnything) {
-    const { skills, agents, commands, rules } = computeAssetsToRemove(plugins, installedPlugins);
+export async function removeSelectedPlugins(claudeDir, plugins, verbose, installedPlugins = DEVFLOW_PLUGINS, mayChange, links = { refusedFolders: [] }, folderWorkflows = WORKFLOW_FOLDER_NAMES) {
+    const { skills, agents, commands, rules } = computeAssetsToRemove(plugins, installedPlugins, folderWorkflows);
+    const guard = mayChange ?? devflowFolderGuard(claudeDir, links);
     const commandsDir = path.join(claudeDir, 'commands', 'devflow');
     for (const cmd of commands) {
         const cmdPath = path.join(commandsDir, mdFileName(cmd.replace(/^\//, '')));
-        if (!(await mayChange(cmdPath)))
+        if (!(await guard(cmdPath)))
             continue;
         try {
             await fs.rm(cmdPath, { force: true });
@@ -1864,7 +2158,7 @@ export async function removeSelectedPlugins(claudeDir, plugins, verbose, install
     const agentsDir = path.join(claudeDir, 'agents', 'devflow');
     for (const agent of agents) {
         const agentPath = path.join(agentsDir, mdFileName(agent));
-        if (!(await mayChange(agentPath)))
+        if (!(await guard(agentPath)))
             continue;
         try {
             await fs.rm(agentPath, { force: true });
@@ -1885,7 +2179,7 @@ export async function removeSelectedPlugins(claudeDir, plugins, verbose, install
         // namespace shipped in dcecda3, 2026-03-30), so a bare dir for a current
         // registry name is by construction foreign.
         const skillPath = path.join(skillsDir, prefixSkillName(skill));
-        if (!(await mayChange(skillPath)))
+        if (!(await guard(skillPath)))
             continue;
         try {
             await fs.rm(skillPath, { recursive: true, force: true });
@@ -1898,7 +2192,7 @@ export async function removeSelectedPlugins(claudeDir, plugins, verbose, install
     const rulesDir = path.join(claudeDir, 'rules', 'devflow');
     for (const rule of rules) {
         const rulePath = path.join(rulesDir, mdFileName(rule));
-        if (!(await mayChange(rulePath)))
+        if (!(await guard(rulePath)))
             continue;
         try {
             await fs.rm(rulePath, { force: true });
@@ -1912,6 +2206,6 @@ export async function removeSelectedPlugins(claudeDir, plugins, verbose, install
     // Removes any orphaned files whose names left the registry (retired, renamed,
     // or deleted from all plugins). Spans ALL plugins so assets belonging to
     // non-selected plugins are never swept.
-    return sweepDevflowNamespaces(claudeDir, verbose, mayChange);
+    return sweepDevflowNamespaces(claudeDir, verbose, mayChange, links, folderWorkflows);
 }
 //# sourceMappingURL=uninstall.js.map