devflow-kit 2.4.0 → 2.5.0

package/dist/cli/commands/init.js

@@ -7,13 +7,15 @@ import color from 'picocolors';
 import { getInstallationPaths } from '../../targets/claude-code/claude-paths.js';
 import { getGitRoot } from '../../core/git.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 { DEVFLOW_PLUGINS, LEGACY_COMMAND_NAMES, LEGACY_RULE_NAMES, buildAssetMaps, buildFullSkillsMap, buildRulesMap, partitionSelectablePlugins, WORKFLOW_ORDER, parsePluginSelection, resolveFeatureRedirect } from '../../core/plugins.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 { 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,13 +28,16 @@ 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 { 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 { 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 { 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';
@@ -99,6 +104,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,6 +192,250 @@ 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,
+        renameStaleConventions: renameStaleTrackerConventions,
+        convergeArtifacts: (claudeDir, provider, warn) => convergeTrackerArtifacts({ claudeDir, provider, 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 three 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.
+ *
+ * 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.
+ *
+ * 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 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, attempt counter and ` +
+                `conventions file 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).
+    const agentWarnings = [];
+    const artifacts = await io.convergeArtifacts(claudeDir, provider, (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;
+    const [rearm, sentinel] = await Promise.all([
+        // [DR-22] The documented re-arm path: devflow init resets the attempt counter
+        // 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),
+    ]);
+    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,
+        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.
+ */
+export async function drainDisabledFeatureQueues(opts, io = { drainMemoryQueue, drainLearningQueue }) {
+    if (!opts.manifestWritten || opts.gitRoot === null)
+        return;
+    if (!opts.memoryEnabled)
+        await io.drainMemoryQueue(opts.gitRoot);
+    if (!opts.learningEnabled)
+        await io.drainLearningQueue(opts.gitRoot);
+}
+/**
+ * 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
+ * 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
+ * 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) {
+    if (existing !== null) {
+        return {
+            ...existing,
+            features: { ...existing.features, hud: true },
+            updatedAt: now,
+        };
+    }
+    return {
+        version,
+        plugins: [],
+        scope,
+        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,
+    };
+}
 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)
@@ -183,6 +457,7 @@ export const initCommand = new Command('init')
     .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('--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)')
@@ -261,28 +536,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, scope, new Date().toISOString()));
         }
         catch { /* non-fatal */ }
         p.log.success('HUD installed');
@@ -319,7 +581,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 +595,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) {
@@ -506,6 +782,9 @@ 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.
@@ -520,6 +799,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 +872,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 +894,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 +906,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) {
@@ -612,6 +942,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 +991,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 +1025,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 +1043,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 +1133,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
@@ -993,6 +1351,10 @@ export const initCommand = new Command('init')
         }
     }
     // 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 +1367,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);
@@ -1068,9 +1431,17 @@ export const initCommand = new Command('init')
     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();
+    // 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)
@@ -1107,16 +1478,23 @@ 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,
             agentsMap,
             rulesMap,
+            trackerProvider,
             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) {
@@ -1400,18 +1778,18 @@ export const initCommand = new Command('init')
         content = ambientEnabled ? await addAmbientHook(cleanedForAmbient, devflowDir) : cleanedForAmbient;
         // 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
+        // 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).
         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-MACHINE-WIDE). 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)
@@ -1480,32 +1858,21 @@ 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, 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
+    // 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).
     if (gitRoot) {
-        await writeConfig(gitRoot, {
-            memory: memoryEnabled,
-            learning: learningEnabled,
-            knowledge: knowledgeEnabled,
+        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; }),
-            ]);
-        }
     }
     // Configure HUD
     const existingHud = loadHudConfig();
@@ -1626,11 +1993,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 +2065,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, trackerProvider));
+    // 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) {
@@ -1741,11 +2132,13 @@ 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),
+        // 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,
         // Snapshot of known plugin names at this install — used by resolveSeedPlugins on next init
         // to detect new non-optional plugins and auto-adopt them.
@@ -1767,16 +2160,54 @@ 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 three
+    // 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) {
+        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,
+        memoryEnabled,
+        learningEnabled,
+        manifestWritten: trackerLifecycle.manifestWritten,
+    });
+    // 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`);