devflow-kit 2.5.0 → 3.0.0

package/dist/cli/commands/init.js

@@ -1,20 +1,23 @@
-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 { formatOverlaySummary, formatSkillScopeSummary, formatTrackerAssetSummary, isPluginListUnchanged } from './install-report.js';
 import { convergeTrackerArtifacts } from '../../targets/claude-code/tracker-install.js';
-import { installSettings, installManagedSettings, installClaudeignore, discoverProjectGitRoots, updateGitignore, ensureDevflowGitignore, createDocsStructure, applyUserSecurityDenyList, detectDenyState, resolveSecurityAction, assertHistoricalDenySuperset, loadTemplateDenyEntries, stripUserSecurityDenyList, } from '../../targets/claude-code/post-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 { convergeAmbientHooks } from './ambient.js';
 import { convergeMemoryHooks, drainMemoryQueue } from './memory.js';
 import { addCaptureHooks, removeCaptureHooks } from './capture.js';
 import { removeDreamHook } from './legacy-hooks.js';
@@ -28,19 +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 { 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 } from './init-seed.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, renameStaleTrackerConventions, DEFAULT_TRACKER_PROVIDER, } from '../../core/tracker.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 * 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';
@@ -240,8 +244,7 @@ export function trackerOverrideMessage(provider) {
 export function buildTrackerLifecycleIO() {
     return {
         writeManifest,
-        renameStaleConventions: renameStaleTrackerConventions,
-        convergeArtifacts: (claudeDir, provider, warn) => convergeTrackerArtifacts({ claudeDir, provider, warn }),
+        convergeArtifacts: (claudeDir, warn) => convergeTrackerArtifacts({ claudeDir, warn }),
         rearmInference: rearmTrackerInference,
         applySentinel: applyTrackerSentinel,
     };
@@ -250,33 +253,26 @@ export function buildTrackerLifecycleIO() {
  * Persist the installation manifest, then converge the tracker artifacts against
  * the provider that was actually persisted.
  *
- * D-TRACKER-CONVERGE: the manifest write and the three tracker file-lifecycle
- * owners are ONE unit because their relative order is the invariant, not an
+ * 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, the attempt counter or
- * the conventions file ahead of it leaves the artifacts disagreeing in both
- * directions: github→jira writes a sentinel for a provider the manifest never
- * records (a per-session fork cost forever), and jira→github removes the
- * sentinel, renames tracker.md to .bak and leaves the manifest on jira (silent
- * permanent degradation with no re-trigger). Writing first and gating the three
- * owners on `manifestWritten` makes the artifacts converge all-or-none, and puts
- * this call site in the same order as the sibling `devflow tracker --set`
- * (src/cli/commands/tracker.ts): rename → persist → rearm → sentinel.
+ * 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 artifacts
- * cannot converge on a value other than the one on disk.
- *
- * `previousProvider` is the caller's REAL prior manifest value, never the
- * --reset-gated seed: under --reset the resolved provider collapses to github
- * while the prior provider is still jira/linear, and that IS a transition the
- * stale-conventions rename has to fire on.
+ * 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, previousProvider, io } = 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
@@ -293,77 +289,35 @@ export async function persistManifestThenConvergeTracker(opts) {
         });
         messages.push({
             level: 'warn',
-            text: `Tracker selection (${provider}) was not persisted — the sentinel, attempt counter and ` +
-                `conventions file are unchanged. Re-run devflow init, or devflow tracker --set ${provider}.`,
+            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 };
     }
-    // Move a now-stale conventions file aside (the writer arm of the provider change).
-    //
-    // D-TRACKER-PARALLEL: the rename stays strictly ahead of the other two. It is
-    // the only step that reads the PREVIOUS provider and the only one that reports
-    // a transition, so keeping it first fixes the message order (the transition
-    // notice always precedes any owner warning) and keeps the sequence readable as
-    // "settle the old provider, then converge the new one". The two that follow
-    // touch disjoint files — the attempt counter and the presence 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 transition = await io.renameStaleConventions(devflowDir, previousProvider, provider);
-    if (transition.kind === 'renamed') {
-        messages.push({
-            level: 'info',
-            text: `Tracker provider changed — previous ${transition.previous} conventions moved to ` +
-                `${color.dim(transition.to)}`,
-        });
-    }
-    else if (transition.kind === 'failed') {
-        messages.push({ level: 'warn', text: transition.error });
-    }
-    // The fourth owner — the Tracker agent file. SEQUENTIAL, and strictly before
-    // the pair below, because the sentinel's WRITE is gated on its outcome: a
-    // sentinel that advertises jira while the agent it would spawn is missing is
-    // the drifted state this whole ordering exists to prevent (design review H6 —
-    // the parallel pair stays a parallel pair, it is not flattened to make room).
+    // 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, provider, (msg) => agentWarnings.push(msg));
+    const artifacts = await io.convergeArtifacts(claudeDir, (msg) => agentWarnings.push(msg));
     for (const text of agentWarnings)
         messages.push({ level: 'warn', text });
-    // C2: the sentinel converges in BOTH directions, and only the WRITE is gated.
-    //   provider ≠ github → a write, when a spawnable agent is actually there.
-    //   provider = github → a removal. ALWAYS attempted, because leaving a stale
-    //     sentinel behind costs every future session a fork for a provider the
-    //     user has left, and a failed agent removal is not a reason to keep it.
-    //
-    // The write gate reads `agentPresent`, not `converged`. `converged` answers
-    // "did THIS run copy it", and reading that alone is wrong in both directions:
-    // a re-copy that fails over an already-installed agent would disable a provider
-    // that still works, and merely SUPPRESSING the write leaves the PREVIOUS
-    // provider's sentinel in place — so a jira → linear init whose agent copy
-    // failed goes on advertising jira, which is the state the suppression exists to
-    // prevent. Not-spawnable therefore REMOVES, through the one sentinel owner in
-    // src/core/tracker.ts (D-TRACKER-OWNER), never an inline fs.rm here.
-    const advertisable = provider === DEFAULT_TRACKER_PROVIDER || artifacts.agentPresent;
+    // 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 counter
+        // [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 presence sentinel: written for jira/linear, removed for
-        // github. This is what keeps the GitHub SessionStart path at one stat and zero forks.
-        io.applySentinel(devflowDir, advertisable ? provider : DEFAULT_TRACKER_PROVIDER),
+        // [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 });
-    if (!advertisable) {
-        messages.push({
-            level: 'warn',
-            text: `Tracker sentinel removed — no ${provider} agent is installed, so nothing advertises a ` +
-                `provider whose agent is missing and no session will try to spawn it. ` +
-                `Re-run devflow init, or devflow tracker --set ${provider}.`,
-        });
-    }
     return {
         manifestWritten: true,
         converged: artifacts.converged && sentinel.ok,
@@ -385,34 +339,38 @@ export async function persistManifestThenConvergeTracker(opts) {
  * 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 || opts.gitRoot === null)
+    if (!opts.manifestWritten)
         return;
-    if (!opts.memoryEnabled)
+    if (!opts.memoryEnabled && opts.gitRoot !== null)
         await io.drainMemoryQueue(opts.gitRoot);
-    if (!opts.learningEnabled)
-        await io.drainLearningQueue(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,
- * scope, installedAt and every feature — and only `features.hud` turns on. The
+ * 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-MACHINE-WIDE) a HUD install would have really disabled them
+ * (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, scope, now) {
+export function buildHudOnlyManifest(existing, version, now) {
     if (existing !== null) {
         return {
             ...existing,
@@ -423,7 +381,7 @@ export function buildHudOnlyManifest(existing, version, scope, now) {
     return {
         version,
         plugins: [],
-        scope,
+        scope: 'user',
         features: {
             ambient: false, memory: false, hud: true, knowledge: false,
             learning: false, rules: false, flags: {}, proxy: false,
@@ -436,9 +394,84 @@ export function buildHudOnlyManifest(existing, version, scope, 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)')
@@ -456,8 +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('--tracker <id>', 'Issue tracker provider: github, jira, or linear')
+    .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)')
@@ -483,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 });
@@ -521,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}`);
@@ -544,7 +568,7 @@ export const initCommand = new Command('init')
         }
         catch { /* absent on fresh install — existingHudManifest stays null */ }
         try {
-            await writeManifest(devflowDir, buildHudOnlyManifest(existingHudManifest, version, scope, new Date().toISOString()));
+            await writeManifest(devflowDir, buildHudOnlyManifest(existingHudManifest, version, new Date().toISOString()));
         }
         catch { /* non-fatal */ }
         p.log.success('HUD installed');
@@ -552,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
@@ -717,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];
     }
@@ -791,7 +818,7 @@ export const initCommand = new Command('init')
     // --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;
@@ -914,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;
@@ -1200,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,
@@ -1279,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');
@@ -1323,32 +1334,17 @@ 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
@@ -1396,41 +1392,19 @@ 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);
-    }
+    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
@@ -1450,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
@@ -1488,7 +1461,6 @@ export const initCommand = new Command('init')
             skillsMap,
             agentsMap,
             rulesMap,
-            trackerProvider,
             isPartialInstall: !!options.plugin,
             spinner: s,
             // Non-fatal install notices with no other channel (skipped symlinks in the
@@ -1514,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.');
         }
     }
@@ -1773,20 +1745,20 @@ 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 on the machine-wide switch, so there
-        // is no CLI-level enable/disable toggle here. MUST run before convergeMemoryHooks below
-        // so capture-turn lands before memory-worker in the Stop array (AC-C2 ordering:
-        // append-before-spawn).
+        // 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 — Stop (memory-worker), SessionStart (session-start-memory),
         // PreCompact — through the same transform `devflow memory --enable/--disable`
-        // uses (D-FEATURES-MACHINE-WIDE). Learning agent (spawned via
+        // 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);
@@ -1843,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');
@@ -1858,28 +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 — facts about this repo, never a feature switch
-    // (memory/learning/knowledge are the manifest's alone, D-FEATURES-MACHINE-WIDE;
-    // the managed write drops their retired per-repo keys). A managed
+    // 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 writeManagedConfig(gitRoot, {
+        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 ?? DEFAULT_CONFIG.reviewPublication,
         });
+        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) {
@@ -1894,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);
@@ -2068,7 +2039,7 @@ export const initCommand = new Command('init')
     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, trackerProvider));
+    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.
     //
@@ -2123,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);
@@ -2139,7 +2109,7 @@ export const initCommand = new Command('init')
         // 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,
+        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),
@@ -2169,17 +2139,13 @@ export const initCommand = new Command('init')
         updatedAt: now,
     };
     // ── Manifest write + tracker selection lifecycle (the ONE call site) ──────
-    // persistManifestThenConvergeTracker owns the ordering invariant: the three
+    // 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,
-        // The REAL manifest, not the --reset-gated seed: under --reset the resolved
-        // provider collapses to github while the prior provider is still jira/linear,
-        // and that IS a transition the stale-file rename has to fire on.
-        previousProvider: existingManifest?.features.tracker.provider,
         io: buildTrackerLifecycleIO(),
     });
     for (const msg of trackerLifecycle.messages) {
@@ -2191,10 +2157,22 @@ export const initCommand = new Command('init')
     // 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