devflow-kit 2.5.0 → 3.0.0

package/dist/cli/commands/compliance.js

@@ -7,18 +7,19 @@
  * Avoids PF-009: per-artifact failures are warn-not-throw.
  * Avoids PF-015: enable/disable each converge BOTH artifacts unconditionally.
  * The evidence-policy lines (--status, and the --enable/--set suggestion) come
- *   from src/core/evidence-policy.ts, the seam onto the package's own resolver;
- *   the CLI prints .devflow/policy.json and never writes it (applies ADR-024).
+ *   from src/core/evidence-policy.ts, the seam onto the package's own resolvers;
+ *   the CLI prints the keys to add to .devflow/project.json and never writes it
+ *   (applies ADR-024).
  */
 import { Command } from 'commander';
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
-import { ALWAYS_PRESENT_REFS, COMPLIANCE_FRAMEWORKS, normalizeFrameworks, parseFrameworkList, } from '../../core/compliance.js';
+import { COMPLIANCE_FRAMEWORKS, normalizeFrameworks, parseFrameworkList, } from '../../core/compliance.js';
 import { frameworkChoices, FRAMEWORK_SELECT_MESSAGE } from './compliance-prompts.js';
 import { COMPLIANCE_SKILL_TOKENS } from '../../core/compliance-compose.js';
-import { evidencePolicyStatusLine, evidencePolicySuggestion, formatEvidencePolicyUnavailable, loadEvidencePolicyModule, } from '../../core/evidence-policy.js';
+import { evidencePolicyStatusLine, evidencePolicySuggestion, formatEvidencePolicyUnavailable, loadEvidencePolicyModule, loadSettingsModule, repoComplianceStatusLines, } from '../../core/evidence-policy.js';
 import { readManifest, writeManifest } from '../../core/manifest.js';
 import { convergeFromManifest } from '../../targets/claude-code/compliance-install.js';
 import { validateRuleShadow, validateSkillShadow } from '../../targets/claude-code/installer.js';
@@ -65,7 +66,7 @@ export function resolveComplianceCliAction(current, action, setFrameworks) {
                 messages: [
                     {
                         level: 'success',
-                        text: 'Compliance disabled — artifacts removed, frameworks remembered for re-enable',
+                        text: 'Compliance disabled — rule removed, frameworks remembered for re-enable',
                     },
                 ],
             };
@@ -93,23 +94,17 @@ export function resolveComplianceCliAction(current, action, setFrameworks) {
         }
     }
 }
-// ── Drift classification ───────────────────────────────────────────────────────
+// ── Manifest classification ────────────────────────────────────────────────────
 /**
- * Classify a list of manifest framework IDs that are not currently installed.
- * Separates valid (registry-known) IDs from invalid (unknown) IDs so the status
- * display can recommend the correct remediation for each class.
+ * The manifest framework IDs the registry does not know — a hand-edited or
+ * newer-devflow manifest. Every install drops them (normalizeFrameworks), so
+ * `--status` names them with the one remedy that removes them: `--set`.
  *
- * Called by the --status handler to compute drift between the manifest and
- * installed artifacts. Also exported to allow unit testing of the classification
- * logic in isolation.
+ * Installed reference files are no drift signal: every install carries all six
+ * (D-COMPLIANCE-INSTALL-ALWAYS), whatever the manifest selects.
  */
-export function classifyDriftMissing(manifestFrameworks, installedRefIds, registryIds) {
-    const installedSet = new Set(installedRefIds);
-    const missing = manifestFrameworks.filter(id => !installedSet.has(id));
-    return {
-        validMissing: missing.filter(id => registryIds.has(id)),
-        invalidIds: missing.filter(id => !registryIds.has(id)),
-    };
+export function unknownFrameworkIds(manifestFrameworks, registryIds) {
+    return manifestFrameworks.filter(id => !registryIds.has(id));
 }
 // ── Status helpers ─────────────────────────────────────────────────────────────
 /** Returns true if the compliance skill dir exists at the install target. */
@@ -122,23 +117,6 @@ async function skillInstalled(claudeDir) {
         return false;
     }
 }
-/** Returns the set of installed framework reference IDs from the skill dir. */
-async function installedRefIds(claudeDir) {
-    const refDir = path.join(claudeDir, 'skills', 'devflow:compliance', 'references');
-    try {
-        const entries = await fs.readdir(refDir);
-        return entries
-            .filter(e => e.endsWith('.md') && !ALWAYS_PRESENT_REFS.includes(e))
-            .map(e => path.basename(e, '.md'))
-            // S58: sanitize — keep only entries whose basename matches the expected id
-            // shape (lowercase letters, digits, hyphens). Strips terminal-escape sequences
-            // or path segments that could be injected via a crafted filename.
-            .filter(id => /^[a-z0-9-]+$/.test(id));
-    }
-    catch {
-        return [];
-    }
-}
 /** Returns true if the compliance rule file exists at the install target. */
 async function ruleInstalled(claudeDir) {
     try {
@@ -180,7 +158,7 @@ async function skillShadowState(devflowDir) {
 export const complianceCommand = new Command('compliance')
     .description('Enable, disable, or configure the compliance feature')
     .option('--enable', 'Enable compliance (restores previously selected frameworks)')
-    .option('--disable', 'Disable compliance (artifacts removed; frameworks remembered for re-enable)')
+    .option('--disable', 'Disable compliance (rule removed; frameworks remembered for re-enable)')
     .option('--status', 'Show compliance state: manifest, installed artifacts, shadow presence, and the evidence policy for the current repository')
     .option('--set <list>', 'Set active frameworks (comma-separated IDs); enables compliance. Use --set "" for zero frameworks (generic controls only)')
     .action(async (options) => {
@@ -221,24 +199,22 @@ export const complianceCommand = new Command('compliance')
             ? current.frameworks.join(', ')
             : color.dim('none declared');
         const rulesEnabled = manifest.features.rules;
-        const [skillOk, refIds, ruleOk, isRuleShadowed, skillShadow] = await Promise.all([
+        const [skillOk, ruleOk, isRuleShadowed, skillShadow] = await Promise.all([
             skillInstalled(claudeDir),
-            installedRefIds(claudeDir),
             ruleInstalled(claudeDir),
             ruleShadowed(devflowDir),
             skillShadowState(devflowDir),
         ]);
-        // Detect framework drift: manifest says X, installed refs say Y.
-        // Invalid IDs (not in the registry) are reported separately from valid-but-missing
-        // IDs so the suggested remediation is correct: --enable can reconcile valid IDs,
-        // but only --set can remove IDs that are not in the registry.
-        const registrySet = new Set(COMPLIANCE_FRAMEWORKS.map(fw => fw.id));
-        const manifestSet = new Set(current.frameworks);
-        const driftInstalled = refIds.filter(id => !manifestSet.has(id));
-        const { validMissing, invalidIds } = classifyDriftMissing(current.frameworks, refIds, registrySet);
+        const invalidIds = unknownFrameworkIds(current.frameworks, new Set(COMPLIANCE_FRAMEWORKS.map(fw => fw.id)));
+        // The repository's own declaration (.devflow/project.json) and, while the
+        // retired policy file is in the working tree, the hint to migrate it. Both come from
+        // the local settings resolver — one git call, no network — and add nothing
+        // when the repository declares nothing (the block is then unchanged).
+        const repoLines = repoComplianceStatusLines(loadSettingsModule(), { dir: process.cwd() });
         const lines = [
             `State:      ${enabledLabel}`,
             `Frameworks: ${fwLabel}`,
+            ...repoLines,
             '',
             `Skill:      ${skillOk ? color.green('installed') : color.dim('not installed')}` +
                 (skillShadow === 'composition-skipped'
@@ -254,20 +230,11 @@ export const complianceCommand = new Command('compliance')
             '',
             // The repository in cwd, resolved by the package's own resolver with the
             // compliance state already read above (D-POLICY-CJS-SEAM). Bounded: at most
-            // two `gh` calls, each with a timeout, so offline degrades to a flagged line.
+            // three `gh` calls, each with a timeout, so offline degrades to a flagged line.
             evidencePolicyStatusLine(loadEvidencePolicyModule(), { dir: process.cwd(), compliance: current }),
         ];
-        if (driftInstalled.length > 0 || validMissing.length > 0 || invalidIds.length > 0) {
+        if (invalidIds.length > 0) {
             lines.push('');
-            if (driftInstalled.length > 0 || validMissing.length > 0) {
-                lines.push(color.yellow('Artifact drift detected (run devflow compliance --enable to reconcile):'));
-                if (driftInstalled.length > 0) {
-                    lines.push(`  Installed not in manifest: ${driftInstalled.join(', ')}`);
-                }
-                if (validMissing.length > 0) {
-                    lines.push(`  In manifest but not installed: ${validMissing.join(', ')}`);
-                }
-            }
             for (const id of invalidIds) {
                 lines.push(color.red(`  unknown framework id in manifest (ignored): ${id} — remove with --set`));
             }
@@ -342,15 +309,19 @@ export const complianceCommand = new Command('compliance')
         p.log.info(color.dim('Note: compliance rule withheld (rules disabled) — ' +
             'run `devflow rules --enable` to install the stamped rule'));
     }
-    // Suggest the team policy file compliance now implies. Printed, never written:
-    // .devflow/policy.json is team-owned (D-POLICY-NO-WRITE, applies ADR-024).
+    // Suggest the team file compliance now implies. Printed, never written:
+    // .devflow/project.json is team-owned (D-POLICY-NO-WRITE, applies ADR-024).
     if (resolved.nextState.enabled) {
         const policyModule = loadEvidencePolicyModule();
+        const settingsModule = loadSettingsModule();
         if (!policyModule.ok) {
             p.log.warn(formatEvidencePolicyUnavailable(policyModule.error));
         }
+        else if (!settingsModule.ok) {
+            p.log.warn(formatEvidencePolicyUnavailable(settingsModule.error));
+        }
         else {
-            const suggestion = evidencePolicySuggestion(resolved.nextState, policyModule.value);
+            const suggestion = evidencePolicySuggestion(resolved.nextState, policyModule.value, settingsModule.value);
             if (suggestion !== null)
                 p.note(suggestion, 'Evidence policy');
         }

package/dist/cli/commands/context.js

@@ -1,9 +1,16 @@
-import * as path from 'path';
+import { devflowHookOwner, hasHook, removeHooks, runHookCommand, } from '../../targets/claude-code/hooks.js';
 // ─── Context hook utilities ────────────────────────────────────────────────
 //
 // The session-start-context hook is always-on (registered unconditionally by
 // init, removed by uninstall). It has internal sentinel awareness per feature.
 const CONTEXT_HOOK_MARKER = 'session-start-context';
+/**
+ * D-EXACT-HOOK-OWNER: the context hook is devflow's only when its command ends in
+ * `/scripts/hooks/run-hook session-start-context` (hooks.ts), under any directory.
+ * It has been registered through run-hook since it first shipped, so there is no
+ * legacy form to recognise.
+ */
+const isContextHook = devflowHookOwner([CONTEXT_HOOK_MARKER]);
 /**
  * Add the session-start-context hook to SessionStart in settings JSON.
  * Idempotent — returns unchanged JSON if hook already present.
@@ -13,46 +20,24 @@ export function addContextHook(settingsJson, devflowDir) {
         return settingsJson;
     }
     const settings = JSON.parse(settingsJson);
-    if (!settings.hooks) {
-        settings.hooks = {};
-    }
-    const hookCommand = path.join(devflowDir, 'scripts', 'hooks', 'run-hook') + ` ${CONTEXT_HOOK_MARKER}`;
-    const newEntry = {
-        hooks: [
-            {
-                type: 'command',
-                command: hookCommand,
-                timeout: 10,
-            },
-        ],
-    };
-    if (!settings.hooks.SessionStart) {
-        settings.hooks.SessionStart = [];
-    }
-    settings.hooks.SessionStart.push(newEntry);
+    settings.hooks ??= {};
+    settings.hooks.SessionStart ??= [];
+    settings.hooks.SessionStart.push({
+        hooks: [{ type: 'command', command: runHookCommand(devflowDir, CONTEXT_HOOK_MARKER), timeout: 10 }],
+    });
     return JSON.stringify(settings, null, 2) + '\n';
 }
 /**
  * Remove the session-start-context hook from settings JSON.
  * Idempotent — returns unchanged JSON if hook not present.
- * Preserves all other SessionStart hooks.
+ * Removes the single hook, so the other hooks of its matcher group and every
+ * other SessionStart group stay in place (D-EXACT-HOOK-OWNER).
  */
 export function removeContextHook(settingsJson) {
     const settings = JSON.parse(settingsJson);
-    if (!settings.hooks?.SessionStart) {
+    if (!removeHooks(settings, 'SessionStart', isContextHook)) {
         return settingsJson;
     }
-    const before = settings.hooks.SessionStart.length;
-    settings.hooks.SessionStart = settings.hooks.SessionStart.filter((matcher) => !matcher.hooks.some((h) => h.command.includes(CONTEXT_HOOK_MARKER)));
-    if (settings.hooks.SessionStart.length === before) {
-        return settingsJson;
-    }
-    if (settings.hooks.SessionStart.length === 0) {
-        delete settings.hooks.SessionStart;
-    }
-    if (Object.keys(settings.hooks).length === 0) {
-        delete settings.hooks;
-    }
     return JSON.stringify(settings, null, 2) + '\n';
 }
 /**
@@ -61,6 +46,6 @@ export function removeContextHook(settingsJson) {
  */
 export function hasContextHook(input) {
     const settings = typeof input === 'string' ? JSON.parse(input) : input;
-    return settings.hooks?.SessionStart?.some((matcher) => matcher.hooks.some((h) => h.command.includes(CONTEXT_HOOK_MARKER))) ?? false;
+    return hasHook(settings, 'SessionStart', isContextHook);
 }
 //# sourceMappingURL=context.js.map

package/dist/cli/commands/debug.js

@@ -4,17 +4,47 @@ import * as path from 'path';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
 import { getClaudeDirectory, getHomeDirectory } from '../../targets/claude-code/claude-paths.js';
-// ─── Pure functions — no I/O, fully testable ─────────────────────────────────
+import { writeSettingsFileAtomic } from '../../core/fs-atomic.js';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The settings object and its `env` (undefined when absent), or why not.
+ *
+ * D-DEBUG-ENV-OBJECT: Claude Code reads `env` as an object of variables. A
+ * present `env` that is anything else — an array, a string, `null` — is
+ * rejected, never repaired and never written through: a key set on an array is
+ * dropped by JSON.stringify, so the command would report success and write
+ * nothing, and replacing the value would discard what the user wrote.
+ */
+function parseSettingsEnv(settingsJson) {
+    let settings;
+    try {
+        settings = JSON.parse(settingsJson);
+    }
+    catch {
+        return { ok: false, error: { kind: 'malformed' } };
+    }
+    if (!isPlainObject(settings))
+        return { ok: false, error: { kind: 'malformed' } };
+    if (!Object.prototype.hasOwnProperty.call(settings, 'env'))
+        return { ok: true, settings, env: undefined };
+    const env = settings.env;
+    if (!isPlainObject(env))
+        return { ok: false, error: { kind: 'env-not-object' } };
+    return { ok: true, settings, env };
+}
 /**
  * Apply DEVFLOW_HOOK_DEBUG=1 to a settings JSON string.
  * Returns a new serialized settings string. Does not mutate.
  * Follows the applyFlags pattern from flags.ts.
  */
 export function applyDebugTrace(settingsJson) {
-    const settings = JSON.parse(settingsJson);
-    settings.env ??= {};
-    settings.env.DEVFLOW_HOOK_DEBUG = '1';
-    return JSON.stringify(settings, null, 2) + '\n';
+    const parsed = parseSettingsEnv(settingsJson);
+    if (!parsed.ok)
+        return parsed;
+    const next = { ...parsed.settings, env: { ...parsed.env, DEVFLOW_HOOK_DEBUG: '1' } };
+    return { ok: true, value: JSON.stringify(next, null, 2) + '\n' };
 }
 /**
  * Remove DEVFLOW_HOOK_DEBUG from a settings JSON string.
@@ -23,15 +53,28 @@ export function applyDebugTrace(settingsJson) {
  * Follows the stripFlags pattern from flags.ts.
  */
 export function stripDebugTrace(settingsJson) {
-    const settings = JSON.parse(settingsJson);
-    const env = settings.env;
-    if (env) {
-        delete env.DEVFLOW_HOOK_DEBUG;
-        if (Object.keys(env).length === 0) {
-            delete settings.env;
+    const parsed = parseSettingsEnv(settingsJson);
+    if (!parsed.ok)
+        return parsed;
+    if (parsed.env === undefined)
+        return { ok: true, value: JSON.stringify(parsed.settings, null, 2) + '\n' };
+    const without = (obj, key) => Object.fromEntries(Object.entries(obj).filter(([k]) => k !== key));
+    const env = without(parsed.env, 'DEVFLOW_HOOK_DEBUG');
+    const next = Object.keys(env).length === 0 ? without(parsed.settings, 'env') : { ...parsed.settings, env };
+    return { ok: true, value: JSON.stringify(next, null, 2) + '\n' };
+}
+/** The message a rejected settings file gets. Pure. */
+export function describeDebugSettingsError(error) {
+    switch (error.kind) {
+        case 'malformed':
+            return 'settings.json is malformed — fix it before modifying env vars';
+        case 'env-not-object':
+            return 'settings.json has an "env" that is not an object — fix it before modifying env vars';
+        default: {
+            const exhaustive = error;
+            return exhaustive;
         }
     }
-    return JSON.stringify(settings, null, 2) + '\n';
 }
 /**
  * Read the debug tracing state from a settings JSON string.
@@ -90,29 +133,25 @@ export const debugCommand = new Command('debug')
         settingsJson = '{}';
     }
     if (options.enable) {
-        let updated;
-        try {
-            updated = applyDebugTrace(settingsJson);
-        }
-        catch {
-            p.log.error('settings.json is malformed — fix it before modifying env vars');
+        const updated = applyDebugTrace(settingsJson);
+        if (!updated.ok) {
+            p.log.error(describeDebugSettingsError(updated.error));
+            process.exitCode = 1;
             return;
         }
-        await fs.writeFile(settingsPath, updated, 'utf-8');
+        await writeSettingsFileAtomic(settingsPath, updated.value);
         p.log.success('Hook debug tracing enabled');
         p.log.info(color.dim('Remember to disable after debugging: devflow debug --disable'));
         return;
     }
     if (options.disable) {
-        let updated;
-        try {
-            updated = stripDebugTrace(settingsJson);
-        }
-        catch {
-            p.log.error('settings.json is malformed — fix it before modifying env vars');
+        const updated = stripDebugTrace(settingsJson);
+        if (!updated.ok) {
+            p.log.error(describeDebugSettingsError(updated.error));
+            process.exitCode = 1;
             return;
         }
-        await fs.writeFile(settingsPath, updated, 'utf-8');
+        await writeSettingsFileAtomic(settingsPath, updated.value);
         p.log.success('Hook debug tracing disabled');
         return;
     }

package/dist/cli/commands/flags.js

@@ -23,7 +23,7 @@ import color from 'picocolors';
 import { getClaudeDirectory, getDevFlowDirectory, } from '../../targets/claude-code/claude-paths.js';
 import { FLAG_REGISTRY, findFlag, convergeFlagsIntoSettings, parseFlagValueInput, formatFlagValue, effectiveDisplay, neutralValueOf, describeFlagKind, expectedInputFor, } from '../../core/flags.js';
 import { readManifest, writeManifest } from '../../core/manifest.js';
-import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
+import { writeSettingsFileAtomic } from '../../core/fs-atomic.js';
 import { sanitizeCell } from '../tui/cells.js';
 // Static imports for pure view-state helpers — no TTY machinery (applies PF-017).
 // runFlagsTui stays lazily imported in handleBare to keep TTY module out of
@@ -98,7 +98,7 @@ manifest, opts = { viewModeExplicit: false }) {
     // Settings write — independent error path (avoids PF-015 fan-out).
     const settingsPath = path.join(claudeDir, 'settings.json');
     try {
-        await writeFileAtomicExclusive(settingsPath, updatedSettings);
+        await writeSettingsFileAtomic(settingsPath, updatedSettings);
     }
     catch (err) {
         p.log.error(`Failed to write settings.json: ${err instanceof Error ? err.message : String(err)}`);
@@ -456,7 +456,7 @@ async function handleBare(claudeDir, devflowDir) {
             // The read captured before runFlagsTui is a stale snapshot by the time the
             // user saves — any concurrent writer (proxy enable, devflow agents, Claude
             // Code /config) that ran during the session would be silently overwritten by
-            // the atomic rename in writeFileAtomicExclusive. Re-reading rebases the flag
+            // the atomic rename in writeSettingsFileAtomic. Re-reading rebases the flag
             // write onto current content and ensures convergeFlagsIntoSettings sees the
             // fresh viewMode (applies PF-022 — file state, not config state, is reality).
             const freshSettings = await readSettingsSafe(path.join(claudeDir, 'settings.json'));

package/dist/cli/commands/hud.js

@@ -5,12 +5,13 @@ import * as p from '@clack/prompts';
 import color from 'picocolors';
 import { getClaudeDirectory, getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
 import { syncManifestFeature } from '../../core/manifest.js';
-import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
+import { writeSettingsFileAtomic } from '../../core/fs-atomic.js';
 import { HUD_COMPONENTS, loadConfig, saveConfig, } from '../../hud/config.js';
 /**
  * Add the HUD statusLine to settings JSON.
  * Idempotent — returns unchanged JSON if HUD already set.
- * Upgrades legacy statusline.sh to hud.sh automatically.
+ * Upgrades devflow's legacy statusline.sh to hud.sh automatically; a statusLine
+ * that is not devflow's is returned unchanged (D-HUD-EXACT-OWNER).
  */
 export function addHudStatusLine(settingsJson, devflowDir) {
     const settings = JSON.parse(settingsJson);
@@ -54,16 +55,39 @@ export function hasHudStatusLine(settingsJson) {
         return false;
     return isDevFlowStatusLine(settings.statusLine);
 }
+/**
+ * The statusLine command endings devflow has ever written: the HUD, and the
+ * pre-HUD `statusline.sh` it replaced.
+ */
+const DEVFLOW_STATUSLINE_SUFFIXES = [
+    '/.devflow/scripts/hud.sh',
+    '/.devflow/scripts/statusline.sh',
+];
 /**
  * Check if an existing statusLine belongs to Devflow (HUD or legacy statusline).
- * Matches paths containing 'hud.sh', 'statusline.sh', or a '/devflow/' directory segment.
+ *
+ * D-HUD-EXACT-OWNER: a statusLine is devflow's only when its command ends in
+ * `/.devflow/scripts/hud.sh` or the legacy `/.devflow/scripts/statusline.sh`, under
+ * any parent directory — so installs from the custom-directory and local-scope era
+ * are still recognised. A bare `statusline.sh` (the Claude Code docs' own example,
+ * `~/.claude/statusline.sh`) or a path that merely contains a `devflow` segment is
+ * the user's (applies ADR-024: remove or replace only what devflow provably wrote).
+ * Backslashes are read as slashes so a Windows install is matched the same way. A
+ * hand-edited command that is not a string is the user's, as in `endsWithAny`.
+ *
+ * Every caller converges through this one predicate: `addHudStatusLine` (init's
+ * settings pass with the HUD on, `init --hud-only`, `hud --enable`),
+ * `removeHudStatusLine` (init's settings pass with `--no-hud`, `hud --disable`,
+ * uninstall's `runCleanupPhase`), and `hasHudStatusLine` / `hasNonDevFlowStatusLine`
+ * (`hud --enable`, `hud --status`).
  */
 function isDevFlowStatusLine(statusLine) {
-    const cmd = statusLine.command ?? '';
-    return (cmd.includes('hud.sh') ||
-        cmd.includes('statusline.sh') ||
-        cmd.includes('/devflow/') ||
-        cmd.includes('\\devflow\\'));
+    // Parsed from a hand-editable settings.json, so the declared type is not a guarantee.
+    const raw = statusLine.command;
+    if (typeof raw !== 'string')
+        return false;
+    const cmd = raw.trim().replace(/\\/g, '/');
+    return DEVFLOW_STATUSLINE_SUFFIXES.some((suffix) => cmd.endsWith(suffix));
 }
 /**
  * Check if an existing statusLine belongs to a non-Devflow tool.
@@ -171,7 +195,7 @@ export function createHudCommand() {
                     }
                 }
                 const updated = addHudStatusLine(settingsContent, devflowDir);
-                await writeFileAtomicExclusive(settingsPath, updated);
+                await writeSettingsFileAtomic(settingsPath, updated);
             }
             // Always update config and sync manifest — removing the already-enabled
             // early-return makes --enable self-healing symmetric with --disable.
@@ -209,7 +233,7 @@ export function createHudCommand() {
                 const settingsContent = await fs.readFile(settingsPath, 'utf-8');
                 const updated = removeHudStatusLine(settingsContent);
                 if (updated !== settingsContent) {
-                    await writeFileAtomicExclusive(settingsPath, updated);
+                    await writeSettingsFileAtomic(settingsPath, updated);
                     statusLineRemoved = true;
                 }
             }

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

@@ -32,9 +32,9 @@ export const FEATURE_DEFAULTS = {
  * Resolve feature booleans for the init seed: every feature comes from
  * manifest.features, with registry defaults when the manifest is absent.
  *
- * D-FEATURES-MACHINE-WIDE (src/core/feature-switch.ts): memory, learning and
- * knowledge are machine-wide, recorded in the manifest alone, so the seed takes
- * no per-repo input at all. Seeding from whatever repo init happens to run in
+ * D-FEATURES-NARROW-ONLY (src/core/feature-switch.ts): the machine switches for
+ * memory, learning and knowledge are recorded in the manifest alone (a repository
+ * only narrows them at read time), so the seed takes no per-repo input at all. Seeding from whatever repo init happens to run in
  * would flip the switch for EVERY repo as a side effect — a stale per-repo
  * `true` would silently re-enable a feature the user turned off. ADR-014's
  * state-aware re-init preserves the prior machine-wide choice, the manifest's.
@@ -116,7 +116,7 @@ export function resolveSeedFlags(manifestFlags, registry = FLAG_REGISTRY) {
  *   - Otherwise → split + adopt newly-added non-optional selectable plugins
  *     whose name is ∉ knownPlugins and ∉ manifestPlugins
  *
- * Always-installed plugins (devflow-core-skills, devflow-ambient) are filtered
+ * The plugins init adds itself (devflow-core-skills, devflow-ambient) are filtered
  * out by partitionSelectablePlugins and never appear in the returned buckets.
  */
 export function resolveSeedPlugins(manifestPlugins, knownPlugins, allPlugins) {
@@ -157,6 +157,42 @@ export function resolveSeedPlugins(manifestPlugins, knownPlugins, allPlugins) {
     }
     return { workflowPlugins, languagePlugins };
 }
+/**
+ * The plugins an init run installs, from the selection and the ambient switch.
+ *
+ * `selectedPlugins` is empty when nothing picked a selection (a fresh
+ * non-interactive install), and then every non-optional plugin is installed.
+ * `devflow-core-skills` is always added; `devflow-ambient` is added exactly
+ * when ambient mode is on.
+ *
+ * D-AMBIENT-FOLLOWS-SWITCH: `devflow-ambient` is installed iff ambient mode is
+ * on, on EVERY path. It is not a selectable plugin (`EXCLUDED` keeps it out of
+ * both multiselect buckets and out of the re-init seed, see
+ * {@link resolveSeedPlugins}); since #150 the ambient switch is what includes
+ * it, and #150's own test plan reads "`init --no-ambient` — confirm ambient
+ * plugin NOT installed". The fresh default branch used to take every
+ * non-optional plugin, ambient included, so a first `init --no-ambient`
+ * recorded `devflow-ambient` in the manifest and the re-init — seeded without
+ * it — dropped it: the first install was the wrong one, not the re-init
+ * (#388 AC-3). The default branch therefore leaves ambient out and lets the
+ * switch below add it, exactly as it does for an explicit selection.
+ *
+ * Pure function — no I/O; returns a new array, never mutates its inputs.
+ */
+export function resolvePluginsToInstall(selectedPlugins, ambientEnabled, allPlugins) {
+    let pluginsToInstall = selectedPlugins.length > 0
+        ? allPlugins.filter(p => selectedPlugins.includes(p.name))
+        : allPlugins.filter(p => !p.optional && p.name !== 'devflow-ambient');
+    const coreSkillsPlugin = allPlugins.find(p => p.name === 'devflow-core-skills');
+    if (pluginsToInstall.length > 0 && coreSkillsPlugin && !pluginsToInstall.includes(coreSkillsPlugin)) {
+        pluginsToInstall = [coreSkillsPlugin, ...pluginsToInstall];
+    }
+    const ambientPlugin = allPlugins.find(p => p.name === 'devflow-ambient');
+    if (ambientEnabled && ambientPlugin && !pluginsToInstall.includes(ambientPlugin)) {
+        pluginsToInstall = [...pluginsToInstall, ambientPlugin];
+    }
+    return pluginsToInstall;
+}
 /**
  * Extract the attribution suppression state from a settings JSON string.
  *