devflow-kit 2.5.0 → 3.0.0

package/dist/core/evidence-policy.js

@@ -12,10 +12,25 @@
  * `~/.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
+ * The same seam loads the sibling `resolve-settings.cjs` (loadSettingsModule),
+ * the local resolver of the per-repository settings layer — `.devflow/project.json`,
+ * the personal `.devflow/config.json` and the machine manifest. Its shapes are
+ * transcribed the same way, and there is no TypeScript copy of its fold either.
+ * It also loads the shared strict parser both resolvers use,
+ * `lib/project-config.cjs` (loadProjectConfigLib), so the CLI judges a config
+ * file's bytes exactly as the resolvers do.
+ *
+ * D-POLICY-NO-WRITE (applies ADR-024): `.devflow/project.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`).
+ * choose to commit (`evidencePolicySuggestion`, and the migration lines of
+ * `repoComplianceStatusLines`), all from the settings resolver's project.json
+ * serializer.
+ *
+ * D-POLICY-JSON-RETIRED: the evidence resolver never parses `.devflow/policy.json`;
+ * at a source whose project.json has no `evidence`, the file's presence alone
+ * resolves `required` (see the resolver's own note). This side neither reads nor
+ * serializes it — it only names it in the migration hint.
  */
 import { createRequire } from 'module';
 import { join } from 'path';
@@ -23,8 +38,14 @@ 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';
+/** Basename of the settings resolver under src/assets/scripts/ (and ~/.devflow/scripts/). */
+export const SETTINGS_SCRIPT_NAME = 'resolve-settings.cjs';
+/** The shared strict config parser, relative to src/assets/scripts/ (and ~/.devflow/scripts/). */
+export const PROJECT_CONFIG_LIB_NAME = join('lib', 'project-config.cjs');
 /** The team file the CLI suggests committing, relative to a repository root. */
-const POLICY_FILE = '.devflow/policy.json';
+const PROJECT_FILE = '.devflow/project.json';
+/** The retired team file project.json's `evidence` replaces, relative to a repository root. */
+const RETIRED_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.
@@ -38,7 +59,20 @@ export const EVIDENCE_POLICY_MODULE_SURFACE = Object.freeze({
     FAIL_CLOSED_LINE: 'string',
     complianceDefault: 'function',
     resolve: 'function',
-    serializePolicy: 'function',
+});
+/** Every key of SettingsModule and the runtime kind the loader requires of it. */
+export const SETTINGS_MODULE_SURFACE = Object.freeze({
+    SETTINGS_LINE_RE: 'regexp',
+    SETTINGS_FAIL_CLOSED_LINE: 'string',
+    resolveSettings: 'function',
+    serializeProjectSuggestion: 'function',
+});
+/** Every key of ProjectConfigLib and the runtime kind the loader requires of it. */
+export const PROJECT_CONFIG_LIB_SURFACE = Object.freeze({
+    MAX_CONFIG_BYTES: 'number',
+    decodeConfigBytes: 'function',
+    readBoundedRegularFile: 'function',
+    collectDuplicateKeyPaths: 'function',
 });
 function hasKind(value, kind) {
     switch (kind) {
@@ -46,6 +80,7 @@ function hasKind(value, kind) {
         case 'object': return typeof value === 'object' && value !== null;
         case 'regexp': return value instanceof RegExp;
         case 'string': return typeof value === 'string';
+        case 'number': return typeof value === 'number' && Number.isFinite(value);
         case 'function': return typeof value === 'function';
         default: {
             const exhaustive = kind;
@@ -54,21 +89,21 @@ function hasKind(value, kind) {
     }
 }
 /** Surface keys that are absent or of the wrong kind on `value`, in surface order. */
-function surfaceMismatches(value) {
+function surfaceMismatches(value, surface) {
     if (typeof value !== 'object' || value === null)
-        return Object.keys(EVIDENCE_POLICY_MODULE_SURFACE);
+        return Object.keys(surface);
     const record = value;
-    return Object.entries(EVIDENCE_POLICY_MODULE_SURFACE)
+    return Object.entries(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`.
+ * require() one package script and shape-check it against `surface`. Never
+ * throws: a missing file is `not-found`; a module that throws on load or lacks a
+ * surface key is `unusable`. The caller's type parameter is justified by the
+ * surface check, which `satisfies` ties to the interface's keys.
  */
-export function loadEvidencePolicyModule(dir = scriptsDir()) {
-    const file = join(dir, RESOLVER_SCRIPT_NAME);
+function loadScript(file, surface) {
     let loaded;
     try {
         loaded = createRequire(import.meta.url)(file);
@@ -80,12 +115,34 @@ export function loadEvidencePolicyModule(dir = scriptsDir()) {
         const detail = err instanceof Error ? err.message : String(err);
         return { ok: false, error: { kind: 'unusable', path: file, detail } };
     }
-    const mismatches = surfaceMismatches(loaded);
+    const mismatches = surfaceMismatches(loaded, surface);
     if (mismatches.length > 0) {
         return { ok: false, error: { kind: 'unusable', path: file, detail: `missing or mistyped: ${mismatches.join(', ')}` } };
     }
     return { ok: true, value: loaded };
 }
+/**
+ * Load the evidence resolver from `dir` (default: the package's own scripts
+ * directory) and shape-check its surface.
+ */
+export function loadEvidencePolicyModule(dir = scriptsDir()) {
+    return loadScript(join(dir, RESOLVER_SCRIPT_NAME), EVIDENCE_POLICY_MODULE_SURFACE);
+}
+/**
+ * Load the settings resolver from `dir` (default: the package's own scripts
+ * directory) and shape-check its surface. A `resolveSettings()` call makes one
+ * local `git` call and no network call (D-SETTINGS-LOCAL-ONLY).
+ */
+export function loadSettingsModule(dir = scriptsDir()) {
+    return loadScript(join(dir, SETTINGS_SCRIPT_NAME), SETTINGS_MODULE_SURFACE);
+}
+/**
+ * Load the shared strict config parser from `dir` (default: the package's own
+ * scripts directory) and shape-check its surface.
+ */
+export function loadProjectConfigLib(dir = scriptsDir()) {
+    return loadScript(join(dir, PROJECT_CONFIG_LIB_NAME), PROJECT_CONFIG_LIB_SURFACE);
+}
 // ── Presentation (pure) ────────────────────────────────────────────────────────
 /** `Evidence policy: <policy> (source: <source>)`, plus ` [warn: a, b]` when warnings exist. */
 export function formatEvidencePolicyStatus(r) {
@@ -111,7 +168,7 @@ export function formatEvidencePolicyUnavailable(error) {
  * 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
+ * manifest is never read twice. `resolve()` makes at most three `gh` calls and
  * bounds every subprocess with a timeout, so an offline machine degrades to a
  * flagged result rather than a hang.
  */
@@ -121,27 +178,186 @@ export function evidencePolicyStatusLine(loaded, opts) {
     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
+ * The frameworks a compliance state names, for the suggestion: the raw list when
+ * the state is well-formed, else none. The settings resolver's serializer
+ * normalizes and drops unknown ids, so no id reaches the printed bytes unchecked.
+ */
+function suggestedFrameworks(complianceState) {
+    if (typeof complianceState !== 'object' || complianceState === null)
+        return [];
+    const frameworks = complianceState.frameworks;
+    return Array.isArray(frameworks) && frameworks.every(f => typeof f === 'string') ? frameworks : [];
+}
+/**
+ * What `--enable`/`--set` print when compliance is on: the keys to add to a
+ * repository's `.devflow/project.json` on its default branch — merged into the
+ * file when it already has one, never replacing it — to hold every developer to
+ * what this machine now gets by default: the required evidence policy and this
+ * machine's frameworks. Returned only when the evidence 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).
+ * count); `null` otherwise. The bytes come
+ * from the settings resolver's `serializeProjectSuggestion`, which returns them
+ * only when they read back through the shared parser as exactly what was asked.
+ * Nothing is written (D-POLICY-NO-WRITE, applies ADR-024).
  */
-export function evidencePolicySuggestion(complianceState, mod) {
-    if (mod.complianceDefault(complianceState) !== 'required')
+export function evidencePolicySuggestion(complianceState, policy, settings) {
+    if (policy.complianceDefault(complianceState) !== 'required')
         return null;
-    const body = mod.serializePolicy('required');
+    const body = settings.serializeProjectSuggestion({
+        evidence: 'required',
+        compliance: suggestedFrameworks(complianceState),
+    });
     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:`,
+        'evidence setting default to the required evidence policy here. To apply it for',
+        `everyone working in a repository, add these keys to its ${PROJECT_FILE} on its`,
+        'default branch — merged into the file when it already has one, never replacing it:',
         '',
         `${body}`,
         'devflow never writes this file: the team owns it, and once committed it applies',
         'repo-wide.',
     ].join('\n');
 }
+// ── The settings layer, for `--status` (pure) ──────────────────────────────────
+/** A repo layer's file, as a `--status` line names it. */
+export function settingsSourceFile(source) {
+    switch (source) {
+        case 'project': return PROJECT_FILE;
+        case 'personal': return '.devflow/config.json';
+        default: {
+            const exhaustive = source;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * The effective state of a feature switch in this repository, ONLY when a repo
+ * layer narrows it — `disabled (.devflow/project.json)` — and null otherwise, so a
+ * `--status` whose machine switch alone decides prints exactly what it always has
+ * (D-FEATURES-NARROW-ONLY). A repository file that exists but is unreadable fails
+ * every field closed but the compliance lens, and a switch that closed off is
+ * labelled with that file —
+ * `disabled (.devflow/project.json is unreadable)` — since commands act on it. Any
+ * other failure (the resolver failed to load, or git could not answer) yields
+ * null: it knows nothing about this repository.
+ */
+export function narrowedSwitchLabel(loaded, opts, feature) {
+    if (!loaded.ok)
+        return null;
+    const settings = loaded.value.resolveSettings(opts);
+    if (!settings.ok) {
+        if (settings.unreadable === null || settings.switches[feature].on)
+            return null;
+        return `disabled (${settingsSourceFile(settings.unreadable)} is unreadable)`;
+    }
+    const state = settings.switches[feature];
+    if (state.on || state.source === 'machine')
+        return null;
+    return `disabled (${settingsSourceFile(state.source)})`;
+}
+/**
+ * The tracker in effect in the repository at `opts.dir`, ONLY when a repository
+ * layer decides it — its committed project.json, or the personal config.json
+ * narrowing — and null otherwise. A machine whose own selection (or the github
+ * default) decides gets null, so `tracker --status` prints exactly what it always
+ * has there. So does a resolver that failed to load or failed closed: it knows
+ * nothing about this repository, and a fail-closed `github` is not a selection
+ * anyone made.
+ */
+export function repoTrackerSelection(loaded, opts) {
+    if (!loaded.ok)
+        return null;
+    const settings = loaded.value.resolveSettings(opts);
+    if (!settings.ok)
+        return null;
+    const source = settings.trackerSource;
+    if (source !== 'project' && source !== 'personal')
+        return null;
+    return { provider: settings.tracker, source };
+}
+/** A declared id list as a `--status` line shows it. */
+function idsLabel(ids) {
+    return ids.length > 0 ? ids.join(', ') : 'generic controls only';
+}
+/**
+ * The `compliance --status` lines about the repository in `opts.dir`, mirroring
+ * the resolver's lens fold (D-LENS-UNION: machine ∪ default branch ∪ worktree):
+ * the ids this checkout's project.json declares (`generic controls only` for an
+ * empty or malformed list), the ids the default branch's copy declares, the
+ * effective lens those add up to with the machine's, and a migration hint while
+ * the retired policy file is in the working tree.
+ *
+ * A broken file affects only the keys it owns. An unreadable project.json is a
+ * malformed declaration — generic — and says so, naming the file; an unreadable
+ * config.json owns no compliance, so the lines are those of a readable one. Empty
+ * when the resolver is unavailable or failed closed for any other reason, or no
+ * repository layer declares anything and there is no policy file — the status
+ * output is then unchanged.
+ *
+ * The hint states the rule (D-POLICY-JSON-RETIRED): the file is not read, and
+ * while project.json has no `evidence` its presence holds the repository at
+ * `required`. The value is not read either, so the hint shows the project.json
+ * line for each value the file may hold, from the settings resolver's serializer.
+ */
+export function repoComplianceStatusLines(loaded, opts) {
+    if (!loaded.ok)
+        return [];
+    const settings = loaded.value.resolveSettings(opts);
+    if (!settings.ok && settings.unreadable === null)
+        return [];
+    const lines = [];
+    if (settings.unreadable === 'project') {
+        lines.push(`Repository: generic controls only (${PROJECT_FILE} is unreadable)`);
+    }
+    else if (settings.repoCompliance !== null) {
+        lines.push(`Repository: ${idsLabel(settings.repoCompliance)} (${PROJECT_FILE})`);
+    }
+    if (settings.defaultBranchCompliance !== null) {
+        lines.push(`Default branch: ${idsLabel(settings.defaultBranchCompliance)} (its ${PROJECT_FILE})`);
+    }
+    if (lines.length > 0) {
+        const lens = settings.compliance;
+        lines.push(`Effective here: ${lens.enabled ? idsLabel(lens.frameworks) : 'off'} (this machine + the default branch + this checkout)`);
+    }
+    if (settings.retiredPolicyFile)
+        lines.push(...retiredPolicyHint(loaded.value));
+    return lines;
+}
+/**
+ * The warning a `--status` prints when this checkout's `.devflow/config.json` is
+ * 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.
+ */
+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}`;
+}
+/** The policies the hint maps, in the order it prints them. */
+const HINT_POLICIES = ['standard', 'required'];
+/**
+ * The migration hint for a working tree holding the retired policy file: what the
+ * file does now, and the project.json line that states each value it may hold.
+ * A value whose line the serializer refuses is left out rather than hand-built.
+ */
+function retiredPolicyHint(settings) {
+    const mappings = HINT_POLICIES.flatMap((policy) => {
+        const body = settings.serializeProjectSuggestion({ evidence: policy });
+        return body === null ? [] : [`              ${policy.padEnd(8)}  →  ${body.trimEnd()}`];
+    });
+    return [
+        `Migration:  ${RETIRED_POLICY_FILE} is not read. While ${PROJECT_FILE} has no "evidence",`,
+        '            its presence alone holds this repository at required. Add its value to',
+        `            ${PROJECT_FILE} as "evidence", and keep ${RETIRED_POLICY_FILE} until every`,
+        `            teammate runs devflow 3.0 or later; only then delete it:`,
+        ...mappings,
+    ];
+}
 //# sourceMappingURL=evidence-policy.js.map

package/dist/core/feature-config.js

@@ -2,16 +2,19 @@ import * as path from 'path';
 import { promises as fs } from 'fs';
 import { getFeatureConfigPath } from './project-paths.js';
 import { parseTrackerId } from './tracker.js';
+import { loadProjectConfigLib } from './evidence-policy.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.
+ * D-FEATURES-NARROW-ONLY: `memory`, `learning` and `knowledge` were top-level
+ * per-repo feature switches from the per-repo-install era. A repository now
+ * narrows a feature only through the `features` namespace, so a stale top-level
+ * 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. `features` is deliberately NOT here — it is a live key,
+ * carried like any other unmanaged key (avoids PF-071).
  */
 const RETIRED_CONFIG_KEYS = new Set([
     'memory', 'learning', 'knowledge', 'decisions', 'autoCommit',
@@ -65,7 +68,7 @@ function isJsonObject(value) {
  * DEFAULT_CONFIG. Pure function — no I/O, no side effects.
  *
  * 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).
+ * still hold them, and none of them decides anything (D-FEATURES-NARROW-ONLY).
  *
  * Returns null when `parsed` is not a plain object (caller falls through to
  * the next candidate path).
@@ -99,25 +102,72 @@ function coerceConfig(parsed) {
 }
 /**
  * Read the per-repo config for a project root.
- * Returns DEFAULT_CONFIG when the file is missing or unreadable.
+ * Returns DEFAULT_CONFIG when the file is missing or unusable.
  */
 export async function readConfig(projectRoot) {
-    return coerceConfig(await readConfigBody(projectRoot)) ?? { ...DEFAULT_CONFIG };
+    return coerceConfig(objectOf(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.
+ * Classify a config file's bytes (`null` is no file). Pure.
+ *
+ * D-CONFIG-STRICT-PARSE: `.devflow/config.json` is judged by the one parser the
+ * resolvers use (lib/project-config.cjs, D-PROJECT-STRICT-KEYS), never by a bare
+ * `JSON.parse`. The two disagreed where it mattered: `JSON.parse` keeps the
+ * LAST of two duplicate keys silently, while the resolvers read the file as
+ * saying two things and fail its keys closed — so devflow could rewrite a file
+ * into a meaning it never had. A file the parser rejects is `malformed`.
  */
-async function readConfigBody(projectRoot) {
+export function classifyConfigBytes(buf, lib) {
+    const decoded = lib.decodeConfigBytes(buf);
+    if (decoded.kind === 'absent')
+        return { kind: 'absent' };
+    if (decoded.kind === 'invalid')
+        return { kind: 'malformed' };
+    let parsed;
     try {
-        return JSON.parse(await fs.readFile(getFeatureConfigPath(projectRoot), 'utf-8'));
+        parsed = JSON.parse(decoded.text);
     }
     catch {
-        // ENOENT (absent) or SyntaxError (malformed) — treat as not present
-        return undefined;
+        return { kind: 'malformed' };
+    }
+    if (!isJsonObject(parsed))
+        return { kind: 'malformed' };
+    const duplicates = lib.collectDuplicateKeyPaths(decoded.text);
+    if (duplicates === null || duplicates.size > 0)
+        return { kind: 'malformed' };
+    return { kind: 'object', value: parsed };
+}
+/** The object a config body holds, or undefined for any other body. */
+function objectOf(body) {
+    return body.kind === 'object' ? body.value : undefined;
+}
+/**
+ * Read and classify a project's config file. Every read of the file goes
+ * through here, so readConfig, readConfigIfPresent and writeManagedConfig agree
+ * on what an unusable file means. Never throws.
+ *
+ * D-CONFIG-NO-FOLLOW: the bytes come from the resolvers' own bounded read
+ * (lib/project-config.cjs readBoundedRegularFile, `followSymlinks` false — the
+ * read resolve-settings' readConfigFile makes), so devflow and the settings line
+ * never disagree about which file configures the repository. A symlink —
+ * dangling or not — a directory, a FIFO or a file over MAX_CONFIG_BYTES is
+ * refused unopened and reads as `unreadable`: readers configure nothing from it,
+ * and writeManagedConfig leaves it in place (D-CONFIG-NO-REPAIR) rather than
+ * writing through the link or renaming a regular file over it.
+ */
+async function readConfigBody(projectRoot, lib = loadProjectConfigLib()) {
+    if (!lib.ok)
+        return { kind: 'unreadable', detail: `config parser unavailable: ${lib.error.path}` };
+    const read = lib.value.readBoundedRegularFile(getFeatureConfigPath(projectRoot), lib.value.MAX_CONFIG_BYTES, false);
+    if (read.kind === 'absent')
+        return { kind: 'absent' };
+    if (read.kind === 'refused') {
+        return {
+            kind: 'unreadable',
+            detail: `not a regular file of at most ${lib.value.MAX_CONFIG_BYTES} bytes; a symlink is never followed`,
+        };
     }
+    return classifyConfigBytes(read.bytes, lib.value);
 }
 /**
  * Serialise a config body to a project's config file.
@@ -146,8 +196,8 @@ async function writeConfigBody(projectRoot, body) {
  * `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.
+ * not a JSON object reads as empty, exactly as readConfigIfPresent treats it;
+ * writeManagedConfig never reaches here with a malformed file.
  *
  * This holds under `devflow init --reset` too: a factory reset returns
  * devflow's own settings to their defaults through `managed`, and leaves the
@@ -164,16 +214,35 @@ export function mergeManagedConfig(existing, managed) {
 }
 /**
  * Write devflow's managed keys to a project's config, keeping every key it
- * does not manage (D-CONFIG-PRESERVE-UNMANAGED).
+ * does not manage (D-CONFIG-PRESERVE-UNMANAGED). Never throws.
+ *
+ * D-CONFIG-NO-REPAIR: a file that exists but is malformed or unreadable
+ * (D-CONFIG-STRICT-PARSE) is left byte-for-byte as it is, and the Result says
+ * why. The file is the user's: a syntax error in it still holds their
+ * hand-written keys — the `tracker` override first among them — and a rewrite
+ * from an empty merge would delete them silently. The resolvers fail its keys
+ * closed meanwhile, so leaving it costs nothing but the managed key.
  *
  * 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 writeManagedConfig(projectRoot, managed) {
-    const existing = await readConfigBody(projectRoot);
-    await writeConfigBody(projectRoot, mergeManagedConfig(existing, managed));
+export async function writeManagedConfig(projectRoot, managed, lib = loadProjectConfigLib()) {
+    const configPath = getFeatureConfigPath(projectRoot);
+    const existing = await readConfigBody(projectRoot, lib);
+    if (existing.kind === 'malformed')
+        return { ok: false, error: { kind: 'malformed', path: configPath } };
+    if (existing.kind === 'unreadable') {
+        return { ok: false, error: { kind: 'unreadable', path: configPath, detail: existing.detail } };
+    }
+    try {
+        await writeConfigBody(projectRoot, mergeManagedConfig(objectOf(existing), managed));
+    }
+    catch (err) {
+        return { ok: false, error: { kind: 'write-failed', path: configPath, detail: err instanceof Error ? err.message : String(err) } };
+    }
+    return { ok: true };
 }
 /**
  * Read the per-repo config for a project root, returning null when the file
@@ -185,7 +254,7 @@ export async function writeManagedConfig(projectRoot, managed) {
  * distinction to carry a repo's own reviewPublication across a re-init.
  */
 export async function readConfigIfPresent(projectRoot) {
-    // null when the file is absent or malformed, or its JSON is not a plain object
-    return coerceConfig(await readConfigBody(projectRoot));
+    // null when the file is absent, malformed or unreadable
+    return coerceConfig(objectOf(await readConfigBody(projectRoot)));
 }
 //# sourceMappingURL=feature-config.js.map

package/dist/core/feature-switch.js

@@ -23,7 +23,7 @@ const LEGACY_KEYS = {
  * 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):
+ * D-LEARNING-LEGACY-DECISIONS (a sub-decision of D-FEATURES-NARROW-ONLY):
  * `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

package/dist/core/flags.js

@@ -1259,7 +1259,35 @@ export function convergeFlagsIntoSettings(settingsJson, record, opts) {
     }
     // ── Step 3: strip all managed keys, then apply the folded record ──────────
     const stripped = stripFlags(settingsJson);
-    const settings = applyFlags(stripped, folded);
-    return { settings, record: folded };
+    const applied = JSON.parse(applyFlags(stripped, folded));
+    // ── Step 4: restore the pre-strip key order (D-KEY-ORDER) ────────────────
+    const ordered = orderKeysLike(parsed, applied);
+    const beforeEnv = asPlainObject(parsed.env);
+    const afterEnv = asPlainObject(ordered.env);
+    const settings = beforeEnv && afterEnv
+        ? { ...ordered, env: orderKeysLike(beforeEnv, afterEnv) }
+        : ordered;
+    return { settings: JSON.stringify(settings, null, 2) + '\n', record: folded };
+}
+/**
+ * Return `after`'s entries ordered as `before` had them: every key `before` held,
+ * in `before`'s order, then the keys only `after` holds, in `after`'s order.
+ *
+ * D-KEY-ORDER: strip-then-apply deletes every managed key and re-adds it, so each
+ * one lands after whatever key followed it on disk. init merges the security deny
+ * list AFTER the flags, which appends `permissions` behind them; a second init then
+ * moved the flags behind `permissions` and re-init stopped being a no-op on disk
+ * (#388 AC-3). Keeping the pre-converge order makes the first run's order the stable
+ * one: a key that stays keeps its place, a key the record newly sets is appended, a
+ * key it drops is simply absent. Values are `after`'s — only the order is borrowed.
+ *
+ * `Object.fromEntries` defines each key as an own data property, so a `__proto__`
+ * key parsed from settings.json stays a key rather than becoming the prototype.
+ */
+function orderKeysLike(before, after) {
+    const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+    const kept = Object.keys(before).filter(k => has(after, k));
+    const added = Object.keys(after).filter(k => !has(before, k));
+    return Object.fromEntries([...kept, ...added].map(k => [k, after[k]]));
 }
 //# sourceMappingURL=flags.js.map

package/dist/core/fs-atomic.js

@@ -71,4 +71,31 @@ export async function writeFileAtomicExclusive(filePath, data) {
     }
     await fs.rename(tmp, filePath);
 }
+/**
+ * Write a Claude Code settings file (`settings.json`) atomically.
+ *
+ * D-SETTINGS-ATOMIC: every write of a Claude settings file goes through this one
+ * helper, so no command can leave a half-written file for Claude Code — or a
+ * concurrent devflow command — to read: the bytes land in a sibling temp file
+ * and one rename swaps them in ({@link writeFileAtomicExclusive}).
+ *
+ * A settings file that is a symbolic link (a dotfiles-managed `settings.json`)
+ * stays one: the temp file and the rename target the link's resolved file, so
+ * the link keeps pointing where the user pointed it. A dangling link has no file
+ * to resolve and is replaced like a missing file.
+ */
+export async function writeSettingsFileAtomic(filePath, data) {
+    await writeFileAtomicExclusive(await resolveLinkedFile(filePath), data);
+}
+/** `filePath`, or the file it resolves to when it is a symbolic link that resolves. */
+async function resolveLinkedFile(filePath) {
+    try {
+        if (!(await fs.lstat(filePath)).isSymbolicLink())
+            return filePath;
+        return await fs.realpath(filePath);
+    }
+    catch {
+        return filePath;
+    }
+}
 //# sourceMappingURL=fs-atomic.js.map