devflow-kit 3.5.0 → 3.7.0

package/dist/cli/commands/gates.js

@@ -0,0 +1,276 @@
+/**
+ * devflow gates — Show or set the machine's default gate level.
+ *
+ * The gate level is one of `full`, `standard` or `lean`. `--set` writes the MACHINE
+ * default, `features.gateLevel` in `~/.devflow/manifest.json`, and nothing else: not
+ * the repository's `project.json`, not the personal `.devflow/config.json` (no
+ * command writes that key), and no sentinel, re-arm or install step. `--status` shows
+ * the level that applies in the current directory, which layer decided it and what
+ * the machine records; it writes nothing.
+ *
+ * Three parts, so no business logic throws or prints:
+ *   gatherGateStatus   resolves the settings ONCE and reads the manifest raw, and
+ *                      returns a {@link GateStatus} that is a discriminated union
+ *   renderGateStatus   pure: one {@link GateStatus} to lines and warnings
+ *   gatesCommand       the thin shell: parse, call, print, set the exit code
+ *
+ * No code here chooses a level from a task or a diff: the level comes from the
+ * resolver (personal key, machine key, default) or from the word typed after `--set`.
+ */
+import { Command } from 'commander';
+import * as path from 'path';
+import * as p from '@clack/prompts';
+import color from 'picocolors';
+import { DEFAULT_GATE_LEVEL, GATE_LEVELS, machineGateLevel, parseGateLevel, readGateManifest, writeMachineGateLevel, } from '../../core/gate-level.js';
+import { describeEchoedValue } from '../../core/echo-value.js';
+import { loadSettingsModule, settingsSourceFile, trackedConfigWarning, } from '../../core/evidence-policy.js';
+import { getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
+// ── Wording ────────────────────────────────────────────────────────────────────
+/**
+ * What each level means, in one line. Each line says what the word stands for and
+ * not what a command does with it.
+ */
+export const GATE_LEVEL_MEANINGS = Object.freeze({
+    full: 'the most checking; any value that is not a level also reads as full',
+    standard: 'the default when no level is set',
+    lean: 'the least checking',
+});
+/** What reads the level today; each later reader updates this text. */
+export const GATE_LEVEL_EFFECT = '/code-review and /plan read the level: standard and lean run fewer review focuses and fewer planning agents. Other commands read it once issue #480 lands.';
+const MACHINE_MANIFEST_NAME = 'manifest.json';
+const MACHINE_INVALID_LINE = `invalid (${MACHINE_MANIFEST_NAME}; reads as full)`;
+const VALID_LEVELS = GATE_LEVELS.join(', ');
+const VALID_LEVELS_OR = `${GATE_LEVELS.slice(0, -1).join(', ')}, or ${GATE_LEVELS[GATE_LEVELS.length - 1]}`;
+/** The resolved settings, or null when the resolver is unusable or throws despite its contract. */
+function resolveOnce(module, dir) {
+    try {
+        return module.resolveSettings({ dir });
+    }
+    catch {
+        return null;
+    }
+}
+function manifestState(read) {
+    switch (read.kind) {
+        case 'absent': return 'absent';
+        case 'object': return 'readable';
+        case 'corrupt':
+        case 'rejected': return 'unreadable';
+        default: {
+            const exhaustive = read;
+            return exhaustive;
+        }
+    }
+}
+/** Why a fail-closed result failed, or null when the resolver names no reason. */
+function failClosedReason(settings) {
+    return settings.unreadable === null ? null : `${settingsSourceFile(settings.unreadable)} is unreadable`;
+}
+/**
+ * Gather one {@link GateStatus}. Never throws, never writes.
+ *
+ * The settings resolve ONCE, and that one result feeds the level, the machine value
+ * and the tracked-config warning. The manifest is read with the gate reader, never
+ * with `readManifest()`, which heal-writes and returns null for a manifest it
+ * rejects: a read-only status must do neither. The manifest is read twice, once by
+ * the gate reader here and once by the resolver; a write between the two reads can
+ * mix two versions, which is acceptable because the result is display only and no
+ * action follows it.
+ */
+export async function gatherGateStatus(deps) {
+    const manifestPath = path.join(deps.devflowDir, MACHINE_MANIFEST_NAME);
+    const read = await deps.readManifest(deps.devflowDir);
+    const base = { manifest: manifestState(read), manifestPath };
+    // The TypeScript reader's machine value, for a result that carries none of its own.
+    const stored = read.kind === 'object' || read.kind === 'rejected' ? machineGateLevel(read.raw) : null;
+    const loaded = deps.loadSettings();
+    const settings = loaded.ok ? resolveOnce(loaded.value, deps.dir) : null;
+    if (settings === null) {
+        return { ...base, kind: 'unloadable', machine: stored };
+    }
+    const trackedWarning = trackedConfigWarning(settings);
+    if (!settings.ok || settings.gateLevelSource === null) {
+        // Only a result that names an unreadable file carries the manifest's value; a
+        // fail-closed result without one (git did not answer) never read the manifest.
+        const machine = settings.unreadable !== null ? settings.gateLevelMachine : stored;
+        return { ...base, kind: 'fail-closed', reason: failClosedReason(settings), machine, trackedWarning };
+    }
+    return {
+        ...base,
+        kind: 'resolved',
+        level: settings.gateLevel,
+        source: settings.gateLevelSource,
+        invalid: settings.gateLevelInvalid,
+        machine: settings.gateLevelMachine,
+        trackedWarning,
+    };
+}
+/** The machine line: `none` when the manifest records no level or cannot be read (its own warning says which). */
+function machineLine(machine) {
+    if (machine === 'invalid')
+        return `Machine:   ${MACHINE_INVALID_LINE}`;
+    if (machine === null)
+        return 'Machine:   none';
+    return `Machine:   ${machine}`;
+}
+function manifestWarning(status) {
+    if (status.manifest !== 'unreadable')
+        return null;
+    return `Manifest at ${status.manifestPath} cannot be read as a manifest; devflow init will replace this file.`;
+}
+/**
+ * Render a {@link GateStatus}. Pure and total over every `kind`.
+ *
+ * A malformed level is reported by the layer that holds it and its state, never by
+ * its value: a raw config value never reaches a terminal.
+ */
+export function renderGateStatus(status) {
+    const warnings = [];
+    const lines = [];
+    switch (status.kind) {
+        case 'resolved': {
+            lines.push(`Effective: ${status.level} (${status.source}${status.invalid ? ', invalid' : ''})`);
+            lines.push(machineLine(status.machine));
+            if (status.invalid && status.source === 'personal') {
+                warnings.push(`gateLevel in ${settingsSourceFile('personal')} is not one of ${VALID_LEVELS}, so ${status.level} is in effect. ` +
+                    'The value is not shown.');
+            }
+            if (status.trackedWarning !== null)
+                warnings.push(status.trackedWarning);
+            break;
+        }
+        case 'fail-closed': {
+            lines.push(`Effective: full (fail-closed: ${status.reason ?? 'reason unknown'})`);
+            lines.push(machineLine(status.machine));
+            if (status.trackedWarning !== null)
+                warnings.push(status.trackedWarning);
+            break;
+        }
+        case 'unloadable': {
+            lines.push('Effective: level unknown');
+            lines.push(machineLine(status.machine));
+            warnings.push('The settings resolver could not be loaded, so the level that applies is unknown.');
+            break;
+        }
+        default: {
+            const exhaustive = status;
+            return exhaustive;
+        }
+    }
+    const fromManifest = manifestWarning(status);
+    if (fromManifest !== null)
+        warnings.push(fromManifest);
+    return { lines, warnings };
+}
+/**
+ * Map the writer's result to a message and an exit code. Pure and total. Every
+ * refusal exits 1 and says nothing was written, except a failed write, which names
+ * the path and the error code.
+ */
+export function describeGateWrite(result, level, manifestPath) {
+    switch (result.kind) {
+        case 'written':
+            return { kind: 'success', message: `Gate level: ${level}`, exitCode: 0 };
+        case 'unchanged':
+            return { kind: 'info', message: `Gate level: ${level} (unchanged)`, exitCode: 0 };
+        case 'not-installed':
+            return { kind: 'error', message: `No manifest found at ${manifestPath}. Run devflow init first.`, exitCode: 1 };
+        case 'unreadable':
+            return {
+                kind: 'error',
+                message: `Manifest at ${result.path} exists but cannot be read; nothing changed. Move it aside, then run devflow init.`,
+                exitCode: 1,
+            };
+        case 'write-failed':
+            return {
+                kind: 'error',
+                message: `Could not write the manifest at ${result.path} (${result.reason}); nothing changed.`,
+                exitCode: 1,
+            };
+        case 'invalid-level':
+            return {
+                kind: 'error',
+                message: `Unknown gate level: "${describeEchoedValue(level)}"; nothing changed. Valid levels: ${VALID_LEVELS}`,
+                exitCode: 1,
+            };
+        default: {
+            const exhaustive = result;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * Write the machine default and describe the result. Never throws. `now` is injected
+ * so a test fixes the `updatedAt` stamp.
+ */
+export async function runGatesSet(devflowDir, level, now = () => new Date().toISOString()) {
+    const result = await writeMachineGateLevel(devflowDir, level, now);
+    return describeGateWrite(result, level, path.join(devflowDir, MACHINE_MANIFEST_NAME));
+}
+function printOutcome(outcome) {
+    switch (outcome.kind) {
+        case 'success':
+            p.log.success(outcome.message);
+            break;
+        case 'info':
+            p.log.info(outcome.message);
+            break;
+        case 'error':
+            p.log.error(outcome.message);
+            break;
+        default: {
+            const exhaustive = outcome.kind;
+            return exhaustive;
+        }
+    }
+}
+function levelsHelp() {
+    const width = Math.max(...GATE_LEVELS.map(level => level.length));
+    return GATE_LEVELS.map(level => `  ${level.padEnd(width)}  ${GATE_LEVEL_MEANINGS[level]}`).join('\n');
+}
+export const gatesCommand = new Command('gates')
+    .description('Show or set the machine\'s default gate level')
+    .option('--status', 'Show the gate level in effect here, which layer decided it, and the machine default')
+    .option('--set <level>', `Set the machine's default gate level: ${VALID_LEVELS_OR}`)
+    .addHelpText('after', `\nGate levels:\n${levelsHelp()}\n\n` +
+    `The default is ${DEFAULT_GATE_LEVEL}. --set writes only the machine default. A personal .devflow/config.json ` +
+    '"gateLevel" overrides it in one repository; no command writes that key.\n' +
+    GATE_LEVEL_EFFECT)
+    .action(async (options) => {
+    const devflowDir = getDevFlowDirectory();
+    if (!options.status && options.set === undefined) {
+        p.intro(color.bgCyan(color.white(' Gates ')));
+        p.note(`${color.cyan('devflow gates --status')}       Show the gate level in effect here and the machine default\n` +
+            `${color.cyan('devflow gates --set <level>')}  Set the machine default\n\n` +
+            `Valid levels:\n${levelsHelp()}`, 'Usage');
+        p.outro(color.dim(GATE_LEVEL_EFFECT));
+        return;
+    }
+    // Validate --set before any I/O, even beside --status: a bad word is rejected,
+    // never repaired, and exits 1 as it does in `devflow tracker` and `devflow compliance`.
+    const parsed = options.set === undefined ? undefined : parseGateLevel(options.set);
+    if (parsed !== undefined && !parsed.ok) {
+        p.log.error(parsed.error);
+        process.exitCode = 1;
+        return;
+    }
+    // --status wins over a valid --set and writes nothing, mirroring `devflow tracker`.
+    // With neither flag the usage printed above, so no --set here means --status alone.
+    if (options.status || parsed === undefined) {
+        const status = await gatherGateStatus({
+            devflowDir,
+            dir: process.cwd(),
+            loadSettings: loadSettingsModule,
+            readManifest: readGateManifest,
+        });
+        const rendered = renderGateStatus(status);
+        p.note(rendered.lines.join('\n'), 'Gate Level Status');
+        for (const warning of rendered.warnings)
+            p.log.warn(warning);
+        return;
+    }
+    const outcome = await runGatesSet(devflowDir, parsed.value);
+    printOutcome(outcome);
+    process.exitCode = outcome.exitCode;
+});
+//# sourceMappingURL=gates.js.map

package/dist/cli/commands/init-seed.js

@@ -27,6 +27,7 @@ export const FEATURE_DEFAULTS = {
     behavior: false,
     compliance: { enabled: false, frameworks: [] },
     tracker: { provider: DEFAULT_TRACKER_PROVIDER },
+    gateLevel: undefined,
 };
 // ── Helpers ───────────────────────────────────────────────────────────────────
 /**
@@ -60,7 +61,11 @@ export function resolveSeedFeatures(manifest) {
     const memory = manifest?.features.memory ?? FEATURE_DEFAULTS.memory;
     const knowledge = manifest?.features.knowledge ?? FEATURE_DEFAULTS.knowledge;
     const learning = manifest?.features.learning ?? FEATURE_DEFAULTS.learning;
-    return { ambient, memory, hud, knowledge, learning, rules, proxy, behavior, compliance, tracker };
+    // The raw stored level, with no default operator: `??` would turn a stored `null`
+    // into the default, and init would then write the default over a value the
+    // fold reads as the strictest level.
+    const gateLevel = manifest?.features.gateLevel;
+    return { ambient, memory, hud, knowledge, learning, rules, proxy, behavior, compliance, tracker, gateLevel };
 }
 /**
  * Resolve the flag record for the init seed.
@@ -318,6 +323,9 @@ export function applyCliToggles(base, toggles) {
         behavior: toggles.behavior ?? base.behavior,
         compliance: toggles.compliance ?? base.compliance,
         tracker: toggles.tracker ?? base.tracker,
+        // No command-line flag names the gate level, so the seed's raw value passes
+        // through. Only `undefined` means "not specified": `null` is a value, not a gap.
+        gateLevel: toggles.gateLevel !== undefined ? toggles.gateLevel : base.gateLevel,
     };
 }
 //# sourceMappingURL=init-seed.js.map

package/dist/cli/commands/init.js

@@ -9,6 +9,7 @@ import { getGitRoot } from '../../core/git.js';
 import { isSameLocation, withoutHomeRoots } from '../../core/same-location.js';
 import { pruneHookLogDirs, MAX_HOOK_LOG_DIRS } from '../../core/hook-log-dirs.js';
 import { getLedgerRoot } from '../../core/ledger-root.js';
+import { describeEchoedValue } from '../../core/echo-value.js';
 import { installViaFileCopy, composeScripts } from '../../targets/claude-code/installer.js';
 import { formatOverlaySummary, formatSkillScopeSummary, formatTrackerAssetSummary, isPluginListUnchanged } from './install-report.js';
 import { convergeTrackerArtifacts } from '../../targets/claude-code/tracker-install.js';
@@ -18,7 +19,7 @@ import { LEGACY_SKILL_NAMES } from '../../targets/claude-code/legacy.js';
 import { detectPlatform, detectShell, getProfilePath, getSafeDeleteInfo, hasSafeDelete } from '../../core/safe-delete.js';
 import { generateSafeDeleteBlock, installToProfile, removeFromProfile, getInstalledVersion, SAFE_DELETE_BLOCK_VERSION } from '../../core/safe-delete-install.js';
 import { convergeAmbientHooks } from './ambient.js';
-import { convergeMemoryHooks, drainMemoryQueue } from './memory.js';
+import { convergeMemoryHooks, drainMemoryQueue, workingMemoryNote } from './memory.js';
 import { addCaptureHooks, removeCaptureHooks } from './capture.js';
 import { removeDreamHook } from './legacy-hooks.js';
 import { addProxyHooks, removeProxyHooks, applyProxyEnv, stripProxyEnv, runProxyPreflight, buildRealPreflightDeps } from './proxy.js';
@@ -45,7 +46,7 @@ import { applyTrackerSentinel, effectiveTrackerServers, parseTrackerId, rearmTra
 import { formatTrackerSummary, shouldRunTrackerStep, runTrackerStep, buildClackTrackerPrompts, } from './tracker-prompts.js';
 import { shouldRunAttributionStep, runAttributionStep, buildClackAttributionPrompts, applyAttributionAnswer, attributionSeedFrom, } from './attribution-prompts.js';
 import { convergeFromManifest } from '../../targets/claude-code/compliance-install.js';
-import { convergeLearningVariants } from '../../targets/claude-code/learning-install.js';
+import { convergeLearningVariants, installedVersionMatches, readRunningVersion } from '../../targets/claude-code/learning-install.js';
 import { auditAndRecordClaudeMd, formatClaudeMdAuditNote, formatClaudeMdAuditUnavailable, } from '../../core/claude-md-audit.js';
 import * as os from 'os';
 // Re-export pure functions for tests (canonical source is post-install.ts)
@@ -507,6 +508,23 @@ export function buildHudOnlyManifest(existing, version, now) {
         updatedAt: now,
     };
 }
+/**
+ * The line `init --hud-only` prints when the version the manifest records is not the
+ * running version, or null when there is nothing to say. Pure.
+ *
+ * `--hud-only` refreshes the scripts under ~/.devflow and leaves the installed
+ * commands and agents alone, so after an upgrade or a downgrade the prompts and the
+ * scripts they call can disagree until a full init. The window is accepted; this
+ * line names it, in either direction, and ends with the remedy. A machine with no
+ * readable manifest records no version, so there is nothing to compare. The recorded
+ * version is hand-editable file content, so it prints through `describeEchoedValue`.
+ */
+export function formatHudOnlySkew(recordedVersion, runningVersion) {
+    if (recordedVersion === null || installedVersionMatches(recordedVersion, runningVersion))
+        return null;
+    return `The installed prompts come from devflow ${describeEchoedValue(recordedVersion)} and this CLI is ${runningVersion ?? 'of unknown version'}. ` +
+        '--hud-only refreshed only the scripts, so run `devflow init` to update the prompts.';
+}
 /**
  * Decide what `init --scope <value>` does now that there is one install scope.
  * Pure — the action performs the exit.
@@ -686,6 +704,9 @@ export const initCommand = new Command('init')
             await writeManifest(devflowDir, buildHudOnlyManifest(existingHudManifest, version, new Date().toISOString()));
         }
         catch { /* non-fatal */ }
+        const hudOnlySkew = formatHudOnlySkew(existingHudManifest?.version ?? null, await readRunningVersion());
+        if (hudOnlySkew !== null)
+            p.log.warn(hudOnlySkew);
         p.log.success('HUD installed');
         p.log.info(`Configure later: ${color.cyan('devflow hud --status')}`);
         p.outro(color.green('HUD-only install complete.'));
@@ -784,7 +805,7 @@ export const initCommand = new Command('init')
             'devflow-explore': 'codebase exploration + knowledge bases',
             'devflow-research': 'multi-type research with synthesis',
             'devflow-release': 'adaptive release with learned config',
-            'devflow-self-review': 'Simplify agent + Scrutinize agent',
+            'devflow-self-review': 'Polish agent + Harden agent',
             'devflow-bug-analysis': 'proactive bug finding, post-pipeline',
             'devflow-typescript': 'TypeScript patterns',
             'devflow-react': 'React patterns',
@@ -935,6 +956,11 @@ export const initCommand = new Command('init')
     // alone, so init carries the prior value through untouched: it stamps the installed agents
     // with it and writes it back to the manifest. Absent stays absent (the default list).
     const trackerServers = seed.features.tracker.servers;
+    // The machine gate level (features.gateLevel) is set by `devflow gates --set` alone, so init
+    // carries the prior value through raw: no default, no narrowing, a stored `null` kept. The
+    // seed holds `undefined` only for an absent key or a --reset seed, and the full manifest
+    // write below then leaves the key out.
+    const gateLevel = seed.features.gateLevel;
     let enabledFlags = { ...seed.flags };
     // viewModeExplicit: true when --reset is passed; signals resolveFinalViewMode to let the
     // seed-time view-mode win over an externally-set value in settings.json.
@@ -1145,12 +1171,7 @@ export const initCommand = new Command('init')
             memoryEnabled = options.memory;
         }
         else {
-            p.note('Preserves session context across /clear, restarts, and context\n' +
-                'compaction. Clear your session at any point and resume right\n' +
-                'where you left off.\n\n' +
-                'Runs a background agent on session stop that consumes additional\n' +
-                'tokens. Consider skipping if token usage is a concern.\n' +
-                'Applies to every project.', 'Working Memory');
+            p.note(workingMemoryNote(), 'Working Memory');
             const memoryChoice = await p.confirm({
                 message: 'Enable working memory? (Recommended)',
                 initialValue: seed.features.memory,
@@ -1967,7 +1988,7 @@ export const initCommand = new Command('init')
         content = addCaptureHooks(cleanedForCapture, devflowDir);
         // Memory hooks — Stop (memory-worker), SessionStart (session-start-memory),
         // PreCompact — through the same transform `devflow memory --enable/--disable`
-        // uses (D-FEATURES-NARROW-ONLY). Learning agent (spawned via
+        // uses (D-FEATURES-NARROW-ONLY). Curate agent (spawned via
         // session-start-context directive) handles decision/pitfall detection.
         // Knowledge is handled in-command via write-through (knowledge_writeback MDS partial).
         content = convergeMemoryHooks(content, memoryEnabled, devflowDir);
@@ -1980,7 +2001,7 @@ export const initCommand = new Command('init')
         content = addContextHook(cleanedForContext, devflowDir);
         // Legacy dream-worker hook cleanup — strip any stale spawn-dream-worker entry
         // left in settings.json by a prior install (session-start-context now spawns
-        // the Learning agent via directive).
+        // the Curate agent via directive).
         content = removeDreamHook(content);
         // Strip Devflow-managed teammateMode ("auto"). User-set values (e.g. "tmux") are preserved.
         content = stripDevflowTeammateModeFromJson(content);
@@ -2324,6 +2345,8 @@ export const initCommand = new Command('init')
             // through parseTrackerId (CLI), the typed wizard select, or the seed, which
             // itself came through normalizeTrackerFeature on read.
             tracker: { provider: trackerProvider, ...(trackerServers !== undefined ? { servers: trackerServers } : {}) },
+            // The prior machine gate level, raw (see where `gateLevel` is read above).
+            ...(gateLevel !== undefined ? { gateLevel } : {}),
         },
         installedAt: existingManifest?.installedAt ?? now,
         updatedAt: now,

package/dist/cli/commands/learning.js

@@ -3,7 +3,7 @@ import { promises as fs } from 'fs';
 import * as path from 'path';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
-import { getLearningDir, getLearningTuningConfigPath, } from '../../core/project-paths.js';
+import { getLearningDir, getCurateTuningConfigPath, } from '../../core/project-paths.js';
 import { loadShippedAgentDefaults } from '../../core/agent-models.js';
 import { readMachineFeature, writeMachineFeature } from '../../core/feature-switch.js';
 import { loadSettingsModule, narrowedSwitchLabel, personalConfigTrackedWarning } from '../../core/evidence-policy.js';
@@ -263,7 +263,7 @@ async function handleRestore(anchor) {
  * The scope choices of `devflow learning --configure`.
  *
  * D-LEARNING-MODEL-PRECEDENCE: the session-start hook takes the first layer that
- * supplies a model — the project file, then a `devflow agents` Learning mapping,
+ * supplies a model — the project file, then a `devflow agents` Curate mapping,
  * then the global file. A global file therefore has no effect for a user who has
  * such a mapping, and its hint says so.
  */
@@ -272,24 +272,24 @@ export const CONFIGURE_SCOPE_OPTIONS = [
     {
         value: 'global',
         label: 'Global',
-        hint: 'All projects (~/.devflow/learning.json); a devflow agents Learning mapping takes precedence over it',
+        hint: 'All projects (~/.devflow/learning.json); a devflow agents Curate mapping takes precedence over it',
     },
 ];
 /** The models `devflow learning --configure` offers, each with what it is good for. */
-const LEARNING_MODEL_CHOICES = [
+const CURATE_MODEL_CHOICES = [
     { value: 'opus', label: 'Opus', note: 'highest quality for detection + curation judgment' },
     { value: 'sonnet', label: 'Sonnet', note: 'good balance of quality and speed' },
     { value: 'haiku', label: 'Haiku', note: 'fastest, lowest cost' },
 ];
 /**
- * D-LEARNING-SHIPPED-ROW: the model offered as "Recommended" is the one the Learning
+ * D-LEARNING-SHIPPED-ROW: the model offered as "Recommended" is the one the Curate
  * agent ships with, the `model:` line of its frontmatter. It is read from there and
  * written nowhere else, so a change of the shipped tier moves the recommendation with
  * it and this list never has to be edited. A shipped model outside the three offered
  * (or none) recommends nothing.
  */
-export function learningModelOptions(shippedModel) {
-    return LEARNING_MODEL_CHOICES.map(choice => ({
+export function curateModelOptions(shippedModel) {
+    return CURATE_MODEL_CHOICES.map(choice => ({
         value: choice.value,
         label: choice.label,
         hint: choice.value === shippedModel
@@ -299,10 +299,10 @@ export function learningModelOptions(shippedModel) {
 }
 async function handleConfigure() {
     p.intro(color.bgCyan(color.black(' Learning Configuration ')));
-    const shippedModel = (await loadShippedAgentDefaults()).learning?.model;
+    const shippedModel = (await loadShippedAgentDefaults()).curate?.model;
     const model = await p.select({
         message: 'Model for decision detection',
-        options: learningModelOptions(shippedModel),
+        options: curateModelOptions(shippedModel),
     });
     if (p.isCancel(model)) {
         p.cancel('Configuration cancelled.');
@@ -341,7 +341,7 @@ async function handleConfigure() {
         // main checkout in a linked worktree; the current directory outside git.
         const projectRoot = (await getLedgerRoot()) ?? process.cwd();
         const learningDir = getLearningDir(projectRoot);
-        const projectConfigPath = getLearningTuningConfigPath(projectRoot);
+        const projectConfigPath = getCurateTuningConfigPath(projectRoot);
         // D-CLI-NO-SYMLINK (core/linked-path.ts): nothing is written through a .devflow,
         // a learning folder or a learning.json that is a symbolic link.
         const linked = await firstSymbolicLink([path.dirname(learningDir), learningDir, projectConfigPath]);
@@ -419,7 +419,7 @@ async function handleClear() {
         process.exitCode = 1;
         return;
     }
-    // A mid-run Learning agent whose claimed batch vanishes stops without further
+    // A mid-run Curate agent whose claimed batch vanishes stops without further
     // writes — the desired outcome of clearing.
     const drain = await drainLearningQueue(ledgerRoot);
     p.log.success(`Cleared ${counted(cleared.value.cleared, 'observation')} no entry uses and kept ${cleared.value.kept} ` +
@@ -480,7 +480,7 @@ async function handleToggle(enabled) {
         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
+    // turns don't process on re-enable. A mid-run Curate agent whose claimed
     // batch vanishes aborts without changes — the desired outcome of disabling.
     const ledgerRoot = await getLedgerRoot();
     if (ledgerRoot) {

package/dist/cli/commands/legacy-hooks.js

@@ -2,7 +2,7 @@ import { devflowHookOwner, hasHook, removeHooks, } from '../../targets/claude-co
 // ─── Dream worker hook cleanup ──────────────────────────────────────────────
 //
 // The spawn-dream-worker SessionStart hook belonged to the retired detached
-// dream worker. Decisions processing runs as the directive-spawned Learning agent
+// dream worker. Decisions processing runs as the directive-spawned Curate agent
 // (session-start-context Section 2), which needs no hook registration of its
 // own. remove/has exist for upgrade cleanup: init and uninstall strip any
 // stale entry left in settings.json by a prior install.

package/dist/cli/commands/memory.js

@@ -56,6 +56,24 @@ const LEGACY_HOOK_SUFFIXES = {
         'sidecar-evaluate', 'dream-evaluate',
     ].map(runHookSuffix),
 };
+/**
+ * The lowest Claude Code the memory worker runs on: the lowest version on which the
+ * worker's write was measured to be limited to its staged file (2026-10-15,
+ * docs/reference/platform-assumptions.md). Below it the worker does not run and logs one
+ * line. `background-memory-update` holds the same value as MEMORY_MIN_PERMISSION_VERSION;
+ * a test holds the two equal.
+ */
+export const MEMORY_MIN_PERMISSION_VERSION = '2.1.269';
+/** The note `devflow init` shows at its working-memory step. */
+export function workingMemoryNote() {
+    return ('Preserves session context across /clear, restarts, and context\n' +
+        'compaction. Clear your session at any point and resume right\n' +
+        'where you left off.\n\n' +
+        'Runs a background agent on session stop that consumes additional\n' +
+        'tokens. Consider skipping if token usage is a concern.\n' +
+        `Needs Claude Code ${MEMORY_MIN_PERMISSION_VERSION} or newer.\n` +
+        'Applies to every project.');
+}
 /** D-EXACT-HOOK-OWNER: the current memory hook for `marker` (hooks.ts). */
 function isMemoryHook(marker) {
     return devflowHookOwner([marker]);