devflow-kit 2.4.0 → 3.0.0

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

@@ -0,0 +1,200 @@
+/**
+ * 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 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, skillName = SKILL_REFS_SKILL_NAME) {
+    const lines = [];
+    if (report.overlaidRefs.length > 0) {
+        lines.push({
+            level: 'info',
+            message: `Installed ${report.overlaidRefs.length} generated skill reference(s) for ` +
+                prefixSkillName(skillName),
+        });
+    }
+    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 install has no other visible trace of:
+ *
+ *   - WHICH provider is the machine default. The sentinel is a dotfile and every
+ *     provider's mechanics are installed (D-INSTALL-ALL-PROVIDERS), so nothing on
+ *     disk says which one the machine selected. `(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 this run moved: references written or pruned, and the Tracker agent
+ *     when this run wrote 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 (a repository can opt out)')
+    .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-NARROW-ONLY (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, plus the repository's narrowing when a repo layer narrows it.
  */
 import { promises as fs } from 'fs';
 import * as path from 'path';
@@ -9,8 +13,8 @@ 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 { loadSettingsModule, narrowedSwitchLabel, personalConfigTrackedWarning } from '../../../core/evidence-policy.js';
 import { getFeaturesDir } from '../../../core/project-paths.js';
 async function getWorktreePath() {
     return (await getGitRoot()) ?? process.cwd();
@@ -39,46 +43,40 @@ 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')}`);
+        const settingsModule = loadSettingsModule();
+        const narrowed = enabled ? narrowedSwitchLabel(settingsModule, { dir: process.cwd() }, 'knowledge') : null;
+        if (narrowed !== null)
+            p.log.info(`Effective here: ${color.yellow(narrowed)}`);
+        const trackedWarning = personalConfigTrackedWarning(settingsModule, { dir: process.cwd() });
+        if (trackedWarning !== null)
+            p.log.warn(trackedWarning);
+        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 (a repository can opt out)');
+        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,10 +4,10 @@ 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 { loadSettingsModule, narrowedSwitchLabel, personalConfigTrackedWarning } from '../../core/evidence-policy.js';
 import { getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
-import { getGitRoot } from '../../core/git.js';
+import { getLedgerRoot } from '../../core/ledger-root.js';
 import { sweepLegacyDreamMarkers, drainLearningQueue } from '../../core/learning-queue-cleanup.js';
 import { readObservations, warnIfInvalid, } from '../../core/observation-io.js';
 // ---------------------------------------------------------------------------
@@ -15,8 +15,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 (a repository can opt out)\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` +
@@ -25,25 +25,39 @@ function printUsage() {
     p.outro(color.dim('Detects architectural decisions and known pitfalls from your sessions'));
 }
 /**
- * Resolve the git root for a state-mutating subcommand, warning and
+ * Resolve the ledger root for a state-mutating subcommand, warning and
  * returning null if the caller isn't inside a git project. `actionSuffix`
  * completes "Could not resolve git root — {actionSuffix}".
+ *
+ * D-LEDGER-MAIN-WORKTREE: every subcommand here resolves the ledger with
+ * getLedgerRoot — the hooks' DF_LEDGER_ROOT rule — so in a linked worktree it
+ * reads, clears and drains the main checkout's ledger the hooks write.
  */
-async function requireGitRoot(actionSuffix) {
-    const gitRoot = await getGitRoot();
-    if (!gitRoot) {
+async function requireLedgerRoot(actionSuffix) {
+    const ledgerRoot = await getLedgerRoot();
+    if (!ledgerRoot) {
         p.log.warn(`Could not resolve git root — ${actionSuffix}`);
     }
-    return gitRoot;
+    return ledgerRoot;
 }
 async function handleStatus() {
-    const gitRoot = await getGitRoot();
-    if (!gitRoot) {
-        p.log.info('Learning: disabled (not in a git project)');
+    // D-FEATURES-NARROW-ONLY: the machine switch is the manifest's and reads the
+    // same from every directory; a repository layer can only narrow it, and adds a
+    // line only when it does. The observation counts are per-project.
+    const enabled = await readMachineFeature(getDevFlowDirectory(), 'learning');
+    const settingsModule = loadSettingsModule();
+    const narrowed = enabled ? narrowedSwitchLabel(settingsModule, { dir: process.cwd() }, 'learning') : null;
+    const stateLine = `Learning: ${enabled ? 'enabled' : 'disabled'}`
+        + (narrowed === null ? '' : `\nEffective here: ${narrowed}`);
+    const trackedWarning = personalConfigTrackedWarning(settingsModule, { dir: process.cwd() });
+    if (trackedWarning !== null)
+        p.log.warn(trackedWarning);
+    const ledgerRoot = await getLedgerRoot();
+    if (!ledgerRoot) {
+        p.log.info(`${stateLine}\nObservations: not in a git project`);
         return;
     }
-    const logPath = getDecisionsLogPath(gitRoot);
-    const enabled = await isFeatureEnabled(gitRoot, 'learning');
+    const logPath = getDecisionsLogPath(ledgerRoot);
     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 +66,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');
     }
@@ -65,12 +79,12 @@ async function handleStatus() {
     warnIfInvalid(invalidCount);
 }
 async function handleList() {
-    // Resolve the log from the git root (matches --status, --clear, --reset,
-    // --disable) so `--list` run from a subdirectory finds the real log
-    // instead of a nonexistent one under process.cwd(). Falls back to cwd
-    // when not in a git project, preserving the prior behavior for that case.
-    const gitRoot = await getGitRoot();
-    const logPath = getDecisionsLogPath(gitRoot ?? process.cwd());
+    // Resolve the log from the ledger root (matches --status, --clear, --reset,
+    // --disable) so `--list` run from a subdirectory or a linked worktree finds
+    // the real log instead of a nonexistent one under process.cwd(). Falls back
+    // to cwd when not in a git project, preserving the prior behavior for that case.
+    const ledgerRoot = await getLedgerRoot();
+    const logPath = getDecisionsLogPath(ledgerRoot ?? process.cwd());
     let logExists = true;
     try {
         await fs.access(logPath);
@@ -148,19 +162,22 @@ async function handleConfigure() {
         p.log.success(`Global config written to ${color.dim(path.join(globalDir, 'learning.json'))}`);
     }
     else {
-        const learningDir = getLearningDir(process.cwd());
-        await fs.mkdir(learningDir, { recursive: true });
-        const projectConfigPath = getLearningTuningConfigPath(process.cwd());
+        // D-LEDGER-MAIN-WORKTREE: session-start-context reads the project tuning config
+        // from the ledger ($LEDGER_ROOT/.devflow/learning/), so write it there — the
+        // main checkout in a linked worktree; the current directory outside git.
+        const projectRoot = (await getLedgerRoot()) ?? process.cwd();
+        await fs.mkdir(getLearningDir(projectRoot), { recursive: true });
+        const projectConfigPath = getLearningTuningConfigPath(projectRoot);
         await fs.writeFile(projectConfigPath, configJson, 'utf-8');
         p.log.success(`Project config written to ${color.dim(projectConfigPath)}`);
     }
     p.outro(color.green('Configuration saved.'));
 }
 async function handleReset() {
-    const gitRoot = await requireGitRoot('reset not performed');
-    if (!gitRoot)
+    const ledgerRoot = await requireLedgerRoot('reset not performed');
+    if (!ledgerRoot)
         return;
-    const lockDir = getDecisionsLockDir(gitRoot);
+    const lockDir = getDecisionsLockDir(ledgerRoot);
     // Ensure the parent directory exists so a second reset (after .devflow/learning/
     // was already removed) does not fail with ENOENT and emit a false contention error.
     await fs.mkdir(path.dirname(lockDir), { recursive: true });
@@ -187,13 +204,13 @@ async function handleReset() {
         // Remove the entire learning directory (contains queue files, content files,
         // ledger, and tuning config). Single-dir semantics: all learning state lives here.
         try {
-            await fs.rm(getLearningDir(gitRoot), { recursive: true, force: true });
+            await fs.rm(getLearningDir(ledgerRoot), { recursive: true, force: true });
         }
         catch { /* best effort */ }
         // Clean legacy dream marker-pipeline stamps from old installs.
         // Best-effort: sweeps the now-absent dir silently (ENOENT-tolerant).
         try {
-            await sweepLegacyDreamMarkers(getLearningDir(gitRoot));
+            await sweepLegacyDreamMarkers(getLearningDir(ledgerRoot));
         }
         catch { /* best effort */ }
         p.log.success('Reset complete — removed .devflow/learning/ state.');
@@ -206,10 +223,10 @@ async function handleReset() {
     }
 }
 async function handleClear() {
-    const gitRoot = await requireGitRoot('clear not performed');
-    if (!gitRoot)
+    const ledgerRoot = await requireLedgerRoot('clear not performed');
+    if (!ledgerRoot)
         return;
-    const decisionsLogPath = getDecisionsLogPath(gitRoot);
+    const decisionsLogPath = getDecisionsLogPath(ledgerRoot);
     try {
         await fs.access(decisionsLogPath);
     }
@@ -232,35 +249,40 @@ async function handleClear() {
     // on the next session — mirrors memory.ts's drain-on-disable behavior for
     // the sibling memory queue. A mid-run Learning agent whose claimed batch
     // vanishes aborts without changes — the desired outcome of clearing.
-    await drainLearningQueue(gitRoot);
+    await drainLearningQueue(ledgerRoot);
     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-NARROW-ONLY),
+ * 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 (a repository can opt out)');
+        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 ledgerRoot = await getLedgerRoot();
+    if (ledgerRoot) {
+        await drainLearningQueue(ledgerRoot);
+    }
+    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 (a repository can opt out)')
+    .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 +322,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/legacy-hooks.js

@@ -1,3 +1,4 @@
+import { devflowHookOwner, hasHook, removeHooks, } from '../../targets/claude-code/hooks.js';
 // ─── Dream worker hook cleanup ──────────────────────────────────────────────
 //
 // The spawn-dream-worker SessionStart hook belonged to the retired detached
@@ -6,27 +7,23 @@
 // own. remove/has exist for upgrade cleanup: init and uninstall strip any
 // stale entry left in settings.json by a prior install.
 const SPAWN_DREAM_WORKER_MARKER = 'spawn-dream-worker';
+/**
+ * D-EXACT-HOOK-OWNER: the dream-worker hook is devflow's only when its command
+ * ends in `/scripts/hooks/run-hook spawn-dream-worker` (hooks.ts), under any
+ * directory — the one form it was ever registered in.
+ */
+const isDreamHook = devflowHookOwner([SPAWN_DREAM_WORKER_MARKER]);
 /**
  * Remove the spawn-dream-worker hook from settings JSON.
  * Idempotent — returns unchanged JSON if hook not present.
- * Preserves all other SessionStart hooks (session-start-memory, session-start-context).
+ * Removes the single hook, so the other hooks of its matcher group and every
+ * other SessionStart group (session-start-memory, session-start-context) stay in place.
  */
 export function removeDreamHook(settingsJson) {
     const settings = JSON.parse(settingsJson);
-    if (!settings.hooks?.SessionStart) {
-        return settingsJson;
-    }
-    const before = settings.hooks.SessionStart.length;
-    settings.hooks.SessionStart = settings.hooks.SessionStart.filter((matcher) => !matcher.hooks.some((h) => h.command.includes(SPAWN_DREAM_WORKER_MARKER)));
-    if (settings.hooks.SessionStart.length === before) {
+    if (!removeHooks(settings, 'SessionStart', isDreamHook)) {
         return settingsJson;
     }
-    if (settings.hooks.SessionStart.length === 0) {
-        delete settings.hooks.SessionStart;
-    }
-    if (Object.keys(settings.hooks).length === 0) {
-        delete settings.hooks;
-    }
     return JSON.stringify(settings, null, 2) + '\n';
 }
 /**
@@ -35,6 +32,6 @@ export function removeDreamHook(settingsJson) {
  */
 export function hasDreamHook(input) {
     const settings = typeof input === 'string' ? JSON.parse(input) : input;
-    return settings.hooks?.SessionStart?.some((matcher) => matcher.hooks.some((h) => h.command.includes(SPAWN_DREAM_WORKER_MARKER))) ?? false;
+    return hasHook(settings, 'SessionStart', isDreamHook);
 }
 //# sourceMappingURL=legacy-hooks.js.map