devflow-kit 3.4.0 → 3.6.0

package/dist/core/agent-frontmatter.js

@@ -231,4 +231,105 @@ export function rewriteAgentFrontmatter(content, opts) {
     const changed = newContent !== content;
     return Ok({ content: newContent, changed });
 }
+const WHOLE_SERVER_PREFIX = 'mcp__';
+/** A server name as it appears in a whole-server entry: the charset Claude Code keeps, no `__`. */
+const WHOLE_SERVER_NAME_RE = /^[A-Za-z0-9_-]{1,64}$/;
+/**
+ * True when `tool` is a whole-server allowlist entry: `mcp__` and a server name of
+ * 1-64 characters from `[A-Za-z0-9_-]` with no `__` (D-WHOLE-SERVER-ENTRY).
+ */
+export function isWholeServerTool(tool) {
+    if (!tool.startsWith(WHOLE_SERVER_PREFIX))
+        return false;
+    const name = tool.slice(WHOLE_SERVER_PREFIX.length);
+    return WHOLE_SERVER_NAME_RE.test(name) && !name.includes('__');
+}
+/** The single-line inline form `tools: ["A", "B"]`, within a frontmatter body. */
+const INLINE_TOOLS_RE = /^tools:[ \t]*\[([^\r\n]*)\][ \t]*(?=\r?$)/m;
+function toolItems(inner) {
+    return inner.split(',').filter(item => item.trim() !== '');
+}
+function unquoteTool(item) {
+    return item.trim().replace(/^(["'])(.*)\1$/, '$2');
+}
+/**
+ * Replace the whole-server entries of the first frontmatter block's inline `tools:` line
+ * with `extraTools`, and touch nothing else.
+ *
+ * Idempotent: stamping the same list twice yields the same bytes, and stamping a new list
+ * replaces the previous one rather than adding to it. Every other entry of the line keeps
+ * its original text, and every other byte of the file (other keys, the body, CRLF or LF)
+ * is untouched. An empty `extraTools` removes the stamp.
+ *
+ * Rejects, rather than repairs: an entry that is not a whole-server entry (`invalid-tool`;
+ * it would otherwise reach the frontmatter as free text), a file with no inline
+ * `tools: [...]` line (`no-tools-line`; a block-list `tools:` is not edited) and a file
+ * with no well-formed frontmatter.
+ *
+ * Pure function — no I/O.
+ */
+export function stampAgentTools(content, extraTools) {
+    for (const tool of extraTools) {
+        if (!isWholeServerTool(tool))
+            return Err('invalid-tool');
+    }
+    const parts = parseFrontmatter(content);
+    if (!parts.ok)
+        return Err(parts.error);
+    const { fmBody, openDelim, closeDelim, afterClose, eol } = parts.value;
+    const match = INLINE_TOOLS_RE.exec(fmBody);
+    if (!match)
+        return Err('no-tools-line');
+    const rawItems = toolItems(match[1]);
+    const kept = rawItems.filter(item => !isWholeServerTool(unquoteTool(item)));
+    const stamped = [...new Set(extraTools)].map(tool => `"${tool}"`);
+    // Nothing to remove and nothing to add: the line, whatever its spacing, is already right.
+    if (kept.length === rawItems.length && stamped.length === 0)
+        return Ok({ content, changed: false });
+    // The kept entries keep their own text; only the edges lose the padding that no longer
+    // borders a neighbour, so the appended entries land after `, ` and the line stays one shape.
+    const keptText = kept
+        .map((item, i) => {
+        const lead = i === 0 ? item.trimStart() : item;
+        return i === kept.length - 1 ? lead.trimEnd() : lead;
+    })
+        .join(',');
+    const inner = [keptText, stamped.join(', ')].filter(text => text !== '').join(', ');
+    const line = `tools: [${inner}]`;
+    const newBody = fmBody.slice(0, match.index) + line + fmBody.slice(match.index + match[0].length);
+    const newContent = openDelim + newBody + eol + closeDelim + afterClose;
+    return Ok({ content: newContent, changed: newContent !== content });
+}
+/**
+ * The whole-server entries of the first frontmatter block's inline `tools:` line, in
+ * order. Ok([]) when the line carries none; an error when there is no line to read.
+ * Pure function — no I/O.
+ */
+export function readStampedTools(content) {
+    const parts = parseFrontmatter(content);
+    if (!parts.ok)
+        return Err(parts.error);
+    const match = INLINE_TOOLS_RE.exec(parts.value.fmBody);
+    if (!match)
+        return Err('no-tools-line');
+    return Ok(toolItems(match[1]).map(unquoteTool).filter(isWholeServerTool));
+}
+/**
+ * The text a converge installs for an agent: the variant `source` wearing the whole-server
+ * entries the installed copy carries. The stamp is applied at install and by
+ * `devflow tracker --servers`, never by a converge, so a converge only CARRIES it. Without
+ * the carry, switching an agent between prompt variants would drop its stamp and compare
+ * unequal to the installed copy on every run.
+ *
+ * `source` is returned unchanged when there is nothing safe to carry: either side has no
+ * well-formed inline `tools:` line, or the installed copy carries no entries.
+ * Pure function — no I/O.
+ */
+export function carryStampedTools(source, installed) {
+    const carried = readStampedTools(installed);
+    if (!carried.ok || carried.value.length === 0)
+        return source;
+    const stamped = stampAgentTools(source, carried.value);
+    return stamped.ok ? stamped.value.content : source;
+}
 //# sourceMappingURL=agent-frontmatter.js.map

package/dist/core/agent-models.js

@@ -142,38 +142,56 @@ export function validateWorkerValue(field, value) {
 // Key migration
 // ---------------------------------------------------------------------------
 /**
- * Maps old agent keys (form A slugs) to their canonical replacement keys.
+ * Maps every retired agent key to the live slug that replaces it. Two renames feed it:
  *
- * 13 agents renamed from noun form (coder, reviewer, …) to action-verb form
- * (code, review, …). The canonicalise-agent-keys-v1 migration in migrations.ts
- * calls canonicaliseAgentKeys() to rewrite ~/.devflow/agent-models.json on the
- * user's first init after upgrading.
+ *   - The 2.0.0 action-verb rename (coder, reviewer, …) and the 1.x names that rename
+ *     retired (scrutinizer, simplifier, bug-analyzer).
+ *   - The rename of six agents to the names that state their job (code-fix, code-edit,
+ *     scrutinize, simplify, diagnose, learning).
+ *
+ * SINGLE HOP: every value is a live slug and no value is itself a key. A 1.x name
+ * therefore points straight at its final slug (scrutinizer → harden, never
+ * scrutinizer → scrutinize → harden), so one pass of canonicaliseAgentKeys() lands
+ * every key. The two canonicalise-agent-keys migrations in migrations.ts call it to
+ * rewrite ~/.devflow/agent-models.json; readAgentMapping() calls it on every read.
  *
  * PROTOTYPE SAFETY: Object.create(null) prevents prototype-pollution.
  * Every lookup MUST use Object.hasOwn — never key in LEGACY_AGENT_KEYS or
  * direct bracket access. `--set constructor` would otherwise return a function
  * that flows into path.join (the object-literal lookup on argv trap).
  *
+ * ORDER: entries are declared oldest first. canonicaliseAgentKeys() reads that order
+ * when two keys meet at one slug (scrutinizer and scrutinize both mean harden): the
+ * entry declared later is the more recent name and wins.
+ *
  * DORMANCY: entries here are stored whether or not the key rename has been
  * applied to the file yet. canonicaliseAgentKeys() is idempotent, so
  * double-execution from concurrent sessions is a harmless no-op — the second
  * run finds the file already migrated and makes zero writes.
  */
 export const LEGACY_AGENT_KEYS = Object.assign(Object.create(null), {
-    // Phase 4 — agent-action-verbs rename (old slug → new slug)
+    // 1.x names (noun form), retargeted to the live slug of their final rename.
+    'scrutinizer': 'harden',
+    'simplifier': 'polish',
+    'bug-analyzer': 'debug',
+    // 2.0.0 action-verb rename (old slug → new slug).
     'coder': 'code',
     'designer': 'design',
     'evaluator': 'evaluate',
     'researcher': 'research',
     'reviewer': 'review',
-    'scrutinizer': 'scrutinize',
-    'simplifier': 'simplify',
     'skimmer': 'skim',
     'synthesizer': 'synthesize',
     'tester': 'test',
     'triager': 'triage',
     'validator': 'validate',
-    'bug-analyzer': 'diagnose',
+    // Rename of six agents to the names that state their job.
+    'code-fix': 'fix',
+    'code-edit': 'refactor',
+    'scrutinize': 'harden',
+    'simplify': 'polish',
+    'diagnose': 'debug',
+    'learning': 'curate',
 });
 /**
  * Canonicalise agent keys in a raw agents map by applying LEGACY_AGENT_KEYS.
@@ -184,6 +202,10 @@ export const LEGACY_AGENT_KEYS = Object.assign(Object.create(null), {
  *
  * Collision detection is against the ORIGINAL map so results are order-independent.
  *
+ * Two legacy keys that name one agent (scrutinizer and scrutinize both mean harden) meet
+ * at one slug. The key declared later in LEGACY_AGENT_KEYS, the more recent name, wins;
+ * the other is dropped. The pick reads the declaration order, never the file order.
+ *
  * The function is pure and idempotent: calling it twice on the same input
  * produces the same result as calling it once (idempotent under concurrent execution).
  *
@@ -208,6 +230,19 @@ export function canonicaliseAgentKeys(rawAgents, onWarning) {
     }
     // Snapshot the original keys for collision detection (order-independent result).
     const originalKeys = new Set(Object.keys(rawAgents));
+    // When several legacy keys in the file name one agent, the one declared latest in
+    // LEGACY_AGENT_KEYS is the one that is renamed; the others are dropped below.
+    const declared = Object.keys(LEGACY_AGENT_KEYS);
+    const winnerByTarget = new Map();
+    for (const oldKey of originalKeys) {
+        if (oldKey === '__proto__' || !Object.hasOwn(LEGACY_AGENT_KEYS, oldKey))
+            continue;
+        const target = LEGACY_AGENT_KEYS[oldKey];
+        const held = winnerByTarget.get(target);
+        if (held === undefined || declared.indexOf(oldKey) > declared.indexOf(held)) {
+            winnerByTarget.set(target, oldKey);
+        }
+    }
     const result = { ...rawAgents };
     let didMutate = false;
     for (const oldKey of originalKeys) {
@@ -237,8 +272,9 @@ export function canonicaliseAgentKeys(rawAgents, onWarning) {
             didMutate = true;
             continue;
         }
-        if (originalKeys.has(newKey)) {
-            // Collision: new (canonical) key already present → new wins, old dropped.
+        if (originalKeys.has(newKey) || winnerByTarget.get(newKey) !== oldKey) {
+            // Collision: new (canonical) key already present, or a more recent legacy key
+            // names the same agent → that value wins, old dropped.
             // Warning is surfaced by the caller's structured dropped-block (e.g. migrations.ts)
             // to avoid printing the same collision twice in two different vocabularies (F8).
             dropped.push(oldKey);

package/dist/core/compliance-compose.js

@@ -172,13 +172,15 @@ function collectMissingFragmentWarnings(fnName, activeFrameworks, fragments, omi
  *
  * Every framework reference is installed on every machine
  * (D-COMPLIANCE-INSTALL-ALWAYS), so file presence no longer says which
- * frameworks apply. The caller hands the agent `COMPLIANCE_FRAMEWORKS` — the
- * `COMPLIANCE` field of the settings line, which folds this machine's selection
- * with the repository's `.devflow/project.json` — and those ids alone are in force.
+ * frameworks apply. The command names the ids in the agent's prompt
+ * (D-COMPLIANCE-INJECT: the compliance directive) — the `COMPLIANCE` field of the
+ * settings line, which folds this machine's selection with the repository's
+ * `.devflow/project.json` — and those ids alone are in force. No agent takes a
+ * named lens input, so the stamp names the prompt, not a variable.
  */
 const RUNTIME_SELECTION_LINES = [
     'Every `references/{id}.md` is installed, so presence decides nothing: the ids you were given',
-    "(`COMPLIANCE_FRAMEWORKS`, this machine's plus the repository's) are the frameworks in force.",
+    "(named in your prompt; this machine's plus the repository's) are the frameworks in force.",
     'Load `references/{id}.md` for each given id and no other; `none` means generic controls only.',
     'Apply generic controls always.',
     '',

package/dist/core/{learning-tuning-config.js → curate-tuning-config.js}

@@ -1,17 +1,17 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { getDevFlowDirectory } from '../targets/claude-code/claude-paths.js';
-import { getLearningTuningConfigPath } from './project-paths.js';
+import { getCurateTuningConfigPath } from './project-paths.js';
 const VALID_MODELS = new Set(['opus', 'sonnet', 'haiku']);
 function isValidModel(value) {
     return typeof value === 'string' && VALID_MODELS.has(value);
 }
 /**
- * D-LEARNING-SHIPPED-ROW: the default model is the model the Learning agent ships
- * with, the `model:` line of src/assets/agents/learning.md. With no layer
+ * D-LEARNING-SHIPPED-ROW: the default model is the model the Curate agent ships
+ * with, the `model:` line of src/assets/agents/curate.md. With no layer
  * configuring a model, the spawn directive names none and that line decides, so a
  * different default here would describe a run that never happens.
- * tests/decisions/config.test.ts holds this value equal to the Learning row of the
+ * tests/decisions/config.test.ts holds this value equal to the Curate row of the
  * agent-config table, which a change of the shipped tier edits with the frontmatter.
  */
 const DEFAULTS = {
@@ -19,12 +19,12 @@ const DEFAULTS = {
     debug: false,
 };
 /**
- * Apply a single JSON config layer onto a LearningTuningConfig, returning a new object.
+ * Apply a single JSON config layer onto a CurateTuningConfig, returning a new object.
  * Skips fields with wrong types. Swallows parse errors — callers see defaults.
  * Unknown fields (e.g. an old config still on disk with extra knobs) are
  * silently ignored, not an error.
  */
-export function applyLearningTuningConfigLayer(config, json) {
+export function applyCurateTuningConfigLayer(config, json) {
     try {
         const parsed = JSON.parse(json);
         // Object-shape guard mirrors coerceConfig in feature-config.ts: a JSON
@@ -34,7 +34,7 @@ export function applyLearningTuningConfigLayer(config, json) {
         }
         const raw = parsed;
         return {
-            // Only accept a model value that belongs to the closed LearningModelAlias domain.
+            // Only accept a model value that belongs to the closed CurateModelAlias domain.
             model: isValidModel(raw.model) ? raw.model : config.model,
             debug: typeof raw.debug === 'boolean' ? raw.debug : config.debug,
         };
@@ -54,13 +54,13 @@ function readConfigFile(filePath) {
     catch (err) {
         if (err.code !== 'ENOENT') {
             // Warn but don't crash — callers fall back to defaults.
-            console.warn(`[learning-tuning-config] warning: could not read ${filePath}: ${err.message}`);
+            console.warn(`[curate-tuning-config] warning: could not read ${filePath}: ${err.message}`);
         }
         return null;
     }
 }
 /**
- * Load and merge learning agent tuning configuration.
+ * Load and merge curate agent tuning configuration.
  *
  * Priority (highest wins): project config → global config → defaults.
  *
@@ -71,18 +71,18 @@ function readConfigFile(filePath) {
  *
  * Invalid JSON in either file is silently ignored and treated as absent.
  */
-export function loadLearningTuningConfig(ledgerRoot) {
+export function loadCurateTuningConfig(ledgerRoot) {
     const globalConfigPath = path.join(getDevFlowDirectory(), 'learning.json');
-    const projectConfigPath = getLearningTuningConfigPath(ledgerRoot);
+    const projectConfigPath = getCurateTuningConfigPath(ledgerRoot);
     let config = { ...DEFAULTS };
     const globalJson = readConfigFile(globalConfigPath);
     if (globalJson !== null) {
-        config = applyLearningTuningConfigLayer(config, globalJson);
+        config = applyCurateTuningConfigLayer(config, globalJson);
     }
     const projectJson = readConfigFile(projectConfigPath);
     if (projectJson !== null) {
-        config = applyLearningTuningConfigLayer(config, projectJson);
+        config = applyCurateTuningConfigLayer(config, projectJson);
     }
     return config;
 }
-//# sourceMappingURL=learning-tuning-config.js.map
+//# sourceMappingURL=curate-tuning-config.js.map

package/dist/core/feature-switch.js

@@ -106,6 +106,27 @@ async function readRawManifest(devflowDir) {
 export async function readMachineFeature(devflowDir, feature) {
     return isMachineFeatureOn(await readRawManifest(devflowDir), feature);
 }
+/**
+ * Whether a RAW parsed manifest has an opt-in `feature` switched on. Pure.
+ *
+ * D-BEHAVIOR-OPT-IN: only an explicit boolean `true` is on. A missing key, a
+ * non-boolean value, a manifest without a `features` record and anything that is not an
+ * object all read as OFF — fail-closed, the mirror of {@link isMachineFeatureOn}. Like
+ * that reader it is deliberately not built on readManifest(): a read-only status must
+ * not heal-write, and a manifest missing a required field is still a manifest here.
+ */
+export function isOptInFeatureOn(rawManifest, feature) {
+    if (!isJsonObject(rawManifest) || !isJsonObject(rawManifest.features))
+        return false;
+    return rawManifest.features[feature] === true;
+}
+/**
+ * Read an opt-in machine switch from `<devflowDir>/manifest.json`. Read-only (no heal
+ * write); an absent, unreadable or malformed manifest reads as OFF.
+ */
+export async function readOptInFeature(devflowDir, feature) {
+    return isOptInFeatureOn(await readRawManifest(devflowDir), feature);
+}
 /**
  * Write the machine-wide switch to `<devflowDir>/manifest.json` (atomic
  * temp + rename). Refuses with `not-installed` when there is no manifest to
@@ -115,8 +136,8 @@ export async function readMachineFeature(devflowDir, feature) {
  * D-NOOP-TOGGLE: a toggle to the value the manifest already records writes
  * nothing. The only bytes such a write could change are `updatedAt`, and that
  * field means "the manifest's content last changed", so a no-op must not move
- * it. This is the one write point of `devflow memory|learning|knowledge
- * --enable/--disable`, so the rule holds for all three at once.
+ * it. This is the one write point of `devflow memory|learning|knowledge|behavior
+ * --enable/--disable`, so the rule holds for all four at once.
  */
 export async function writeMachineFeature(devflowDir, feature, enabled) {
     const raw = await readRawManifest(devflowDir);

package/dist/core/flags.js

@@ -88,6 +88,45 @@ export const FLAG_REGISTRY = [
         recommended: true,
         defaultValue: true,
     },
+    {
+        // D-SUBAGENT-CACHE-5M: subagents write their prompt cache with the 5-minute TTL
+        // while the main session keeps the 1-hour TTL of `prompt-caching-1h` (untouched).
+        //
+        // Why: the wave-4 token audit (2026-10-10) found 99.998% of subagent cache writes
+        // are 1-hour writes, yet fewer than 0.1% of subagent requests idle longer than
+        // 5 minutes - a subagent finishes or is resumed long before a 5-minute entry
+        // lapses, so the 1-hour premium buys nothing. Modelled effect of 5m: -8.9% on
+        // subagent cache-equivalent cost, -7.7% on total.
+        //
+        // Mechanism (VENDOR BEHAVIOUR, probed 2026-10-11 on Claude Code 2.1.296 in a
+        // sandboxed session): with ENABLE_PROMPT_CACHING_1H=true and this setting at
+        // "5m", subagent requests wrote only ephemeral_5m cache (36,387 tokens, none at
+        // 1h) while the main session wrote 100% 1h (35,209). Precedence of the subagent
+        // TTL in the binary, highest first: an env var that forces 5m, env
+        // CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL, this setting, a per-agent frontmatter
+        // `experimental.cacheTtl`, ENABLE_PROMPT_CACHING_1H. The 1-hour TTL is ignored
+        // while a subscription is in overage. A Claude Code that predates the setting
+        // ignores the key, so subagents then follow ENABLE_PROMPT_CACHING_1H as before.
+        // Re-probe when the precedence matters again; this is an observation, not a spec.
+        //
+        // Rejected: per-agent `experimental.cacheTtl` - it would spread one policy over
+        // every agent file; one devflow-managed flag keeps the policy in one place.
+        //
+        // Delete guard: only "5m" is deleted on disable or uninstall, so a user's own
+        // "1h" stays (D-GUARD-SCALAR). Adoption: init seeds this flag OFF when a value
+        // that is not "5m" is already on disk (D-ADOPT-RESPECTS-USER, respectUserOwnedSettings).
+        id: 'subagent-cache-5m',
+        label: 'Subagent 5-min cache',
+        description: 'Write subagent prompt-cache entries with the 5-minute TTL; the main session keeps 1 hour',
+        hint: 'Subagents rarely idle past 5 min, so 5-min cache writes cost less',
+        blurb: '5-min cache TTL for subagents',
+        kind: 'boolean',
+        target: { type: 'setting', key: 'subagentPromptCacheTtl' },
+        onPayload: '5m',
+        settingDeleteGuard: '5m',
+        recommended: true,
+        defaultValue: true,
+    },
     {
         id: 'show-turn-duration',
         label: 'Show turn duration',
@@ -969,6 +1008,78 @@ export function settingHoldsManagedShape(settingsJson, flagId) {
         return false;
     }
 }
+/**
+ * D-ADOPT-RESPECTS-USER predicate: the mirror of `settingHoldsManagedShape`.
+ *
+ * Returns true when the settings.json string carries a value at the guarded flag's
+ * target key that is NOT the flag's managed shape - a value the user (or another
+ * tool) owns, which enabling the flag would overwrite. Presence is decided with
+ * `hasOwnProperty`, so an explicit `null` counts as a value; the shape decision is
+ * delegated to `settingValueHoldsManagedShape`, never compared here.
+ *
+ * Returns false when:
+ *   - settingsJson is malformed
+ *   - root is not a plain object
+ *   - flagId is not in the registry
+ *   - the flag has no settingDeleteGuard, or is not a setting-target boolean
+ *   - the key is absent
+ *   - the on-disk value holds the managed shape
+ */
+export function settingHoldsUserValue(settingsJson, flagId) {
+    try {
+        const parsed = JSON.parse(settingsJson);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return false;
+        const flag = FLAG_REGISTRY_MAP.get(flagId);
+        if (!flag || flag.kind !== 'boolean' || flag.target.type !== 'setting')
+            return false;
+        if (flag.settingDeleteGuard === undefined)
+            return false;
+        const root = parsed;
+        if (!Object.prototype.hasOwnProperty.call(root, flag.target.key))
+            return false;
+        return !settingValueHoldsManagedShape(flag, root[flag.target.key]);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * D-ADOPT-RESPECTS-USER: seed a guarded setting flag OFF when adopting it ON would
+ * overwrite a value the user already owns.
+ *
+ * A flag the manifest does not record is adopted at its `defaultValue`. For a flag whose
+ * target is a settings.json key with a `settingDeleteGuard`, adopting ON writes its
+ * managed payload over whatever is on disk (the guard protects deletion, not writes).
+ * When the key already holds a value that is not the managed shape - a user's own `"1h"`
+ * under `subagentPromptCacheTtl` - that write would silently replace a deliberate choice.
+ * Such a flag is set `false` instead; with the record then claiming `false`, the converge
+ * pipeline neither writes nor deletes the user's value.
+ *
+ * Scope: only flags ABSENT from `manifestFlags` (or all of them on a fresh install, when
+ * it is null). A flag the manifest records keeps its value in `flags`, so an explicit
+ * enable still wins. `devflow init --reset` hands this an empty settings snapshot
+ * (resolveResetGatedInputs), so nothing is detected and the factory default stands. The rule is generic over guarded
+ * setting flags: no flag id is special-cased, and `settingHoldsUserValue` is the one place
+ * that decides "the disk holds something that is not ours". For a flag whose default is
+ * already OFF (suppress-attribution) it changes nothing.
+ *
+ * Two callers apply the same rule: the init seed, and the flags TUI's starting rows (an
+ * upgrade that has not run init yet would otherwise offer a Save that overwrites the value).
+ *
+ * Pure function - the settings snapshot is read by the caller and passed in.
+ */
+export function respectUserOwnedSettings(flags, manifestFlags, settingsSnapshot) {
+    const result = { ...flags };
+    for (const flag of FLAG_REGISTRY) {
+        const adoptedAtDefault = manifestFlags === null || !(flag.id in manifestFlags);
+        if (!adoptedAtDefault)
+            continue;
+        if (settingHoldsUserValue(settingsSnapshot, flag.id))
+            result[flag.id] = false;
+    }
+    return result;
+}
 /**
  * D-ATTR-GUARD: returns true when it is safe to delete a flag's target key from
  * settings. For flags with a settingDeleteGuard the key is only deleted when the

package/dist/core/learning-queue-cleanup.js

@@ -11,7 +11,7 @@ import { drainQueueFiles } from './queue-drain.js';
 /**
  * Drain the learning (decisions-detection) pending-turns queue, its claimed
  * batch and the claim's owner file so stale turns don't process later — used by
- * both `--clear` and `--disable`. A mid-run Learning agent whose claimed batch
+ * both `--clear` and `--disable`. A mid-run Curate agent whose claimed batch
  * vanishes aborts without changes, which is the desired outcome in both cases.
  * Refused, deleting nothing, when `.devflow` or `.devflow/learning` under `gitRoot`
  * is a symbolic link (D-CLI-NO-SYMLINK). ENOENT-tolerant; other errors propagate.

package/dist/core/manifest.js

@@ -62,12 +62,15 @@ function parseManifestFlags(features, knownFlags) {
  * - features.knownFlags stripped from result (folded into FlagsRecord key-presence)
  * - features.proxy absent → false
  * - features.compliance absent/malformed → {enabled:false, frameworks:[]}
+ * - features.behavior absent → false; malformed → false, healed on disk (D-BEHAVIOR-OPT-IN)
  * - features.tracker absent/malformed → {provider:'github'}
+ * - features.tracker.servers absent → the default list; invalid → the default list, reported
+ *   through `opts.onWarning` when the caller supplies one (this reader has no output channel)
  *
  * D39: heal-write failure returns the migrated in-memory manifest (not null).
  * The on-disk format remains unhealed; next read triggers another attempt.
  */
-export async function readManifest(devflowDir) {
+export async function readManifest(devflowDir, opts) {
     const manifestPath = path.join(devflowDir, 'manifest.json');
     try {
         const content = await fs.readFile(manifestPath, 'utf-8');
@@ -129,7 +132,10 @@ export async function readManifest(devflowDir) {
             features.decisions !== undefined ||
             flagsWereLegacy ||
             features.knownFlags !== undefined ||
-            features.viewMode !== undefined;
+            features.viewMode !== undefined ||
+            // D-BEHAVIOR-OPT-IN: a malformed switch (present, not a boolean) is rewritten as
+            // the false it reads as; an absent one is not a defect and owes no write.
+            (features.behavior !== undefined && typeof features.behavior !== 'boolean');
         const SECURITY_MODES = ['none', 'user', 'managed'];
         const manifest = {
             version: data.version,
@@ -158,12 +164,14 @@ export async function readManifest(devflowDir) {
                 proxy: typeof features.proxy === 'boolean' ? features.proxy : false,
                 // Self-heal: absent/malformed compliance → {enabled:false, frameworks:[]}
                 compliance: normalizeComplianceFeature(features.compliance),
+                // D-BEHAVIOR-OPT-IN: absent/malformed → false (opt-in; the inverse of knowledge/learning).
+                behavior: features.behavior === true,
                 // Self-heal: absent/malformed/unknown tracker → {provider:'github'} (AC-3.21).
                 // Deliberately NOT in the hard-null set above — see the field's doc comment.
                 // Healing here is silent and emits no DEGRADED: that is the correct
                 // self-heal behaviour, and a different condition from a per-repo config
                 // value outside the domain (which does emit `unknown tracker provider`).
-                tracker: normalizeTrackerFeature(features.tracker),
+                tracker: normalizeTrackerFeature(features.tracker, opts?.onWarning),
             },
             installedAt: data.installedAt,
             updatedAt: data.updatedAt,