devflow-kit 3.5.0 → 3.7.0

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/{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/echo-value.js

@@ -0,0 +1,42 @@
+/**
+ * Render an untrusted value for a terminal message.
+ *
+ * A neutral home for the sanitizer that every parser echoing a rejected value
+ * shares (the tracker provider and the gate level today), so no parser imports
+ * another feature's module just to reach it.
+ */
+/** Longest rejected value echoed back to the terminal, in CODE POINTS. */
+const MAX_ECHOED_VALUE = 40;
+/**
+ * Render an untrusted token for a terminal message.
+ *
+ * Rejected values are echoed so the user can see what they typed, so they are
+ * third-party input at a display sink: control characters (terminal escapes,
+ * BEL, newlines) are replaced and the value is truncated.
+ *
+ * Takes `unknown`, and a non-string renders as its TYPE: the never-throws
+ * contract of the callers has to hold for what reaches this sink, not
+ * only for what the signature says — a caller reads hand-editable
+ * files, and a caller-side guard is one edit from being gone. Naming the type
+ * also keeps the render total, where `String()` would hand control to a
+ * caller-supplied `toString` — itself both a throw path and an echo path this
+ * function exists to close.
+ */
+export function describeEchoedValue(raw) {
+    if (typeof raw !== 'string')
+        return `<${raw === null ? 'null' : typeof raw}>`;
+    // The class is written with ESCAPES, never literal control bytes. A raw NUL
+    // makes grep classify this whole file as binary — it prints "Binary file
+    // matches" and skips the lines — so every grep-based sweep over src/core/
+    // silently stops covering the file while still exiting 0. Pinned by
+    // tests/guards/no-control-bytes.test.ts.
+    // eslint-disable-next-line no-control-regex
+    const stripped = raw.replace(/[\x00-\x1f\x7f]/g, '?');
+    // Cut by CODE POINT. `slice` cuts UTF-16 code units, so a cut landing inside an
+    // astral character (emoji, CJK ext-B) emits the lone surrogate half of it.
+    const points = [...stripped];
+    return points.length > MAX_ECHOED_VALUE
+        ? `${points.slice(0, MAX_ECHOED_VALUE).join('')}…`
+        : stripped;
+}
+//# sourceMappingURL=echo-value.js.map

package/dist/core/evidence-policy.js

@@ -331,15 +331,27 @@ export function repoComplianceStatusLines(loaded, opts) {
  * tracked by git, or null (D-PERSONAL-UNTRACKED). The resolver ignores such a file
  * and says so on stderr, but prompts run it with stderr discarded, so a status
  * command is where the user sees why their personal settings have no effect.
+ *
+ * Takes the ONE resolved result, so a caller that already holds it adds no second
+ * resolve (each resolve forks git).
+ */
+export function trackedConfigWarning(settings) {
+    if (!settings.personalTracked)
+        return null;
+    const file = settingsSourceFile('personal');
+    return `Git tracks an entry at or under ${file}, so devflow ignores that file. It holds personal settings. ` +
+        'Find the entry in the output of: git ls-files. Untrack it with: git rm --cached <entry>. ' +
+        'Then check the file contents, or delete the file. ' +
+        'Untracking leaves the committed bytes on disk as your personal file.';
+}
+/**
+ * {@link trackedConfigWarning} for a caller that holds the loaded module and not a
+ * resolved result: it resolves once and returns null when the module is unusable.
  */
 export function personalConfigTrackedWarning(loaded, opts) {
     if (!loaded.ok)
         return null;
-    if (!loaded.value.resolveSettings(opts).personalTracked)
-        return null;
-    const file = settingsSourceFile('personal');
-    return `${file} is tracked by git, so devflow ignores it — it holds personal settings. ` +
-        `Untrack it with: git rm --cached ${file}`;
+    return trackedConfigWarning(loaded.value.resolveSettings(opts));
 }
 /** The policies the hint maps, in the order it prints them. */
 const HINT_POLICIES = ['standard', 'required'];

package/dist/core/gate-level.js

@@ -0,0 +1,213 @@
+import { promises as fs, constants as fsConstants } from 'fs';
+import * as path from 'path';
+import { writeFileAtomicExclusive } from './fs-atomic.js';
+import { hasRequiredManifestFields } from './manifest.js';
+import { describeEchoedValue } from './echo-value.js';
+/**
+ * The gate level: how much checking a command applies. One of three words, from
+ * most to least checking.
+ *
+ * `features.gateLevel` in `~/.devflow/manifest.json` is the MACHINE default, and
+ * `gateLevel` in a repository's personal `.devflow/config.json` overrides it.
+ * Neither is a feature switch: a switch can only be narrowed by a repository
+ * layer, but a level may be raised or lowered by the personal file. The settings
+ * resolver (`resolve-settings.cjs`) folds both into the `GATE_LEVEL=` field of its
+ * settings line; this module owns the closed set, the parser and the machine
+ * layer's raw reader and writer. No code here chooses a level from a task or a
+ * diff.
+ *
+ * A present value that is not one of the three words is MALFORMED. A reader reads
+ * it as `full` and leaves it on disk as written: no read and no unrelated write
+ * heals it to absent, which would lower the level without a word.
+ */
+export const GATE_LEVELS = Object.freeze(['full', 'standard', 'lean']);
+/** The level when neither the personal file nor the manifest records one. */
+export const DEFAULT_GATE_LEVEL = 'standard';
+/**
+ * Largest manifest read, in bytes. Pinned by a parity test to the resolver
+ * library's MAX_MANIFEST_BYTES, so the CLI and a prompt never disagree about a
+ * manifest that is too large to read.
+ */
+export const MAX_MANIFEST_BYTES = 1048576;
+const VALID_LEVELS_LIST = GATE_LEVELS.join(', ');
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isGateLevel(value) {
+    return typeof value === 'string' && GATE_LEVELS.includes(value);
+}
+/**
+ * Strict boundary parser for a gate level typed on the command line.
+ *
+ * REJECT, NEVER REPAIR: membership is byte-exact. No trim, no case folding, no
+ * alias. `Lean` and `lean ` are errors, not `lean`. The message names every valid
+ * level and echoes the offending value only in the sanitized form of
+ * {@link describeEchoedValue}.
+ */
+export function parseGateLevel(value) {
+    if (isGateLevel(value))
+        return { ok: true, value };
+    if (value === undefined || value === '') {
+        return { ok: false, error: `Missing gate level. Valid levels: ${VALID_LEVELS_LIST}` };
+    }
+    return {
+        ok: false,
+        error: `Unknown gate level: "${describeEchoedValue(value)}". Valid levels: ${VALID_LEVELS_LIST}`,
+    };
+}
+/**
+ * The machine layer's level in a RAW parsed manifest. Pure and total.
+ *
+ *   null       no level is recorded: not an object, `features` not an object, or
+ *              no own `gateLevel` key
+ *   'invalid'  a `gateLevel` key is present and is not one of the three words
+ *   a level    the recorded level
+ *
+ * Deliberately NOT built on readManifest(): that reader rejects a manifest
+ * missing a required field and heal-writes, and a read-only status must do
+ * neither. The resolver script's `machineGateLevel` is the CommonJS twin; a
+ * table test holds the two to the same rows.
+ */
+export function machineGateLevel(raw) {
+    if (!isPlainObject(raw))
+        return null;
+    const features = raw.features;
+    if (!isPlainObject(features))
+        return null;
+    if (!Object.hasOwn(features, 'gateLevel'))
+        return null;
+    const value = features.gateLevel;
+    return isGateLevel(value) ? value : 'invalid';
+}
+/**
+ * Set `features.gateLevel` in a RAW parsed manifest. Pure — returns a new object
+ * and never mutates its input. Null when the top level or `features` is not a
+ * plain object (there is no `features` record to write into).
+ *
+ * Only `features.gateLevel` and `updatedAt` change; every other key is carried
+ * verbatim, including keys this build does not model.
+ */
+export function setMachineGateLevel(raw, level, now) {
+    if (!isPlainObject(raw) || !isPlainObject(raw.features))
+        return null;
+    return {
+        ...raw,
+        features: { ...raw.features, gateLevel: level },
+        updatedAt: now,
+    };
+}
+const ABSENT = Object.freeze({ kind: 'absent' });
+const CORRUPT = Object.freeze({ kind: 'corrupt' });
+function startsWithBom(bytes) {
+    return bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf;
+}
+/** Bytes of the manifest, or why not: one bounded read of a regular file, followed through links. */
+async function readManifestBytes(manifestPath) {
+    try {
+        let st;
+        try {
+            st = await fs.stat(manifestPath);
+        }
+        catch (err) {
+            const code = err.code;
+            return code === 'ENOENT' || code === 'ENOTDIR' ? 'absent' : 'corrupt';
+        }
+        if (!st.isFile() || st.size > MAX_MANIFEST_BYTES)
+            return 'corrupt';
+        // O_NONBLOCK: a FIFO swapped in after the stat cannot block the open.
+        const handle = await fs.open(manifestPath, fsConstants.O_RDONLY | (fsConstants.O_NONBLOCK || 0));
+        try {
+            const opened = await handle.stat();
+            if (!opened.isFile() || opened.size > MAX_MANIFEST_BYTES)
+                return 'corrupt';
+            // One byte past the stat'd size: a file that grew between the stat and the
+            // read is refused rather than truncated into something that parses. Each
+            // pass reads at least one byte or stops, so the loop is bounded by the buffer.
+            const buf = Buffer.alloc(opened.size + 1);
+            let total = 0;
+            for (let pass = 0; pass < buf.length && total < buf.length; pass++) {
+                const { bytesRead } = await handle.read(buf, total, buf.length - total, null);
+                if (bytesRead === 0)
+                    break;
+                total += bytesRead;
+            }
+            return total > opened.size ? 'corrupt' : buf.subarray(0, total);
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+        }
+    }
+    catch {
+        return 'corrupt';
+    }
+}
+/**
+ * Read `<devflowDir>/manifest.json` raw, for the gate level. Never throws, never
+ * exits and never writes: unlike readManifest() it heals nothing, models no key
+ * and keeps every key it does not name.
+ *
+ * It follows the resolver library's rules, so the CLI and a prompt see the same
+ * file: the path is followed through links, a missing path is absent, and every
+ * other failure is corrupt. Bytes decode as UTF-8 with a fatal error, which also
+ * strips a leading BOM, and then parse as JSON, so the level is read past a BOM
+ * as it is in the resolver. A file with a BOM is still `rejected`, because
+ * readManifest() parses the text as read and refuses it.
+ */
+export async function readGateManifest(devflowDir) {
+    const bytes = await readManifestBytes(path.join(devflowDir, 'manifest.json'));
+    if (bytes === 'absent')
+        return ABSENT;
+    if (bytes === 'corrupt')
+        return CORRUPT;
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    catch {
+        return CORRUPT;
+    }
+    if (!isPlainObject(parsed) || !isPlainObject(parsed.features))
+        return CORRUPT;
+    const readable = !startsWithBom(bytes) && hasRequiredManifestFields(parsed);
+    return { kind: readable ? 'object' : 'rejected', raw: parsed };
+}
+/**
+ * Write the machine default to `<devflowDir>/manifest.json` (atomic temp +
+ * rename). Never throws. Refuses with `invalid-level`, before any I/O, a level
+ * that is not one of the three words, because the type is no check at run time.
+ * Refuses with `not-installed` when there is no manifest to write into — a
+ * manifest is created by `devflow init`, never by this write.
+ *
+ * Only `features.gateLevel` and `updatedAt` change. A write to the level the
+ * manifest already records changes nothing, `updatedAt` included, because that
+ * field means "the manifest's content last changed". A manifest that
+ * readManifest() would reject for another key gets the same write as one it
+ * accepts: its level is valid, and the fault is not this write's to fix.
+ *
+ * `now` is injected so a test fixes the timestamp.
+ */
+export async function writeMachineGateLevel(devflowDir, level, now) {
+    if (!isGateLevel(level))
+        return { kind: 'invalid-level' };
+    const manifestPath = path.join(devflowDir, 'manifest.json');
+    const read = await readGateManifest(devflowDir);
+    if (read.kind === 'absent')
+        return { kind: 'not-installed' };
+    if (read.kind === 'corrupt')
+        return { kind: 'unreadable', path: manifestPath };
+    const features = read.raw.features;
+    if (isPlainObject(features) && features.gateLevel === level)
+        return { kind: 'unchanged' };
+    try {
+        const next = setMachineGateLevel(read.raw, level, now());
+        if (next === null)
+            return { kind: 'unreadable', path: manifestPath };
+        await writeFileAtomicExclusive(manifestPath, JSON.stringify(next, null, 2) + '\n');
+        return { kind: 'written' };
+    }
+    catch (err) {
+        const code = err?.code;
+        return { kind: 'write-failed', path: manifestPath, reason: typeof code === 'string' ? code : 'unknown error' };
+    }
+}
+//# sourceMappingURL=gate-level.js.map

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

@@ -51,6 +51,27 @@ function parseManifestFlags(features, knownFlags) {
     // Case C: missing/malformed → empty record
     return { flags: {}, legacy: false };
 }
+/**
+ * Whether a parsed manifest object carries every field {@link readManifest}
+ * requires: a version, a plugin list, a `features` object with boolean `ambient`
+ * and `memory`, and string `installedAt` and `updatedAt`. Pure. A manifest that
+ * fails it reads as "no prior install".
+ *
+ * Exported so a raw reader can tell a manifest this reader rejects from one it
+ * accepts without calling it: readManifest heal-writes, and a read-only status
+ * must not.
+ */
+export function hasRequiredManifestFields(data) {
+    const features = data.features;
+    return !(!data.version ||
+        !Array.isArray(data.plugins) ||
+        typeof features !== 'object' ||
+        features === null ||
+        typeof features.ambient !== 'boolean' ||
+        typeof features.memory !== 'boolean' ||
+        typeof data.installedAt !== 'string' ||
+        typeof data.updatedAt !== 'string');
+}
 /**
  * Read and parse the manifest file. Returns null if missing or corrupt.
  *
@@ -75,17 +96,9 @@ export async function readManifest(devflowDir, opts) {
     try {
         const content = await fs.readFile(manifestPath, 'utf-8');
         const data = JSON.parse(content);
-        const features = data.features;
-        if (!data.version ||
-            !Array.isArray(data.plugins) ||
-            typeof features !== 'object' ||
-            features === null ||
-            typeof features.ambient !== 'boolean' ||
-            typeof features.memory !== 'boolean' ||
-            typeof data.installedAt !== 'string' ||
-            typeof data.updatedAt !== 'string') {
+        if (!hasRequiredManifestFields(data))
             return null;
-        }
+        const features = data.features;
         // D-FEATURES-ABSENT-ON (a sub-decision of D-FEATURES-NARROW-ONLY,
         // src/core/feature-switch.ts): knowledge and learning are machine-wide
         // switches, and every runtime gate — queue_read_gates in the hooks,
@@ -172,6 +185,9 @@ export async function readManifest(devflowDir, opts) {
                 // 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, opts?.onWarning),
+                // The machine gate level, raw (see the field's doc comment): kept when the
+                // key is present, a stored `null` included, and left out when it is absent.
+                ...(Object.hasOwn(features, 'gateLevel') ? { gateLevel: features.gateLevel } : {}),
             },
             installedAt: data.installedAt,
             updatedAt: data.updatedAt,