devflow-kit 2.4.0 → 3.0.0

package/dist/cli/commands/init.js

@@ -1,19 +1,24 @@
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import { execSync } from 'child_process';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
-import { getInstallationPaths } from '../../targets/claude-code/claude-paths.js';
+import { resolveInstallationPaths } from '../../targets/claude-code/claude-paths.js';
 import { getGitRoot } from '../../core/git.js';
+import { isSameLocation, withoutHomeRoots } from '../../core/same-location.js';
+import { pruneHookLogDirs, MAX_HOOK_LOG_DIRS } from '../../core/hook-log-dirs.js';
+import { getLedgerRoot } from '../../core/ledger-root.js';
 import { installViaFileCopy, composeScripts } from '../../targets/claude-code/installer.js';
-import { installSettings, installManagedSettings, installClaudeignore, discoverProjectGitRoots, updateGitignore, ensureDevflowGitignore, createDocsStructure, applyUserSecurityDenyList, detectDenyState, resolveSecurityAction, assertHistoricalDenySuperset, loadTemplateDenyEntries, stripUserSecurityDenyList, } from '../../targets/claude-code/post-install.js';
-import { DEVFLOW_PLUGINS, LEGACY_COMMAND_NAMES, LEGACY_RULE_NAMES, buildAssetMaps, buildFullSkillsMap, buildRulesMap, partitionSelectablePlugins, WORKFLOW_ORDER, parsePluginSelection, resolveFeatureRedirect } from '../../core/plugins.js';
+import { formatOverlaySummary, formatSkillScopeSummary, formatTrackerAssetSummary, isPluginListUnchanged } from './install-report.js';
+import { convergeTrackerArtifacts } from '../../targets/claude-code/tracker-install.js';
+import { installSettings, installManagedSettings, installClaudeignore, discoverProjectGitRoots, ensureDevflowGitignore, applyUserSecurityDenyList, detectDenyState, resolveSecurityAction, assertHistoricalDenySuperset, loadTemplateDenyEntries, stripUserSecurityDenyList, } from '../../targets/claude-code/post-install.js';
+import { DEVFLOW_PLUGINS, LEGACY_COMMAND_NAMES, LEGACY_RULE_NAMES, buildAssetMaps, buildScopedSkillsMap, buildRulesMap, partitionSelectablePlugins, WORKFLOW_ORDER, parsePluginSelection, resolveFeatureRedirect } from '../../core/plugins.js';
 import { LEGACY_SKILL_NAMES } from '../../targets/claude-code/legacy.js';
 import { detectPlatform, detectShell, getProfilePath, getSafeDeleteInfo, hasSafeDelete } from '../../core/safe-delete.js';
 import { generateSafeDeleteBlock, installToProfile, removeFromProfile, getInstalledVersion, SAFE_DELETE_BLOCK_VERSION } from '../../core/safe-delete-install.js';
-import { addAmbientHook, removeAmbientHook } from './ambient.js';
-import { addMemoryHooks, removeMemoryHooks } from './memory.js';
+import { convergeAmbientHooks } from './ambient.js';
+import { convergeMemoryHooks, drainMemoryQueue } from './memory.js';
 import { addCaptureHooks, removeCaptureHooks } from './capture.js';
 import { removeDreamHook } from './legacy-hooks.js';
 import { addProxyHooks, removeProxyHooks, applyProxyEnv, stripProxyEnv, runProxyPreflight, buildRealPreflightDeps } from './proxy.js';
@@ -26,16 +31,20 @@ import { loadConfig as loadHudConfig, saveConfig as saveHudConfig } from '../../
 import { readManifest, writeManifest, resolvePluginList, detectUpgrade } from '../../core/manifest.js';
 import { convergeFlagsIntoSettings, countActiveFlags, readViewMode } from '../../core/flags.js';
 import { addContextHook, removeContextHook, hasContextHook } from './context.js';
-import { writeConfig, readConfigIfPresent } from '../../core/feature-config.js';
-import { resolveInitSeed, applyCliToggles, resolveResetGatedInputs } from './init-seed.js';
+import { writeSettingsFileAtomic } from '../../core/fs-atomic.js';
+import { writeManagedConfig, readConfigIfPresent, DEFAULT_CONFIG } from '../../core/feature-config.js';
+import { drainLearningQueue } from '../../core/learning-queue-cleanup.js';
+import { removeManagedDenyList, describeManagedDenyRemoval } from './security.js';
+import { resolveInitSeed, applyCliToggles, resolveResetGatedInputs, resolvePluginsToInstall } from './init-seed.js';
 import { parseFrameworkList, normalizeFrameworks } from '../../core/compliance.js';
 import { formatComplianceSummary, shouldRunComplianceStep, runComplianceStep, buildClackCompliancePrompts, } from './compliance-prompts.js';
+import { applyTrackerSentinel, parseTrackerId, rearmTrackerInference, DEFAULT_TRACKER_PROVIDER, } from '../../core/tracker.js';
+import { formatTrackerSummary, shouldRunTrackerStep, runTrackerStep, buildClackTrackerPrompts, } from './tracker-prompts.js';
 import { shouldRunAttributionStep, runAttributionStep, buildClackAttributionPrompts, applyAttributionAnswer, attributionSeedFrom, } from './attribution-prompts.js';
 import { convergeFromManifest } from '../../targets/claude-code/compliance-install.js';
-import { getPendingTurnsPath, getPendingTurnsProcessingPath } from '../../core/project-paths.js';
 import * as os from 'os';
 // Re-export pure functions for tests (canonical source is post-install.ts)
-export { substituteSettingsTemplate, computeGitignoreAppend, mergeDenyList, discoverProjectGitRoots } from '../../targets/claude-code/post-install.js';
+export { substituteSettingsTemplate, mergeDenyList, discoverProjectGitRoots } from '../../targets/claude-code/post-install.js';
 export { addAmbientHook, removeAmbientHook, hasAmbientHook } from './ambient.js';
 export { addMemoryHooks, removeMemoryHooks, hasMemoryHooks } from './memory.js';
 export { addCaptureHooks, removeCaptureHooks, hasCaptureHooks } from './capture.js';
@@ -99,6 +108,31 @@ export function formatSweepSummary(report) {
     }
     return lines;
 }
+/**
+ * Log each summary line at the severity it carries — the one dispatch every
+ * `SummaryLine[]` renderer shares.
+ *
+ * Exhaustive over `SummaryLine['level']` rather than an `if/else`: a level added
+ * to the interface has to be routed here, at compile time, instead of silently
+ * degrading to `info` at every call site.
+ */
+function logSummaryLines(lines) {
+    for (const line of lines) {
+        switch (line.level) {
+            case 'info':
+                p.log.info(line.message);
+                break;
+            case 'warn':
+                p.log.warn(line.message);
+                break;
+            default: {
+                const _exhaustive = line.level;
+                void _exhaustive;
+                break;
+            }
+        }
+    }
+}
 /**
  * Classify the safe-delete installation state based on the installed version
  * in the user's shell profile.
@@ -162,9 +196,282 @@ export function resolveComplianceInitState(complianceOption, seedFrameworks) {
 // Re-export formatComplianceSummary from compliance-prompts.ts so existing test imports
 // (tests/init-logic.test.ts:1615 — imports from '../src/cli/commands/init.js') keep resolving.
 export { formatComplianceSummary } from './compliance-prompts.js';
+/**
+ * Parse the --tracker CLI option into a tracker override.
+ *
+ * Pure function — no I/O, no side effects; extracted for testability.
+ *
+ * Returns:
+ *   {ok: true, value}  — override state derived from the option
+ *   {ok: false, error} — not a registry provider ID (caller handles exit)
+ *   undefined          — option was not supplied; no override
+ *
+ * There is no `--no-tracker` (decision D-E): `--tracker github` IS the off
+ * switch, because `provider:'github'` is the off position. Parsing is strict —
+ * reject, never repair — so `--tracker jira-cloud` exits rather than silently
+ * selecting jira.
+ */
+export function resolveTrackerInitState(trackerOption) {
+    if (typeof trackerOption !== 'string')
+        return undefined;
+    const parsed = parseTrackerId(trackerOption);
+    if (!parsed.ok)
+        return { ok: false, error: parsed.error };
+    return { ok: true, value: { provider: parsed.value } };
+}
+/**
+ * The outcome line for a provider that arrived as `--tracker <id>`.
+ *
+ * D-TRACKER-CLI-SURFACE [PF-029]: the Advanced path prints no end-of-wizard
+ * summary, and `--tracker` suppresses the wizard step that would otherwise
+ * print one, so the CLI-override arm is the only place the selection can
+ * surface there. Without this line `devflow init --advanced --tracker jira`
+ * changes the machine-wide provider with nothing on screen — the same
+ * unreachable-step failure the wizard gate exists to prevent, arrived at from
+ * the flag side. Recommended already has its surface in the summary note's
+ * Tracker row; both paths or the step is invisible on one.
+ *
+ * Pure — the caller renders. The summary half is `formatTrackerSummary`, the one
+ * spelling every tracker surface shares.
+ */
+export function trackerOverrideMessage(provider) {
+    return {
+        level: provider === DEFAULT_TRACKER_PROVIDER ? 'info' : 'success',
+        text: `Tracker: ${formatTrackerSummary(provider)}`,
+    };
+}
+/** The real adapter — the ONE binding of each owner into the init lifecycle. */
+export function buildTrackerLifecycleIO() {
+    return {
+        writeManifest,
+        convergeArtifacts: (claudeDir, warn) => convergeTrackerArtifacts({ claudeDir, warn }),
+        rearmInference: rearmTrackerInference,
+        applySentinel: applyTrackerSentinel,
+    };
+}
+/**
+ * Persist the installation manifest, then converge the tracker artifacts against
+ * the provider that was actually persisted.
+ *
+ * D-TRACKER-CONVERGE: the manifest write and the tracker file-lifecycle owners
+ * are ONE unit because their relative order is the invariant, not an
+ * implementation detail (PF-015). The manifest write is explicitly failable —
+ * init must not abort on it — so converging the sentinel ahead of it leaves the
+ * two disagreeing in both directions: github→jira writes a sentinel naming a
+ * provider the manifest never records, and jira→github removes the sentinel while
+ * the manifest stays on jira. Writing first and gating the owners on
+ * `manifestWritten` makes them converge all-or-none, in the same order as the
+ * sibling `devflow tracker --set` (src/cli/commands/tracker.ts): persist → rearm →
+ * sentinel.
+ *
+ * The provider is read from `manifestData.features.tracker.provider` rather than
+ * taken as a separate argument, so there is exactly one binding and the sentinel
+ * cannot name a value other than the one on disk.
+ *
+ * Every step reports rather than aborts (PF-009's isolation posture): a
+ * feature-state change must never fail `devflow init`.
+ */
+export async function persistManifestThenConvergeTracker(opts) {
+    const { devflowDir, claudeDir, manifestData, io } = opts;
+    const provider = manifestData.features.tracker.provider;
+    const messages = [];
+    // The gate. Non-fatal for the install (which has already succeeded) but
+    // decisive for the tracker artifacts: an unpersisted selection converges none
+    // of them, so the on-disk state stays internally consistent and the next
+    // `devflow init` retries the whole transition from an unchanged starting point.
+    try {
+        await io.writeManifest(devflowDir, manifestData);
+    }
+    catch (error) {
+        messages.push({
+            level: 'warn',
+            text: `Failed to write installation manifest (install succeeded): ${error instanceof Error ? error.message : error}`,
+        });
+        messages.push({
+            level: 'warn',
+            text: `Tracker selection (${provider}) was not persisted — the sentinel and attempt counters ` +
+                `are unchanged. Re-run devflow init, or devflow tracker --set ${provider}.`,
+        });
+        return { manifestWritten: false, converged: false, agent: 'unchanged', messages };
+    }
+    // The Tracker agent file — installed on every machine (D-INSTALL-ALL-PROVIDERS),
+    // because a repository can select a provider the machine never did.
+    const agentWarnings = [];
+    const artifacts = await io.convergeArtifacts(claudeDir, (msg) => agentWarnings.push(msg));
+    for (const text of agentWarnings)
+        messages.push({ level: 'warn', text });
+    // D-TRACKER-PARALLEL: the two owners touch disjoint files — the attempt
+    // counters and the sentinel — depend on nothing the other writes, and both
+    // report through TrackerResult instead of throwing (PF-014), so they run
+    // concurrently and their warnings are pushed in a fixed order regardless of
+    // which settles first.
+    const [rearm, sentinel] = await Promise.all([
+        // [DR-22] The documented re-arm path: devflow init resets the attempt counters
+        // so a previously-capped inference gets another five tries.
+        io.rearmInference(devflowDir),
+        // [DR-10] Converge the sentinel onto the persisted machine provider: its name
+        // for jira/linear, removed for github. The SessionStart hook reads it with a
+        // builtin, which is what keeps the machine provider free of forks.
+        io.applySentinel(devflowDir, provider),
+    ]);
+    if (!rearm.ok)
+        messages.push({ level: 'warn', text: rearm.error });
+    if (!sentinel.ok)
+        messages.push({ level: 'warn', text: sentinel.error });
+    return {
+        manifestWritten: true,
+        converged: artifacts.converged && sentinel.ok,
+        agent: artifacts.agent,
+        messages,
+    };
+}
+/**
+ * Drain this repo's memory and learning queues for each feature init switched
+ * off, so stale turns are not processed on a future re-enable — the same drains
+ * `devflow memory --disable` and `devflow learning --disable` perform. Other
+ * repos' queues are inert: every gate reads the machine-wide switch, so nothing
+ * appends to or processes them while the feature is off.
+ *
+ * D-INIT-DRAIN-AFTER-SWITCH: the drain runs only AFTER the manifest holding the
+ * switch is persisted (`manifestWritten`), the order the standalone toggles use
+ * (write the switch, then drain). The capture hooks read the manifest on every
+ * turn, so draining first left a window — the whole install — in which a
+ * concurrent session, still reading the old "on", appended turns that then
+ * survived the disable. When the manifest write failed the feature is still on
+ * everywhere, so its queue is live and is left alone.
+ *
+ * D-LEDGER-MAIN-WORKTREE: each queue drains where the hooks write it — memory at
+ * this checkout's toplevel (`gitRoot`), learning at the ledger root (`ledgerRoot`,
+ * getLedgerRoot), which in a linked worktree is the main checkout.
+ */
+export async function drainDisabledFeatureQueues(opts, io = { drainMemoryQueue, drainLearningQueue }) {
+    if (!opts.manifestWritten)
+        return;
+    if (!opts.memoryEnabled && opts.gitRoot !== null)
+        await io.drainMemoryQueue(opts.gitRoot);
+    if (!opts.learningEnabled && opts.ledgerRoot !== null)
+        await io.drainLearningQueue(opts.ledgerRoot);
+}
+/**
+ * The manifest `devflow init --hud-only` writes. Pure — never mutates `existing`.
+ *
+ * D-HUD-ONLY-PRESERVE: over a prior install, --hud-only installs the HUD and
+ * nothing else, so the manifest keeps every recorded value — plugins, version,
+ * installedAt and every feature — and only `features.hud` turns on. The
+ * earlier shape rewrote the whole record as a HUD-only fresh install (ambient,
+ * memory, learning, knowledge, rules and proxy all `false`, plugins `[]`) while
+ * leaving those features' artifacts on disk: the record stopped describing the
+ * machine, the next re-init seeded every feature off (ADR-014), and with
+ * memory/learning/knowledge switched by the manifest alone
+ * (D-FEATURES-NARROW-ONLY) a HUD install would have really disabled them
+ * everywhere. `version` is kept too: --hud-only reinstalls no plugin, and a
+ * bumped version would make the next init skip the upgrade it still owes.
+ *
+ * With no prior manifest the result is the fresh HUD-only record: every other
+ * feature off, which is what is installed.
+ */
+export function buildHudOnlyManifest(existing, version, now) {
+    if (existing !== null) {
+        return {
+            ...existing,
+            features: { ...existing.features, hud: true },
+            updatedAt: now,
+        };
+    }
+    return {
+        version,
+        plugins: [],
+        scope: 'user',
+        features: {
+            ambient: false, memory: false, hud: true, knowledge: false,
+            learning: false, rules: false, flags: {}, proxy: false,
+            compliance: { enabled: false, frameworks: [] },
+            // The exported default, not a literal — the one constant every other
+            // module reads, so a moved default moves here too.
+            tracker: { provider: DEFAULT_TRACKER_PROVIDER },
+        },
+        installedAt: now,
+        updatedAt: now,
+    };
+}
+/**
+ * Decide what `init --scope <value>` does now that there is one install scope.
+ * Pure — the action performs the exit.
+ *
+ * D-SCOPE-RETIRED: `--scope` is kept as a hidden option so existing scripts keep
+ * parsing. `user` (any case) is exactly the no-flag install. `local` is refused
+ * before anything is written: the repo-local install wrote `<repo>/.claude` and
+ * `<repo>/.devflow` while every hook and prompt read `~/.devflow`, so it never
+ * worked, and the only thing left to do with one is remove it. Any other value
+ * is refused the same way rather than silently treated as `user`.
+ */
+export function resolveRetiredScopeOption(scope) {
+    if (scope === undefined || scope.toLowerCase() === 'user')
+        return { kind: 'proceed' };
+    if (scope.toLowerCase() === 'local') {
+        return {
+            kind: 'refuse',
+            message: 'Project-local installs are no longer supported: Devflow installs machine-wide only. ' +
+                'To remove an old project-local install, run `devflow uninstall --scope local` to clean up.',
+        };
+    }
+    return {
+        kind: 'refuse',
+        message: `Unknown --scope value "${scope}": Devflow installs machine-wide only (omit --scope).`,
+    };
+}
+/** The line init prints after removing old hook log folders (D-LOG-DIR-CAP). Pure. */
+export function formatLogPruneLine(report) {
+    const base = `Removed ${report.removed} old hook log folder${report.removed === 1 ? '' : 's'} ` +
+        `(keeping the ${MAX_HOOK_LOG_DIRS} most recent)`;
+    return report.overCap > 0 ? `${base}; ${report.overCap} more go on the next init` : base;
+}
+/**
+ * The warning init prints when the running CLI is older than the one that last
+ * installed this machine, or null. Pure.
+ *
+ * D-INIT-DOWNGRADE-WARN: a downgrade is allowed — an older CLI installs a
+ * consistent older devflow — but never silent: its install sweeps every skill,
+ * agent and command the newer version added as an orphan, and settings the newer
+ * version wrote may mean nothing to it. The warning names both versions and how
+ * to get back; nothing blocks.
+ */
+export function formatDowngradeWarning(upgrade, version) {
+    if (!upgrade.isDowngrade || upgrade.previousVersion === null)
+        return null;
+    return `Downgrading: this machine was installed by devflow v${upgrade.previousVersion}, newer than this CLI (v${version}). ` +
+        'Assets only the newer version ships will be removed. To keep them, run the newer CLI instead ' +
+        '(npx devflow-kit@latest init).';
+}
+/**
+ * The warning init prints when it leaves a repository's `.devflow/config.json`
+ * alone (D-CONFIG-NO-REPAIR). Pure.
+ */
+export function formatManagedConfigWriteError(error) {
+    switch (error.kind) {
+        case 'malformed':
+            return `${error.path} is not a valid config (not a JSON object, or a key appears twice) — left unchanged. ` +
+                'Fix it by hand; until then devflow treats it as unreadable.';
+        case 'unreadable':
+            return `${error.path} could not be read (${error.detail}) — left unchanged.`;
+        case 'write-failed':
+            return `Could not write ${error.path}: ${error.detail}`;
+        default: {
+            const exhaustive = error;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * The git repositories Claude has worked in, as project roots: every
+ * history.jsonl project with a `.git`, less any rooted at HOME (D-INIT-NOT-HOME).
+ */
+async function discoverRepoRoots(claudeDir, homeDir) {
+    return withoutHomeRoots(await discoverProjectGitRoots(claudeDir), homeDir);
+}
 export const initCommand = new Command('init')
     .description('Initialize Devflow for Claude Code')
-    .option('--scope <type>', 'Installation scope: user or local (project-only)', /^(user|local)$/i)
+    .addOption(new Option('--scope <type>', 'Retired: Devflow installs machine-wide only').hideHelp())
     .option('--verbose', 'Show detailed installation output')
     .option('--plugin <names>', 'Install specific plugin(s), comma-separated (e.g., implement,code-review)')
     .option('--ambient', 'Enable ambient mode (orchestrator charter + plan handoff)')
@@ -182,7 +489,8 @@ export const initCommand = new Command('init')
     .option('--proxy', 'Enable external model routing (GPT models via your OpenAI/Codex subscription)')
     .option('--no-proxy', 'Disable external model routing')
     .option('--compliance <list>', 'Enable compliance with comma-separated framework IDs (e.g., gdpr,hipaa)')
-    .option('--no-compliance', 'Disable compliance (artifacts removed; frameworks remembered for re-enable)')
+    .option('--no-compliance', 'Disable compliance (removes the rule; the skill and framework references stay installed; frameworks remembered for re-enable)')
+    .option('--tracker <id>', 'The machine\'s default issue tracker provider: github, jira, or linear')
     .option('--security <mode>', 'Security deny list location: user, managed, or none', /^(user|managed|none)$/i)
     .option('--hud-only', 'Install only the HUD (no plugins, hooks, or extras)')
     .option('--recommended', 'Apply recommended defaults after plugin selection (skip advanced prompts)')
@@ -208,30 +516,21 @@ export const initCommand = new Command('init')
         p.log.error('--reset and --plugin are mutually exclusive. Use --reset alone to restore defaults, or --plugin to update a specific plugin.');
         process.exit(1);
     }
-    // Determine installation scope
-    let scope = 'user';
-    if (options.hudOnly) {
-        // --hud-only: skip scope prompt, always user scope
-        scope = 'user';
-    }
-    else if (options.scope) {
-        const normalizedScope = options.scope.toLowerCase();
-        if (normalizedScope !== 'user' && normalizedScope !== 'local') {
-            p.log.error('Invalid scope. Use "user" or "local"');
-            process.exit(1);
-        }
-        scope = normalizedScope;
+    // D-SCOPE-RETIRED: refuse a retired --scope value before anything is written.
+    const scopeDecision = resolveRetiredScopeOption(options.scope);
+    if (scopeDecision.kind === 'refuse') {
+        p.log.error(scopeDecision.message);
+        process.exit(1);
     }
-    else if (!process.stdin.isTTY) {
-        p.log.info('Non-interactive mode detected, using scope: user');
-        scope = 'user';
+    // The install locations, resolved once. They fail only with no home directory.
+    const resolvedPaths = resolveInstallationPaths();
+    if (!resolvedPaths.ok) {
+        p.log.error(resolvedPaths.error);
+        process.exit(1);
     }
+    const { homeDir, claudeDir, devflowDir } = resolvedPaths.value;
     // --hud-only: install only HUD (skip plugins, hooks, extras)
     if (options.hudOnly) {
-        // Resolve paths
-        const paths = await getInstallationPaths(scope);
-        const claudeDir = paths.claudeDir;
-        const devflowDir = paths.devflowDir;
         // Save HUD config
         const existingHud = loadHudConfig();
         saveHudConfig({ enabled: true, detail: existingHud.detail });
@@ -246,7 +545,7 @@ export const initCommand = new Command('init')
                 content = '{}';
             }
             const updated = addHudStatusLine(content, devflowDir);
-            await fs.writeFile(settingsPath, updated, 'utf-8');
+            await writeSettingsFileAtomic(settingsPath, updated);
         }
         catch (error) {
             p.log.error(`Failed to update settings: ${error instanceof Error ? error.message : error}`);
@@ -261,28 +560,15 @@ export const initCommand = new Command('init')
             p.log.error(`Failed to install HUD scripts: ${error instanceof Error ? error.message : error}`);
             process.exit(1);
         }
-        // Read existing manifest to preserve user-set compliance state (disable-keeps-frameworks
-        // contract: the hud-only path must not erase frameworks the user previously selected).
+        // Read the existing manifest: over a prior install, --hud-only touches only
+        // the HUD (D-HUD-ONLY-PRESERVE in buildHudOnlyManifest).
         let existingHudManifest = null;
         try {
             existingHudManifest = await readManifest(devflowDir);
         }
         catch { /* absent on fresh install — existingHudManifest stays null */ }
-        // Write minimal manifest
-        const now = new Date().toISOString();
         try {
-            await writeManifest(devflowDir, {
-                version,
-                plugins: [],
-                scope,
-                features: {
-                    ambient: false, memory: false, hud: true, knowledge: false,
-                    learning: false, rules: false, flags: {}, proxy: false,
-                    compliance: existingHudManifest?.features.compliance ?? { enabled: false, frameworks: [] },
-                },
-                installedAt: now,
-                updatedAt: now,
-            });
+            await writeManifest(devflowDir, buildHudOnlyManifest(existingHudManifest, version, new Date().toISOString()));
         }
         catch { /* non-fatal */ }
         p.log.success('HUD installed');
@@ -290,28 +576,30 @@ export const initCommand = new Command('init')
         p.outro(color.green('HUD-only install complete.'));
         return;
     }
-    // ── Hoist reads: resolve paths early to compute InitSeed for pre-seeded prompts (Phase 4) ──
-    // Best-effort: if path resolution fails here, seed falls back to fresh-install defaults.
-    // The authoritative error gate for failed path resolution remains at the install-begins
-    // spinner (see "Resolving paths" below). Hoisted above multiselect so Phase 4 can
-    // pre-seed plugin/flag/feature prompts.
+    // ── Hoisted reads: the prior state that seeds the prompts (InitSeed, Phase 4) ──
     let existingManifest = null;
-    let earlyProjectConfig = null;
+    try {
+        existingManifest = await readManifest(devflowDir);
+    }
+    catch { /* unreadable manifest — seeded as a fresh install */ }
+    // D-INIT-NOT-HOME (same-location.ts): a repository rooted at HOME is no
+    // project, so init treats it as no repository — no .devflow/config.json (that
+    // would be the machine root's), no .claudeignore, no .gitignore block, no
+    // per-project migration or queue drain.
+    const cwdGitRoot = await getGitRoot();
+    const homeRootedRepo = cwdGitRoot !== null && await isSameLocation(cwdGitRoot, homeDir);
+    const gitRoot = homeRootedRepo ? null : cwdGitRoot;
+    if (homeRootedRepo) {
+        p.log.info('This git repository is rooted at your home directory, so init writes no per-repository files here.');
+    }
+    const earlyProjectConfig = gitRoot
+        ? await readConfigIfPresent(gitRoot)
+        : null;
     let earlySettingsJson = null;
-    let earlyGitRoot = null;
     try {
-        const earlyPaths = await getInstallationPaths(scope);
-        existingManifest = await readManifest(earlyPaths.devflowDir);
-        earlyGitRoot = earlyPaths.gitRoot ?? await getGitRoot();
-        if (earlyGitRoot) {
-            earlyProjectConfig = await readConfigIfPresent(earlyGitRoot);
-        }
-        try {
-            earlySettingsJson = await fs.readFile(path.join(earlyPaths.claudeDir, 'settings.json'), 'utf-8');
-        }
-        catch { /* settings.json absent — treated as empty */ }
+        earlySettingsJson = await fs.readFile(path.join(claudeDir, 'settings.json'), 'utf-8');
     }
-    catch { /* path resolution deferred to install-begins gate */ }
+    catch { /* settings.json absent — treated as empty */ }
     // --reset: factory reset — treat as a fresh install for all seeding and routing decisions.
     // The REAL existingManifest / earlySettingsJson are still used below for installedAt
     // preservation, upgrade messaging, and security deny-state detection. resolveResetGatedInputs
@@ -319,7 +607,7 @@ export const initCommand = new Command('init')
     // registry defaults — including viewMode 'default' (an externally-set /focus in settings.json
     // must not survive a factory reset).
     const { seedManifest, seedConfig, seedSettings } = resolveResetGatedInputs(!!options.reset, existingManifest, earlyProjectConfig, earlySettingsJson ?? '');
-    const seed = resolveInitSeed(seedManifest, seedConfig, seedSettings, DEVFLOW_PLUGINS);
+    const seed = resolveInitSeed(seedManifest, seedSettings, DEVFLOW_PLUGINS);
     // Early validation: parse --compliance <list> at the boundary before any prompts (PF-parse-at-boundary).
     // options.compliance: string → --compliance <list>; false → --no-compliance; undefined → not passed
     let cliComplianceOverride;
@@ -333,6 +621,20 @@ export const initCommand = new Command('init')
             cliComplianceOverride = complianceStateResult.value;
         }
     }
+    // Early validation: parse --tracker <id> at the boundary before any prompts.
+    // Strict — reject, never repair — so a typo'd provider exits here rather than
+    // installing mechanics for a tracker the user did not name.
+    let cliTrackerOverride;
+    {
+        const trackerStateResult = resolveTrackerInitState(options.tracker);
+        if (trackerStateResult !== undefined) {
+            if (!trackerStateResult.ok) {
+                p.log.error(trackerStateResult.error);
+                process.exit(1);
+            }
+            cliTrackerOverride = trackerStateResult.value;
+        }
+    }
     // Select plugins to install
     let selectedPlugins = [];
     if (options.plugin) {
@@ -441,7 +743,8 @@ export const initCommand = new Command('init')
     // When no --plugin flag is given and a manifest exists, the seed carries the prior
     // selection (existing plugins ∪ new non-optional plugins not yet in knownPlugins).
     // Fresh non-interactive installs (no manifest) fall through to the default path
-    // in pluginsToInstall which installs all non-optional plugins.
+    // in resolvePluginsToInstall: every non-optional plugin, with devflow-ambient
+    // following the ambient switch (D-AMBIENT-FOLLOWS-SWITCH).
     if (!options.plugin && !process.stdin.isTTY && seedManifest !== null) {
         selectedPlugins = [...seed.workflowPlugins, ...seed.languagePlugins];
     }
@@ -506,13 +809,16 @@ export const initCommand = new Command('init')
     // CLI override applied below in both Recommended and Advanced paths.
     let complianceEnabled = seed.features.compliance.enabled;
     let complianceFrameworks = seed.features.compliance.frameworks;
+    // tracker: manifest-group (like proxy and compliance); seed from prior manifest.
+    // CLI override applied below in both Recommended and Advanced paths.
+    let trackerProvider = seed.features.tracker.provider;
     let enabledFlags = { ...seed.flags };
     // viewModeExplicit: true when --reset is passed; signals resolveFinalViewMode to let the
     // seed-time view-mode win over an externally-set value in settings.json.
     // --reset empties the settings snapshot via resolveResetGatedInputs so seed.flags['view-mode']
     // collapses to 'default', and explicit=true makes it take effect at settings write time.
     let viewModeExplicit = !!options.reset;
-    let claudeignoreEnabled = !!earlyGitRoot;
+    let claudeignoreEnabled = !!gitRoot;
     let discoveredProjects = [];
     let safeDeleteAction = 'skip';
     let safeDeleteBlock = null;
@@ -520,6 +826,47 @@ export const initCommand = new Command('init')
     // The final value is written to the manifest and consumed by the dedicated security step.
     let securityMode = 'user'; // placeholder; overwritten below by resolve
     let managedSettingsConfirmed = false;
+    /**
+     * Run the tracker wizard step for one wizard path.
+     *
+     * D-TRACKER-CALLSHAPE: both paths share one gate (shouldRunTrackerStep), one
+     * cancel idiom and one prompt adapter; they differ only in the mode they
+     * declare, the provider they seed from, and whether the step's own outcome
+     * line is emitted. Holding all three differences as parameters keeps the
+     * shared half single-sourced, so the paths cannot drift the way two
+     * hand-copied call sites do.
+     *
+     * Returns the chosen state, or undefined when the gate declined to run — the
+     * caller then owns the CLI-override fallback, which is the only other way the
+     * provider can change on that path.
+     */
+    const runTrackerStepAt = async (mode, seedProvider, emitMessages) => {
+        if (!shouldRunTrackerStep({
+            mode,
+            modePromptShown,
+            isTTY: process.stdin.isTTY,
+            hasCliOverride: cliTrackerOverride !== undefined,
+        })) {
+            return undefined;
+        }
+        const trackerStep = await runTrackerStep({
+            seed: { provider: seedProvider },
+            prompts: buildClackTrackerPrompts(),
+        });
+        if (trackerStep.kind === 'cancelled') {
+            p.cancel('Installation cancelled.');
+            process.exit(0);
+        }
+        if (emitMessages) {
+            for (const msg of trackerStep.messages) {
+                if (msg.level === 'success')
+                    p.log.success(msg.text);
+                else
+                    p.log.info(msg.text);
+            }
+        }
+        return trackerStep.state;
+    };
     // Safe-delete detection (both paths need this)
     const platform = detectPlatform();
     const shell = detectShell();
@@ -552,6 +899,13 @@ export const initCommand = new Command('init')
             // Step messages not emitted here — the Recommended summary note (below) already
             // prints the Compliance line from complianceSummary via formatComplianceSummary.
         }
+        // Tracker wizard step — same gate as compliance, so both wizard paths are
+        // governed by the one documented gate table (AC-3.6). Runs only when the
+        // Setup-mode prompt actually ran, so --recommended and !isTTY stay promptless.
+        // emitMessages=false: the Recommended summary note (below) prints the
+        // Tracker line via formatTrackerSummary, so the step's own outcome line
+        // would be a duplicate.
+        const wizardTracker = await runTrackerStepAt('recommended', seed.features.tracker.provider, false);
         // No attribution step here: the suppress-attribution question is Advanced-only (D27).
         // Recommended silently carries the seeded value in enabledFlags — fresh installs get
         // the registry default (off), re-inits get prior state. See shouldRunAttributionStep.
@@ -567,6 +921,8 @@ export const initCommand = new Command('init')
             rules: options.rules,
             proxy: options.proxy,
             compliance: cliComplianceOverride ?? wizardCompliance,
+            // Precedence: cliOverride ?? wizardResult ?? seed (applyCliToggles supplies the seed arm).
+            tracker: cliTrackerOverride ?? wizardTracker,
         });
         ambientEnabled = effectiveFeatures.ambient;
         memoryEnabled = effectiveFeatures.memory;
@@ -577,6 +933,7 @@ export const initCommand = new Command('init')
         proxyEnabled = effectiveFeatures.proxy;
         complianceEnabled = effectiveFeatures.compliance.enabled;
         complianceFrameworks = effectiveFeatures.compliance.frameworks;
+        trackerProvider = effectiveFeatures.tracker.provider;
         // enabledFlags is already initialised to seed.flags above.
         // Compute safe-delete block synchronously so we know whether to fetch installed version
         if (profilePath && safeDeleteAvailable) {
@@ -584,10 +941,10 @@ export const initCommand = new Command('init')
             safeDeleteBlock = generateSafeDeleteBlock(shell, process.platform, trashCmd);
         }
         // Run independent I/O in parallel: project discovery + safe-delete version check
-        const needsDiscovery = earlyGitRoot && scope === 'user';
+        const needsDiscovery = gitRoot !== null;
         const needsVersionCheck = safeDeleteBlock && profilePath;
         const [discoveredResult, installedVersionResult] = await Promise.all([
-            needsDiscovery ? discoverProjectGitRoots() : Promise.resolve([]),
+            needsDiscovery ? discoverRepoRoots(claudeDir, homeDir) : Promise.resolve([]),
             needsVersionCheck ? getInstalledVersion(profilePath) : Promise.resolve(0),
         ]);
         discoveredProjects = discoveredResult;
@@ -612,6 +969,10 @@ export const initCommand = new Command('init')
             `Knowledge bases: ${knowledgeEnabled ? 'enabled' : 'disabled'}`,
             `Ext model routing: ${proxyEnabled ? 'enabled' : 'disabled'}`,
             `Compliance:      ${complianceSummary}`,
+            // Recommended emits no per-step outcome lines, so this summary row is the
+            // tracker step's ONLY surface on this path — both surfaces or it is
+            // invisible on one path.
+            `Tracker:         ${formatTrackerSummary(trackerProvider)}`,
             `View mode:       ${readViewMode(enabledFlags)}`,
             `Claude Code flags: ${defaultFlagCount} configured`,
             `${claudeignoreEnabled ? '.claudeignore:   created' : ''}`,
@@ -657,7 +1018,8 @@ export const initCommand = new Command('init')
                 'compaction. Clear your session at any point and resume right\n' +
                 'where you left off.\n\n' +
                 'Runs a background agent on session stop that consumes additional\n' +
-                'tokens. Consider skipping if token usage is a concern.', 'Working Memory');
+                'tokens. Consider skipping if token usage is a concern.\n' +
+                'Applies to every project.', 'Working Memory');
             const memoryChoice = await p.confirm({
                 message: 'Enable working memory? (Recommended)',
                 initialValue: seed.features.memory,
@@ -690,7 +1052,8 @@ export const initCommand = new Command('init')
         else {
             p.note('Per-feature knowledge bases capture cross-cutting patterns,\n' +
                 'conventions, and gotchas. Created and updated automatically\n' +
-                'when workflows touch a documented area (write-through model).', 'Feature Knowledge Bases');
+                'when workflows touch a documented area (write-through model).\n' +
+                'Applies to every project.', 'Feature Knowledge Bases');
             const knowledgeChoice = await p.confirm({
                 message: 'Enable feature knowledge bases? (Recommended)',
                 initialValue: seed.features.knowledge,
@@ -707,7 +1070,7 @@ export const initCommand = new Command('init')
         else {
             p.note('Detects architectural decisions and pitfalls from your session\n' +
                 'dialogs. Runs a background agent on session stop that consumes\n' +
-                'additional tokens.', 'Learning (Decision/Pitfall Tracking)');
+                'additional tokens. Applies to every project.', 'Learning (Decision/Pitfall Tracking)');
             const learningChoice = await p.confirm({
                 message: 'Enable learning? (Recommended)',
                 initialValue: seed.features.learning,
@@ -797,6 +1160,28 @@ export const initCommand = new Command('init')
         // No third case in practice: on this path the predicate only returns false for a
         // CLI override (isTTY is guaranteed true by the non-TTY guard above). If it ever
         // did, the seed values assigned at declaration stand — which is the right default.
+        // Tracker feature (after compliance, before attribution). Gated by the same
+        // shouldRunTrackerStep predicate as the Recommended path, so the documented
+        // gate table is the single authority for both and they cannot drift.
+        // This call site is the one that matters on RE-INIT: re-init is Advanced-only
+        // by construction, so a Recommended-only wiring would be dead there.
+        // emitMessages=true: Advanced has no end-of-wizard summary recap, so the
+        // step's outcome line is this path's ONLY surface — mandatory, not decorative.
+        const advancedTracker = await runTrackerStepAt('advanced', trackerProvider, true);
+        if (advancedTracker !== undefined) {
+            trackerProvider = advancedTracker.provider;
+        }
+        else if (cliTrackerOverride !== undefined) {
+            // --tracker passed explicitly — honour without prompting, and say so.
+            // The gate declined the step, and this path has no summary recap, so
+            // this line is the selection's ONLY surface (D-TRACKER-CLI-SURFACE).
+            trackerProvider = cliTrackerOverride.provider;
+            const overrideLine = trackerOverrideMessage(trackerProvider);
+            if (overrideLine.level === 'success')
+                p.log.success(overrideLine.text);
+            else
+                p.log.info(overrideLine.text);
+        }
         // Attribution feature (after compliance, before flags). This is the ONLY call site —
         // the attribution question is Advanced-only (D27); the Recommended path never asks and
         // silently carries the seeded value. The gate stays an explicit predicate call so the
@@ -842,45 +1227,29 @@ export const initCommand = new Command('init')
             p.log.info(`Flags: ${activeCount} active — customize any time with 'devflow flags'`);
         }
         // .claudeignore prompt
-        if (earlyGitRoot) {
-            if (scope === 'user') {
-                discoveredProjects = await discoverProjectGitRoots();
-                p.note('Scans all projects Claude has worked on and creates a\n' +
-                    '.claudeignore in each git repository. Excludes secrets,\n' +
-                    'API keys, dependencies, and build artifacts from context.', '.claudeignore');
-                if (discoveredProjects.length > 0) {
-                    const maxShow = 5;
-                    const projectLines = discoveredProjects.slice(0, maxShow).join('\n');
-                    const overflow = discoveredProjects.length > maxShow
-                        ? `\n... (${discoveredProjects.length - maxShow} more)`
-                        : '';
-                    p.note(projectLines + overflow, `Discovered ${discoveredProjects.length} projects`);
-                    const claudeignoreChoice = await p.confirm({
-                        message: `Install .claudeignore to ${discoveredProjects.length} projects? (Recommended)`,
-                        initialValue: true,
-                    });
-                    if (p.isCancel(claudeignoreChoice)) {
-                        p.cancel('Installation cancelled.');
-                        process.exit(0);
-                    }
-                    claudeignoreEnabled = claudeignoreChoice;
-                }
-                else {
-                    const claudeignoreChoice = await p.confirm({
-                        message: 'Create .claudeignore? (Recommended)',
-                        initialValue: true,
-                    });
-                    if (p.isCancel(claudeignoreChoice)) {
-                        p.cancel('Installation cancelled.');
-                        process.exit(0);
-                    }
-                    claudeignoreEnabled = claudeignoreChoice;
+        if (gitRoot) {
+            discoveredProjects = await discoverRepoRoots(claudeDir, homeDir);
+            p.note('Scans all projects Claude has worked on and creates a\n' +
+                '.claudeignore in each git repository. Excludes secrets,\n' +
+                'API keys, dependencies, and build artifacts from context.', '.claudeignore');
+            if (discoveredProjects.length > 0) {
+                const maxShow = 5;
+                const projectLines = discoveredProjects.slice(0, maxShow).join('\n');
+                const overflow = discoveredProjects.length > maxShow
+                    ? `\n... (${discoveredProjects.length - maxShow} more)`
+                    : '';
+                p.note(projectLines + overflow, `Discovered ${discoveredProjects.length} projects`);
+                const claudeignoreChoice = await p.confirm({
+                    message: `Install .claudeignore to ${discoveredProjects.length} projects? (Recommended)`,
+                    initialValue: true,
+                });
+                if (p.isCancel(claudeignoreChoice)) {
+                    p.cancel('Installation cancelled.');
+                    process.exit(0);
                 }
+                claudeignoreEnabled = claudeignoreChoice;
             }
             else {
-                p.note('Creates a .claudeignore in this project that excludes\n' +
-                    'secrets, API keys, dependencies, and build artifacts from\n' +
-                    'Claude\'s context window.', '.claudeignore');
                 const claudeignoreChoice = await p.confirm({
                     message: 'Create .claudeignore? (Recommended)',
                     initialValue: true,
@@ -921,8 +1290,8 @@ export const initCommand = new Command('init')
                 }
             }
         }
-        // Security deny list placement (user scope + TTY only)
-        if (scope === 'user' && process.stdin.isTTY) {
+        // Security deny list placement (TTY only)
+        if (process.stdin.isTTY) {
             p.note('Devflow includes a security deny list that blocks dangerous\n' +
                 'commands (rm -rf, sudo, eval, etc). It can be installed as a\n' +
                 'read-only system file or in your editable settings.json.', 'Security Deny List');
@@ -965,34 +1334,23 @@ export const initCommand = new Command('init')
     // ╭──────────────────────────────────────────────────────────╮
     // │  All prompts collected — installation begins             │
     // ╰──────────────────────────────────────────────────────────╯
+    const upgrade = existingManifest ? detectUpgrade(version, existingManifest.version) : null;
+    const downgradeWarning = upgrade === null ? null : formatDowngradeWarning(upgrade, version);
+    if (downgradeWarning !== null)
+        p.log.warn(downgradeWarning);
     const s = p.spinner();
-    s.start('Resolving paths');
-    // Get installation paths
-    let claudeDir;
-    let devflowDir;
-    let gitRoot = null;
-    try {
-        const paths = await getInstallationPaths(scope);
-        claudeDir = paths.claudeDir;
-        devflowDir = paths.devflowDir;
-        gitRoot = paths.gitRoot ?? earlyGitRoot;
+    s.start('Installing');
+    if (upgrade?.isUpgrade) {
+        s.message(`Upgrading from v${upgrade.previousVersion} to v${version}`);
     }
-    catch (error) {
-        s.stop('Path resolution failed');
-        p.log.error(`Path configuration error: ${error instanceof Error ? error.message : error}`);
-        process.exit(1);
-    }
-    // existingManifest was read early above (hoisted for seed computation); use it here for upgrade detection
-    if (existingManifest) {
-        const upgrade = detectUpgrade(version, existingManifest.version);
-        if (upgrade.isUpgrade) {
-            s.message(`Upgrading from v${upgrade.previousVersion} to v${version}`);
-        }
-        else if (upgrade.isSameVersion) {
-            s.message('Reinstalling same version');
-        }
+    else if (upgrade?.isSameVersion) {
+        s.message('Reinstalling same version');
     }
     // Detect current deny list state in user settings (read-only; write happens in security step)
+    // Whether the managed settings file holds a Devflow deny entry — the security
+    // step's `none` branch removes it only then (and only then stops the spinner
+    // for a possible sudo prompt).
+    let managedDenyDetected = false;
     {
         const userSettingsJson = earlySettingsJson;
         let managedExists = false;
@@ -1005,6 +1363,7 @@ export const initCommand = new Command('init')
         }
         catch { /* absent or unsupported platform */ }
         const detected = detectDenyState(userSettingsJson, managedExists, managedContentJson);
+        managedDenyDetected = detected.managed;
         const flagValue = options.security;
         const manifestMode = existingManifest?.features.security;
         const resolution = resolveSecurityAction(flagValue, manifestMode, detected, process.stdin.isTTY);
@@ -1033,44 +1392,30 @@ export const initCommand = new Command('init')
     }
     // Validate target directory
     s.message('Validating target directory');
-    if (scope === 'local') {
-        try {
-            await fs.mkdir(claudeDir, { recursive: true });
-        }
-        catch (error) {
-            s.stop('Installation failed');
-            p.log.error(`Failed to create ${claudeDir}: ${error}`);
-            process.exit(1);
-        }
+    try {
+        await fs.access(claudeDir);
     }
-    else {
-        try {
-            await fs.access(claudeDir);
-        }
-        catch {
-            s.stop('Installation failed');
-            p.log.error(`Claude Code not detected at ${claudeDir}`);
-            p.log.info('Install from: https://claude.ai/download');
-            process.exit(1);
-        }
+    catch {
+        s.stop('Installation failed');
+        p.log.error(`Claude Code not detected at ${claudeDir}`);
+        p.log.info('Install from: https://claude.ai/download');
+        process.exit(1);
     }
     // Resolve plugins and deduplication maps
     s.message('Installing components');
     const rootDir = getPackageRoot();
-    let pluginsToInstall = selectedPlugins.length > 0
-        ? DEVFLOW_PLUGINS.filter(p => selectedPlugins.includes(p.name))
-        : DEVFLOW_PLUGINS.filter(p => !p.optional);
-    const coreSkillsPlugin = DEVFLOW_PLUGINS.find(p => p.name === 'devflow-core-skills');
-    if (pluginsToInstall.length > 0 && coreSkillsPlugin && !pluginsToInstall.includes(coreSkillsPlugin)) {
-        pluginsToInstall = [coreSkillsPlugin, ...pluginsToInstall];
-    }
-    const ambientPlugin = DEVFLOW_PLUGINS.find(p => p.name === 'devflow-ambient');
-    if (ambientEnabled && ambientPlugin && !pluginsToInstall.includes(ambientPlugin)) {
-        pluginsToInstall.push(ambientPlugin);
-    }
-    // Skills: install ALL from ALL plugins (skills are tiny markdown files;
-    // commands need skills from other plugins to function)
-    const skillsMap = buildFullSkillsMap();
+    const pluginsToInstall = resolvePluginsToInstall(selectedPlugins, ambientEnabled, DEVFLOW_PLUGINS);
+    // The EFFECTIVE selection — what the manifest will record, resolved here
+    // rather than at manifest-write time because the skills install set is
+    // derived from it. On a full install it is `pluginsToInstall`; on a partial
+    // install (`--plugin=X`) it merges the prior manifest's plugins with X, so a
+    // previously-installed plugin's skills survive an add-one run (AC-22).
+    const installedPluginNames = pluginsToInstall.map(pl => pl.name);
+    const effectivePluginNames = resolvePluginList(installedPluginNames, existingManifest, !!options.plugin);
+    const effectivePlugins = DEVFLOW_PLUGINS.filter(pl => effectivePluginNames.includes(pl.name));
+    // Skills: the effective selection's closure — every plugin's own skills plus
+    // the ones it requires. Scoped like rules, agents and commands already are.
+    const skillsMap = buildScopedSkillsMap(effectivePlugins);
     // Agents: install only from selected plugins
     const { agentsMap } = buildAssetMaps(pluginsToInstall);
     // Rules: install only from selected plugins (plugin-scoped, not universal)
@@ -1079,12 +1424,11 @@ export const initCommand = new Command('init')
     // Migrations clean up ~/.devflow runtime data and never touch the installer's copy
     // targets, so their position relative to installViaFileCopy carries no dependency.
     // Migrations are always-run-unapplied: helpers short-circuit when the target data is
-    // absent, so fresh installs are safe no-ops. State lives at the home-dir ~/.devflow
-    // location regardless of install scope (D30).
+    // absent, so fresh installs are safe no-ops. State lives at the machine root
+    // ~/.devflow (D30).
     {
         const { runMigrations } = await import('../../core/migrations.js');
-        const userDevflowDir = path.join(os.homedir(), '.devflow');
-        await runMigrationsWithFallback(discoveredProjects, gitRoot, userDevflowDir, { warn: p.log.warn, info: p.log.info, success: p.log.success }, verbose, runMigrations);
+        await runMigrationsWithFallback(discoveredProjects, gitRoot, devflowDir, { warn: p.log.warn, info: p.log.info, success: p.log.success }, verbose, runMigrations);
     }
     // devflow-compliance was a selectable plugin in earlier releases; it is now a built-in
     // feature (devflow compliance --enable/--disable). If the prior manifest still lists it
@@ -1107,9 +1451,11 @@ export const initCommand = new Command('init')
     catch { /* absent — no legacy artifact */ }
     // Install via file copy
     let installReport;
+    const installWarnings = [];
     try {
         installReport = await installViaFileCopy({
             plugins: pluginsToInstall,
+            effectivePlugins,
             claudeDir,
             devflowDir,
             skillsMap,
@@ -1117,6 +1463,10 @@ export const initCommand = new Command('init')
             rulesMap,
             isPartialInstall: !!options.plugin,
             spinner: s,
+            // Non-fatal install notices with no other channel (skipped symlinks in the
+            // generated reference tree, mode-normalisation failures) reach the user rather
+            // than the void. Collected now, emitted after the spinner stops.
+            warn: (msg) => { installWarnings.push(msg); },
         });
     }
     catch (error) {
@@ -1136,13 +1486,13 @@ export const initCommand = new Command('init')
             manifest: { features: { compliance: { enabled: complianceEnabled, frameworks: complianceFrameworks }, rules: rulesEnabled } },
             warn: (msg) => p.log.warn(msg),
         });
-        // I41: emit legacy-upgrade notice when compliance is disabled AND pre-existing artifacts
-        // were found. After I09, the skill dir survives the orphan sweep (knownNames now unions
-        // FEATURE_OWNED_SKILLS), so convergeResult.removedPreexisting correctly fires for the
-        // skill path. hadComplianceRule covers the rule path (wiped by installViaFileCopy before
-        // converge probes on full installs).
+        // I41: emit legacy-upgrade notice when compliance is disabled AND a pre-existing rule
+        // was found. The skill is no signal — converge installs it on every machine
+        // (D-COMPLIANCE-INSTALL-ALWAYS) — so removedPreexisting reports the rule alone, on a
+        // partial install; hadComplianceRule covers full installs, where installViaFileCopy
+        // wipes the rules dir before converge probes it.
         if (!complianceEnabled && (convergeResult.removedPreexisting || hadComplianceRule)) {
-            p.log.info('Compliance artifacts removed — if you previously had devflow-compliance installed, ' +
+            p.log.info('Compliance rule removed — if you previously had devflow-compliance installed, ' +
                 'run `devflow compliance --enable` to re-enable with your framework selection.');
         }
     }
@@ -1395,23 +1745,23 @@ export const initCommand = new Command('init')
     try {
         let content = await fs.readFile(settingsPath, 'utf-8');
         const original = content;
-        // Ambient hook — always remove-then-add to upgrade from legacy ambient-prompt → preamble
-        const cleanedForAmbient = await removeAmbientHook(content);
-        content = ambientEnabled ? await addAmbientHook(cleanedForAmbient, devflowDir) : cleanedForAmbient;
+        // Ambient hooks — remove-then-add, upgrading a legacy ambient-prompt hook to preamble
+        content = await convergeAmbientHooks(content, ambientEnabled, devflowDir);
         // Capture hooks — always-on (like the context hook below), remove-then-add for
         // upgrade safety. Queue-append only (capture-prompt/capture-turn/capture-question);
-        // each script gates its own per-queue write internally via feature config, so there
-        // is no CLI-level enable/disable toggle here. MUST run before addMemoryHooks below
-        // so capture-turn lands before memory-worker in the Stop array (AC-C2 ordering:
-        // append-before-spawn).
+        // each script gates its own per-queue write on the machine-wide switch, so there
+        // is no CLI-level enable/disable toggle here. Runs before convergeMemoryHooks below
+        // so capture-turn lands before memory-worker in the Stop array, matching what
+        // `devflow memory --enable` produces (AC-C2). The Stop hooks still run in
+        // parallel; the memory worker tolerates a not-yet-appended turn.
         const cleanedForCapture = removeCaptureHooks(content);
         content = addCaptureHooks(cleanedForCapture, devflowDir);
-        // Memory hooks — always remove-then-add to upgrade hook format (e.g., .sh → run-hook).
-        // Three hooks: Stop (memory-worker), SessionStart (session-start-memory), PreCompact.
-        // Learning agent (spawned via session-start-context directive) handles decision/pitfall
-        // detection. Knowledge is handled in-command via write-through (knowledge_writeback MDS partial).
-        const cleaned = removeMemoryHooks(content);
-        content = memoryEnabled ? addMemoryHooks(cleaned, devflowDir) : cleaned;
+        // Memory hooks — Stop (memory-worker), SessionStart (session-start-memory),
+        // PreCompact — through the same transform `devflow memory --enable/--disable`
+        // uses (D-FEATURES-NARROW-ONLY). Learning agent (spawned via
+        // session-start-context directive) handles decision/pitfall detection.
+        // Knowledge is handled in-command via write-through (knowledge_writeback MDS partial).
+        content = convergeMemoryHooks(content, memoryEnabled, devflowDir);
         // HUD statusLine
         content = hudEnabled
             ? addHudStatusLine(content, devflowDir)
@@ -1465,7 +1815,7 @@ export const initCommand = new Command('init')
         if (proxyEnabled)
             content = applyProxyEnv(content, effectivePort);
         if (content !== original) {
-            await fs.writeFile(settingsPath, content, 'utf-8');
+            await writeSettingsFileAtomic(settingsPath, content);
             if (verbose) {
                 if (ambientEnabled)
                     p.log.success('Ambient mode hook installed');
@@ -1480,39 +1830,33 @@ export const initCommand = new Command('init')
         p.log.warn(`Could not configure settings.json: ${err instanceof Error ? err.message : err}. ` +
             'Manifest records intended state; run devflow init again to retry.');
     }
-    // Write .devflow/config.json to manage per-feature enable/disable at runtime.
-    // Uses writeConfig (full atomic write) rather than three updateFeature calls because
-    // init always sets all three features at once and is never concurrent with toggle
-    // commands — it is a one-time setup action. See D1 in feature-config.ts for the
-    // concurrency assumption shared by both write strategies.
+    // Write .devflow/config.json — facts about this repo. The machine switches for
+    // memory/learning/knowledge are the manifest's; a hand-written `features`
+    // object here only narrows them and is carried, never written
+    // (D-FEATURES-NARROW-ONLY; the managed write drops the retired top-level
+    // per-repo keys). A managed
+    // read-modify-write, not a whole-file write: init owns only reviewPublication,
+    // and every other key in the file — the hand-written per-repo `tracker`
+    // override first among them — is carried from disk, under --reset too
+    // (D-CONFIG-PRESERVE-UNMANAGED in feature-config.ts, avoids PF-071).
+    // A malformed or unreadable file is left untouched and named (D-CONFIG-NO-REPAIR).
     if (gitRoot) {
-        await writeConfig(gitRoot, {
-            memory: memoryEnabled,
-            learning: learningEnabled,
-            knowledge: knowledgeEnabled,
+        const configWrite = await writeManagedConfig(gitRoot, {
             // reviewPublication has no prompt, so it is carried over from the
             // reset-gated snapshot rather than re-read from disk: seedConfig is null
             // under --reset, which is what collapses the field back to 'auto' with
             // every other feature (PF-015 — read the post-gate binding, not the file).
-            reviewPublication: seedConfig?.reviewPublication ?? 'auto',
+            reviewPublication: seedConfig?.reviewPublication ?? DEFAULT_CONFIG.reviewPublication,
         });
-        // Drain orphaned queue files when memory is disabled so stale turns
-        // don't process on a future re-enable. Mirrors memory.ts --disable drain.
-        if (!memoryEnabled) {
-            await Promise.all([
-                fs.unlink(getPendingTurnsPath(gitRoot)).catch((e) => { if (e.code !== 'ENOENT')
-                    throw e; }),
-                fs.unlink(getPendingTurnsProcessingPath(gitRoot)).catch((e) => { if (e.code !== 'ENOENT')
-                    throw e; }),
-            ]);
-        }
+        if (!configWrite.ok)
+            p.log.warn(formatManagedConfigWriteError(configWrite.error));
     }
     // Configure HUD
     const existingHud = loadHudConfig();
     saveHudConfig({ enabled: hudEnabled, detail: existingHud.detail });
     // File extras
     if (claudeignoreEnabled) {
-        if (scope === 'user' && discoveredProjects.length > 0) {
+        if (discoveredProjects.length > 0) {
             const results = await Promise.all(discoveredProjects.map(root => installClaudeignore(root, rootDir, verbose)));
             const created = results.filter(Boolean).length;
             if (created > 0) {
@@ -1527,18 +1871,12 @@ export const initCommand = new Command('init')
         }
     }
     // Deterministically ensure .devflow/ is gitignored at the repo root — independent
-    // of install scope and every feature toggle. The always-on ensure-root-gitignore
+    // of every feature toggle. The always-on ensure-root-gitignore
     // hook covers projects that never re-run init; this covers the init-time path so a
     // fresh install never tracks .devflow/. Decoupled from memory (avoids PF-014).
     if (gitRoot) {
         await ensureDevflowGitignore(gitRoot, verbose);
     }
-    if (scope === 'local' && gitRoot) {
-        await updateGitignore(gitRoot, verbose);
-    }
-    if (scope === 'local') {
-        await createDocsStructure(verbose);
-    }
     // Safe-delete execution (decision was captured during prompt phase)
     if (safeDeleteAction === 'install' && safeDeleteBlock && profilePath) {
         await installToProfile(profilePath, safeDeleteBlock);
@@ -1626,11 +1964,26 @@ export const initCommand = new Command('init')
             }
         }
         else if (securityMode === 'none') {
-            // None: strip Devflow deny entries from user settings.
-            // Uses the canonical helper (atomic temp+rename; ENOENT-safe; only-write-if-changed).
+            // None: strip Devflow deny entries from EVERY location, as
+            // `devflow security --disable` does. User settings first, via the
+            // canonical helper (atomic temp+rename; ENOENT-safe; only-write-if-changed).
             const stripResult = await stripUserSecurityDenyList(userSettingsPath);
             if (stripResult && verbose)
                 p.log.info(`Security deny list removed (${stripResult.removed.length} entries stripped)`);
+            // Then managed settings, through the one removal security.ts also uses.
+            // Before this, `none` left the managed file in place: the deny list kept
+            // applying — at the highest precedence — while the manifest said `none`.
+            // A permission failure is reported, never thrown (the install already
+            // succeeded; the manifest records the choice and a re-run can retry).
+            if (managedDenyDetected) {
+                s.stop('Removing managed security settings (may prompt for sudo password)...');
+                const managedMsg = describeManagedDenyRemoval(await removeManagedDenyList(rootDir, verbose));
+                if (managedMsg.level === 'warn')
+                    p.log.warn(managedMsg.text);
+                else if (verbose)
+                    p.log.info(managedMsg.text);
+                s.start('Finalizing installation...');
+            }
         }
         else {
             // Exhaustive guard — if TypeScript reaches here, a new SecurityMode variant was added
@@ -1683,12 +2036,21 @@ export const initCommand = new Command('init')
     // failed removal leaves a retired asset live. Both must surface.
     // After I09, the installer's knownNames set unions FEATURE_OWNED_SKILLS, so
     // devflow:compliance is never swept here — no suppression predicate is needed.
-    for (const line of formatSweepSummary(installReport)) {
-        if (line.level === 'warn')
-            p.log.warn(line.message);
-        else
-            p.log.info(line.message);
-    }
+    logSummaryLines(formatSweepSummary(installReport));
+    // Reference-overlay reporting: the overlay rewrites files inside an installed skill
+    // the user may have shadowed, and reports any unit it had to leave alone (PF-015).
+    logSummaryLines(formatOverlaySummary(installReport));
+    // Skill-scoping reporting: a deselected skill is deleted and a dormant shadow
+    // is inert, and neither is distinguishable from "never installed" on disk.
+    //
+    // L2: "the plugin list is unchanged" means a prior manifest EXISTS and its
+    // plugin set equals this run's. A first install had nothing to remove, so
+    // there is no upgrade to explain — the removal notice would be addressed to
+    // a user who never had the skills.
+    const pluginListUnchanged = isPluginListUnchanged(existingManifest?.plugins ?? null, effectivePluginNames);
+    logSummaryLines(formatSkillScopeSummary(installReport, pluginListUnchanged));
+    for (const warning of installWarnings)
+        p.log.warn(warning);
     const installedSet = new Set(pluginsToInstall.flatMap(p => p.commands).filter(c => c.length > 0));
     const orderedCommands = WORKFLOW_ORDER.filter(cmd => installedSet.has(cmd));
     if (orderedCommands.length > 0) {
@@ -1732,7 +2094,6 @@ export const initCommand = new Command('init')
             .map(plugin => `${color.yellow(plugin.name.padEnd(24))}${color.dim(plugin.description)}`)
             .join('\n');
         p.note(pluginsList, 'Installed plugins');
-        p.log.info(`Scope: ${scope}`);
         p.log.info(`Claude dir: ${claudeDir}`);
         p.log.info(`Devflow dir: ${devflowDir}`);
         const totalSkillDeclarations = pluginsToInstall.reduce((sum, p) => sum + p.skills.length, 0);
@@ -1741,12 +2102,14 @@ export const initCommand = new Command('init')
         p.log.info(`Deduplication: ${agentsMap.size} unique agents (from ${totalAgentDeclarations} declarations)`);
     }
     // Write installation manifest for upgrade tracking (non-fatal — install already succeeded)
-    const installedPluginNames = pluginsToInstall.map(pl => pl.name);
     const now = new Date().toISOString();
     const manifestData = {
         version,
-        plugins: resolvePluginList(installedPluginNames, existingManifest, !!options.plugin),
-        scope,
+        // Resolved above, before the install, because the skills install set is
+        // derived from it — one binding, so the manifest can never record a
+        // selection other than the one the assets were installed for.
+        plugins: effectivePluginNames,
+        scope: 'user',
         // Snapshot of known plugin names at this install — used by resolveSeedPlugins on next init
         // to detect new non-optional plugins and auto-adopt them.
         knownPlugins: DEVFLOW_PLUGINS.map(p => p.name),
@@ -1767,16 +2130,62 @@ export const initCommand = new Command('init')
             // and Advanced wizard selection. convergeComplianceArtifacts was called above.
             // normalizeFrameworks: dedup + filter unknowns before persisting.
             compliance: { enabled: complianceEnabled, frameworks: normalizeFrameworks(complianceFrameworks) },
+            // Resolved tracker selection. Already a validated TrackerProvider — it came
+            // through parseTrackerId (CLI), the typed wizard select, or the seed, which
+            // itself came through normalizeTrackerFeature on read.
+            tracker: { provider: trackerProvider },
         },
         installedAt: existingManifest?.installedAt ?? now,
         updatedAt: now,
     };
-    try {
-        await writeManifest(devflowDir, manifestData);
-    }
-    catch (error) {
-        p.log.warn(`Failed to write installation manifest (install succeeded): ${error instanceof Error ? error.message : error}`);
-    }
+    // ── Manifest write + tracker selection lifecycle (the ONE call site) ──────
+    // persistManifestThenConvergeTracker owns the ordering invariant: the
+    // tracker file-lifecycle owners in src/core/tracker.ts converge only against
+    // a provider the manifest actually persisted (D-TRACKER-CONVERGE, PF-015).
+    const trackerLifecycle = await persistManifestThenConvergeTracker({
+        devflowDir,
+        claudeDir,
+        manifestData,
+        io: buildTrackerLifecycleIO(),
+    });
+    for (const msg of trackerLifecycle.messages) {
+        if (msg.level === 'warn')
+            p.log.warn(msg.text);
+        else
+            p.log.info(msg.text);
+    }
+    // Only now that the machine-wide switch is on disk (D-INIT-DRAIN-AFTER-SWITCH).
+    await drainDisabledFeatureQueues({
+        gitRoot,
+        ledgerRoot: learningEnabled || gitRoot === null ? null : await getLedgerRoot(),
+        memoryEnabled,
+        learningEnabled,
+        manifestWritten: trackerLifecycle.manifestWritten,
+    });
+    // The hooks' per-directory log folders, capped (D-LOG-DIR-CAP): one pass
+    // clears every folder it scans beyond the cap; only a backlog beyond the
+    // scan bound (MAX_LOG_DIRS_SCANNED, 100,000) waits for the next init.
+    const logPrune = await pruneHookLogDirs(path.join(devflowDir, 'logs'));
+    if (!logPrune.ok) {
+        if (verbose)
+            p.log.warn(`Could not prune hook log folders: ${logPrune.error}`);
+    }
+    else if (logPrune.value.removed > 0) {
+        p.log.info(formatLogPruneLine(logPrune.value));
+    }
+    // Name the active provider and what the selection moved. The reference
+    // counts come from the install report rather than being recomputed: the
+    // overlay is what actually installed and pruned them, so a second count
+    // here could only ever disagree with it.
+    const trackerLines = formatTrackerAssetSummary({
+        provider: trackerProvider,
+        previous: existingManifest?.features.tracker.provider,
+        isDefault: trackerProvider === DEFAULT_TRACKER_PROVIDER,
+        installedRefs: installReport.overlaidRefs.length,
+        removedRefs: installReport.sweptOrphans.filter(o => o.kind === 'reference').length,
+        agent: trackerLifecycle.agent,
+    });
+    logSummaryLines(trackerLines);
     // External model routing status line (Advanced path / explicit --proxy flag only)
     if (proxyEnabled) {
         p.log.info(`External model routing: ${color.green('enabled')} — takes effect in new Claude Code sessions`);