devflow-kit 2.5.0 → 3.0.0

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

@@ -24,9 +24,6 @@ import { prefixSkillName } from '../../core/plugins.js';
  *
  * 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
@@ -34,14 +31,13 @@ import { prefixSkillName } from '../../core/plugins.js';
  *   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) {
+export function formatOverlaySummary(report, 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,
+                prefixSkillName(skillName),
         });
     }
     for (const failure of report.overlayFailures) {
@@ -94,16 +90,15 @@ export function describeOverlayFailureState(state) {
 /**
  * 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:
+ * Two facts the install has no other visible trace of:
  *
- *   - 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.
+ *   - 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.

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

@@ -10,7 +10,7 @@ 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 in every project')
+    .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) => {

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

@@ -1,11 +1,11 @@
 /**
  * Handle the enable/disable/status toggle actions for `devflow knowledge`.
  *
- * D-FEATURES-MACHINE-WIDE (src/core/feature-switch.ts): knowledge write-back is
+ * 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.
+ * reports it, plus the repository's narrowing when a repo layer narrows it.
  */
 import { promises as fs } from 'fs';
 import * as path from 'path';
@@ -14,6 +14,7 @@ import color from 'picocolors';
 import { getGitRoot } from '../../../core/git.js';
 import { getDevFlowDirectory } from '../../../targets/claude-code/claude-paths.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();
@@ -48,6 +49,13 @@ export async function handleToggle(options) {
         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;
@@ -62,7 +70,7 @@ export async function handleToggle(options) {
         return;
     }
     if (enabled) {
-        p.log.success('Feature knowledge bases enabled in every project');
+        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 {

package/dist/cli/commands/learning.js

@@ -5,8 +5,9 @@ import * as p from '@clack/prompts';
 import color from 'picocolors';
 import { getLearningDir, getLearningTuningConfigPath, getDecisionsLogPath, getDecisionsLockDir, } from '../../core/project-paths.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';
 // ---------------------------------------------------------------------------
@@ -14,7 +15,7 @@ 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 in every project\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` +
@@ -24,28 +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() {
-    // 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.
+    // 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 stateLine = `Learning: ${enabled ? 'enabled' : 'disabled'}`;
-    const gitRoot = await getGitRoot();
-    if (!gitRoot) {
+    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 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');
@@ -67,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);
@@ -150,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 });
@@ -189,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.');
@@ -208,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);
     }
@@ -234,11 +249,11 @@ 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.');
 }
 /**
- * `--enable` / `--disable`: the machine-wide switch (D-FEATURES-MACHINE-WIDE),
+ * `--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.
@@ -251,22 +266,22 @@ async function handleToggle(enabled) {
         return;
     }
     if (enabled) {
-        p.log.success('Learning enabled in every project');
+        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;
     }
     // 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.
-    const gitRoot = await getGitRoot();
-    if (gitRoot) {
-        await drainLearningQueue(gitRoot);
+    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) in every project')
-    .option('--enable', 'Enable learning 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')

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

package/dist/cli/commands/memory.js

@@ -4,11 +4,13 @@ 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 { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
+import { writeSettingsFileAtomic } 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 { HOOKS_DIR_SUFFIX, devflowHookOwner, endsWithAny, ensureHook, hasHook, removeHooks, runHookCommand, runHookSuffix, } from '../../targets/claude-code/hooks.js';
 import { readMachineFeature, writeMachineFeature } from '../../core/feature-switch.js';
+import { loadSettingsModule, narrowedSwitchLabel, personalConfigTrackedWarning } from '../../core/evidence-policy.js';
 /**
  * Map of hook event type → filename marker for the memory hooks.
  * Three hooks total: Stop, SessionStart, PreCompact.
@@ -18,10 +20,11 @@ import { readMachineFeature, writeMachineFeature } from '../../core/feature-swit
  * at the hook-registration level), and decisions detection is a SessionStart-spawned
  * detached worker rather than a SessionEnd hook (see legacy-hooks.ts).
  *
- * Stop-array ordering contract: memory-worker MUST be registered AFTER capture-turn
- * in the Stop hook array (append-before-spawn — memory-worker's throttle/spawn
- * decision assumes the current turn was already appended by capture-turn earlier
- * in the same Stop event). Enforced by init.ts's registration order, not here.
+ * Stop-event concurrency: Claude Code runs one event's hooks in parallel, so
+ * memory-worker can spawn background-memory-update before capture-turn has
+ * appended this turn's assistant row. The worker tolerates that — a queue that
+ * holds only user rows is left in place and the LLM run skipped
+ * (D-QUEUE-NO-ORPHAN-DELETE) — so nothing here depends on hook order.
  */
 const MEMORY_HOOK_CONFIG = {
     Stop: 'memory-worker',
@@ -29,14 +32,32 @@ const MEMORY_HOOK_CONFIG = {
     PreCompact: 'pre-compact-memory',
 };
 /**
- * Legacy hook filename markers from prior architectures.
- * Used by removeMemoryHooks to clean up hooks from upgrading users.
+ * The command endings of the memory-era hooks earlier releases registered, per
+ * event. Removed by removeMemoryHooks so an upgrade leaves no hook pointing at a
+ * script that no longer exists; never counted as a current memory hook.
+ *
+ * D-EXACT-HOOK-OWNER (hooks.ts): matched as command ENDINGS under any directory —
+ * the v1 (≤ v1.2) direct `.sh` scripts, then the retired `run-hook` markers of the
+ * prompt-capture, learning, decisions, knowledge-refresh, sidecar and dream
+ * pipelines — never as substrings, so a user's hook that mentions one is theirs.
  */
-const LEGACY_HOOK_MARKERS = {
-    UserPromptSubmit: ['prompt-capture-memory', 'sidecar-dispatch', 'dream-dispatch'],
-    Stop: ['stop-update-memory', 'stop-update-learning', 'sidecar-capture', 'dream-capture'],
-    SessionEnd: ['session-end-learning', 'session-end-decisions', 'session-end-knowledge-refresh', 'sidecar-evaluate', 'dream-evaluate'],
+const LEGACY_HOOK_SUFFIXES = {
+    UserPromptSubmit: ['prompt-capture-memory', 'sidecar-dispatch', 'dream-dispatch'].map(runHookSuffix),
+    Stop: [
+        `${HOOKS_DIR_SUFFIX}stop-update-memory.sh`,
+        ...['stop-update-memory', 'stop-update-learning', 'sidecar-capture', 'dream-capture'].map(runHookSuffix),
+    ],
+    SessionStart: [`${HOOKS_DIR_SUFFIX}session-start-memory.sh`],
+    PreCompact: [`${HOOKS_DIR_SUFFIX}pre-compact-memory.sh`],
+    SessionEnd: [
+        'session-end-learning', 'session-end-decisions', 'session-end-knowledge-refresh',
+        'sidecar-evaluate', 'dream-evaluate',
+    ].map(runHookSuffix),
 };
+/** D-EXACT-HOOK-OWNER: the current memory hook for `marker` (hooks.ts). */
+function isMemoryHook(marker) {
+    return devflowHookOwner([marker]);
+}
 /**
  * Add all 3 memory hooks (Stop, SessionStart, PreCompact) to settings JSON.
  * Idempotent — skips hooks that already exist. Returns unchanged JSON if all 3 present.
@@ -46,28 +67,10 @@ export function addMemoryHooks(settingsJson, devflowDir) {
     if (hasMemoryHooks(settings)) {
         return settingsJson;
     }
-    if (!settings.hooks) {
-        settings.hooks = {};
-    }
     for (const [hookType, marker] of Object.entries(MEMORY_HOOK_CONFIG)) {
-        const existing = settings.hooks[hookType] ?? [];
-        const alreadyPresent = existing.some((matcher) => matcher.hooks.some((h) => h.command.includes(marker)));
-        if (!alreadyPresent) {
-            const hookCommand = path.join(devflowDir, 'scripts', 'hooks', 'run-hook') + ` ${marker}`;
-            const newEntry = {
-                hooks: [
-                    {
-                        type: 'command',
-                        command: hookCommand,
-                        timeout: 10,
-                    },
-                ],
-            };
-            if (!settings.hooks[hookType]) {
-                settings.hooks[hookType] = [];
-            }
-            settings.hooks[hookType].push(newEntry);
-        }
+        ensureHook(settings, hookType, isMemoryHook(marker), {
+            hooks: [{ type: 'command', command: runHookCommand(devflowDir, marker), timeout: 10 }],
+        });
     }
     return JSON.stringify(settings, null, 2) + '\n';
 }
@@ -80,36 +83,16 @@ export function addMemoryHooks(settingsJson, devflowDir) {
 export function removeMemoryHooks(input) {
     const settingsJson = typeof input === 'string' ? input : JSON.stringify(input);
     const settings = typeof input === 'string' ? JSON.parse(input) : structuredClone(input);
-    if (!settings.hooks) {
-        return settingsJson;
-    }
+    // Evaluate every removal into a local — never short-circuit (PF-015).
     let changed = false;
     for (const [hookType, marker] of Object.entries(MEMORY_HOOK_CONFIG)) {
-        if (!settings.hooks[hookType]) {
-            continue;
-        }
-        const before = settings.hooks[hookType].length;
-        settings.hooks[hookType] = settings.hooks[hookType].filter((matcher) => !matcher.hooks.some((h) => h.command.includes(marker)));
-        if (settings.hooks[hookType].length !== before) {
-            changed = true;
-        }
-        if (settings.hooks[hookType].length === 0) {
-            delete settings.hooks[hookType];
-        }
-    }
-    // Remove legacy pre-dream hooks from upgrading users
-    for (const [hookType, markers] of Object.entries(LEGACY_HOOK_MARKERS)) {
-        if (!settings.hooks[hookType])
-            continue;
-        const before = settings.hooks[hookType].length;
-        settings.hooks[hookType] = settings.hooks[hookType].filter((matcher) => !matcher.hooks.some((h) => markers.some((m) => h.command.includes(m))));
-        if (settings.hooks[hookType].length !== before)
-            changed = true;
-        if (settings.hooks[hookType].length === 0)
-            delete settings.hooks[hookType];
+        const removed = removeHooks(settings, hookType, isMemoryHook(marker));
+        changed = changed || removed;
     }
-    if (settings.hooks && Object.keys(settings.hooks).length === 0) {
-        delete settings.hooks;
+    // Remove the memory-era hooks of earlier releases from upgrading users
+    for (const [hookType, suffixes] of Object.entries(LEGACY_HOOK_SUFFIXES)) {
+        const removed = removeHooks(settings, hookType, endsWithAny(suffixes));
+        changed = changed || removed;
     }
     if (!changed) {
         return settingsJson;
@@ -128,32 +111,29 @@ export function hasMemoryHooks(input) {
  */
 export function countMemoryHooks(input) {
     const settings = typeof input === 'string' ? JSON.parse(input) : input;
-    if (!settings.hooks) {
-        return 0;
-    }
     let count = 0;
     for (const [hookType, marker] of Object.entries(MEMORY_HOOK_CONFIG)) {
-        const matchers = settings.hooks[hookType] ?? [];
-        if (matchers.some((matcher) => matcher.hooks.some((h) => h.command.includes(marker)))) {
+        if (hasHook(settings, hookType, isMemoryHook(marker)))
             count++;
-        }
     }
     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,
+ * D-FEATURES-NARROW-ONLY: 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.
+ * Stop-array position (AC-C2): memory-worker is appended after whatever the
+ * Stop array already holds, so it lands after capture-turn — init registers the
+ * capture hooks earlier in the same pass, and on a standalone toggle they are
+ * already present. The position keeps settings.json identical across init and
+ * the toggle; it sequences nothing at run time, where the Stop hooks run in
+ * parallel.
  */
 export function convergeMemoryHooks(settingsJson, enabled, devflowDir) {
     const cleaned = removeMemoryHooks(settingsJson);
@@ -227,7 +207,7 @@ 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 in every project')
+    .option('--enable', 'Enable working memory in every project (a repository can opt out)')
     .option('--disable', 'Disable working memory in every project')
     .option('--status', 'Show current state')
     .option('--clear', 'Clean up queue files from projects')
@@ -235,7 +215,7 @@ export const memoryCommand = new Command('memory')
     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')}   Enable working memory (every project)\n` +
+        p.note(`${color.cyan('devflow memory --enable')}   Enable working memory (every project; a repository can opt out)\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');
@@ -245,7 +225,7 @@ export const memoryCommand = new Command('memory')
     if (options.clear) {
         p.intro(color.bgCyan(color.white(' Memory Cleanup ')));
         // Discover current project and all known projects in parallel
-        const [gitRoots, gitRoot] = await Promise.all([discoverProjectGitRoots(), getGitRoot()]);
+        const [gitRoots, gitRoot] = await Promise.all([discoverProjectGitRoots(getClaudeDirectory()), getGitRoot()]);
         const [projectsWithMemory, currentProjectHasMem] = await Promise.all([
             filterProjectsWithMemory(gitRoots),
             gitRoot ? hasMemoryDir(gitRoot) : Promise.resolve(false),
@@ -302,8 +282,10 @@ export const memoryCommand = new Command('memory')
         settingsContent = '{}';
     }
     if (options.status) {
-        // 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.
+        // D-FEATURES-NARROW-ONLY: the machine switch, the manifest's, is reported
+        // first. The hook count is reported beside it because the hooks are how that
+        // switch takes effect. A repository layer can only narrow it, and says so on
+        // a line of its own — only when it does, so the output is otherwise unchanged.
         const enabled = await readMachineFeature(devflowDir, 'memory');
         const count = countMemoryHooks(settingsContent);
         const total = Object.keys(MEMORY_HOOK_CONFIG).length;
@@ -317,10 +299,17 @@ export const memoryCommand = new Command('memory')
             p.log.info(`Working memory: ${color.yellow(`enabled, but ${count}/${total} hooks registered`)} — ` +
                 `run ${color.cyan('devflow memory --enable')} to fix`);
         }
+        const settingsModule = loadSettingsModule();
+        const narrowed = enabled ? narrowedSwitchLabel(settingsModule, { dir: process.cwd() }, 'memory') : 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);
         return;
     }
     // --enable / --disable: the machine-wide switch, converged exactly as
-    // `devflow init --memory / --no-memory` converges it (D-FEATURES-MACHINE-WIDE).
+    // `devflow init --memory / --no-memory` converges it (D-FEATURES-NARROW-ONLY).
     // 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.
@@ -341,10 +330,10 @@ export const memoryCommand = new Command('memory')
         return;
     }
     if (converged !== settingsContent) {
-        await writeFileAtomicExclusive(settingsPath, converged);
+        await writeSettingsFileAtomic(settingsPath, converged);
     }
     if (enabled) {
-        p.log.success('Working memory enabled in every project');
+        p.log.success('Working memory enabled in every project (a repository can opt out)');
         p.log.info(color.dim('Session context will be automatically preserved across conversations'));
         return;
     }