devflow-kit 2.4.0 → 2.5.0

package/dist/core/assets.js

@@ -1,5 +1,6 @@
 import { join } from 'path';
 import { getPackageRoot } from './paths.js';
+import { SKILL_REFS_OUTPUT_DIR } from './mds-variants.js';
 /**
  * Flat skills source directory: src/assets/skills/{name}/
  * All plugins' skills live here directly (no per-plugin subdirectory).
@@ -10,9 +11,13 @@ export function skillsDir() {
 /**
  * Flat agents source directory: src/assets/agents/{name}.md
  * All plugins' agents live here directly.
+ *
+ * @param root - Package root to resolve against. Injectable so a caller working
+ *   on a temp tree (the test harness) reads the layout from here rather than
+ *   spelling the path itself.
  */
-export function agentsDir() {
-    return join(getPackageRoot(), 'src', 'assets', 'agents');
+export function agentsDir(root = getPackageRoot()) {
+    return join(root, 'src', 'assets', 'agents');
 }
 /**
  * Flat rules source directory: src/assets/rules/{name}.md
@@ -36,4 +41,55 @@ export function scriptsDir() {
 export function commandsDir() {
     return join(getPackageRoot(), 'dist', 'commands');
 }
+/**
+ * Compiled agents directory: dist/agents/{name}.md
+ *
+ * Output of the .mds generator hosts. The directory is absent until at least
+ * one generator host exists, so every reader must tolerate its absence.
+ *
+ * @param root - Package root to resolve against (see agentsDir).
+ */
+export function compiledAgentsDir(root = getPackageRoot()) {
+    return join(root, 'dist', 'agents');
+}
+/**
+ * Compiled skill-reference directory: dist/skills/git/references/
+ *
+ * Output of the `.mds` reference modules — the generated `devflow:git` mechanics
+ * files, one per (provider, operation) pair under `tracker/{provider}/`. Like
+ * compiledAgentsDir(), the directory is absent until the build has run, so every
+ * reader must tolerate its absence.
+ *
+ * The spelling comes from SKILL_REFS_OUTPUT_DIR in src/core/mds-variants.ts —
+ * the build's own allowlist table — rather than being retyped here, so the
+ * destination has exactly one definition.
+ *
+ * @param root - Package root to resolve against (see agentsDir).
+ */
+export function compiledSkillRefsDir(root = getPackageRoot()) {
+    return join(root, ...SKILL_REFS_OUTPUT_DIR.split('/'));
+}
+/**
+ * Agent source directories, MOST-PREFERRED FIRST.
+ *
+ * The single owner of the dist-first agent-resolution policy: a generator
+ * host's compiled artifact in dist/agents/ supersedes a hand-authored file of
+ * the same name in src/assets/agents/. Every consumer reads the order from
+ * here — the installer's first-hit-wins resolve, loadShippedDefaults's
+ * first-wins merge, and the test harness's resolveAgentSource — so the
+ * convention is stated once and cannot drift apart between call sites.
+ *
+ * Order is invisible to the type system: a list spelled least-preferred-first
+ * still typechecks and silently inverts the answer. Consumers therefore take
+ * this list as-is and never re-spell it; tests/guards/agent-source-precedence
+ * pins that they agree.
+ *
+ * The non-empty tuple makes an empty list a compile error at every call site:
+ * an empty list would survive a `??` default and resolve to nothing.
+ *
+ * @param root - Package root to resolve against (see agentsDir).
+ */
+export function agentSourceDirs(root = getPackageRoot()) {
+    return [compiledAgentsDir(root), agentsDir(root)];
+}
 //# sourceMappingURL=assets.js.map

package/dist/core/evidence-policy.js

@@ -0,0 +1,147 @@
+/**
+ * The CLI's view of the evidence policy — a typed seam onto the package's own
+ * `resolve-evidence-policy.cjs`, never a second implementation of it.
+ *
+ * D-POLICY-CJS-SEAM: the resolver is plain CommonJS under src/assets/scripts/,
+ * outside every tsconfig (PF-043, PF-069), so the interfaces below are
+ * TRANSCRIBED from its JSDoc typedefs and are the only shape authority on this
+ * side — open those typedefs before changing anything here. The module is loaded
+ * with `require()` from `scriptsDir()`, which resolves under the package root both
+ * from `dist/cli.js` and under vitest (`package.json` `files` ships src/assets/),
+ * so the CLI and the resolver it runs are always the same version. The installed
+ * `~/.devflow/scripts` copy is never loaded: it may be older than this CLI. There
+ * is deliberately no TypeScript copy of the parser, the fold or the grammar.
+ *
+ * D-POLICY-NO-WRITE (applies ADR-024): `.devflow/policy.json` is team-owned, and
+ * devflow never writes or replaces a shared file it cannot prove it wrote. This
+ * module therefore imports no fs API; the CLI only PRINTS the bytes a team may
+ * choose to commit (`evidencePolicySuggestion`).
+ */
+import { createRequire } from 'module';
+import { join } from 'path';
+import { scriptsDir } from './assets.js';
+// ── Transcribed shapes (resolve-evidence-policy.cjs JSDoc) ─────────────────────
+/** Basename of the resolver under src/assets/scripts/ (and ~/.devflow/scripts/). */
+export const RESOLVER_SCRIPT_NAME = 'resolve-evidence-policy.cjs';
+/** The team file the CLI suggests committing, relative to a repository root. */
+const POLICY_FILE = '.devflow/policy.json';
+/**
+ * Every key of EvidencePolicyModule and the runtime kind the loader requires of
+ * it. `satisfies` makes the compiler reject an interface key missing here.
+ */
+export const EVIDENCE_POLICY_MODULE_SURFACE = Object.freeze({
+    POLICIES: 'string-array',
+    SOURCES: 'string-array',
+    WARNINGS: 'string-array',
+    MECHANISM_INPUTS: 'object',
+    OUTPUT_LINE_RE: 'regexp',
+    FAIL_CLOSED_LINE: 'string',
+    complianceDefault: 'function',
+    resolve: 'function',
+    serializePolicy: 'function',
+});
+function hasKind(value, kind) {
+    switch (kind) {
+        case 'string-array': return Array.isArray(value) && value.every(v => typeof v === 'string');
+        case 'object': return typeof value === 'object' && value !== null;
+        case 'regexp': return value instanceof RegExp;
+        case 'string': return typeof value === 'string';
+        case 'function': return typeof value === 'function';
+        default: {
+            const exhaustive = kind;
+            return exhaustive;
+        }
+    }
+}
+/** Surface keys that are absent or of the wrong kind on `value`, in surface order. */
+function surfaceMismatches(value) {
+    if (typeof value !== 'object' || value === null)
+        return Object.keys(EVIDENCE_POLICY_MODULE_SURFACE);
+    const record = value;
+    return Object.entries(EVIDENCE_POLICY_MODULE_SURFACE)
+        .filter(([key, kind]) => !hasKind(record[key], kind))
+        .map(([key]) => key);
+}
+/**
+ * Load the resolver from `dir` (default: the package's own scripts directory) and
+ * shape-check its surface. Never throws: a missing file is `not-found`; a module
+ * that throws on load or lacks a surface key is `unusable`.
+ */
+export function loadEvidencePolicyModule(dir = scriptsDir()) {
+    const file = join(dir, RESOLVER_SCRIPT_NAME);
+    let loaded;
+    try {
+        loaded = createRequire(import.meta.url)(file);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'MODULE_NOT_FOUND')
+            return { ok: false, error: { kind: 'not-found', path: file } };
+        const detail = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: { kind: 'unusable', path: file, detail } };
+    }
+    const mismatches = surfaceMismatches(loaded);
+    if (mismatches.length > 0) {
+        return { ok: false, error: { kind: 'unusable', path: file, detail: `missing or mistyped: ${mismatches.join(', ')}` } };
+    }
+    return { ok: true, value: loaded };
+}
+// ── Presentation (pure) ────────────────────────────────────────────────────────
+/** `Evidence policy: <policy> (source: <source>)`, plus ` [warn: a, b]` when warnings exist. */
+export function formatEvidencePolicyStatus(r) {
+    const warn = r.warnings.length > 0 ? ` [warn: ${r.warnings.join(', ')}]` : '';
+    return `Evidence policy: ${r.policy} (source: ${r.source})${warn}`;
+}
+/**
+ * The line shown in place of a policy when the resolver cannot be loaded. The
+ * remedy is a package reinstall: the CLI loads the package's own copy, which
+ * `devflow init` does not restore.
+ */
+export function formatEvidencePolicyUnavailable(error) {
+    switch (error.kind) {
+        case 'not-found': return 'Evidence policy: unavailable (resolver not found — reinstall devflow-kit)';
+        case 'unusable': return 'Evidence policy: unavailable (resolver failed to load — reinstall devflow-kit)';
+        default: {
+            const exhaustive = error;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * The `compliance --status` line: the resolved policy for `opts.dir`, or the
+ * unavailable line when the loader failed — that line is the whole handling
+ * (ADR-028). The caller passes the compliance state it already read, so the
+ * manifest is never read twice. `resolve()` makes at most two `gh` calls and
+ * bounds every subprocess with a timeout, so an offline machine degrades to a
+ * flagged result rather than a hang.
+ */
+export function evidencePolicyStatusLine(loaded, opts) {
+    if (!loaded.ok)
+        return formatEvidencePolicyUnavailable(loaded.error);
+    return formatEvidencePolicyStatus(loaded.value.resolve(opts));
+}
+/**
+ * What `--enable`/`--set` print when compliance is on: the file a team may commit
+ * to pin the policy it now gets by default. Returned only when the resolver's own
+ * `complianceDefault` says `required` (compliance enabled, at any framework
+ * count); `null` otherwise. The bytes come from the resolver's `serializePolicy`,
+ * so they always parse as a valid policy file. Nothing is written
+ * (D-POLICY-NO-WRITE).
+ */
+export function evidencePolicySuggestion(complianceState, mod) {
+    if (mod.complianceDefault(complianceState) !== 'required')
+        return null;
+    const body = mod.serializePolicy('required');
+    if (body === null)
+        return null;
+    return [
+        'Compliance is enabled on this machine, so repositories without a committed',
+        'policy default to the required evidence policy here. To apply it for everyone',
+        `working in a repository, commit this as ${POLICY_FILE} on its default branch:`,
+        '',
+        `${body}`,
+        'devflow never writes this file: the team owns it, and once committed it applies',
+        'repo-wide.',
+    ].join('\n');
+}
+//# sourceMappingURL=evidence-policy.js.map

package/dist/core/feature-config.js

@@ -1,125 +1,191 @@
 import * as path from 'path';
 import { promises as fs } from 'fs';
 import { getFeatureConfigPath } from './project-paths.js';
+import { parseTrackerId } from './tracker.js';
+/**
+ * Keys devflow itself once wrote and has retired. A managed write drops them
+ * rather than carrying them; no reader consults them.
+ *
+ * D-FEATURES-MACHINE-WIDE: `memory`, `learning` and `knowledge` were per-repo
+ * feature switches from the per-repo-install era. A feature is now on or off
+ * for the whole machine, in the manifest, so a stale per-repo value must
+ * neither decide anything nor linger to be mistaken for a switch: carrying it
+ * would leave a `learning: false` in the file that no longer does what it says.
+ * `decisions` is the pre-rename spelling of `learning`; `autoCommit` is inert.
+ */
+const RETIRED_CONFIG_KEYS = new Set([
+    'memory', 'learning', 'knowledge', 'decisions', 'autoCommit',
+]);
 export const DEFAULT_CONFIG = {
-    memory: true,
-    learning: true,
-    knowledge: true,
     reviewPublication: 'auto',
 };
 export function getConfigPath(projectRoot) {
     return getFeatureConfigPath(projectRoot);
 }
+/**
+ * Parse the per-repo tracker override from the raw config value.
+ *
+ * Pure. Delegates membership to `parseTrackerId` rather than re-spelling a
+ * closed-domain ternary the way `reviewPublication` does: `reviewPublication`
+ * self-heals any invalid value to `'auto'`, which is correct for a publication
+ * mode and wrong for a provider — a repaired provider is the laundering path
+ * GAP-10 names, and §14.2 gives the invalid case its own DEGRADED reason, which
+ * only exists if the parse REFUSES instead of healing.
+ *
+ * An empty string reads as absent: `"tracker": ""` is an unset key with a
+ * character in it, not an attempt to name a provider.
+ *
+ * A non-string JSON value (`42`, `true`, `null`, an array, an object) is
+ * `invalid`, not `absent` — a present-but-wrong-typed value means the file was
+ * edited, and reporting it as absent would make the whole class silent.
+ */
+export function parseTrackerOverride(raw) {
+    if (raw === undefined || raw === '')
+        return { kind: 'absent' };
+    // `unknown` all the way from the field: this is a boundary parse over
+    // hand-edited JSON, and a signature that promised a string would make the
+    // wrong-type arm unreachable to the compiler while it stays entirely reachable
+    // to a user with a text editor.
+    if (typeof raw !== 'string') {
+        return { kind: 'invalid', raw: JSON.stringify(raw) ?? String(raw) };
+    }
+    const parsed = parseTrackerId(raw);
+    return parsed.ok ? { kind: 'valid', provider: parsed.value } : { kind: 'invalid', raw };
+}
+/**
+ * Whether a parsed JSON value is an object a config can be read from — the one
+ * test for "the file holds a config", shared by the reader and the managed
+ * write so the two never disagree about which files count as empty.
+ */
+function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 /**
  * Parse and narrow an unknown JSON value into a FeatureConfig, merging onto
  * DEFAULT_CONFIG. Pure function — no I/O, no side effects.
  *
- * Coalesces legacy `decisions` key into `learning` when both are present:
- * `decisions` wins (legacy-decisions-wins semantics; intentionally opposite to
- * manifest.ts's new-key-wins self-heal — migration-compat requires the old key
- * to take precedence so old configs with `decisions: false` are not silently
- * re-enabled by a newer `learning: true` key).
- * Silently ignores `autoCommit` — old configs may still contain it.
+ * The retired keys ({@link RETIRED_CONFIG_KEYS}) are ignored: an old config may
+ * still hold them, and none of them decides anything (D-FEATURES-MACHINE-WIDE).
  *
  * Returns null when `parsed` is not a plain object (caller falls through to
  * the next candidate path).
  */
 function coerceConfig(parsed) {
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+    if (!isJsonObject(parsed))
         return null;
     const p = parsed;
-    // Coalesce decisions (legacy key) → learning. decisions wins when both present.
-    let learning = DEFAULT_CONFIG.learning;
-    if (typeof p.learning === 'boolean')
-        learning = p.learning;
-    if (typeof p.decisions === 'boolean')
-        learning = p.decisions; // decisions wins
     // Coerce reviewPublication: any invalid or absent value → 'auto' (self-heal, ADR-014 idiom).
     const rp = p.reviewPublication;
     const reviewPublication = rp === 'auto' || rp === 'full' || rp === 'off' ? rp : 'auto';
+    // The per-repo tracker override is carried through VERBATIM — never coerced,
+    // never type-filtered. Two reasons, and the second is the one a reader is
+    // likely to miss:
+    //   (a) repair is forbidden for a provider value (§14.9-6), so there is no
+    //       healed value to fall back to the way reviewPublication has 'auto';
+    //   (b) a non-string is a state parseTrackerOverride CLASSIFIES (`invalid`),
+    //       not a state this function repairs. Filtering by type here would leave
+    //       that arm reachable from a direct call to the parser and unreachable
+    //       from the file, which is the only place it can actually be written.
+    // Key PRESENCE is the whole rule: a present key is carried as written, and an
+    // absent one stays absent. `hasOwnProperty` rather than `in` because the
+    // object comes from JSON.parse at a trust boundary. Retention on disk is not
+    // decided here: the writers carry every unmanaged key from the file itself
+    // (D-CONFIG-PRESERVE-UNMANAGED).
+    const hasTracker = Object.prototype.hasOwnProperty.call(p, 'tracker');
     return {
-        memory: typeof p.memory === 'boolean' ? p.memory : DEFAULT_CONFIG.memory,
-        learning,
-        knowledge: typeof p.knowledge === 'boolean' ? p.knowledge : DEFAULT_CONFIG.knowledge,
         reviewPublication,
+        ...(hasTracker ? { tracker: p.tracker } : {}),
     };
 }
 /**
- * Read the feature config for a project root.
+ * Read the per-repo config for a project root.
  * Returns DEFAULT_CONFIG when the file is missing or unreadable.
- * Applies ADR-001: .devflow/config.json is the sole source of truth;
- * `devflow init` writes it directly on first install. An absent file falls
- * through to DEFAULT_CONFIG (all features enabled by default).
  */
 export async function readConfig(projectRoot) {
-    const configPath = getFeatureConfigPath(projectRoot);
+    return coerceConfig(await readConfigBody(projectRoot)) ?? { ...DEFAULT_CONFIG };
+}
+/**
+ * The parsed JSON body of a project's config file, or `undefined` when the file
+ * is absent, unreadable or malformed. Every read of the file goes through here,
+ * so readConfig, readConfigIfPresent and writeManagedConfig agree on what an
+ * unusable file means.
+ */
+async function readConfigBody(projectRoot) {
     try {
-        const config = coerceConfig(JSON.parse(await fs.readFile(configPath, 'utf-8')));
-        if (config !== null)
-            return config;
-        return { ...DEFAULT_CONFIG };
+        return JSON.parse(await fs.readFile(getFeatureConfigPath(projectRoot), 'utf-8'));
     }
     catch {
-        return { ...DEFAULT_CONFIG };
+        // ENOENT (absent) or SyntaxError (malformed) — treat as not present
+        return undefined;
     }
 }
 /**
- * Write the feature config for a project root.
+ * Serialise a config body to a project's config file.
  * Creates the .devflow/ directory if missing.
  * Uses an atomic temp+rename pattern to prevent partial reads under concurrent writes.
  */
-export async function writeConfig(projectRoot, config) {
+async function writeConfigBody(projectRoot, body) {
     const configPath = getFeatureConfigPath(projectRoot);
     await fs.mkdir(path.join(projectRoot, '.devflow'), { recursive: true });
     const tmpPath = configPath + '.tmp.' + process.pid;
-    await fs.writeFile(tmpPath, JSON.stringify(config, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+    await fs.writeFile(tmpPath, JSON.stringify(body, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
     await fs.rename(tmpPath, configPath);
 }
 /**
- * Toggle a single feature in the feature config.
- * Reads current config, applies the change, and writes back.
+ * Merge devflow's managed keys over the config body the file already holds.
+ * Pure — returns a new object and never mutates `existing`.
+ *
+ * D-CONFIG-PRESERVE-UNMANAGED (avoids PF-071): `.devflow/config.json` is a
+ * user-editable file that devflow only PARTLY owns. The managed keys come from
+ * `managed`; every other key comes from the file, verbatim and by key presence
+ * — the hand-written per-repo `tracker` override (whose invalid values must
+ * survive so their DEGRADED report can name them) and any key devflow does not
+ * know. The alternative, writing the declared shape, is a silent delete of all
+ * of them on every `devflow init`. Every writer of the file goes through here
+ * (writeManagedConfig, called by init). Only the managed key is copied from
+ * `managed`, by name, so a caller holding a whole FeatureConfig still cannot
+ * overwrite the file's override with its in-memory copy. The retired keys in
+ * RETIRED_CONFIG_KEYS are dropped, not carried. A body that is
+ * not a JSON object (absent, malformed, an array) reads as empty, exactly as
+ * readConfigIfPresent treats it.
  *
- * D1: Non-atomic read-modify-write. Concurrent invocations of `updateFeature`
- * could lose each other's writes. Acceptable here because: (a) devflow CLI
- * commands are single-threaded user-initiated actions, and (b) the window is
- * milliseconds on a local filesystem with no concurrent writers in normal use.
- * If concurrent safety is ever required, replace with an atomic file-swap or
- * a lock file.
+ * This holds under `devflow init --reset` too: a factory reset returns
+ * devflow's own settings to their defaults through `managed`, and leaves the
+ * keys devflow never wrote alone.
  */
-export async function updateFeature(projectRoot, feature, enabled) {
-    const config = await readConfig(projectRoot);
-    await writeConfig(projectRoot, { ...config, [feature]: enabled });
+export function mergeManagedConfig(existing, managed) {
+    const fileKeys = isJsonObject(existing)
+        ? Object.fromEntries(Object.entries(existing).filter(([key]) => !RETIRED_CONFIG_KEYS.has(key)))
+        : {};
+    return {
+        ...fileKeys,
+        reviewPublication: managed.reviewPublication,
+    };
 }
 /**
- * Check whether a specific feature is enabled for the given project root.
+ * Write devflow's managed keys to a project's config, keeping every key it
+ * does not manage (D-CONFIG-PRESERVE-UNMANAGED).
+ *
+ * D1: Non-atomic read-modify-write. A concurrent writer could lose the other's
+ * change. Acceptable because init is a single-threaded, user-initiated command
+ * and the window is milliseconds on a local filesystem; the file swap itself is
+ * atomic (temp + rename), so a reader never sees a partial file.
  */
-export async function isFeatureEnabled(projectRoot, feature) {
-    const config = await readConfig(projectRoot);
-    return config[feature];
+export async function writeManagedConfig(projectRoot, managed) {
+    const existing = await readConfigBody(projectRoot);
+    await writeConfigBody(projectRoot, mergeManagedConfig(existing, managed));
 }
 /**
- * Read the feature config for a project root, returning null when the file
+ * Read the per-repo config for a project root, returning null when the file
  * is absent or malformed.
  *
  * Unlike readConfig (which falls back to DEFAULT_CONFIG on any error),
  * readConfigIfPresent distinguishes "not configured yet" (null) from
- * "configured with specific values" (FeatureConfig).  The distinction
- * matters for init-seed resolution: a present config overrides the
- * manifest for memory/learning/knowledge even when the manifest is absent.
- *
- * Applies ADR-001: .devflow/config.json is the source of truth; null means
- * the config file does not exist or is unreadable — not that all features
- * are disabled.
+ * "configured with specific values" (FeatureConfig). init relies on the
+ * distinction to carry a repo's own reviewPublication across a re-init.
  */
 export async function readConfigIfPresent(projectRoot) {
-    const configPath = getFeatureConfigPath(projectRoot);
-    try {
-        const text = await fs.readFile(configPath, 'utf-8');
-        return coerceConfig(JSON.parse(text)); // null when JSON is not a plain object
-    }
-    catch {
-        // ENOENT (absent) or SyntaxError (malformed) — treat as not present
-        return null;
-    }
+    // null when the file is absent or malformed, or its JSON is not a plain object
+    return coerceConfig(await readConfigBody(projectRoot));
 }
 //# sourceMappingURL=feature-config.js.map

package/dist/core/feature-switch.js

@@ -0,0 +1,112 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { writeFileAtomicExclusive } from './fs-atomic.js';
+function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The pre-rename key each machine feature was stored under, where one exists:
+ * `learning` was `decisions` (ADR-011) and `knowledge` was `kb`. A manifest no
+ * command has rewritten since the rename can still hold only the legacy key.
+ * `memory` was never renamed.
+ */
+const LEGACY_KEYS = {
+    learning: 'decisions',
+    knowledge: 'kb',
+};
+/**
+ * Whether a RAW parsed manifest leaves `feature` switched on. Pure.
+ *
+ * Only an explicit boolean `false` switches a feature off. A missing key, a
+ * non-boolean value, or anything that is not a manifest-shaped object reads as
+ * ON — fail-open (ADR-028), and the exact rule `queue_read_gates` applies in the
+ * shell hooks, so the CLI's status and the runtime never disagree about the
+ * same file.
+ *
+ * D-LEARNING-LEGACY-DECISIONS (a sub-decision of D-FEATURES-MACHINE-WIDE):
+ * `learning` is read as `features.learning` when that is a boolean, else the
+ * legacy `features.decisions` when THAT is a boolean, else ON — readManifest's
+ * migration precedence exactly. The legacy key is otherwise honoured only once
+ * some command happens to run readManifest and heal it, so a `decisions: false`
+ * would keep learning running until then. queue_read_gates applies the same
+ * precedence.
+ *
+ * D-KNOWLEDGE-LEGACY-KB (the same sub-decision for the other renamed key):
+ * `knowledge` is read as `features.knowledge` when that is a boolean, else the
+ * legacy `features.kb` when THAT is a boolean, else ON — again readManifest's
+ * precedence exactly, so `devflow knowledge --status` reports a `kb: false`
+ * as disabled. queue_read_gates never reads knowledge, so there is no shell
+ * mirror. The knowledge write-back prose gate deliberately does not learn the
+ * legacy key (ADR-028: no prompt text for a state only an un-upgraded install
+ * can hold); readManifest rewrites `kb` to `knowledge` on the next CLI run
+ * that loads the manifest, after which that gate reads the healed key.
+ *
+ * Deliberately NOT built on readManifest(): it returns null for a manifest
+ * missing any of its required fields — reported as "on" here, as the hooks read
+ * it — and it writes its heals back to disk, which a read-only status must not.
+ */
+export function isMachineFeatureOn(rawManifest, feature) {
+    if (!isJsonObject(rawManifest))
+        return true;
+    const features = rawManifest.features;
+    if (!isJsonObject(features))
+        return true;
+    const legacyKey = LEGACY_KEYS[feature];
+    const value = legacyKey !== undefined && typeof features[feature] !== 'boolean'
+        ? features[legacyKey]
+        : features[feature];
+    return value !== false;
+}
+/**
+ * Set `feature` in a RAW parsed manifest. Pure — returns a new object and never
+ * mutates its input. Null when the value is not a manifest-shaped object (there
+ * is no `features` record to write into).
+ *
+ * Only `features.<feature>` and `updatedAt` change; every other key is carried
+ * verbatim. Writing `learning` leaves a legacy `decisions` key in place, and
+ * writing `knowledge` a legacy `kb` key, inert: the boolean just written wins
+ * over it (D-LEARNING-LEGACY-DECISIONS, D-KNOWLEDGE-LEGACY-KB). Going through
+ * readManifest()/writeManifest() instead would refuse a manifest that reader
+ * rejects, drop every key ManifestData does not model (one a newer devflow
+ * wrote, say), and persist that reader's unrelated heals as a side effect of a
+ * one-key toggle.
+ */
+export function setMachineFeature(rawManifest, feature, enabled, now) {
+    if (!isJsonObject(rawManifest) || !isJsonObject(rawManifest.features))
+        return null;
+    return {
+        ...rawManifest,
+        features: { ...rawManifest.features, [feature]: enabled },
+        updatedAt: now,
+    };
+}
+async function readRawManifest(devflowDir) {
+    try {
+        return JSON.parse(await fs.readFile(path.join(devflowDir, 'manifest.json'), 'utf-8'));
+    }
+    catch {
+        // ENOENT, EACCES or SyntaxError — no usable manifest.
+        return undefined;
+    }
+}
+/**
+ * Read the machine-wide switch from `<devflowDir>/manifest.json`. Read-only (no
+ * heal write); an absent, unreadable or malformed manifest reads as ON.
+ */
+export async function readMachineFeature(devflowDir, feature) {
+    return isMachineFeatureOn(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
+ * write into — a manifest is created by `devflow init`, never by a toggle,
+ * because a bare `{features: {...}}` file is not a manifest any reader accepts.
+ */
+export async function writeMachineFeature(devflowDir, feature, enabled) {
+    const next = setMachineFeature(await readRawManifest(devflowDir), feature, enabled, new Date().toISOString());
+    if (next === null)
+        return { ok: false, error: 'not-installed' };
+    await writeFileAtomicExclusive(path.join(devflowDir, 'manifest.json'), JSON.stringify(next, null, 2) + '\n');
+    return { ok: true, value: undefined };
+}
+//# sourceMappingURL=feature-switch.js.map

package/dist/core/flags.js

@@ -121,8 +121,8 @@ export const FLAG_REGISTRY = [
         kind: 'boolean',
         target: { type: 'setting', key: 'disableBundledSkills' },
         onPayload: true,
-        recommended: true,
-        defaultValue: true,
+        recommended: false,
+        defaultValue: false,
     },
     {
         id: 'pin-sonnet-4-6',
@@ -133,8 +133,8 @@ export const FLAG_REGISTRY = [
         kind: 'boolean',
         target: { type: 'env', key: 'ANTHROPIC_DEFAULT_SONNET_MODEL' },
         onPayload: 'claude-sonnet-4-6',
-        recommended: true,
-        defaultValue: true,
+        recommended: false,
+        defaultValue: false,
     },
     {
         // Devflow fan-outs routinely exceed the upstream default of 20.