devflow-kit 2.4.0 → 2.5.0

package/dist/cli/commands/install-report.js

@@ -0,0 +1,205 @@
+/**
+ * Rendering for the post-install summary — pure functions that turn an
+ * {@link InstallReport} into lines, logging nothing (applies ADR-013).
+ *
+ * Its own module rather than a section of init.ts because `devflow tracker --set`
+ * renders the same overlay outcomes from a different command. A CLI command
+ * importing a renderer out of a 2,450-line sibling couples two commands through
+ * a file neither of them owns; both import from here instead (design review M5).
+ */
+import color from 'picocolors';
+import { overlayUnitLabel } from '../../targets/claude-code/installer.js';
+import { SKILL_REFS_SKILL_NAME } from '../../core/mds-variants.js';
+import { prefixSkillName } from '../../core/plugins.js';
+/**
+ * Turn the reference-overlay half of an InstallReport into summary lines.
+ *
+ * The overlay rewrites files inside an installed skill directory the user may have
+ * shadowed, and a unit it could not refresh is left in one of the states
+ * {@link OverlayFailureState} enumerates — running on the previous install, half
+ * replaced, absent, or recoverable only from a backup path. None of that is visible from
+ * the filesystem at a glance, so all of it reaches the summary — PF-015: a report field
+ * with no render site is not a report, and a render site that flattens four states into
+ * one sentence is the same defect one layer up.
+ *
+ * Pure function — returns lines, logs nothing (applies ADR-013).
+ *
+ * @param provider - The resolved tracker provider the overlay converged to. The
+ *   count alone cannot say WHICH mechanics are installed, and after the install
+ *   became selection-scoped that is the number's whole meaning.
+ * @param skillName - Bare name of the skill hosting the generated references,
+ *   rendered `devflow:`-prefixed. Defaults to the core constant the build path and
+ *   the installer's overlay trigger both read, so the renderer is never a third
+ *   independent statement of which skill owns them — the divergence PF-013
+ *   describes, where changing the answer means finding every retyped spelling and
+ *   nothing fails if one is missed.
+ */
+export function formatOverlaySummary(report, provider, skillName = SKILL_REFS_SKILL_NAME) {
+    const lines = [];
+    if (report.overlaidRefs.length > 0) {
+        const scope = provider === undefined ? '' : ` (${provider} tracker mechanics)`;
+        lines.push({
+            level: 'info',
+            message: `Installed ${report.overlaidRefs.length} generated skill reference(s) for ` +
+                prefixSkillName(skillName) + scope,
+        });
+    }
+    for (const failure of report.overlayFailures) {
+        lines.push({
+            level: 'warn',
+            message: `Could not refresh the generated references for ${overlayUnitLabel(failure.unit)} ` +
+                `(${failure.error}) — ${describeOverlayFailureState(failure.state)}`,
+        });
+    }
+    return lines;
+}
+/**
+ * The half of an overlay warning that describes what is actually on disk.
+ *
+ * One sentence per state, each true of that state and of no other. A single shared
+ * sentence — "the previously installed files were left unchanged" — is true of the first
+ * arm only, and would read loudest over the arms it fits worst: a set left
+ * half-refreshed, and a unit whose only surviving copy is a backup path the user has to
+ * be told about.
+ *
+ * Exported because `devflow tracker --set` renders the same states when it aborts
+ * on an overlay failure (applies PF-013 — one sentence per state, in one place,
+ * rather than a second wording that drifts).
+ *
+ * Exhaustive over {@link OverlayFailureState} — a new state added to the union without a
+ * sentence here is a compile error, not a state that silently prints nothing.
+ */
+export function describeOverlayFailureState(state) {
+    switch (state.kind) {
+        case 'installed-unchanged':
+            return 'the previously installed files were left unchanged';
+        case 'not-installed':
+            return (`nothing is installed in their place, so ${state.absent.length} reference(s) the ` +
+                `agent is told to load are absent: ${state.absent.join(', ')}`);
+        case 'partially-refreshed':
+            return (`${state.refreshed.length} of ${state.refreshed.length + state.stale.length} ` +
+                `document(s) had already been replaced, so the set is part new and part old — ` +
+                `still on the previous install: ${state.stale.join(', ') || 'none'}`);
+        case 'restore-failed':
+            return (`the displaced copy could NOT be put back (${state.restoreError}), so nothing is ` +
+                `installed there now — the only surviving copy is "${state.recoveryPath}", which ` +
+                `this run's stale-reference prune was skipped to preserve`);
+        default: {
+            const _exhaustive = state;
+            void _exhaustive;
+            return 'the state it was left in is unknown';
+        }
+    }
+}
+/**
+ * The install summary's tracker rows.
+ *
+ * Two facts the previous summary never stated, and after the install became
+ * selection-scoped both of them decide what the user actually has:
+ *
+ *   - WHICH provider is active. The install has no other visible trace of it —
+ *     the sentinel is a zero-byte dotfile and the mechanics are a directory the
+ *     user has no reason to list. `(default)` distinguishes "github because I
+ *     chose it" from "github because nothing was chosen"; `(was jira)` is what
+ *     makes a self-heal or a `--reset` collapse legible rather than silent.
+ *   - WHAT the provider change moved. A provider swap installs one tree and
+ *     prunes another, and the agent file appears or disappears with it.
+ *
+ * The delta line is emitted only when something moved: on a steady-state re-init
+ * the counts are noise.
+ *
+ * Pure function — returns lines, logs nothing (applies ADR-013).
+ *
+ * @param previous - The provider recorded by the PRIOR manifest, or undefined on
+ *   a first install. Rendered only when it differs from `provider`.
+ * @param isDefault - Whether `provider` is the registry default.
+ */
+export function formatTrackerAssetSummary(input) {
+    const lines = [];
+    const changed = input.previous !== undefined && input.previous !== input.provider;
+    const qualifier = changed
+        ? ` ${color.dim(`(was ${input.previous})`)}`
+        : input.isDefault ? ` ${color.dim('(default)')}` : '';
+    lines.push({ level: 'info', message: `Tracker: ${input.provider}${qualifier}` });
+    const agentNote = input.agent === 'unchanged' ? '' : `, tracker agent ${input.agent}`;
+    if (input.installedRefs > 0 || input.removedRefs > 0 || agentNote !== '') {
+        lines.push({
+            level: 'info',
+            message: `Tracker assets: +${input.installedRefs} reference(s), ` +
+                `−${input.removedRefs} reference(s)${agentNote}`,
+        });
+    }
+    return lines;
+}
+/**
+ * Did this run's plugin selection match the one already on disk?
+ *
+ * The question {@link formatSkillScopeSummary}'s `pluginListUnchanged` asks, and
+ * a separate function because the two halves fail differently and only one of
+ * them had executed evidence (design review L2): the renderer's behaviour given
+ * an answer, and the answer itself.
+ *
+ * Two clauses, and the first one is the one a set comparison alone would lose:
+ *
+ *   - **A prior manifest must EXIST.** `null` is a first install. Nothing was
+ *     removed from a user who had nothing, so there is no upgrade to explain,
+ *     and comparing "no previous selection" against this run's would otherwise
+ *     read as a match whenever both are empty.
+ *   - **The plugin SETS must be equal**, not the arrays: order is an artifact of
+ *     how the selection was assembled, and a duplicate name in either list is a
+ *     manifest detail rather than a different selection.
+ *
+ * Pure function (applies ADR-013).
+ *
+ * @param previousPlugins - `manifest.plugins` as it stands before this run, or
+ *   `null` when there is no prior manifest.
+ * @param effectivePluginNames - What this run installs.
+ */
+export function isPluginListUnchanged(previousPlugins, effectivePluginNames) {
+    if (previousPlugins === null)
+        return false;
+    const previous = new Set(previousPlugins);
+    const effective = new Set(effectivePluginNames);
+    return previous.size === effective.size && [...effective].every(name => previous.has(name));
+}
+/**
+ * Turn the skill-scoping half of an InstallReport into summary lines.
+ *
+ * Two facts the filesystem cannot tell the user apart from an install that never
+ * happened:
+ *
+ *   - a REMOVED skill. Scoping the install means a re-init after deselecting a
+ *     plugin silently deletes skills the previous install carried. The line is
+ *     emitted only when the plugin list is UNCHANGED, because that is the case
+ *     the user did not ask for: they re-ran init expecting nothing to move, and
+ *     the scoping change is what moved it. When they deselected a plugin
+ *     themselves, the removal is the thing they asked for and needs no notice.
+ *   - a DORMANT shadow. `~/.devflow/skills/{name}/` is never deleted, so an
+ *     inactive shadow and an applied one look identical from disk.
+ *
+ * `pluginListUnchanged` is the caller's answer to "did the selection move?", and
+ * it is FALSE when there is no prior manifest: a first install removed nothing a
+ * user had, so there is no upgrade to explain (design review L2).
+ *
+ * Pure function — returns lines, logs nothing (applies ADR-013).
+ */
+export function formatSkillScopeSummary(report, pluginListUnchanged) {
+    const lines = [];
+    if (pluginListUnchanged && report.removedSkills.length > 0) {
+        const names = [...report.removedSkills].sort().join(', ');
+        lines.push({
+            level: 'info',
+            message: `Removed ${report.removedSkills.length} skill(s) no selected plugin requires: ${names}. ` +
+                `Re-run devflow init and select the plugin that provides them to keep them.`,
+        });
+    }
+    for (const name of report.dormantShadows) {
+        lines.push({
+            level: 'info',
+            message: `Shadow for ${name} is inactive — the plugin that uses it is not selected ` +
+                `(${color.dim('kept in ~/.devflow/skills/')})`,
+        });
+    }
+    return lines;
+}
+//# sourceMappingURL=install-report.js.map

package/dist/cli/commands/knowledge/index.js

@@ -10,8 +10,8 @@ import { handleToggle } from './toggle.js';
 import { handleList } from './list.js';
 export const knowledgeCommand = new Command('knowledge')
     .description('Manage per-feature knowledge bases')
-    .option('--enable', 'Enable per-feature knowledge bases')
-    .option('--disable', 'Disable per-feature knowledge bases')
+    .option('--enable', 'Enable per-feature knowledge bases in every project')
+    .option('--disable', 'Disable per-feature knowledge bases in every project')
     .option('--status', 'Show knowledge base feature status')
     .action(async (options) => {
     await handleToggle(options);

package/dist/cli/commands/knowledge/toggle.js

@@ -1,7 +1,11 @@
 /**
  * Handle the enable/disable/status toggle actions for `devflow knowledge`.
  *
- * The sole opt-out mechanism is the feature config `knowledge` field (config-only gate per ADR-001).
+ * D-FEATURES-MACHINE-WIDE (src/core/feature-switch.ts): knowledge write-back is
+ * switched for the whole machine by `features.knowledge` in
+ * ~/.devflow/manifest.json. `--enable`/`--disable` write that value — the same
+ * one `devflow init --knowledge / --no-knowledge` writes — and `--status`
+ * reports it.
  */
 import { promises as fs } from 'fs';
 import * as path from 'path';
@@ -9,8 +13,7 @@ import * as p from '@clack/prompts';
 import color from 'picocolors';
 import { getGitRoot } from '../../../core/git.js';
 import { getDevFlowDirectory } from '../../../targets/claude-code/claude-paths.js';
-import { readManifest, writeManifest } from '../../../core/manifest.js';
-import { updateFeature, isFeatureEnabled } from '../../../core/feature-config.js';
+import { readMachineFeature, writeMachineFeature } from '../../../core/feature-switch.js';
 import { getFeaturesDir } from '../../../core/project-paths.js';
 async function getWorktreePath() {
     return (await getGitRoot()) ?? process.cwd();
@@ -39,46 +42,33 @@ async function countKnowledgeBases(worktreePath) {
 export async function handleToggle(options) {
     if (!options.enable && !options.disable && !options.status)
         return;
-    const worktreePath = await getWorktreePath();
     const devflowDir = getDevFlowDirectory();
-    if (options.enable) {
-        p.intro(color.cyan('Enable Feature Knowledge Bases'));
-        // Update feature config (the sole gate — config-only per ADR-001)
-        await updateFeature(worktreePath, 'knowledge', true);
-        // Update manifest
-        const manifest = await readManifest(devflowDir);
-        if (manifest) {
-            manifest.features.knowledge = true;
-            manifest.updatedAt = new Date().toISOString();
-            await writeManifest(devflowDir, manifest);
-        }
-        p.log.success('Feature knowledge bases enabled');
-        p.log.info('Knowledge bases are created automatically when workflows detect documented area changes.');
+    if (options.status) {
+        p.intro(color.cyan('Feature Knowledge Status'));
+        const enabled = await readMachineFeature(devflowDir, 'knowledge');
+        const kbCount = await countKnowledgeBases(await getWorktreePath());
+        p.log.info(`Status: ${enabled ? color.green('enabled') : color.yellow('disabled')}`);
+        p.log.info(`Knowledge bases: ${kbCount}`);
         p.outro('');
+        return;
     }
-    else if (options.disable) {
-        p.intro(color.cyan('Disable Feature Knowledge Bases'));
-        // Update feature config (the sole gate — config-only per ADR-001)
-        await updateFeature(worktreePath, 'knowledge', false);
-        // Update manifest
-        const manifest = await readManifest(devflowDir);
-        if (manifest) {
-            manifest.features.knowledge = false;
-            manifest.updatedAt = new Date().toISOString();
-            await writeManifest(devflowDir, manifest);
-        }
-        p.log.success('Feature knowledge bases disabled');
-        p.log.info('Existing knowledge bases preserved. Write-back skipped while disabled.');
+    const enabled = options.enable === true;
+    p.intro(color.cyan(`${enabled ? 'Enable' : 'Disable'} Feature Knowledge Bases`));
+    const recorded = await writeMachineFeature(devflowDir, 'knowledge', enabled);
+    if (!recorded.ok) {
+        p.log.error(`Devflow is not installed on this machine — run ${color.cyan('devflow init')} first`);
+        process.exitCode = 1;
         p.outro('');
+        return;
+    }
+    if (enabled) {
+        p.log.success('Feature knowledge bases enabled in every project');
+        p.log.info('Knowledge bases are created automatically when workflows detect documented area changes.');
     }
     else {
-        // options.status
-        p.intro(color.cyan('Feature Knowledge Status'));
-        const enabled = await isFeatureEnabled(worktreePath, 'knowledge');
-        const kbCount = await countKnowledgeBases(worktreePath);
-        p.log.info(`Status: ${enabled ? color.green('enabled') : color.yellow('disabled')}`);
-        p.log.info(`Knowledge bases: ${kbCount}`);
-        p.outro('');
+        p.log.success('Feature knowledge bases disabled in every project');
+        p.log.info('Existing knowledge bases preserved. Write-back skipped while disabled.');
     }
+    p.outro('');
 }
 //# sourceMappingURL=toggle.js.map

package/dist/cli/commands/learning.js

@@ -4,8 +4,7 @@ import * as path from 'path';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
 import { getLearningDir, getLearningTuningConfigPath, getDecisionsLogPath, getDecisionsLockDir, } from '../../core/project-paths.js';
-import { updateFeature, isFeatureEnabled } from '../../core/feature-config.js';
-import { syncManifestFeature } from '../../core/manifest.js';
+import { readMachineFeature, writeMachineFeature } from '../../core/feature-switch.js';
 import { getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
 import { getGitRoot } from '../../core/git.js';
 import { sweepLegacyDreamMarkers, drainLearningQueue } from '../../core/learning-queue-cleanup.js';
@@ -15,8 +14,8 @@ import { readObservations, warnIfInvalid, } from '../../core/observation-io.js';
 // ---------------------------------------------------------------------------
 function printUsage() {
     p.intro(color.bgCyan(color.black(' Learning ')));
-    p.note(`${color.cyan('devflow learning --enable')}      Enable learning (decision + pitfall detection)\n` +
-        `${color.cyan('devflow learning --disable')}     Disable learning (drains queue)\n` +
+    p.note(`${color.cyan('devflow learning --enable')}      Enable learning in every project\n` +
+        `${color.cyan('devflow learning --disable')}     Disable learning in every project (drains this project's queue)\n` +
         `${color.cyan('devflow learning --status')}      Show learning status\n` +
         `${color.cyan('devflow learning --list')}        Show all observations\n` +
         `${color.cyan('devflow learning --configure')}   Configuration wizard\n` +
@@ -37,13 +36,16 @@ async function requireGitRoot(actionSuffix) {
     return gitRoot;
 }
 async function handleStatus() {
+    // D-FEATURES-MACHINE-WIDE: the one switch is the manifest's, so the state is
+    // the same from every directory; only the observation counts are per-project.
+    const enabled = await readMachineFeature(getDevFlowDirectory(), 'learning');
+    const stateLine = `Learning: ${enabled ? 'enabled' : 'disabled'}`;
     const gitRoot = await getGitRoot();
     if (!gitRoot) {
-        p.log.info('Learning: disabled (not in a git project)');
+        p.log.info(`${stateLine}\nObservations: not in a git project`);
         return;
     }
     const logPath = getDecisionsLogPath(gitRoot);
-    const enabled = await isFeatureEnabled(gitRoot, 'learning');
     const { observations, invalidCount } = await readObservations(logPath);
     const decisionObs = observations.filter(o => o.type === 'decision' || o.type === 'pitfall');
     const decisions = observations.filter(o => o.type === 'decision');
@@ -52,7 +54,7 @@ async function handleStatus() {
     const ready = decisionObs.filter(o => o.status === 'ready');
     const observing = decisionObs.filter(o => o.status === 'observing');
     const deprecated = decisionObs.filter(o => o.status === 'deprecated');
-    const lines = [`Learning: ${enabled ? 'enabled' : 'disabled'}`];
+    const lines = [stateLine];
     if (decisionObs.length === 0) {
         lines.push('Observations: none');
     }
@@ -235,32 +237,37 @@ async function handleClear() {
     await drainLearningQueue(gitRoot);
     p.log.success('Decisions log cleared.');
 }
-async function handleEnable() {
-    const gitRoot = await requireGitRoot('configuration not updated');
-    if (!gitRoot)
+/**
+ * `--enable` / `--disable`: the machine-wide switch (D-FEATURES-MACHINE-WIDE),
+ * converged exactly as `devflow init --learning / --no-learning` converges it —
+ * the manifest value, and on disable a drained queue in the current project.
+ * Never requires a git root: the switch is not a per-project setting.
+ */
+async function handleToggle(enabled) {
+    const recorded = await writeMachineFeature(getDevFlowDirectory(), 'learning', enabled);
+    if (!recorded.ok) {
+        p.log.error(`Devflow is not installed on this machine — run ${color.cyan('devflow init')} first`);
+        process.exitCode = 1;
         return;
-    await updateFeature(gitRoot, 'learning', true);
-    await syncManifestFeature(getDevFlowDirectory(), 'learning', true);
-    p.log.success('Learning enabled — configuration updated');
-    p.log.info(color.dim('Architectural decisions and pitfalls will be detected from your sessions'));
-}
-async function handleDisable() {
-    const gitRoot = await requireGitRoot('configuration not updated');
-    if (!gitRoot)
+    }
+    if (enabled) {
+        p.log.success('Learning enabled in every project');
+        p.log.info(color.dim('Architectural decisions and pitfalls will be detected from your sessions'));
         return;
-    await updateFeature(gitRoot, 'learning', false);
-    // Drain the learning (decisions-detection) queue so stale turns don't process
-    // on re-enable — mirrors memory.ts's drain-on-disable behavior for the
-    // sibling memory queue. Unconditional: a mid-run Learning agent whose claimed
+    }
+    // Drain the current project's learning (decisions-detection) queue so stale
+    // turns don't process on re-enable. A mid-run Learning agent whose claimed
     // batch vanishes aborts without changes — the desired outcome of disabling.
-    await drainLearningQueue(gitRoot);
-    await syncManifestFeature(getDevFlowDirectory(), 'learning', false);
-    p.log.success('Learning disabled — configuration updated');
+    const gitRoot = await getGitRoot();
+    if (gitRoot) {
+        await drainLearningQueue(gitRoot);
+    }
+    p.log.success('Learning disabled in every project');
 }
 export const learningCommand = new Command('learning')
-    .description('Enable or disable learning (decision/pitfall detection + knowledge base)')
-    .option('--enable', 'Enable learning')
-    .option('--disable', 'Disable learning')
+    .description('Enable or disable learning (decision/pitfall detection) in every project')
+    .option('--enable', 'Enable learning in every project')
+    .option('--disable', 'Disable learning in every project')
     .option('--status', 'Show learning status and observation counts')
     .option('--list', 'Show all decision/pitfall observations sorted by confidence')
     .option('--configure', 'Interactive configuration wizard for learning.json')
@@ -300,11 +307,11 @@ export const learningCommand = new Command('learning')
         return;
     }
     if (options.enable) {
-        await handleEnable();
+        await handleToggle(true);
         return;
     }
     if (options.disable) {
-        await handleDisable();
+        await handleToggle(false);
         return;
     }
 });

package/dist/cli/commands/memory.js

@@ -4,12 +4,11 @@ import * as path from 'path';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
 import { getClaudeDirectory, getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
-import { syncManifestFeature } from '../../core/manifest.js';
 import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
 import { discoverProjectGitRoots } from '../../targets/claude-code/post-install.js';
 import { getGitRoot } from '../../core/git.js';
 import { getMemoryDir, getPendingTurnsPath, getPendingTurnsProcessingPath, } from '../../core/project-paths.js';
-import { updateFeature, isFeatureEnabled } from '../../core/feature-config.js';
+import { readMachineFeature, writeMachineFeature } from '../../core/feature-switch.js';
 /**
  * Map of hook event type → filename marker for the memory hooks.
  * Three hooks total: Stop, SessionStart, PreCompact.
@@ -141,6 +140,39 @@ export function countMemoryHooks(input) {
     }
     return count;
 }
+/**
+ * Converge the memory hooks in a settings JSON string to `enabled`. Pure.
+ *
+ * D-FEATURES-MACHINE-WIDE: the ONE settings transform for the memory feature,
+ * shared by `devflow init` (inside its single settings read-modify-write pass)
+ * and `devflow memory --enable/--disable`, so the two controls of the same
+ * machine-wide switch leave settings.json byte-for-byte alike. Always
+ * remove-then-add, which also upgrades an older hook format (e.g. `.sh` →
+ * `run-hook`) in place.
+ *
+ * Stop-array ordering (AC-C2): memory-worker is appended after whatever the
+ * Stop array already holds, so it lands after capture-turn as long as the
+ * capture hooks are registered first — init registers them earlier in the same
+ * pass, and on a standalone toggle they are already present.
+ */
+export function convergeMemoryHooks(settingsJson, enabled, devflowDir) {
+    const cleaned = removeMemoryHooks(settingsJson);
+    return enabled ? addMemoryHooks(cleaned, devflowDir) : cleaned;
+}
+/**
+ * Drain a project's pending memory queue (and a claimed batch) so stale turns
+ * are not processed when memory is next switched on. Shared by `devflow init
+ * --no-memory` and `devflow memory --disable`. ENOENT-tolerant; any other
+ * error propagates to the command boundary, like drainLearningQueue.
+ */
+export async function drainMemoryQueue(projectRoot) {
+    const ignoreMissing = (e) => { if (e.code !== 'ENOENT')
+        throw e; };
+    await Promise.all([
+        fs.unlink(getPendingTurnsPath(projectRoot)).catch(ignoreMissing),
+        fs.unlink(getPendingTurnsProcessingPath(projectRoot)).catch(ignoreMissing),
+    ]);
+}
 /**
  * Returns true if the given project root contains a `.devflow/memory/` directory.
  * Treats unexpected errors (e.g. EACCES) as absent to avoid false positives.
@@ -195,16 +227,16 @@ export async function cleanQueueFiles(projectPaths) {
 }
 export const memoryCommand = new Command('memory')
     .description('Enable, disable, or clean up working memory (session context preservation)')
-    .option('--enable', 'Enable working memory')
-    .option('--disable', 'Disable working memory')
+    .option('--enable', 'Enable working memory in every project')
+    .option('--disable', 'Disable working memory in every project')
     .option('--status', 'Show current state')
     .option('--clear', 'Clean up queue files from projects')
     .action(async (options) => {
     const hasFlag = options.enable || options.disable || options.status || options.clear;
     if (!hasFlag) {
         p.intro(color.bgCyan(color.white(' Working Memory ')));
-        p.note(`${color.cyan('devflow memory --enable')}   Add memory hooks\n` +
-            `${color.cyan('devflow memory --disable')}  Remove memory hooks\n` +
+        p.note(`${color.cyan('devflow memory --enable')}   Enable working memory (every project)\n` +
+            `${color.cyan('devflow memory --disable')}  Disable working memory (every project)\n` +
             `${color.cyan('devflow memory --status')}   Check current state\n` +
             `${color.cyan('devflow memory --clear')}    Clean up queue files`, 'Usage');
         p.outro(color.dim('Memory hooks provide automatic session context preservation'));
@@ -260,90 +292,68 @@ export const memoryCommand = new Command('memory')
             : 'No queue files found to clean');
         return;
     }
-    const claudeDir = getClaudeDirectory();
-    const settingsPath = path.join(claudeDir, 'settings.json');
+    const settingsPath = path.join(getClaudeDirectory(), 'settings.json');
+    const devflowDir = getDevFlowDirectory();
     let settingsContent;
     try {
         settingsContent = await fs.readFile(settingsPath, 'utf-8');
     }
     catch {
-        if (options.status) {
-            p.log.info('Working memory: disabled (no settings.json found)');
-            return;
-        }
-        // Create minimal settings.json
         settingsContent = '{}';
     }
-    // Resolve current project root for feature config
-    const gitRoot = await getGitRoot();
     if (options.status) {
-        if (!gitRoot) {
-            p.log.info(`Working memory: ${color.dim('disabled')} (not in a git project)`);
-            return;
-        }
+        // D-FEATURES-MACHINE-WIDE: one switch, the manifest's. The hook count is
+        // reported beside it because the hooks are how that switch takes effect.
+        const enabled = await readMachineFeature(devflowDir, 'memory');
         const count = countMemoryHooks(settingsContent);
         const total = Object.keys(MEMORY_HOOK_CONFIG).length;
-        // Also check feature config: hooks may be registered but feature toggled off
-        const featureEnabled = await isFeatureEnabled(gitRoot, 'memory');
-        if (count === total && featureEnabled) {
+        if (enabled && count === total) {
             p.log.info(`Working memory: ${color.green('enabled')} (${total}/${total} hooks)`);
         }
-        else if (count === 0 || !featureEnabled) {
+        else if (!enabled) {
             p.log.info(`Working memory: ${color.dim('disabled')}`);
         }
         else {
-            p.log.info(`Working memory: ${color.yellow(`partial (${count}/${total} hooks)`)} — run --enable to fix`);
+            p.log.info(`Working memory: ${color.yellow(`enabled, but ${count}/${total} hooks registered`)} — ` +
+                `run ${color.cyan('devflow memory --enable')} to fix`);
         }
         return;
     }
-    const devflowDir = getDevFlowDirectory();
-    if (options.enable) {
-        // D: --enable both installs hooks AND writes feature config, while --disable only
-        // writes feature config. This asymmetry is intentional: capture hooks are shared
-        // across features (memory, learning, decisions) and must never be removed by a
-        // single-feature disable. --enable must still install them on first use.
-        const alreadyHasHooks = hasMemoryHooks(settingsContent);
-        const alreadyEnabled = alreadyHasHooks && (gitRoot ? await isFeatureEnabled(gitRoot, 'memory') : false);
-        if (alreadyEnabled) {
-            p.log.info('Working memory already enabled');
-        }
-        else if (alreadyHasHooks) {
-            // Hooks are registered but config has memory:false — re-enable via config
-            p.log.success('Working memory enabled — configuration updated');
-            p.log.info(color.dim('Session context will be automatically preserved across conversations'));
-        }
-        else {
-            const updated = addMemoryHooks(settingsContent, devflowDir);
-            await writeFileAtomicExclusive(settingsPath, updated);
-            p.log.success('Working memory enabled — hooks registered');
-            p.log.info(color.dim('Session context will be automatically preserved across conversations'));
-        }
-        // Update config to enable memory feature
-        if (gitRoot) {
-            await updateFeature(gitRoot, 'memory', true);
-        }
-        await syncManifestFeature(getDevFlowDirectory(), 'memory', true);
+    // --enable / --disable: the machine-wide switch, converged exactly as
+    // `devflow init --memory / --no-memory` converges it (D-FEATURES-MACHINE-WIDE).
+    // The settings transform runs FIRST: it is the step that can reject its
+    // input (malformed JSON), and the switch must not be recorded unless the
+    // hooks that enact it can follow.
+    const enabled = options.enable === true;
+    let converged;
+    try {
+        converged = convergeMemoryHooks(settingsContent, enabled, devflowDir);
+    }
+    catch (err) {
+        p.log.error(`Could not update ${settingsPath}: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
         return;
     }
-    if (options.disable) {
-        // Hooks remain registered (shared with other features).
-        // Disable by writing memory: false to config only — hooks are not removed.
-        if (gitRoot) {
-            await updateFeature(gitRoot, 'memory', false);
-            // Drain orphaned queue files so stale turns don't process on re-enable
-            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; }),
-            ]);
-            await syncManifestFeature(getDevFlowDirectory(), 'memory', false);
-            p.log.success('Working memory disabled — configuration updated');
-        }
-        else {
-            p.log.warn('Could not resolve git root — configuration not updated');
-        }
+    const recorded = await writeMachineFeature(devflowDir, 'memory', enabled);
+    if (!recorded.ok) {
+        p.log.error(`Devflow is not installed on this machine — run ${color.cyan('devflow init')} first`);
+        process.exitCode = 1;
         return;
     }
+    if (converged !== settingsContent) {
+        await writeFileAtomicExclusive(settingsPath, converged);
+    }
+    if (enabled) {
+        p.log.success('Working memory enabled in every project');
+        p.log.info(color.dim('Session context will be automatically preserved across conversations'));
+        return;
+    }
+    // Drain the current project's queue, as init does. Outside a git project
+    // there is no project queue to drain, and the switch itself still applies.
+    const gitRoot = await getGitRoot();
+    if (gitRoot) {
+        await drainMemoryQueue(gitRoot);
+    }
+    p.log.success('Working memory disabled in every project');
 });
 //# sourceMappingURL=memory.js.map