devflow-kit 3.1.0 → 3.3.0

package/dist/cli/commands/learning.js

@@ -4,11 +4,14 @@ import * as path from 'path';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
 import { getLearningDir, getLearningTuningConfigPath, } from '../../core/project-paths.js';
+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 { getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
 import { getLedgerRoot } from '../../core/ledger-root.js';
 import { drainLearningQueue } from '../../core/learning-queue-cleanup.js';
+import { firstSymbolicLink } from '../../core/linked-path.js';
+import { formatRefusedDrain } from '../../core/queue-drain.js';
 import { formatLearningStoreUnavailable, loadLearningStore, } from '../../core/learning-store.js';
 // ---------------------------------------------------------------------------
 // Shared helpers
@@ -255,15 +258,50 @@ async function handleRestore(anchor) {
     }
     p.log.success(`Restored ${restored.value.anchor_id} (${restored.value.status}); it is due for review again.`);
 }
+/**
+ * The scope choices of `devflow learning --configure`.
+ *
+ * D-LEARNING-MODEL-PRECEDENCE: the session-start hook takes the first layer that
+ * supplies a model — the project file, then a `devflow agents` Learning mapping,
+ * then the global file. A global file therefore has no effect for a user who has
+ * such a mapping, and its hint says so.
+ */
+export const CONFIGURE_SCOPE_OPTIONS = [
+    { value: 'project', label: 'Project', hint: 'This project only (.devflow/learning/learning.json)' },
+    {
+        value: 'global',
+        label: 'Global',
+        hint: 'All projects (~/.devflow/learning.json); a devflow agents Learning mapping takes precedence over it',
+    },
+];
+/** The models `devflow learning --configure` offers, each with what it is good for. */
+const LEARNING_MODEL_CHOICES = [
+    { value: 'opus', label: 'Opus', note: 'highest quality for detection + curation judgment' },
+    { value: 'sonnet', label: 'Sonnet', note: 'good balance of quality and speed' },
+    { value: 'haiku', label: 'Haiku', note: 'fastest, lowest cost' },
+];
+/**
+ * D-LEARNING-SHIPPED-ROW: the model offered as "Recommended" is the one the Learning
+ * agent ships with, the `model:` line of its frontmatter. It is read from there and
+ * written nowhere else, so a change of the shipped tier moves the recommendation with
+ * it and this list never has to be edited. A shipped model outside the three offered
+ * (or none) recommends nothing.
+ */
+export function learningModelOptions(shippedModel) {
+    return LEARNING_MODEL_CHOICES.map(choice => ({
+        value: choice.value,
+        label: choice.label,
+        hint: choice.value === shippedModel
+            ? `Recommended — ${choice.note}`
+            : choice.note.charAt(0).toUpperCase() + choice.note.slice(1),
+    }));
+}
 async function handleConfigure() {
     p.intro(color.bgCyan(color.black(' Learning Configuration ')));
+    const shippedModel = (await loadShippedAgentDefaults()).learning?.model;
     const model = await p.select({
         message: 'Model for decision detection',
-        options: [
-            { value: 'opus', label: 'Opus', hint: 'Recommended — highest quality for detection + curation judgment' },
-            { value: 'sonnet', label: 'Sonnet', hint: 'Good balance of quality and speed' },
-            { value: 'haiku', label: 'Haiku', hint: 'Fastest, lowest cost' },
-        ],
+        options: learningModelOptions(shippedModel),
     });
     if (p.isCancel(model)) {
         p.cancel('Configuration cancelled.');
@@ -279,10 +317,7 @@ async function handleConfigure() {
     }
     const scope = await p.select({
         message: 'Configuration scope',
-        options: [
-            { value: 'project', label: 'Project', hint: 'This project only (.devflow/learning/learning.json)' },
-            { value: 'global', label: 'Global', hint: 'All projects (~/.devflow/learning.json)' },
-        ],
+        options: [...CONFIGURE_SCOPE_OPTIONS],
     });
     if (p.isCancel(scope)) {
         p.cancel('Configuration cancelled.');
@@ -304,8 +339,17 @@ async function handleConfigure() {
         // from the ledger ($LEDGER_ROOT/.devflow/learning/), so write it there — the
         // main checkout in a linked worktree; the current directory outside git.
         const projectRoot = (await getLedgerRoot()) ?? process.cwd();
-        await fs.mkdir(getLearningDir(projectRoot), { recursive: true });
+        const learningDir = getLearningDir(projectRoot);
         const projectConfigPath = getLearningTuningConfigPath(projectRoot);
+        // D-CLI-NO-SYMLINK (core/linked-path.ts): nothing is written through a .devflow,
+        // a learning folder or a learning.json that is a symbolic link.
+        const linked = await firstSymbolicLink([path.dirname(learningDir), learningDir, projectConfigPath]);
+        if (linked !== null) {
+            p.log.error(`Project config not written: ${linked} is a symbolic link, and devflow writes nothing through one`);
+            process.exitCode = 1;
+            return;
+        }
+        await fs.mkdir(learningDir, { recursive: true });
         await fs.writeFile(projectConfigPath, configJson, 'utf-8');
         p.log.success(`Project config written to ${color.dim(projectConfigPath)}`);
     }
@@ -376,9 +420,11 @@ async function handleClear() {
     }
     // A mid-run Learning agent whose claimed batch vanishes stops without further
     // writes — the desired outcome of clearing.
-    await drainLearningQueue(ledgerRoot);
+    const drain = await drainLearningQueue(ledgerRoot);
     p.log.success(`Cleared ${counted(cleared.value.cleared, 'observation')} no entry uses and kept ${cleared.value.kept} ` +
-        'that entries use; drained the learning queue.');
+        `that entries use${drain.drained ? '; drained the learning queue.' : '.'}`);
+    if (!drain.drained)
+        p.log.warn(formatRefusedDrain('learning', drain.linkedFolder));
 }
 /**
  * `--enable` / `--disable`: the machine-wide switch (D-FEATURES-NARROW-ONLY),
@@ -403,7 +449,9 @@ async function handleToggle(enabled) {
     // batch vanishes aborts without changes — the desired outcome of disabling.
     const ledgerRoot = await getLedgerRoot();
     if (ledgerRoot) {
-        await drainLearningQueue(ledgerRoot);
+        const drain = await drainLearningQueue(ledgerRoot);
+        if (!drain.drained)
+            p.log.warn(formatRefusedDrain('learning', drain.linkedFolder));
     }
     p.log.success('Learning disabled in every project');
 }

package/dist/cli/commands/memory.js

@@ -7,7 +7,9 @@ import { getClaudeDirectory, getDevFlowDirectory } from '../../targets/claude-co
 import { writeSettingsFileAtomic } from '../../core/fs-atomic.js';
 import { discoverProjectGitRoots } from '../../targets/claude-code/post-install.js';
 import { getGitRoot } from '../../core/git.js';
+import { firstSymbolicLink } from '../../core/linked-path.js';
 import { getMemoryDir, getPendingTurnsPath, getPendingTurnsProcessingPath, } from '../../core/project-paths.js';
+import { drainQueueFiles, formatRefusedDrain } from '../../core/queue-drain.js';
 import { HOOKS_DIR_SUFFIX, devflowHookOwner, endsWithAny, ensureHook, hasHook, removeHooks, runHookCommand, runHookSuffix, } from '../../targets/claude-code/hooks.js';
 import { readMachineFeature, writeMachineFeature } from '../../core/feature-switch.js';
 import { loadSettingsModule, narrowedSwitchLabel, personalConfigTrackedWarning } from '../../core/evidence-policy.js';
@@ -142,15 +144,16 @@ export function convergeMemoryHooks(settingsJson, enabled, devflowDir) {
 /**
  * Drain a project's pending memory queue (and a claimed batch) so stale turns
  * are not processed when memory is next switched on. Shared by `devflow init
- * --no-memory` and `devflow memory --disable`. ENOENT-tolerant; any other
- * error propagates to the command boundary, like drainLearningQueue.
+ * --no-memory` and `devflow memory --disable`. Refused, deleting nothing, when
+ * `.devflow` or `.devflow/memory` under `projectRoot` is a symbolic link
+ * (D-CLI-NO-SYMLINK). ENOENT-tolerant; any other error propagates to the command
+ * boundary, like drainLearningQueue.
  */
 export async function drainMemoryQueue(projectRoot) {
-    const ignoreMissing = (e) => { if (e.code !== 'ENOENT')
-        throw e; };
-    await Promise.all([
-        fs.unlink(getPendingTurnsPath(projectRoot)).catch(ignoreMissing),
-        fs.unlink(getPendingTurnsProcessingPath(projectRoot)).catch(ignoreMissing),
+    const memoryDir = getMemoryDir(projectRoot);
+    return drainQueueFiles([path.dirname(memoryDir), memoryDir], [
+        getPendingTurnsPath(projectRoot),
+        getPendingTurnsProcessingPath(projectRoot),
     ]);
 }
 /**
@@ -181,12 +184,24 @@ export async function filterProjectsWithMemory(gitRoots) {
 }
 /**
  * Clean up memory queue files from the given project paths.
- * Skips projects where the background updater lock is held to avoid data loss.
- * Returns the count of projects from which at least one file was removed.
+ * Skips projects where the background updater lock is held to avoid data loss,
+ * and refuses, deleting nothing there, a project whose `.devflow` or
+ * `.devflow/memory` is a symbolic link (D-CLI-NO-SYMLINK); `refused` names each
+ * such link. Returns the count of projects from which at least one file was removed.
  */
 export async function cleanQueueFiles(projectPaths) {
     const results = await Promise.all(projectPaths.map(async (project) => {
         const memDir = getMemoryDir(project);
+        let linkedFolder;
+        try {
+            linkedFolder = await firstSymbolicLink([path.dirname(memDir), memDir]);
+        }
+        catch {
+            // The folders cannot be checked: delete nothing there, and go on to the others.
+            return null;
+        }
+        if (linkedFolder !== null)
+            return { refused: linkedFolder };
         const lockDir = path.join(memDir, '.working-memory.lock');
         try {
             await fs.access(lockDir);
@@ -200,10 +215,11 @@ export async function cleanQueueFiles(projectPaths) {
             fs.unlink(getPendingTurnsPath(project)).then(() => true).catch(() => false),
             fs.unlink(getPendingTurnsProcessingPath(project)).then(() => true).catch(() => false),
         ]);
-        return (q || pr) ? project : null;
+        return (q || pr) ? { cleaned: project } : null;
     }));
-    const cleanedProjects = results.filter((p) => p !== null);
-    return { cleaned: cleanedProjects.length, projects: cleanedProjects };
+    const cleanedProjects = results.flatMap((r) => (r !== null && 'cleaned' in r ? [r.cleaned] : []));
+    const refused = results.flatMap((r) => (r !== null && 'refused' in r ? [r.refused] : []));
+    return { cleaned: cleanedProjects.length, projects: cleanedProjects, refused };
 }
 export const memoryCommand = new Command('memory')
     .description('Enable, disable, or clean up working memory (session context preservation)')
@@ -263,10 +279,13 @@ export const memoryCommand = new Command('memory')
             }
             targets = scope === 'local' && currentProject ? [currentProject] : allProjects;
         }
-        const { cleaned, projects: cleanedProjects } = await cleanQueueFiles(targets);
+        const { cleaned, projects: cleanedProjects, refused } = await cleanQueueFiles(targets);
         for (const project of cleanedProjects) {
             p.log.info(color.dim(`Cleaned: ${project}`));
         }
+        for (const linkedFolder of refused) {
+            p.log.warn(formatRefusedDrain('memory', linkedFolder));
+        }
         p.log.success(cleaned > 0
             ? `Cleaned queue files from ${cleaned} project${cleaned > 1 ? 's' : ''}`
             : 'No queue files found to clean');
@@ -341,7 +360,9 @@ export const memoryCommand = new Command('memory')
     // there is no project queue to drain, and the switch itself still applies.
     const gitRoot = await getGitRoot();
     if (gitRoot) {
-        await drainMemoryQueue(gitRoot);
+        const drain = await drainMemoryQueue(gitRoot);
+        if (!drain.drained)
+            p.log.warn(formatRefusedDrain('memory', drain.linkedFolder));
     }
     p.log.success('Working memory disabled in every project');
 });

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.
  *
@@ -567,17 +639,22 @@ 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)
     // Inform the user if a proxy relay process is still running (never kill — informational only).
@@ -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)
@@ -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 {
@@ -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) {
@@ -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`:
@@ -1477,18 +1582,24 @@ export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose) {
  * 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}`);
             }
@@ -1547,8 +1665,11 @@ export async function removeSelectedPlugins(claudeDir, plugins, verbose, install
         // 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.
+        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}`);
             }
@@ -1569,6 +1693,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.
-    await sweepDevflowNamespaces(claudeDir, verbose);
+    await sweepDevflowNamespaces(claudeDir, verbose, mayChange);
 }
 //# sourceMappingURL=uninstall.js.map

package/dist/commands/code-review.md

@@ -24,7 +24,7 @@ Run a comprehensive code review of the current branch by spawning parallel revie
 
 1. **Discover reviewable worktrees** using the `devflow:worktree-support` skill discovery algorithm:
    - Run `git worktree list --porcelain` → parse, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit
-   - See the `devflow:worktree-support` skill for the full 7-step algorithm and canonical protected branch list
+   - Invoke the `devflow:worktree-support` skill, then Read its `references/discovery.md` from the skill's base directory for the full 7-step algorithm; the canonical protected branch list stays in the skill
 2. **If `--path` flag provided:** use only that worktree, skip discovery
    **`--path` validation**: Before proceeding, verify the path exists as a directory and appears in `git worktree list` output. If not: report error and stop.
 3. **If only 1 reviewable worktree** (the common case): proceed as single-worktree flow — zero behavior change
@@ -228,8 +228,6 @@ Only `exit=0` means the skill is installed. On any other result, do NOT add that
 
 **Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, COMPLIANCE_FRAMEWORKS (carried from Step 0b)
 
-**Load Companion Skills** — Load via Skill tool: `devflow:quality-gates`, `devflow:software-design`. If a skill fails to load, continue without it.
-
 ### Load DECISIONS_CONTEXT
 
 The decisions ledger belongs to the repository, not to one checkout: in a linked worktree it lives in the main worktree, and a session started in a subdirectory reads the copy at the repository root. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):