devflow-kit 2.5.0 → 3.0.0

package/dist/cli/commands/uninstall.js

@@ -4,11 +4,11 @@ import * as os from 'os';
 import * as path from 'path';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
-import { getInstallationPaths, getClaudeDirectory, getManagedSettingsPath } from '../../targets/claude-code/claude-paths.js';
+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, getAllSkillNames, getAllAgentNames, getAllCommandNames, parsePluginSelection, resolveFeatureRedirect, prefixSkillName, unprefixSkillName, skillsOf, FEATURE_OWNED_SKILLS } from '../../core/plugins.js';
 import { readManifest } from '../../core/manifest.js';
-import { TRACKER_ATTEMPTS_FILE, TRACKER_CLAIM_FILE, TRACKER_ENABLED_FILE } from '../../core/tracker.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';
@@ -20,15 +20,54 @@ import { removeContextHook } from './context.js';
 import { applyProxyTeardownToSettings } from './proxy.js';
 import { readProxyState, proxyJsonExists } from '../../core/proxy-state.js';
 import { hudCacheDir } from '../../core/cache.js';
-import { TRACKER_CONVENTIONS_FILE, TRACKER_CONVENTIONS_BACKUP_NAMES, TRACKER_STAGED_PREFIX, } from '../../core/tracker.js';
+import { TRACKER_ATTEMPTS_NAMES, TRACKER_CLAIM_FILE, TRACKER_CONVENTIONS_DIR, TRACKER_ENABLED_FILE, TRACKER_LEGACY_ATTEMPTS_FILE, TRACKER_LEGACY_CONVENTIONS_FILE, TRACKER_PROVIDER_IDS, TRACKER_STAGED_PREFIX, } from '../../core/tracker.js';
 import { revertExternalAgents } from '../../core/agent-models.js';
 import { detectShell, getProfilePath } from '../../core/safe-delete.js';
 import { isAlreadyInstalled, removeFromProfile } from '../../core/safe-delete-install.js';
-import { removeManagedSettings, stripUserDenyList, detectDenyState, DEVFLOW_HISTORICAL_DENY } from '../../targets/claude-code/post-install.js';
-import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
+import { removeManagedSettings, stripUserDenyList, detectDenyState, DEVFLOW_HISTORICAL_DENY, DEVFLOW_TRACKED_PATHS } from '../../targets/claude-code/post-install.js';
+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';
+/**
+ * Where a retired repo-local install lives: `<gitRoot>/.claude` and `<gitRoot>/.devflow`.
+ *
+ * D-LEGACY-LOCAL-CLEANUP: `init --scope local` no longer exists (D-SCOPE-RETIRED
+ * in claude-paths.ts), but repos installed by it still carry its assets, so
+ * `uninstall` keeps detecting and removing them. This is the ONLY place a
+ * repo-local install path is derived, and it is private to uninstall: nothing
+ * installs there any more. A local-only uninstall never reaches the user's
+ * settings.json or anything else under HOME — the settings strip edits
+ * `<gitRoot>/.claude/settings.json`, the legacy commands-rule purge is skipped,
+ * and the machine-wide steps (security deny list, safe-delete) run only when
+ * the user scope is being uninstalled too.
+ *
+ * Returns null when either repo-local directory IS a machine-wide one — a
+ * repository rooted at HOME (a dotfiles repo) puts `<gitRoot>/.claude` and
+ * `<gitRoot>/.devflow` on `~/.claude` and `~/.devflow`, and a "local" removal
+ * there would be a machine-wide uninstall under another name.
+ */
+async function legacyLocalInstallPaths(gitRoot) {
+    const legacy = {
+        claudeDir: path.join(gitRoot, '.claude'),
+        devflowDir: path.join(gitRoot, '.devflow'),
+    };
+    const machine = getInstallationPaths();
+    if (await isSameLocation(legacy.claudeDir, machine.claudeDir))
+        return null;
+    if (await isSameLocation(legacy.devflowDir, machine.devflowDir))
+        return null;
+    return legacy;
+}
+/**
+ * The directories for `scope`, or null for a local scope with no repo-local
+ * install to act on: outside a git repository, or in one rooted at HOME.
+ */
+async function scopeInstallPaths(scope, gitRoot) {
+    if (scope === 'user')
+        return getInstallationPaths();
+    return gitRoot === null ? null : legacyLocalInstallPaths(gitRoot);
+}
 /**
  * The plugins the manifest records as installed, as registry definitions.
  *
@@ -164,6 +203,103 @@ export function resolveSecurityRemovalDecision(opts) {
 export function resolveProjectDataCleanup(answer) {
     return answer === true;
 }
+/** Tracked entries by name and kind: `features/` is a directory, the rest are files. */
+const TRACKED_ENTRIES = DEVFLOW_TRACKED_PATHS.map((tracked) => ({
+    name: tracked.replace(/\/$/, ''),
+    isDir: tracked.endsWith('/'),
+}));
+/**
+ * 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.
+ */
+export function partitionProjectData(entries) {
+    const isTracked = (entry) => TRACKED_ENTRIES.some((t) => t.name === entry.name && t.isDir === entry.isDir);
+    const byName = (a, b) => a.name.localeCompare(b.name);
+    return {
+        remove: entries.filter((e) => !isTracked(e)).sort(byName),
+        keep: entries.filter(isTracked).sort(byName),
+    };
+}
+/**
+ * Resolve the project-data step's target: `<gitRoot>/.devflow`, partitioned.
+ *
+ * D-UNINSTALL-CARVE-OUT: the step acts on the repository's `.devflow` at its git
+ * root — the directory devflow's hooks write — never on whatever `.devflow` the
+ * cwd happens to hold. It is skipped with no git root, and when the git root is
+ * HOME or its `.devflow` is the machine-wide devflow directory (a dotfiles repo):
+ * there `.devflow` is the install itself, not project data. Both comparisons use
+ * 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.
+ */
+export async function resolveProjectDataPlan(opts) {
+    if (opts.gitRoot === null)
+        return { kind: 'skip', reason: 'no-git-root' };
+    if (await isSameLocation(opts.gitRoot, opts.homeDir))
+        return { kind: 'skip', reason: 'home-root' };
+    const dir = path.join(opts.gitRoot, '.devflow');
+    if (await isSameLocation(dir, opts.machineDevflowDir))
+        return { kind: 'skip', reason: 'machine-dir' };
+    try {
+        if ((await fs.lstat(dir)).isSymbolicLink())
+            return { kind: 'skip', reason: 'symlink' };
+    }
+    catch {
+        return { kind: 'skip', reason: 'absent' };
+    }
+    let dirents;
+    try {
+        dirents = await fs.readdir(dir, { withFileTypes: true });
+    }
+    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 } };
+}
+/**
+ * The line that tells the user why the project-data step was skipped, or null
+ * when there is nothing worth saying (no repository, no `.devflow`). Shared by
+ * the real cleanup and the dry run so both say the same. PURE.
+ */
+export function formatProjectDataSkip(reason, gitRoot) {
+    if (gitRoot === null)
+        return null;
+    const dir = path.join(gitRoot, '.devflow');
+    switch (reason) {
+        case 'home-root':
+        case 'machine-dir':
+            return `Project data step skipped: ${dir}/ is the machine-wide devflow directory`;
+        case 'symlink':
+            return `Project data step skipped: ${dir} is a symbolic link — devflow does not follow it; remove it yourself if nothing there is needed`;
+        case 'no-git-root':
+        case 'absent':
+            return null;
+    }
+}
+/** An entry as the prompt shows it: directories carry a trailing `/`. */
+function entryLabel(entry) {
+    return entry.isDir ? `${entry.name}/` : entry.name;
+}
+/** Comma-separated labels, or `(none)`. */
+function entryList(entries) {
+    return entries.length === 0 ? '(none)' : entries.map(entryLabel).join(', ');
+}
+/**
+ * The lines shown before the project-data confirm: what is removed and what is
+ * kept. PURE.
+ */
+export function formatProjectDataPlan(plan) {
+    return [
+        `Project data in ${plan.dir}/:`,
+        `  Remove: ${entryList(plan.remove)}`,
+        `  Keep (shared via git): ${entryList(plan.keep)}`,
+    ];
+}
 /**
  * Determine the appropriate cleanup action for the user-scope devflow directory on
  * full uninstall. Mirrors the resolveSecurityRemovalDecision pattern.
@@ -175,7 +311,7 @@ export function resolveProjectDataCleanup(answer) {
  *   1. basename(devflowDir) must be '.devflow'
  *   2. devflowDir must not equal homeDir
  *   3. devflowDir must not be the filesystem root '/'
- *   4. devflowDir must reside inside $HOME (guards DEVFLOW_DIR env overrides)
+ *   4. devflowDir must reside inside $HOME
  *
  * Returns:
  *   - 'artifacts-only' — remove only manifest.json; leave the directory intact
@@ -192,14 +328,11 @@ export function resolveProjectDataCleanup(answer) {
  * --keep-docs from triggering prompts about skill shadows or preference-profile.md.
  */
 export function resolveDevflowDirCleanup(opts) {
-    // Local scope never removes project data — only install artifacts.
-    if (opts.scope !== 'user')
-        return 'artifacts-only';
     // --keep-docs: suppress the full cleanup prompt entirely; artifacts-only.
     if (opts.keepDocs)
         return 'artifacts-only';
     // Precondition guard: devflowDir must be a well-known, safe-to-rm path.
-    // Any anomalous value (DEVFLOW_DIR override, bare homedir, filesystem root)
+    // Any anomalous value (bare homedir, filesystem root, a path outside HOME)
     // resolves to artifacts-only — never throw in business logic (engineering rule).
     const isBasenameValid = path.basename(opts.devflowDir) === '.devflow';
     const isNotHomeDir = opts.devflowDir !== opts.homeDir;
@@ -239,35 +372,48 @@ export function userContentPaths(devflowDir) {
         { relPath: 'rules', isDir: true, label: `rule shadows (${path.join(devflowDir, 'rules')})` },
         // preference-profile.md — user-curated decision-preference profile
         { relPath: 'preference-profile.md', label: 'preference-profile.md' },
-        // tracker.md — the inferred, hand-editable issue-tracker conventions file.
+        // tracker/ — the inferred, hand-editable issue-tracker conventions, one file
+        // per provider (D-TRACKER-PER-PROVIDER-CONVENTIONS).
         //
         // USER CONTENT (OD-15), classified the same way as preference-profile.md above
-        // rather than as an install artifact like agent-models.json, because it is
-        // inferred ONCE per machine and then hand-editable: absence is the trigger that
-        // re-runs inference, so deleting it on every decline/cancel/--keep-docs path
-        // would silently discard work the user may have corrected by hand.
+        // rather than as an install artifact like agent-models.json, because each file
+        // is inferred ONCE per machine and then hand-editable: absence is the trigger
+        // that re-runs inference, so deleting one on every decline/cancel/--keep-docs
+        // path would silently discard work the user may have corrected by hand.
         //
         // REVERSAL CONDITION, recorded: this classification is CONDITIONAL on the
         // provider-mismatch guard shipping. agent-models.json was reclassified to an
         // artifact precisely because stale overrides re-apply *silently*; "silently" is
-        // the load-bearing word. A stale tracker.md whose frontmatter provider
+        // the load-bearing word. A conventions file whose frontmatter provider
         // disagrees with the resolved provider produces
         // `TRACEABILITY: DEGRADED (tracker configuration mismatch (conventions file))`
         // and no tracker call — that is what removes the silence, and the reason names
-        // THIS file rather than the per-repo override so the user is told which of the
-        // two to edit. If that guard is ever dropped,
-        // reclassify tracker.md to an install artifact IN THE SAME CHANGE, otherwise a
-        // silently-authoritative stale file survives uninstall.
-        { relPath: TRACKER_CONVENTIONS_FILE, label: `${TRACKER_CONVENTIONS_FILE} (issue tracker conventions)` },
-        // tracker.md.{provider}.bak — what renameStaleTrackerConventions leaves behind
-        // on a provider change. Same inferred content as tracker.md (the user's site
-        // and project key), so the same classification: named by the confirm prompt,
-        // kept by every artifacts-only pass. The names come from the registry, so a
-        // fourth provider is covered the day it lands.
-        ...TRACKER_CONVENTIONS_BACKUP_NAMES.map(name => ({
-            relPath: name,
-            label: `${name} (previous issue tracker conventions)`,
-        })),
+        // THE FILE rather than the per-repo override so the user is told which of the
+        // two to edit. If that guard is ever dropped, reclassify these to install
+        // artifacts IN THE SAME CHANGE, otherwise a silently-authoritative stale file
+        // survives uninstall.
+        {
+            relPath: TRACKER_CONVENTIONS_DIR,
+            isDir: true,
+            label: `issue tracker conventions (${path.join(devflowDir, TRACKER_CONVENTIONS_DIR)})`,
+        },
+        // tracker.md and tracker.md.{provider}.bak — the conventions earlier releases
+        // kept in one machine-wide file, and the copies they moved aside on a provider
+        // change. The per-provider migration moves tracker.md when its frontmatter
+        // names a provider whose file does not exist yet, and leaves it otherwise;
+        // nothing moves or deletes a backup. Both hold what the conventions files
+        // hold — the user's site and project key — so the same classification: named
+        // by the confirm prompt, kept by every artifacts-only pass. The backup names
+        // come from the registry, so every provider an earlier release could have
+        // backed up is covered.
+        {
+            relPath: TRACKER_LEGACY_CONVENTIONS_FILE,
+            label: `${TRACKER_LEGACY_CONVENTIONS_FILE} (issue tracker conventions from an earlier release)`,
+        },
+        ...TRACKER_PROVIDER_IDS.map(id => {
+            const name = `${TRACKER_LEGACY_CONVENTIONS_FILE}.${id}.bak`;
+            return { relPath: name, label: `${name} (previous issue tracker conventions)` };
+        }),
         // learning.json — global learning agent tuning config
         { relPath: 'learning.json', label: 'learning.json' },
         // hud.json — user HUD enable/disable preference and display config
@@ -378,14 +524,16 @@ export function installArtifactPaths(devflowDir) {
         { relPath: 'proxy-routing.json' },
         { relPath: 'proxy.pid' },
         { relPath: '.proxy-spawn.lock', isDir: true },
-        // tracker runtime artifacts — the Tracker agent's atomic claim file, its
-        // inference attempt counter, and the provider presence sentinel the
-        // SessionStart hook stats. All three are machine state with no user-authored
-        // content, so they go on this list; `tracker.md` beside them and the
-        // `tracker.md.{provider}.bak` a provider change leaves are USER CONTENT
-        // (OD-15) and are deliberately NOT here (@D8: the two lists stay disjoint).
+        // tracker runtime artifacts — the Tracker agent's atomic claim file, the
+        // per-provider inference attempt counters (and the single counter earlier
+        // releases kept), and the machine provider sentinel the SessionStart hook
+        // reads. All are machine state with no user-authored content, so they go on
+        // this list; the conventions under `tracker/` beside them, and the legacy
+        // `tracker.md` and its backups, are USER CONTENT (OD-15) and are deliberately
+        // NOT here (@D8: the two lists stay disjoint).
         { relPath: TRACKER_CLAIM_FILE },
-        { relPath: TRACKER_ATTEMPTS_FILE },
+        ...TRACKER_ATTEMPTS_NAMES.map(name => ({ relPath: name })),
+        { relPath: TRACKER_LEGACY_ATTEMPTS_FILE },
         { relPath: TRACKER_ENABLED_FILE },
         // The agent's scrubbed staging file, one per invocation under a mktemp name
         // it removes from a trap — a SIGKILL outruns the trap and leaves it behind.
@@ -414,8 +562,8 @@ export function installArtifactPaths(devflowDir) {
  * This function runs on the decline, cancel, non-interactive AND --keep-docs paths,
  * so an entry here is deleted even when the user answers "no" to the full wipe.
  * User-authored state (everything in `userContentPaths`: skill/rule shadows,
- * preference-profile.md, tracker.md and its provider backups, learning.json,
- * hud.json) is removed only by the confirmed full-dir rm.
+ * preference-profile.md, the tracker conventions with the legacy tracker.md and
+ * its backups, learning.json, hud.json) is removed only by the confirmed full-dir rm.
  * 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.
@@ -619,22 +767,31 @@ export async function runDryRunPhase(opts) {
         // skills sweep. Enumerate what is actually on disk for each detected scope
         // rather than computing from the registry (which misses legacy/orphaned assets).
         const extras = [];
+        const gitRoot = scopesToUninstall.includes('local') ? await getGitRoot() : null;
         for (const scope of [...scopesToUninstall]) {
-            try {
-                const paths = await getInstallationPaths(scope);
-                const { claudeDir: cd, devflowDir: dd } = paths;
-                const moreExtras = await enumerateDryRunExtras(cd, dd);
-                extras.push(...moreExtras);
+            const paths = await scopeInstallPaths(scope, gitRoot);
+            if (paths === null)
+                continue;
+            extras.push(...await enumerateDryRunExtras(paths.claudeDir, paths.devflowDir));
+        }
+        // Project data under <gitRoot>/.devflow — the same plan the real cleanup phase
+        // resolves, so the preview lists exactly what a confirmed removal deletes.
+        const projectRoot = await getGitRoot(process.cwd());
+        const projectData = await resolveProjectDataPlan({
+            gitRoot: projectRoot,
+            homeDir: getHomeDirectory(),
+            machineDevflowDir: getInstallationPaths().devflowDir,
+        });
+        if (projectData.kind === 'plan') {
+            for (const entry of projectData.plan.remove) {
+                extras.push(`${path.join(projectData.plan.dir, entryLabel(entry))} (if confirmed)`);
             }
-            catch { /* scope path resolution failed */ }
         }
-        // Project .devflow/ data dir
-        const devflowDataDir = path.join(process.cwd(), '.devflow');
-        try {
-            await fs.access(devflowDataDir);
-            extras.push(`${devflowDataDir} (if confirmed)`);
+        else {
+            const skipped = formatProjectDataSkip(projectData.reason, projectRoot);
+            if (skipped !== null)
+                extras.push(skipped);
         }
-        catch { /* noop */ }
         extras.push('hooks removed from settings.json');
         for (const line of extras) {
             p.log.info(`  ${line}`);
@@ -653,6 +810,7 @@ export async function runDryRunPhase(opts) {
  */
 export async function runSelectivePhaseForScope(opts) {
     const { claudeDir, devflowDir, selectedPlugins, verbose } = opts;
+    const scope = opts.scope ?? 'user';
     const installedPlugins = opts.installedPlugins ?? DEVFLOW_PLUGINS;
     // Revert GPT agent frontmatter BEFORE removing agent files — strips GPT model
     // lines from installed agent frontmatter while the files are still present.
@@ -676,9 +834,9 @@ export async function runSelectivePhaseForScope(opts) {
         const settingsPath = path.join(claudeDir, 'settings.json');
         try {
             const settings = await fs.readFile(settingsPath, 'utf-8');
-            const updated = await removeAmbientHook(settings);
+            const updated = await removeAmbientHook(settings, { purgeLegacyRule: scope === 'user' });
             if (updated !== settings) {
-                await fs.writeFile(settingsPath, updated, 'utf-8');
+                await writeSettingsFileAtomic(settingsPath, updated);
                 if (verbose) {
                     p.log.success('Ambient mode hooks removed from settings.json');
                 }
@@ -696,7 +854,7 @@ export async function runSelectivePhaseForScope(opts) {
  * User scope: interactive TTY with user-authored content → confirm before wiping
  *   ~/.devflow/; non-interactive or no user content → artifacts-only.
  *
- * @param opts.scope            - 'user' or 'local'.
+ * @param opts.scope            - 'user' or a legacy 'local' install.
  * @param opts.claudeDir        - Target Claude Code directory for this scope.
  * @param opts.devflowDir       - Devflow data directory for this scope.
  * @param opts.devflowScriptsDir - scripts/ sub-directory removed by removeAllDevFlow.
@@ -741,7 +899,6 @@ export async function runFullPhaseForScope(opts) {
         // Non-interactive, no user content, or precondition guard failure → artifacts-only.
         const userContent = await enumerateUserDevFlowContent(devflowDir);
         const cleanupDecision = resolveDevflowDirCleanup({
-            scope: 'user',
             isTTY,
             userContent,
             devflowDir,
@@ -782,11 +939,73 @@ export async function runFullPhaseForScope(opts) {
         }
     }
 }
+/**
+ * The project-data step of the cleanup phase: list what a confirmed cleanup removes
+ * from `<gitRoot>/.devflow` and what it keeps, then remove on an explicit yes.
+ *
+ * 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
+ * directory itself is removed only when nothing tracked was in it.
+ */
+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)`);
+        return;
+    }
+    if (gates.keepDocs) {
+        p.log.info(`${shown} preserved (--keep-docs)`);
+        return;
+    }
+    if (!gates.isTTY) {
+        p.log.info(`${shown} preserved (non-interactive mode)`);
+        return;
+    }
+    for (const line of formatProjectDataPlan(plan))
+        p.log.info(line);
+    const answer = await gates.confirm({
+        message: `Remove the project data listed above from ${shown}?`,
+        initialValue: false,
+    });
+    if (!resolveProjectDataCleanup(answer)) {
+        p.log.info(p.isCancel(answer)
+            ? `${shown} preserved (prompt cancelled — continuing cleanup)`
+            : `${shown} preserved`);
+        return;
+    }
+    // Each removal is non-fatal: a failure is reported and the remaining cleanup
+    // steps (settings.json hooks above all) still run.
+    const removed = [];
+    const failed = [];
+    for (const entry of plan.remove) {
+        try {
+            await fs.rm(path.join(plan.dir, entry.name), { recursive: true, force: true });
+            removed.push(entry);
+        }
+        catch (err) {
+            failed.push(`${entryLabel(entry)} (${err.code ?? err.message})`);
+        }
+    }
+    if (plan.keep.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);
+    }
+    if (removed.length > 0)
+        p.log.success(`Removed from ${shown}: ${entryList(removed)}`);
+    if (failed.length > 0)
+        p.log.warn(`Could not remove from ${shown}: ${failed.join(', ')}`);
+    if (plan.keep.length > 0)
+        p.log.info(`Kept: ${entryList(plan.keep)}`);
+}
 /**
  * CLEANUP PHASE: post-loop extras run only on full uninstall.
  *
  * Steps (all non-fatal, every interactive path gated on opts.isTTY):
- *   1. .devflow/ project data directory
+ *   1. Project data under `<gitRoot>/.devflow`, minus DEVFLOW_TRACKED_PATHS
+ *      (resolveProjectDataPlan; skipped outside a repo, in one rooted at HOME, and
+ *      when `.devflow` is a symbolic link)
  *   2. .claudeignore
  *   3. settings.json — remove all Devflow hooks and flags
  *   4. Security deny list
@@ -798,58 +1017,39 @@ export async function runFullPhaseForScope(opts) {
  * would leave every destructive prompt gated on a global the caller cannot set,
  * which under a TTY test runner points the prompts at the developer's real files.
  *
- * @param opts.scopesToUninstall - Scopes processed by the scope loop.
- * @param opts.keepDocs          - When true, .devflow/ and security prompts are suppressed.
+ * @param opts.scopesToUninstall - Scopes processed by the scope loop. Steps 4 and 5
+ *                                 edit machine-wide files under HOME, so they run
+ *                                 only when this includes `user` — a legacy
+ *                                 local-only uninstall never touches HOME
+ *                                 (D-LEGACY-LOCAL-CLEANUP).
+ * @param opts.keepDocs          - When true, the project-data and security prompts are suppressed.
  * @param opts.verbose           - Whether to emit verbose log lines.
- * @param opts.cwd               - Working directory for project-local path resolution
- *                                 (.devflow/, git root, .claudeignore fallback).
+ * @param opts.cwd               - Working directory the git root is resolved from; it
+ *                                 locates `<gitRoot>/.devflow` and `.claudeignore`
+ *                                 (the cwd itself is the `.claudeignore` fallback).
  * @param opts.isTTY             - Whether the session is interactive. Every confirm
  *                                 prompt in this phase is gated on it.
  */
 export async function runCleanupPhase(opts) {
     const { scopesToUninstall, keepDocs, verbose, cwd, isTTY } = opts;
+    const confirm = opts.confirm ?? p.confirm;
     // Resolve the git root from the injected cwd, not process.cwd(): otherwise
     // .devflow/ resolves under `cwd` while .claudeignore resolves under the process
     // directory, and the two halves of this phase act on different repositories.
     const gitRoot = await getGitRoot(cwd);
-    // 1. .devflow/ project data directory (contains docs/, memory/, learning/, features/, etc.)
-    const devflowDataDir = path.join(cwd, '.devflow');
-    let devflowDataExists = false;
-    try {
-        await fs.access(devflowDataDir);
-        devflowDataExists = true;
-    }
-    catch { /* .devflow doesn't exist */ }
-    if (devflowDataExists) {
-        let shouldRemoveDevflow = false;
-        // Tracks whether a specific "preserved" log was already emitted (e.g. the
-        // cancel-path message below) to avoid printing the generic one twice. (F10)
-        let preservedLogged = false;
-        if (keepDocs) {
-            shouldRemoveDevflow = false;
-        }
-        else if (isTTY) {
-            const removeDevflow = await p.confirm({
-                message: '.devflow/ directory found. Remove project data (docs, memory, learning)?',
-                initialValue: false,
-            });
-            if (p.isCancel(removeDevflow)) {
-                // Treat cancel as decline: preserve .devflow/ and continue cleanup.
-                // avoids PF-014: process.exit() here would skip claudeignore, hooks,
-                // and safe-delete removal — removeAllDevFlow has already run.
-                // applies ADR-003: clean end-state on every path.
-                p.log.info('.devflow/ preserved (prompt cancelled — continuing cleanup)');
-                preservedLogged = true;
-            }
-            shouldRemoveDevflow = resolveProjectDataCleanup(removeDevflow);
-        }
-        if (shouldRemoveDevflow) {
-            await fs.rm(devflowDataDir, { recursive: true, force: true });
-            p.log.success('.devflow/ removed');
-        }
-        else if (!preservedLogged) {
-            p.log.info('.devflow/ preserved');
-        }
+    // 1. Project data under <gitRoot>/.devflow (D-UNINSTALL-CARVE-OUT)
+    const projectData = await resolveProjectDataPlan({
+        gitRoot,
+        homeDir: getHomeDirectory(),
+        machineDevflowDir: getInstallationPaths().devflowDir,
+    });
+    if (projectData.kind === 'plan') {
+        await runProjectDataStep(projectData.plan, { keepDocs, isTTY, confirm });
+    }
+    else {
+        const skipped = formatProjectDataSkip(projectData.reason, gitRoot);
+        if (skipped !== null)
+            p.log.info(skipped);
     }
     // 2. .claudeignore
     const claudeignorePath = gitRoot
@@ -863,7 +1063,7 @@ export async function runCleanupPhase(opts) {
     catch { /* doesn't exist */ }
     if (claudeignoreExists) {
         if (isTTY) {
-            const removeClaudeignore = await p.confirm({
+            const removeClaudeignore = await confirm({
                 message: '.claudeignore found. Remove it? (may contain custom rules)',
                 initialValue: false,
             });
@@ -882,11 +1082,13 @@ export async function runCleanupPhase(opts) {
     // 3. settings.json (Devflow hooks)
     for (const scope of [...scopesToUninstall]) {
         try {
-            const paths = await getInstallationPaths(scope);
+            const paths = await scopeInstallPaths(scope, gitRoot);
+            if (paths === null)
+                continue;
             const settingsPath = path.join(paths.claudeDir, 'settings.json');
             const originalContent = await fs.readFile(settingsPath, 'utf-8');
             // Remove all Devflow hooks and flags in one pass (idempotent)
-            let settingsContent = await removeAmbientHook(originalContent);
+            let settingsContent = await removeAmbientHook(originalContent, { purgeLegacyRule: scope === 'user' });
             settingsContent = removeMemoryHooks(settingsContent);
             settingsContent = removeCaptureHooks(settingsContent);
             settingsContent = removeDreamHook(settingsContent);
@@ -908,7 +1110,7 @@ export async function runCleanupPhase(opts) {
                 settingsContent = JSON.stringify(parsedSettings, null, 2) + '\n';
             }
             if (settingsContent !== originalContent) {
-                await fs.writeFile(settingsPath, settingsContent, 'utf-8');
+                await writeSettingsFileAtomic(settingsPath, settingsContent);
                 if (verbose) {
                     p.log.success(`Devflow hooks removed from settings.json (${scope})`);
                 }
@@ -923,6 +1125,10 @@ export async function runCleanupPhase(opts) {
             // settings.json doesn't exist or can't be parsed — skip
         }
     }
+    // Steps 4 and 5 edit the user's settings.json and shell profile: a legacy
+    // local-only uninstall stops here (D-LEGACY-LOCAL-CLEANUP).
+    if (!scopesToUninstall.includes('user'))
+        return;
     // 4. Security deny list
     // Detect what's installed
     let userSettingsJsonForSecurity = null;
@@ -952,7 +1158,7 @@ export async function runCleanupPhase(opts) {
         });
         let shouldRemoveSecurity = false;
         if (securityDecision === 'prompt') {
-            const removeDenyConfirm = await p.confirm({
+            const removeDenyConfirm = await confirm({
                 message: `Remove Devflow security deny list from ${locationLabel}?`,
                 initialValue: false,
             });
@@ -977,7 +1183,7 @@ export async function runCleanupPhase(opts) {
             if (detectedSecurity.user && userSettingsJsonForSecurity !== null) {
                 const { json: stripped, removed } = stripUserDenyList(userSettingsJsonForSecurity, DEVFLOW_HISTORICAL_DENY);
                 if (removed.length > 0) {
-                    await writeFileAtomicExclusive(userSettingsPathForSecurity, stripped);
+                    await writeSettingsFileAtomic(userSettingsPathForSecurity, stripped);
                     p.log.success(`Security deny list removed from user settings (${removed.length} entries)`);
                 }
             }
@@ -992,7 +1198,7 @@ export async function runCleanupPhase(opts) {
     const profilePath = getProfilePath(shell);
     if (profilePath && await isAlreadyInstalled(profilePath)) {
         if (isTTY) {
-            const removeSafeDelete = await p.confirm({
+            const removeSafeDelete = await confirm({
                 message: `Remove safe-delete function from ${profilePath}?`,
                 initialValue: false,
             });
@@ -1017,7 +1223,7 @@ export async function runCleanupPhase(opts) {
 export const uninstallCommand = new Command('uninstall')
     .description('Uninstall Devflow from Claude Code')
     .option('--keep-docs', 'Keep .devflow/ directory and project data')
-    .option('--scope <type>', 'Uninstall from specific scope only (default: auto-detect all)', /^(user|local)$/i)
+    .option('--scope <type>', 'Uninstall from one scope only: user, or local to remove a legacy project-local install (default: auto-detect both)', /^(user|local)$/i)
     .option('--plugin <names>', 'Uninstall specific plugin(s), comma-separated (e.g., implement,code-review)')
     .option('--verbose', 'Show detailed uninstall output')
     .option('--dry-run', 'Show what would be removed without actually removing anything')
@@ -1054,24 +1260,27 @@ export const uninstallCommand = new Command('uninstall')
         : [];
     // Determine which scopes to uninstall
     let scopesToUninstall = [];
+    const gitRoot = await getGitRoot();
     if (options.scope) {
         scopesToUninstall = [options.scope.toLowerCase()];
+        // A local-only uninstall with no repo-local install to act on stops here,
+        // before its cleanup phase can reach the cwd — HOME, in a repo rooted there.
+        if (scopesToUninstall[0] === 'local' && await scopeInstallPaths('local', gitRoot) === null) {
+            p.log.error('No legacy project-local install here: not in a git repository, or the repository root holds the machine-wide install');
+            process.exit(1);
+        }
     }
     else {
-        const userClaudeDir = getClaudeDirectory();
-        const gitRoot = await getGitRoot();
-        if (await isDevFlowInstalled(userClaudeDir)) {
+        if (await isDevFlowInstalled(getClaudeDirectory())) {
             scopesToUninstall.push('user');
         }
-        if (gitRoot) {
-            const localClaudeDir = path.join(gitRoot, '.claude');
-            if (await isDevFlowInstalled(localClaudeDir)) {
-                scopesToUninstall.push('local');
-            }
+        const legacyPaths = gitRoot === null ? null : await legacyLocalInstallPaths(gitRoot);
+        if (legacyPaths !== null && await isDevFlowInstalled(legacyPaths.claudeDir)) {
+            scopesToUninstall.push('local');
         }
         if (scopesToUninstall.length === 0) {
             p.log.error('No Devflow installation found');
-            p.log.info('Checked user scope (~/.claude/) and local scope (git-root/.claude/)');
+            p.log.info(`Checked user scope (${getClaudeDirectory()}/) and legacy local scope (git-root/.claude/)`);
             process.exit(1);
         }
         if (scopesToUninstall.length > 1 && !dryRun) {
@@ -1080,7 +1289,7 @@ export const uninstallCommand = new Command('uninstall')
                     message: 'Found Devflow in multiple scopes. Uninstall from:',
                     options: [
                         { value: 'both', label: 'Both', hint: 'user + local' },
-                        { value: 'user', label: 'User scope', hint: '~/.claude/' },
+                        { value: 'user', label: 'User scope', hint: `${getClaudeDirectory()}/` },
                         { value: 'local', label: 'Local scope', hint: 'git-root/.claude/' },
                     ],
                 });
@@ -1102,11 +1311,10 @@ export const uninstallCommand = new Command('uninstall')
         // One resolution, handed to the dry-run and (below) to the real removal,
         // so the preview and the outcome are computed from the same list.
         let dryRunInstalled = DEVFLOW_PLUGINS;
-        try {
-            const paths = await getInstallationPaths(scopesToUninstall[0]);
-            dryRunInstalled = await resolveInstalledPlugins(paths.devflowDir);
+        const dryRunPaths = await scopeInstallPaths(scopesToUninstall[0], gitRoot);
+        if (dryRunPaths !== null) {
+            dryRunInstalled = await resolveInstalledPlugins(dryRunPaths.devflowDir);
         }
-        catch { /* scope path resolution failed — fall back to the registry */ }
         await runDryRunPhase({
             scopesToUninstall,
             isSelectiveUninstall,
@@ -1129,7 +1337,9 @@ export const uninstallCommand = new Command('uninstall')
     if (!isSelectiveUninstall) {
         for (const scope of scopesToUninstall) {
             try {
-                const paths = await getInstallationPaths(scope);
+                const paths = await scopeInstallPaths(scope, gitRoot);
+                if (paths === null)
+                    continue;
                 if (await proxyJsonExists(paths.devflowDir)) {
                     const proxyState = await readProxyState(paths.devflowDir);
                     if (proxyState.ok)
@@ -1141,25 +1351,19 @@ export const uninstallCommand = new Command('uninstall')
     }
     // Uninstall from each scope
     for (const scope of scopesToUninstall) {
-        let claudeDir;
-        let devflowScriptsDir;
-        let devflowDir;
-        try {
-            const paths = await getInstallationPaths(scope);
-            claudeDir = paths.claudeDir;
-            devflowDir = paths.devflowDir;
-            devflowScriptsDir = path.join(paths.devflowDir, 'scripts');
-            if (scope === 'user') {
-                p.log.step('Uninstalling user scope (~/.claude/)');
-            }
-            else {
-                p.log.step('Uninstalling local scope (git-root/.claude/)');
-            }
-        }
-        catch (error) {
-            p.log.warn(`Cannot uninstall ${scope} scope: ${error instanceof Error ? error.message : error}`);
+        const paths = await scopeInstallPaths(scope, gitRoot);
+        if (paths === null) {
+            p.log.warn(`Cannot uninstall ${scope} scope: no repo-local install here`);
             continue;
         }
+        const { claudeDir, devflowDir } = paths;
+        const devflowScriptsDir = path.join(devflowDir, 'scripts');
+        if (scope === 'user') {
+            p.log.step(`Uninstalling user scope (${claudeDir})`);
+        }
+        else {
+            p.log.step('Uninstalling legacy local scope (git-root/.claude/)');
+        }
         if (isSelectiveUninstall) {
             await runSelectivePhaseForScope({
                 claudeDir,
@@ -1167,6 +1371,7 @@ export const uninstallCommand = new Command('uninstall')
                 selectedPlugins,
                 verbose,
                 installedPlugins: await resolveInstalledPlugins(devflowDir),
+                scope,
             });
         }
         else {