devflow-kit 3.0.1 → 3.2.0

package/dist/cli/commands/uninstall.js

@@ -29,6 +29,7 @@ import { writeSettingsFileAtomic } from '../../core/fs-atomic.js';
 import { stripFlags } from '../../core/flags.js';
 import { stripDevflowTeammateModeFromJson } from '../../core/teammate-mode-cleanup.js';
 import { getPackageRoot, isContainedIn } from '../../core/paths.js';
+import { firstSymbolicLink } from '../../core/linked-path.js';
 /**
  * Where a retired repo-local install lives: `<gitRoot>/.claude` and `<gitRoot>/.devflow`.
  *
@@ -68,6 +69,77 @@ async function scopeInstallPaths(scope, gitRoot) {
         return getInstallationPaths();
     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.
+ */
+const changeAnything = async () => true;
+/**
+ * `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
+ * neither. PURE.
+ */
+function pathsDownTo(folders, target) {
+    for (const folder of [folders.claudeDir, folders.devflowDir]) {
+        const rel = path.relative(folder, target);
+        if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel))
+            continue;
+        const chain = [folder];
+        for (const part of rel === '' ? [] : rel.split(path.sep)) {
+            chain.push(path.join(chain[chain.length - 1], part));
+        }
+        return chain;
+    }
+    return null;
+}
+/**
+ * The guard for a legacy local install's removals and settings rewrites.
+ *
+ * D-CLI-NO-SYMLINK (firstSymbolicLink): a repository can commit `.claude`, `.devflow`
+ * or any folder or file in them as a symbolic link, and enough of `.claude` for a
+ * plain `uninstall` to detect a legacy install there. `fs.rm` and the settings
+ * rewrite act inside whatever folder a link on the way names, so a target is acted
+ * on only where neither `<gitRoot>/.claude` or `<gitRoot>/.devflow` nor anything
+ * below it on the way to the target, the target included, is a link. Otherwise the
+ * target is skipped, the link is left as it was, and one warning per link, opened
+ * by `skipped`, names it. A target that cannot be checked, or lies in neither
+ * folder, is skipped and reported the same way. The rest of the install is still
+ * removed, so a real, unlinked legacy install comes out whole.
+ */
+function legacyLocalChangeGuard(folders, skipped) {
+    const reported = new Set();
+    const report = (subject, reason) => {
+        if (reported.has(subject))
+            return;
+        reported.add(subject);
+        p.log.warn(`${skipped}: ${reason}`);
+    };
+    return async (target) => {
+        const chain = pathsDownTo(folders, target);
+        if (chain === null) {
+            report(target, `${target} is outside the legacy install`);
+            return false;
+        }
+        let link;
+        try {
+            link = await firstSymbolicLink(chain);
+        }
+        catch (error) {
+            report(target, `${target} could not be checked for a symbolic link (${error instanceof Error ? error.message : String(error)})`);
+            return false;
+        }
+        if (link === null)
+            return true;
+        report(link, `${link} is a symbolic link, and devflow removes or changes nothing through one`);
+        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 plugins the manifest records as installed, as registry definitions.
  *
@@ -178,7 +250,7 @@ export function formatDryRunPlan(assets) {
  *   - "prompt"  — interactive (isTTY=true); caller should ask the user
  *
  * @D1 Non-interactive-preserve invariant: when isTTY is false the result is
- * always "preserve", never "prompt" — avoids PF-004 half-applied-state hazard.
+ * always "preserve", never "prompt" — avoids a half-applied-state hazard.
  */
 export function resolveSecurityRemovalDecision(opts) {
     if (!opts.anySecurityPresent || opts.keepDocs)
@@ -193,7 +265,7 @@ export function resolveSecurityRemovalDecision(opts) {
  *
  * A cancel (user presses Ctrl-C on this prompt) is treated as decline: the
  * .devflow/ directory is preserved and the uninstall continues with the remaining
- * steps rather than aborting via process.exit() (applies PF-014, applies ADR-003).
+ * steps rather than aborting via process.exit().
  *
  * PURE — no I/O, fully testable.
  *
@@ -233,8 +305,8 @@ export function partitionProjectData(entries) {
  * realpaths, so macOS's `/var` → `/private/var` and a symlinked HOME still match.
  *
  * 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 (applies
- * ADR-024), so a confirmed cleanup must not empty it — nor unlink a link the user made.
+ * 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.
  */
 export async function resolveProjectDataPlan(opts) {
     if (opts.gitRoot === null)
@@ -320,9 +392,9 @@ export function formatProjectDataPlan(plan) {
  * @D5 Precondition guard: any anomalous devflowDir falls back to 'artifacts-only' rather
  * than throwing — business logic must not throw (engineering rule). The explicit guard
  * makes the invariant present in production code, not only in tests (reliability rule).
- * @D6 avoids PF-014: the caller must NOT process.exit() after a cancel/decline response;
+ * @D6 The caller must NOT process.exit() after a cancel/decline response;
  * removeAllDevFlow has already run by the time the prompt fires, so removeDevFlowInstallArtifacts
- * must execute on every non-confirm path to leave a clean end-state (applies ADR-003).
+ * must execute on every non-confirm path to leave a clean end-state.
  * @D7 keepDocs gate: when the caller passes --keep-docs, the entire ~/.devflow dir cleanup
  * prompt is suppressed — artifacts-only regardless of isTTY or userContent. This prevents
  * --keep-docs from triggering prompts about skill shadows or preference-profile.md.
@@ -517,7 +589,7 @@ export function installArtifactPaths(devflowDir) {
         { relPath: 'agent-models.json' },
         // cost history — auto-generated session telemetry, not user-authored.
         // The whole costs/ tree is removed so sessions/ and archive.jsonl cannot
-        // drift from their write sites in src/hud/cost-history.ts (avoids PF-013).
+        // drift from their write sites in src/hud/cost-history.ts.
         { relPath: 'costs', isDir: true },
         // proxy artifacts
         { relPath: 'proxy.json' },
@@ -545,7 +617,7 @@ export function installArtifactPaths(devflowDir) {
         { relPath: 'logs', isDir: true },
         // Model-discovery + HUD component caches. hudCacheDir() is the authoritative
         // accessor for the cache/ parent (modelCacheDir() resolves beneath it), so the
-        // removal site stays byte-locked to the write sites (avoids PF-013).
+        // removal site stays byte-locked to the write sites.
         { relPath: path.relative(devflowDir, hudCacheDir(devflowDir)), isDir: true },
     ];
 }
@@ -567,19 +639,24 @@ export function installArtifactPaths(devflowDir) {
  * agent-models.json is an INSTALL ARTIFACT (stale per-agent overrides silently
  * re-apply to renamed/deleted agents on reinstall — AC-P1-F4) and therefore
  * belongs in this list, not in enumerateUserDevFlowContent.
+ *
+ * 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) {
+export async function removeDevFlowInstallArtifacts(devflowDir, verbose, mayChange = changeAnything) {
     const manifestPath = path.join(devflowDir, 'manifest.json');
-    try {
-        await fs.rm(manifestPath, { force: true });
-        if (verbose) {
-            p.log.success('Removed manifest.json');
+    if (await mayChange(manifestPath)) {
+        try {
+            await fs.rm(manifestPath, { force: true });
+            if (verbose) {
+                p.log.success('Removed manifest.json');
+            }
+        }
+        catch (error) {
+            p.log.warn(`Could not remove manifest.json: ${error}`);
         }
     }
-    catch (error) {
-        p.log.warn(`Could not remove manifest.json: ${error}`);
-    }
-    // Proxy install artifacts — remove non-fatally (per-item failure isolation, avoids PF-009)
+    // Proxy install artifacts — remove non-fatally (per-item failure isolation)
     // Inform the user if a proxy relay process is still running (never kill — informational only).
     try {
         const pidContent = await fs.readFile(path.join(devflowDir, 'proxy.pid'), 'utf-8');
@@ -594,7 +671,7 @@ export async function removeDevFlowInstallArtifacts(devflowDir, verbose) {
         }
     }
     catch { /* proxy.pid absent or unreadable — non-fatal */ }
-    // All install artifacts removed non-fatally (avoids PF-009). Resolved against
+    // All install artifacts removed non-fatally. Resolved against
     // disk first, so a per-run staging basename is a real path by the time the
     // containment guard below sees it.
     for (const artifact of await resolveInstallArtifactPaths(devflowDir)) {
@@ -607,6 +684,8 @@ export async function removeDevFlowInstallArtifacts(devflowDir, verbose) {
         if (!isContainedIn(devflowDir, artifact.relPath)) {
             continue;
         }
+        if (!(await mayChange(fullPath)))
+            continue;
         try {
             await fs.rm(fullPath, { force: true, recursive: artifact.isDir === true });
             if (verbose)
@@ -654,7 +733,7 @@ export async function isDevFlowInstalled(claudeDir) {
  * scope directories, intersected with what actually exists on disk.
  *
  * Extracted from the dry-run loop body so the enumeration logic is
- * independently testable (avoids PF-018: tests must exercise the production
+ * independently testable (tests must exercise the production
  * path, not only the pure helper functions).
  *
  * Coverage matches removeAllDevFlow exactly:
@@ -664,7 +743,7 @@ export async function isDevFlowInstalled(claudeDir) {
  *      - Prefixed (devflow:name): live registry ∪ LEGACY_SKILL_NAMES.
  *      - Bare (name or devflow-name legacy): LEGACY_SKILL_NAMES ONLY.
  *        ~/.claude/skills/ is shared; bare dirs for live-registry skill names
- *        are by construction foreign to Devflow (avoids PF-012).
+ *        are by construction foreign to Devflow.
  *   3. manifest.json (removed separately in removeDevFlowInstallArtifacts).
  *   4. Every artifact path from installArtifactPaths(devflowDir) — the single
  *      source of truth shared with the real removal loop.
@@ -688,7 +767,7 @@ export async function enumerateDryRunExtras(claudeDir, devflowDir) {
         catch { /* absent */ }
     }
     // 2. Skills: enumerate ALL removal candidates that exist on disk.
-    // Mirrors removeAllDevFlow's split-pass approach (avoids PF-012 + PF-018):
+    // Mirrors removeAllDevFlow's split-pass approach:
     //   Prefixed: live registry ∪ LEGACY_SKILL_NAMES ∪ FEATURE_OWNED_SKILLS
     //   Bare: LEGACY_SKILL_NAMES only — shared skills/ dir; live-registry bare
     //         dirs are by construction foreign to Devflow.
@@ -812,6 +891,8 @@ 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 });
     // 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.
@@ -819,23 +900,25 @@ export async function runSelectivePhaseForScope(opts) {
         const agentsInstallDir = path.join(claudeDir, 'agents', 'devflow');
         try {
             await fs.access(agentsInstallDir);
-            await revertExternalAgents({
-                installDir: agentsInstallDir,
-                devflowDir,
-                onWarning: (msg) => { if (verbose)
-                    p.log.warn(msg); },
-            });
+            if (await mayChange(agentsInstallDir)) {
+                await revertExternalAgents({
+                    installDir: agentsInstallDir,
+                    devflowDir,
+                    onWarning: (msg) => { if (verbose)
+                        p.log.warn(msg); },
+                });
+            }
         }
         catch { /* agents dir absent or revert failed — non-fatal */ }
     }
-    await removeSelectedPlugins(claudeDir, selectedPlugins, verbose, installedPlugins);
+    await removeSelectedPlugins(claudeDir, selectedPlugins, verbose, installedPlugins, mayChange);
     // Clean up ambient hook if ambient plugin is being removed
     if (selectedPlugins.some(sp => sp.name === 'devflow-ambient')) {
         const settingsPath = path.join(claudeDir, 'settings.json');
         try {
             const settings = await fs.readFile(settingsPath, 'utf-8');
             const updated = await removeAmbientHook(settings, { purgeLegacyRule: scope === 'user' });
-            if (updated !== settings) {
+            if (updated !== settings && await mayChange(settingsPath)) {
                 await writeSettingsFileAtomic(settingsPath, updated);
                 if (verbose) {
                     p.log.success('Ambient mode hooks removed from settings.json');
@@ -866,6 +949,8 @@ export async function runSelectivePhaseForScope(opts) {
  */
 export async function runFullPhaseForScope(opts) {
     const { scope, claudeDir, devflowDir, devflowScriptsDir, verbose, keepDocs, isTTY } = opts;
+    // D-CLI-NO-SYMLINK: a legacy local install's removals and rewrites pass this first.
+    const mayChange = scopeChangeGuard(scope, { claudeDir, devflowDir });
     // Revert GPT agent frontmatter before removing agents — ensures no orphaned
     // GPT model lines remain if agents dir is preserved by a later partial flow.
     // Non-fatal: tolerate missing agents dir or revert errors.
@@ -873,24 +958,26 @@ export async function runFullPhaseForScope(opts) {
         const agentsInstallDir = path.join(claudeDir, 'agents', 'devflow');
         try {
             await fs.access(agentsInstallDir);
-            await revertExternalAgents({
-                installDir: agentsInstallDir,
-                devflowDir,
-                onWarning: (msg) => { if (verbose)
-                    p.log.warn(msg); },
-            });
+            if (await mayChange(agentsInstallDir)) {
+                await revertExternalAgents({
+                    installDir: agentsInstallDir,
+                    devflowDir,
+                    onWarning: (msg) => { if (verbose)
+                        p.log.warn(msg); },
+                });
+            }
         }
         catch { /* agents dir absent or revert failed — non-fatal */ }
     }
     // removeAllDevFlow removes Claude Code assets (commands, agents, rules, skills)
     // and devflowDir/scripts/. Scope-aware cleanup handles the rest of devflowDir.
-    await removeAllDevFlow(claudeDir, devflowScriptsDir, verbose);
+    await removeAllDevFlow(claudeDir, devflowScriptsDir, verbose, mayChange);
     if (scope === 'local') {
         // Local scope: devflowDir is gitRoot/.devflow/ which holds project data
         // (memory, learning, features, docs, config.json). Never remove those —
         // only remove install artifacts: scripts/ (done above) + manifest.json and
         // the other Devflow-generated artifacts (see removeDevFlowInstallArtifacts).
-        await removeDevFlowInstallArtifacts(devflowDir, verbose);
+        await removeDevFlowInstallArtifacts(devflowDir, verbose, mayChange);
         p.log.info('Local project data (memory, learning, features, docs) preserved');
     }
     else {
@@ -923,7 +1010,7 @@ export async function runFullPhaseForScope(opts) {
             });
             if (p.isCancel(confirmFullCleanup)) {
                 // removeAllDevFlow already ran — clean up the manifest to leave a consistent
-                // state. avoids PF-014: process.exit() here would skip removeDevFlowInstallArtifacts,
+                // state. process.exit() here would skip removeDevFlowInstallArtifacts,
                 // leaving a stale manifest.json that points to assets no longer on disk.
                 await removeDevFlowInstallArtifacts(devflowDir, verbose);
                 p.log.info(`${devflowDir} preserved (full removal cancelled; removing scripts and install artifacts only)`);
@@ -945,7 +1032,7 @@ export async function runFullPhaseForScope(opts) {
  *
  * D-UNINSTALL-CARVE-OUT: DEVFLOW_TRACKED_PATHS are never removed. `--keep-docs`,
  * a non-interactive run, a decline and a cancel all leave the directory untouched,
- * and a cancel continues the uninstall rather than exiting (avoids PF-014). The
+ * and a cancel continues the uninstall rather than exiting. The
  * directory itself is removed only when nothing tracked was in it.
  */
 async function runProjectDataStep(plan, gates) {
@@ -1109,7 +1196,12 @@ export async function runCleanupPhase(opts) {
                 applyProxyTeardownToSettings(parsedSettings, opts.managedProxyPorts?.get(scope));
                 settingsContent = JSON.stringify(parsedSettings, null, 2) + '\n';
             }
-            if (settingsContent !== originalContent) {
+            // D-CLI-NO-SYMLINK: a legacy local install's settings.json is rewritten only
+            // where no symbolic link leads it out of `<gitRoot>/.claude`.
+            const mayChange = scope === 'local'
+                ? legacyLocalChangeGuard(paths, 'settings.json not edited')
+                : changeAnything;
+            if (settingsContent !== originalContent && await mayChange(settingsPath)) {
                 await writeSettingsFileAtomic(settingsPath, settingsContent);
                 if (verbose) {
                     p.log.success(`Devflow hooks removed from settings.json (${scope})`);
@@ -1391,8 +1483,11 @@ export const uninstallCommand = new Command('uninstall')
 });
 /**
  * Remove all Devflow assets (full 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) {
+export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose, mayChange = changeAnything) {
     const devflowDirectories = [
         { path: path.join(claudeDir, 'commands', 'devflow'), name: 'commands' },
         { path: path.join(claudeDir, 'agents', 'devflow'), name: 'agents' },
@@ -1400,6 +1495,8 @@ export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose) {
         { path: devflowScriptsDir, name: 'scripts' }
     ];
     for (const dir of devflowDirectories) {
+        if (!(await mayChange(dir.path)))
+            continue;
         try {
             await fs.rm(dir.path, { recursive: true, force: true });
             if (verbose) {
@@ -1412,7 +1509,7 @@ export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose) {
     }
     // Remove Devflow skill directories.
     // ~/.claude/skills/ is shared with other tools; the two passes use different
-    // name sets to avoid deleting foreign dirs (avoids PF-012):
+    // name sets to avoid deleting foreign dirs:
     //
     //   Prefixed pass (devflow:name): live registry ∪ LEGACY_SKILL_NAMES ∪ FEATURE_OWNED_SKILLS.
     //     prefixSkillName() is idempotent for already-prefixed legacy entries.
@@ -1421,7 +1518,7 @@ export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose) {
     //   Bare pass (name or devflow-name legacy): LEGACY_SKILL_NAMES ONLY.
     //     A bare dir whose name matches a live-registry skill is by construction
     //     foreign to Devflow (the devflow: namespace shipped in dcecda3, 2026-03-30).
-    //     A bare 'compliance/' dir is also foreign (not in LEGACY_SKILL_NAMES) — PF-012.
+    //     A bare 'compliance/' dir is also foreign (not in LEGACY_SKILL_NAMES).
     const prefixedSkillNames = new Set([...getAllSkillNames(), ...LEGACY_SKILL_NAMES, ...FEATURE_OWNED_SKILLS]);
     const skillsDir = path.join(claudeDir, 'skills');
     let skillsRemoved = 0;
@@ -1430,6 +1527,8 @@ export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose) {
         const prefixedPath = path.join(skillsDir, prefixSkillName(skillName));
         try {
             await fs.stat(prefixedPath);
+            if (!(await mayChange(prefixedPath)))
+                continue;
             await fs.rm(prefixedPath, { recursive: true, force: true });
             skillsRemoved++;
         }
@@ -1440,6 +1539,8 @@ export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose) {
         const barePath = path.join(skillsDir, skillName);
         try {
             await fs.stat(barePath);
+            if (!(await mayChange(barePath)))
+                continue;
             await fs.rm(barePath, { recursive: true, force: true });
             skillsRemoved++;
         }
@@ -1449,8 +1550,12 @@ export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose) {
         p.log.success(`Removed ${skillsRemoved} Devflow skill directories`);
     }
     // Also remove old nested skills structure if it exists
+    const nestedSkillsDir = path.join(claudeDir, 'skills', 'devflow');
     try {
-        await fs.rm(path.join(claudeDir, 'skills', 'devflow'), { recursive: true, force: true });
+        await fs.stat(nestedSkillsDir);
+        if (await mayChange(nestedSkillsDir)) {
+            await fs.rm(nestedSkillsDir, { recursive: true, force: true });
+        }
     }
     catch {
         // Old structure doesn't exist
@@ -1459,7 +1564,7 @@ export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose) {
     // 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);
+    await sweepDevflowNamespaces(claudeDir, verbose, mayChange);
 }
 /**
  * Registry-diff sweep of all Devflow-owned namespaces in `claudeDir`:
@@ -1472,23 +1577,29 @@ export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose) {
  * cleaned up promptly rather than accumulating on disk.
  *
  * knownNames spans ALL plugins for each asset type so assets belonging to
- * plugins NOT being uninstalled are never swept (avoids PF-012).
+ * plugins NOT being uninstalled are never swept.
  *
  * Removals are announced only under `verbose`, but removal FAILURES always warn:
  * a swept-but-not-actually-removed agent or command keeps loading in Claude Code,
  * 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.
  */
-export async function sweepDevflowNamespaces(claudeDir, verbose) {
+export async function sweepDevflowNamespaces(claudeDir, verbose, mayChange = changeAnything) {
     const agentsDir = path.join(claudeDir, 'agents', 'devflow');
     const commandsDir = path.join(claudeDir, 'commands', 'devflow');
     const skillsDir = path.join(claudeDir, 'skills');
-    const agentsSweep = await sweepOrphanedAssets(agentsDir, new Set(getAllAgentNames()), mdEntryName);
-    const commandsSweep = await sweepOrphanedAssets(commandsDir, new Set(getAllCommandNames()), mdEntryName);
+    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);
     // 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 sweepOrphanedAssets(skillsDir, new Set([...getAllSkillNames(), ...FEATURE_OWNED_SKILLS]), (entry) => entry.startsWith(SKILL_NAMESPACE) ? unprefixSkillName(entry) : null);
+    const skillsSweep = await sweep(skillsDir, new Set([...getAllSkillNames(), ...FEATURE_OWNED_SKILLS]), (entry) => entry.startsWith(SKILL_NAMESPACE) ? unprefixSkillName(entry) : null);
     const byKind = [
         { kind: 'agent', sweep: agentsSweep },
         { kind: 'command', sweep: commandsSweep },
@@ -1511,14 +1622,18 @@ export async function sweepDevflowNamespaces(claudeDir, verbose) {
  * 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).
  */
-export async function removeSelectedPlugins(claudeDir, plugins, verbose, installedPlugins = DEVFLOW_PLUGINS) {
+export async function removeSelectedPlugins(claudeDir, plugins, verbose, installedPlugins = DEVFLOW_PLUGINS, mayChange = changeAnything) {
     const { skills, agents, commands, rules } = computeAssetsToRemove(plugins, installedPlugins);
     const commandsDir = path.join(claudeDir, 'commands', 'devflow');
     for (const cmd of commands) {
-        const cmdFileName = mdFileName(cmd.replace(/^\//, ''));
+        const cmdPath = path.join(commandsDir, mdFileName(cmd.replace(/^\//, '')));
+        if (!(await mayChange(cmdPath)))
+            continue;
         try {
-            await fs.rm(path.join(commandsDir, cmdFileName), { force: true });
+            await fs.rm(cmdPath, { force: true });
             if (verbose) {
                 p.log.success(`Removed command ${cmd}`);
             }
@@ -1529,8 +1644,11 @@ 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)))
+            continue;
         try {
-            await fs.rm(path.join(agentsDir, mdFileName(agent)), { force: true });
+            await fs.rm(agentPath, { force: true });
             if (verbose) {
                 p.log.success(`Removed agent ${agent}`);
             }
@@ -1546,9 +1664,12 @@ export async function removeSelectedPlugins(claudeDir, plugins, verbose, install
         // exclusively by the frozen LEGACY_SKILL_NAMES pass in removeAllDevFlow and
         // in init.ts; live-registry skills never had bare installs (the devflow:
         // namespace shipped in dcecda3, 2026-03-30), so a bare dir for a current
-        // registry name is by construction foreign (avoids PF-012).
+        // registry name is by construction foreign.
+        const skillPath = path.join(skillsDir, prefixSkillName(skill));
+        if (!(await mayChange(skillPath)))
+            continue;
         try {
-            await fs.rm(path.join(skillsDir, prefixSkillName(skill)), { recursive: true, force: true });
+            await fs.rm(skillPath, { recursive: true, force: true });
         }
         catch { /* Skill might not exist */ }
         if (verbose) {
@@ -1557,8 +1678,11 @@ 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)))
+            continue;
         try {
-            await fs.rm(path.join(rulesDir, mdFileName(rule)), { force: true });
+            await fs.rm(rulePath, { force: true });
             if (verbose) {
                 p.log.success(`Removed rule ${rule}`);
             }
@@ -1568,7 +1692,7 @@ export async function removeSelectedPlugins(claudeDir, plugins, verbose, install
     // Registry-diff sweep: agents, commands, AND skills — named step (A6).
     // 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 (avoids PF-012).
-    await sweepDevflowNamespaces(claudeDir, verbose);
+    // non-selected plugins are never swept.
+    await sweepDevflowNamespaces(claudeDir, verbose, mayChange);
 }
 //# sourceMappingURL=uninstall.js.map

package/dist/cli/flags-view/render.js

@@ -1,8 +1,8 @@
 /**
  * Pure TUI frame renderer for the devflow flags view.
  *
- * applies ADR-013: CLI-layer view module; zero fs/tty imports.
- * avoids PF-014: pure function, no process.exit(), no I/O.
+ * CLI-layer view module; zero fs/tty imports.
+ * Pure function, no process.exit(), no I/O.
  *
  * Layout (FIXED_ROWS = 10, viewport = state.viewportHeight — single owner):
  *   1  Title "  Devflow Flags"
@@ -59,14 +59,14 @@ export function computeViewportHeight(termRows) {
  *   non-boolean at devflow default → plain string
  *   non-boolean deviating from devflow default → bold string
  *
- * Colour vocabulary (one colour, one semantic — applies ADR-016's amendment lesson):
+ * Colour vocabulary (one colour, one semantic):
  *   cyan   = focus indicator (chevron wrapper ‹ › on the cursor row only)
  *   yellow = dirty indicator (unconditional ●) and boolean 'off'
  *   green  = boolean 'on'
  *   bold   = non-boolean value deviating from devflow default
  *
  * disk-sourced values are routed through sanitizeCell to prevent TAB/LF
- * layout breaks inside the fixed-width TUI cell (avoids PF-023).
+ * layout breaks inside the fixed-width TUI cell.
  */
 function formatValue(row) {
     const v = row.configuredValue;
@@ -151,7 +151,7 @@ function renderRow(row, isCursor, isEditing, editBuffer, editCaret, labelW, valu
     // so an inner RESET (e.g. from green('on')) does not kill the outer cyan.
     //   cyan('‹ ') + <styled-or-plain content> + cyan(' ›')
     // rather than cyan(`‹ ${content} ›`), which terminates the outer cyan at the
-    // inner RESET, leaving the closing chevron unstyled (applies ADR-016 amendment lesson).
+    // inner RESET, leaving the closing chevron unstyled.
     const chevronBudget = valueW - 4;
     let valueCell;
     if (isCursor && isEditing) {

package/dist/cli/flags-view/state.js

@@ -1,20 +1,20 @@
 /**
  * Pure keypress reducer for the devflow flags TUI.
  *
- * applies ADR-013: CLI-layer view module; consumes src/core/ imports only.
- * applies ADR-016: one syntax, one semantic — value vocabulary.
- * avoids PF-014: pure functions only — no process.exit(), no I/O.
- * avoids PF-017: generic shell in tui/terminal.ts; this module is pure logic.
+ * CLI-layer view module; consumes src/core/ imports only.
+ * One syntax, one semantic — value vocabulary.
+ * Pure functions only — no process.exit(), no I/O.
+ * Generic shell in tui/terminal.ts; this module is pure logic.
  *
  * viewMode GLUE RULE: view-mode's neutralValue ('default') maps to null in the TUI.
  * `buildFlagRows` maps record value 'default' → null via `recordToTui` (core/flags.ts);
  * `collectFlagRecord` maps null → 'default' via `tuiToRecord` (core/flags.ts).
  * Number 0 is ACTIVE — null ≠ 0. Both functions live next to neutralValueOf, their
- * definition dependency (PF-017 one-shared-definition corollary).
+ * definition dependency, so there is one shared definition rather than per-consumer copies.
  *
  * Strict number parsing: leading/trailing whitespace and leading zeros are
  * invalid ('007' → error, ' 8' → error). This rejects pathological inputs
- * before they reach coerceFlagValue (applies PF-023).
+ * before they reach coerceFlagValue.
  *
  * Buffer hard cap: BUFFER_MAX_LEN = 64 chars (paste-flood guard).
  *
@@ -198,8 +198,8 @@ function enterEdit(state) {
  * Contract:
  *   - Empty buffer + allowUnset → commit null (unset)
  *   - Empty buffer + !allowUnset → error "Value is required"
- *   - For number/string flags: delegate to parseFlagValueInput (applies PF-023 —
- *     strict grammar enforced at the core sink, not per-caller). Error messages
+ *   - For number/string flags: delegate to parseFlagValueInput (strict grammar
+ *     enforced at the core sink, not per-caller). Error messages
  *     distinguish format failures (padded/hex/leading-zeros) from bounds failures.
  *   - parseFlagValueInput returns null on invalid input → stay editing + error
  */
@@ -230,7 +230,7 @@ function commitEdit(state) {
             };
         }
     }
-    // Number flag: parseFlagValueInput enforces strict decimal grammar (avoids PF-023).
+    // Number flag: parseFlagValueInput enforces strict decimal grammar.
     // Provide specific error messages to distinguish format from bounds failures.
     if (flagDef.kind === 'number') {
         if (buf !== buf.trim()) {

package/dist/cli/flags-view/terminal.js

@@ -1,10 +1,10 @@
 /**
  * Thin adapter — devflow flags TUI shell over the generic runTui driver.
  *
- * applies ADR-013: impure I/O shell in CLI layer; pure logic lives in state.ts/render.ts.
- * avoids PF-014: cleanup wired via Promise resolve — never process.exit() inside
- *   a finally-guarded scope.
- * avoids PF-017: thin adapter over the generic shell (src/cli/tui/terminal.ts).
+ * Impure I/O shell in CLI layer; pure logic lives in state.ts/render.ts.
+ * Cleanup wired via Promise resolve — never process.exit() inside
+ *   a finally-guarded scope (it would skip the finally).
+ * Thin adapter over the generic shell (src/cli/tui/terminal.ts).
  *
  * Public API:
  *   - runFlagsTui(initialRows, io?) → Promise<FlagsTuiResult>

package/dist/cli/tui/cells.js

@@ -1,7 +1,7 @@
 /**
  * Shared TUI cell helpers — shared by agents-view and flags-view.
  *
- * Applies PF-017: generified into a shared module rather than copy-adapted per consumer.
+ * Generified into a shared module rather than copy-adapted per consumer.
  * Pure functions, no I/O.
  */
 import { stripAnsi, truncate } from '../../core/ansi.js';