devflow-kit 3.3.0 → 3.5.0

package/dist/targets/claude-code/language-stamp.js

@@ -0,0 +1,185 @@
+/**
+ * Language-focus stamp for the installed /code-review command.
+ *
+ * D-LANGUAGE-FOCUS-STAMP: /code-review spawns a language focus only when its file-type trigger fires AND
+ * the focus appears on one fixed-prefix line of the installed command. That line replaces the run-time
+ * `test -f` probe of Claude Code's directory; the installer writes it from the registry and the effective
+ * selection ({@link installedLanguageFocuses}), so the prompt reads a fact instead of discovering one.
+ * Decided here:
+ *
+ *   - The carrier is one line, `Installed language focuses: <list>`, shipped as `(none)` in
+ *     src/assets/commands/code-review.mds and found again by an anchored match, so a later run can
+ *     re-stamp a copy an earlier run stamped. It carries no MDS interpolation braces, and it sits outside
+ *     every learning arm, so both variants carry it. A separate stamped file would add a file to the
+ *     install walk and the install goldens, which an in-place rewrite leaves unchanged.
+ *   - Only code-review.md carries it. /dynamic-build spawns every review focus and drops none (plan
+ *     decision 1), so it has no stamp, no reduced classes and no DIFF_FILE.
+ *   - The stamp describes what is on disk, so it is computed from the EFFECTIVE selection
+ *     (`FileCopyOptions.effectivePlugins`), never from the plugins one run copies, and it is applied after
+ *     the command copy and the orphan sweep, whether or not code-review's own plugin is in the run. The
+ *     rewrite compares the bytes it is about to write with the bytes now on disk, at the moment it writes,
+ *     so no earlier same-run copy or pre-clean can defeat it.
+ *   - `devflow uninstall --plugin` removes a language plugin's skill but no command, so its name would
+ *     stay in the stamped copy; the selective phase re-stamps from the plugins that remain, through
+ *     {@link restampInstalledCommands} like the install.
+ *   - Composition with the learning converge (D-LEARNING-VARIANT-INSTALL), pinned: the converge rewrites
+ *     installed command files from dist or dist/learning-off, and those files carry the shipped `(none)`
+ *     line. It therefore applies {@link carryLanguageStamp} inside its own write path, putting the stamp
+ *     it finds on the installed copy into the variant it writes ({@link stampForConverge}); a copy with no
+ *     list to carry, one installed before the stamp existed, is stamped from the converge's selection
+ *     instead of being given the shipped `(none)`. The alternative, re-stamping after every
+ *     converge write, would make a steady-state run see a stamped copy that differs from its source, rewrite
+ *     it and re-stamp it on every `devflow init`; carrying keeps the converge's byte comparison honest, so a
+ *     run that changes nothing writes nothing, and it leaves one authority for the list: install and
+ *     uninstall change it, a variant switch never does.
+ *   - No prompt rule for a damaged stamp exists: no legitimate configuration produces one. A copy with
+ *     no stamp line, or several, is reported here as a warning and left as it is.
+ *   - Nothing here decides a diff's class or which focuses a diff gets. Those are prompt rules the
+ *     orchestrator executes; this module only turns the registry and a selection into a list.
+ *
+ * Never throws: every failure is a warning, because the install must not die on a stamp.
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
+import { mdFileName } from '../../core/orphan-sweep.js';
+import { installedLanguageFocuses } from '../../core/plugins.js';
+/** The fixed prefix of the stamp line; the prompt and the anchored match share it. */
+export const LANGUAGE_STAMP_PREFIX = 'Installed language focuses: ';
+/** What an empty list renders as, and what the build ships. */
+export const LANGUAGE_STAMP_NONE = '(none)';
+/** Installed commands that carry the stamp line. Only /code-review (plan decision 1). */
+export const LANGUAGE_STAMPED_COMMANDS = ['code-review'];
+/** The most focuses one stamp lists; the registry has eight, so the bound is generous. */
+const MAX_STAMPED_FOCUSES = 16;
+/** One focus name is a plain lowercase skill name. */
+const FOCUS_NAME_RE = /^[a-z][a-z0-9-]{0,31}$/;
+/** A well-formed list as rendered: `(none)`, or comma-space separated plain names. */
+const STAMP_VALUE_RE = /^(?:\(none\)|[a-z][a-z0-9-]{0,31}(?:, [a-z][a-z0-9-]{0,31}){0,15})$/;
+/** The stamp line, anchored to a whole line. Rebuilt per use: a global regex carries state. */
+const stampLineRe = () => /^Installed language focuses: [^\r\n]*$/gm;
+/** The full stamp line for a list. */
+export function renderLanguageStamp(focuses) {
+    return `${LANGUAGE_STAMP_PREFIX}${focuses.length === 0 ? LANGUAGE_STAMP_NONE : focuses.join(', ')}`;
+}
+/**
+ * `content` with its one stamp line replaced by the rendering of `focuses`.
+ *
+ * Pure. Refuses a list holding anything but plain skill names, so no prompt text can ride in on it, and
+ * refuses a file with no stamp line or several rather than guessing which one is the carrier.
+ */
+export function applyLanguageStamp(content, focuses) {
+    if (focuses.length > MAX_STAMPED_FOCUSES || !focuses.every(name => FOCUS_NAME_RE.test(name))) {
+        return { ok: false, reason: 'bad-focus-name' };
+    }
+    const lines = [...content.matchAll(stampLineRe())];
+    if (lines.length === 0)
+        return { ok: false, reason: 'no-stamp-line' };
+    if (lines.length > 1)
+        return { ok: false, reason: 'several-stamp-lines' };
+    const at = lines[0].index ?? 0;
+    return { ok: true, content: content.slice(0, at) + renderLanguageStamp(focuses) + content.slice(at + lines[0][0].length) };
+}
+/**
+ * `source` with its stamp line replaced by the one on `installed`.
+ *
+ * The learning converge's write path (see the header): the variant it installs keeps the list the
+ * install stamped. Returns `source` unchanged unless both sides hold exactly one stamp line and the
+ * installed one is a well-formed list, so a damaged or hostile line is never copied into a fresh file.
+ */
+export function carryLanguageStamp(source, installed) {
+    const carried = carriableStampLine(installed);
+    const into = [...source.matchAll(stampLineRe())];
+    if (carried === null || into.length !== 1)
+        return source;
+    const at = into[0].index ?? 0;
+    return source.slice(0, at) + carried + source.slice(at + into[0][0].length);
+}
+/** The installed copy's one stamp line when it holds exactly one and its list is well formed, else null. */
+function carriableStampLine(installed) {
+    const from = [...installed.matchAll(stampLineRe())];
+    if (from.length !== 1)
+        return null;
+    return STAMP_VALUE_RE.test(from[0][0].slice(LANGUAGE_STAMP_PREFIX.length)) ? from[0][0] : null;
+}
+/**
+ * The text the learning converge installs for a stamped command: `source` carrying the installed copy's
+ * list ({@link carryLanguageStamp}) when the copy holds one, else `source` stamped with `focuses`, the
+ * effective selection's list, exactly as the install stamps it.
+ *
+ * A copy with no list to carry was installed by a version before the stamp existed, or is damaged. A
+ * `--plugin` init right after an upgrade reaches such a copy through the converge alone (the run copies
+ * no command), so installing the shipped `(none)` over it would drop every language focus until the next
+ * full install. A list that IS carried is never changed here. Pure.
+ */
+export function stampForConverge(source, installed, focuses) {
+    if (carriableStampLine(installed) !== null)
+        return carryLanguageStamp(source, installed);
+    const stamped = applyLanguageStamp(source, focuses);
+    return stamped.ok ? stamped.content : source;
+}
+/**
+ * Stamp every installed copy that carries the stamp with the list for `effectivePlugins`.
+ *
+ * Called by installViaFileCopy after the command copy and the orphan sweep (every install shape) and by
+ * the selective uninstall phase after the removals. A command that is not installed is left absent, so a
+ * `--plugin` run never gains a command it did not install.
+ */
+export async function restampInstalledCommands(opts) {
+    const { claudeDir, effectivePlugins, warn, mayChange } = opts;
+    const focuses = installedLanguageFocuses(effectivePlugins);
+    const rewritten = [];
+    const unchanged = [];
+    const absent = [];
+    const failed = [];
+    // Precondition, asserted in production code: a relative claudeDir would resolve the targets
+    // against the working directory.
+    if (!path.isAbsolute(claudeDir)) {
+        warn(`language stamp: claudeDir is not an absolute path ("${claudeDir}") — the installed commands were not stamped`);
+        return { focuses, rewritten, unchanged, absent, failed: [...LANGUAGE_STAMPED_COMMANDS] };
+    }
+    for (const command of LANGUAGE_STAMPED_COMMANDS) {
+        const target = path.join(claudeDir, 'commands', 'devflow', mdFileName(command));
+        let current;
+        try {
+            current = await fs.readFile(target, 'utf-8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                absent.push(command);
+            }
+            else {
+                warn(`language stamp: cannot read ${mdFileName(command)} (${target}) — ${String(err)}`);
+                failed.push(command);
+            }
+            continue;
+        }
+        const stamped = applyLanguageStamp(current, focuses);
+        if (!stamped.ok) {
+            warn(stamped.reason === 'no-stamp-line'
+                ? `language stamp: ${mdFileName(command)} has no stamp line, so the installed language focuses were not recorded. Run \`devflow init\` to reinstall it.`
+                : `language stamp: ${mdFileName(command)} has ${stamped.reason === 'several-stamp-lines' ? 'several stamp lines' : 'an unusable language list'}, so it was left as it is. Run \`devflow init\` to reinstall it.`);
+            failed.push(command);
+            continue;
+        }
+        // Compared at the moment of writing, against what is on disk now.
+        if (stamped.content === current) {
+            unchanged.push(command);
+            continue;
+        }
+        try {
+            if (mayChange !== undefined && !(await mayChange(target))) {
+                failed.push(command);
+                continue;
+            }
+            await writeFileAtomicExclusive(target, stamped.content);
+            rewritten.push(command);
+        }
+        catch (err) {
+            warn(`language stamp: could not rewrite ${mdFileName(command)} (${target}) — ${String(err)}`);
+            failed.push(command);
+        }
+    }
+    return { focuses, rewritten, unchanged, absent, failed };
+}
+//# sourceMappingURL=language-stamp.js.map

package/dist/targets/claude-code/learning-install.js

@@ -0,0 +1,497 @@
+/**
+ * Learning-variant installer for the Claude Code target.
+ *
+ * D-LEARNING-VARIANT-INSTALL: the install follows the machine's learning switch
+ * (`features.learning` in ~/.devflow/manifest.json) and nothing else. When the
+ * switch is off, every command and agent that has a learning-off variant
+ * (dist/learning-off/{commands,agents}, built by D-LEARNING-VARIANTS) is installed
+ * from it, and the apply-decisions skill is not installed, so the decisions text
+ * reaches no prompt and the skill has no reader. When the switch is on, the
+ * learning-on files and the skill are installed. Three pieces carry it:
+ *
+ *   - the source order (src/core/assets.ts commandSourceDirs / agentSourceDirs):
+ *     with learning off the learning-off directory is consulted first, then the
+ *     normal order, so a host with no arm installs its one file as before;
+ *   - the skill condition (LEARNING_GATED_SKILLS in src/core/plugins.ts):
+ *     installViaFileCopy leaves the skill out when learning is off;
+ *   - {@link convergeLearningVariants}, below: the converge that makes an
+ *     ALREADY-installed tree match the switch, run by `devflow init` after the
+ *     file copy and by `devflow learning --enable/--disable` after the switch is
+ *     written ({@link applyLearningToggle}).
+ *
+ * The converge, decided in turn:
+ *   - Its roster is the files that exist under dist/learning-off, not a list typed
+ *     here: the build owns which hosts have an arm, so a new arm is converged with
+ *     no edit to this file.
+ *   - It rewrites only files that are ALREADY installed. A `--plugin` install
+ *     carries one plugin's files; a toggle must not add another plugin's. For the
+ *     same reason the skill is installed on a switch-on only when the machine's
+ *     plugin selection requires it, and removed on a switch-off only if it is
+ *     there.
+ *   - A write is atomic (temp file and rename) and byte-compared first: a file
+ *     already holding the target bytes is never touched, so a steady-state run
+ *     moves nothing and its counts say so (the unchanged-count the pre-clean
+ *     lesson asks for).
+ *   - Each file and the skill are tried separately, with per-item isolation: one
+ *     failure never skips the rest of the fan-out. Every failure is a warning,
+ *     never a throw. A converge failure only warns, because either mismatch is
+ *     safe: an on variant is still gated at run time (`decisions_gate()`), and an
+ *     off variant loads no decisions at all.
+ *   - A shadow is honoured exactly as the install honours it (a valid shadow wins, an
+ *     invalid one is reported and the shipped source installs), because
+ *     the skill is resolved through the installer's own resolveSkillSource. Only
+ *     skills and rules have shadows; commands and agents have none, so there is
+ *     nothing for an off variant to collide with. A shadow of apply-decisions
+ *     under learning off is DORMANT in the same sense as one for a deselected
+ *     skill: kept in ~/.devflow/skills, never installed, never deleted, and
+ *     applied again the moment learning comes back on.
+ *   - Version skew: the variants in this package were built with this version.
+ *     When the manifest records another version, the installed files are not the
+ *     ones this package would rewrite, so {@link applyLearningToggle} skips the
+ *     converge and says to run `devflow init`.
+ *   - An agent's installed `model:` and `effort:` are carried into the variant before
+ *     the byte comparison (D-AGENT-OVERRIDE-CARRY, see {@link withInstalledState}),
+ *     so the overrides `devflow agents` and the proxy put there are never written
+ *     back to the shipped values and a no-op converge writes no agent.
+ *     {@link applyLearningToggle} still runs reapplyAgentMapping straight after a
+ *     converge that rewrote an agent: it reads agent-models.json and is the authority.
+ *
+ * D-LEARNING-PRELOAD-MACHINE-ONLY (amended): the apply-decisions preload follows
+ * the machine switch only, never a repository's narrowing, because a repository
+ * can narrow learning off on a machine where it is on and the installed agents are
+ * machine-wide. Met by the variant: the learning-off agent files do not preload
+ * the skill (no install-time frontmatter rewrite exists), and the learning-on files
+ * keep the preload and their run-time gate for a narrowed repository. A repo
+ * `project.json` with `learning: false` on a learning-on machine therefore changes
+ * nothing installed.
+ *
+ * I/O orchestration in src/targets/; the pure selection rules stay in src/core/.
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { agentSourceDirs, commandSourceDirs, learningOffDir, } from '../../core/assets.js';
+import { carryStampedTools } from '../../core/agent-frontmatter.js';
+import { carryAgentOverrides, reapplyAgentMapping } from '../../core/agent-models.js';
+import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
+import { readManifest } from '../../core/manifest.js';
+import { getPackageRoot } from '../../core/paths.js';
+import { isProxyEnabled } from '../../core/proxy-state.js';
+import { DEVFLOW_PLUGINS, LEARNING_GATED_SKILLS, installedLanguageFocuses, prefixSkillName, skillsOf, } from '../../core/plugins.js';
+import { copyDirectory, resolveSkillSource } from './installer.js';
+import { LANGUAGE_STAMPED_COMMANDS, stampForConverge } from './language-stamp.js';
+// ── Bounds ─────────────────────────────────────────────────────────────────
+/**
+ * The most variant files one kind may carry. The shipped roster is 14 commands and
+ * 9 agents; the bound exists so a directory that grew without limit cannot turn the
+ * converge into an unbounded loop (every loop has an explicit bound).
+ */
+export const MAX_LEARNING_ROSTER = 256;
+/** Deepest skill-directory descent the tree comparison takes. */
+const MAX_SKILL_TREE_DEPTH = 4;
+/** A roster entry is a flat, lowercase, hyphenated markdown basename. */
+const ROSTER_NAME_RE = /^[a-z0-9][a-z0-9-]*\.md$/;
+const KINDS = ['commands', 'agents'];
+// ── Internals ──────────────────────────────────────────────────────────────
+function installedFile(claudeDir, kind, fileName) {
+    return path.join(claudeDir, kind, 'devflow', fileName);
+}
+/** The learning-ON source directories for a kind, most-preferred first. */
+function onSourceDirs(kind, root) {
+    return kind === 'commands' ? commandSourceDirs(true, root) : agentSourceDirs(root, true);
+}
+/**
+ * The roster of one kind: the `.md` files under dist/learning-off/<kind>, sorted.
+ *
+ * `present` is false when the directory does not exist (the build has not run, or
+ * only `build:cli` did), so the caller can say so instead of reporting a converge
+ * that had nothing to do.
+ */
+async function readRoster(kind, root, warn) {
+    let entries;
+    try {
+        entries = await fs.readdir(learningOffDir(kind, root));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { names: [], present: false };
+        warn(`learning variants: cannot read the ${kind} variants — ${String(err)}`);
+        return { names: [], present: false };
+    }
+    const names = entries.filter(entry => ROSTER_NAME_RE.test(entry)).sort();
+    if (names.length > MAX_LEARNING_ROSTER) {
+        warn(`learning variants: ${names.length} ${kind} variants exceed the bound of ${MAX_LEARNING_ROSTER}; converging the first ${MAX_LEARNING_ROSTER}`);
+        return { names: names.slice(0, MAX_LEARNING_ROSTER), present: true };
+    }
+    return { names, present: true };
+}
+async function readIfPresent(file) {
+    try {
+        return await fs.readFile(file);
+    }
+    catch (err) {
+        return err.code === 'ENOENT' ? 'absent' : 'unreadable';
+    }
+}
+/** First of `candidates` that exists, or undefined. Bounded by the candidate list. */
+async function firstReadable(candidates) {
+    for (const file of candidates) {
+        try {
+            return { file, bytes: await fs.readFile(file) };
+        }
+        catch { /* not here — next directory in preference order */ }
+    }
+    return undefined;
+}
+/**
+ * The bytes a write would install: the variant `source` wearing the state the
+ * installed copy carries, so the byte comparison in {@link convergeFile} compares
+ * variants and nothing else.
+ *
+ * D-LANGUAGE-FOCUS-STAMP, composition: the variant on disk carries the language list the
+ * install stamped (code-review.md), and the source carries the shipped `(none)`. The stamp is
+ * carried from the installed copy into the text this write would install, so the byte
+ * comparison stays honest (a stamped copy of the right variant is `unchanged`, not
+ * rewritten on every run) and a variant switch never loses or changes the list. A copy with
+ * no list to carry (installed before the stamp existed) is stamped from the selection instead.
+ *
+ * D-AGENT-OVERRIDE-CARRY, composition: an installed agent carries the `model:` and `effort:`
+ * that `devflow agents` and the proxy put there, and the source carries the shipped ones.
+ * Carrying them keeps the override window shut (no write ever leaves an agent on its shipped
+ * model while reapplyAgentMapping has yet to restore it) and keeps a no-op converge
+ * write-free, so "N agent(s) rewritten" counts only real variant switches. reapplyAgentMapping
+ * stays the authority: it reads agent-models.json after the converge and the carry only agrees
+ * with it (see carryAgentOverrides).
+ *
+ * D-TRACKER-SERVER-ALLOWLIST, composition: the installed Git agent carries the tracker-server
+ * entries the install stamped onto its `tools:` line, and the variant source carries none.
+ * The stamp is carried the same way (carryStampedTools), so a variant switch keeps the list
+ * and a copy already holding the right variant and its stamp compares byte-equal. Install
+ * and `devflow tracker --servers` are the only writers of the list; a converge never changes it.
+ *
+ * Pure.
+ */
+function withInstalledState(kind, fileName, source, installed, focuses) {
+    if (kind === 'agents') {
+        const sourceText = source.toString('utf-8');
+        const installedText = installed.toString('utf-8');
+        const carried = carryStampedTools(carryAgentOverrides(sourceText, installedText), installedText);
+        return carried === sourceText ? source : Buffer.from(carried, 'utf-8');
+    }
+    return LANGUAGE_STAMPED_COMMANDS.includes(fileName.replace(/\.md$/, ''))
+        ? Buffer.from(stampForConverge(source.toString('utf-8'), installed.toString('utf-8'), focuses), 'utf-8')
+        : source;
+}
+/**
+ * Converge ONE installed prompt onto the variant the switch wants.
+ *
+ * Never throws: every failure is a warning and the outcome `failed`, so the next
+ * file is still tried.
+ */
+async function convergeFile(kind, fileName, opts) {
+    const { claudeDir, learning, warn, root, focuses } = opts;
+    const target = installedFile(claudeDir, kind, fileName);
+    const installed = await readIfPresent(target);
+    if (installed === 'absent')
+        return 'not-installed';
+    if (installed === 'unreadable') {
+        warn(`learning variants: cannot read the installed ${kind}/${fileName} (${target}) — left as it is`);
+        return 'failed';
+    }
+    // Learning off: the variant is the roster file itself. Learning on: the normal
+    // source order, which is where the learning-on file of that host lives.
+    const candidates = learning
+        ? onSourceDirs(kind, root).map(dir => path.join(dir, fileName))
+        : [path.join(learningOffDir(kind, root), fileName)];
+    const source = await firstReadable(candidates);
+    if (source === undefined) {
+        warn(`learning variants: no source for ${kind}/${fileName} (searched: ${candidates.join(', ')}) — left as it is`);
+        return 'failed';
+    }
+    const wanted = withInstalledState(kind, fileName, source.bytes, installed, focuses);
+    // Byte-compared: an installed file already holding the target bytes is not
+    // rewritten, so a run that changes nothing writes nothing.
+    if (installed.equals(wanted))
+        return 'unchanged';
+    try {
+        // Prompts are UTF-8 text; the atomic writer takes a string and preserves the
+        // target's permission mode.
+        await writeFileAtomicExclusive(target, wanted.toString('utf-8'));
+    }
+    catch (err) {
+        warn(`learning variants: could not rewrite ${kind}/${fileName} (${target}) — ${String(err)}`);
+        return 'failed';
+    }
+    return 'rewritten';
+}
+/** Every file below `dir` as sorted relative paths; null when anything is not a plain file or directory. */
+async function listTree(dir, depth = 0) {
+    if (depth > MAX_SKILL_TREE_DEPTH)
+        return null;
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    const out = [];
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            const nested = await listTree(path.join(dir, entry.name), depth + 1);
+            if (nested === null)
+                return null;
+            out.push(...nested.map(rel => path.join(entry.name, rel)));
+        }
+        else if (entry.isFile()) {
+            out.push(entry.name);
+        }
+        else {
+            return null;
+        }
+    }
+    return out.sort();
+}
+/** True only when both trees hold the same files with the same bytes. Any error answers false. */
+async function treesIdentical(a, b) {
+    const [left, right] = await Promise.all([listTree(a), listTree(b)]);
+    if (left === null || right === null || left.length !== right.length)
+        return false;
+    for (let i = 0; i < left.length; i++) {
+        if (left[i] !== right[i])
+            return false;
+        try {
+            const [x, y] = await Promise.all([fs.readFile(path.join(a, left[i])), fs.readFile(path.join(b, right[i]))]);
+            if (!x.equals(y))
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+async function pathExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Install one skill directory atomically: stage a copy beside the claude dir's
+ * skills, then swap it in, restoring the old directory if the swap fails.
+ *
+ * Staged under `claudeDir` itself, not under `skills/`: a staging directory a
+ * crash leaves behind must not look like a second skill to Claude Code.
+ */
+async function swapInSkillDirectory(claudeDir, sourceDir, target) {
+    const staging = path.join(claudeDir, `.devflow-learning-${process.pid}-${Date.now().toString(36)}.tmp`);
+    const backup = `${staging}.old`;
+    try {
+        await copyDirectory(sourceDir, staging);
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        const hadTarget = await pathExists(target);
+        if (hadTarget)
+            await fs.rename(target, backup);
+        try {
+            await fs.rename(staging, target);
+        }
+        catch (err) {
+            if (hadTarget)
+                await fs.rename(backup, target);
+            throw err;
+        }
+    }
+    finally {
+        await fs.rm(staging, { recursive: true, force: true }).catch(() => undefined);
+        await fs.rm(backup, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/** Converge the learning-gated skill directories. Never throws. */
+async function convergeSkills(opts) {
+    const { claudeDir, devflowDir, learning, plugins, warn } = opts;
+    const selected = skillsOf(plugins);
+    let state = 'unchanged';
+    // Every gated skill is converged: a failure on one must not skip the next.
+    for (const skill of LEARNING_GATED_SKILLS) {
+        const target = path.join(claudeDir, 'skills', prefixSkillName(skill));
+        try {
+            if (!learning) {
+                if (!(await pathExists(target)))
+                    continue;
+                await fs.rm(target, { recursive: true });
+                state = 'removed';
+                continue;
+            }
+            if (!selected.has(skill)) {
+                if (state === 'unchanged')
+                    state = 'not-selected';
+                continue;
+            }
+            const resolved = await resolveSkillSource(skill, devflowDir, opts.packageRoot);
+            if ((await pathExists(target)) && (await treesIdentical(resolved.dir, target)))
+                continue;
+            await swapInSkillDirectory(claudeDir, resolved.dir, target);
+            state = 'installed';
+        }
+        catch (err) {
+            warn(`learning variants: could not converge the ${prefixSkillName(skill)} skill (${target}) — ${String(err)}`);
+            state = 'failed';
+        }
+    }
+    return state;
+}
+// ── Convergence ────────────────────────────────────────────────────────────
+/**
+ * Make the installed commands, agents and apply-decisions skill match the
+ * machine's learning switch.
+ *
+ * Never throws. A caller reads `converged`; it does not catch. A claudeDir that is
+ * not absolute is reported the same way rather than thrown, because an install
+ * must not die on it.
+ */
+export async function convergeLearningVariants(opts) {
+    const { claudeDir, learning, warn } = opts;
+    const empty = {
+        converged: false, commandsRewritten: [], agentsRewritten: [], unchanged: 0, notInstalled: 0, skill: 'unchanged',
+    };
+    // Precondition, asserted in production code: a relative claudeDir would resolve
+    // the install targets somewhere unexpected.
+    if (!path.isAbsolute(claudeDir)) {
+        warn(`learning variants: claudeDir is not an absolute path ("${claudeDir}") — skipping convergence`);
+        return empty;
+    }
+    const root = opts.packageRoot ?? getPackageRoot();
+    const focuses = installedLanguageFocuses(opts.plugins);
+    let failed = false;
+    let unchanged = 0;
+    let notInstalled = 0;
+    const rewritten = { commands: [], agents: [] };
+    for (const kind of KINDS) {
+        const roster = await readRoster(kind, root, warn);
+        if (!roster.present) {
+            warn(`learning variants: no ${kind} variants under ${learningOffDir(kind, root)} — run \`npm run build:mds\`; installed ${kind} left as they are`);
+            failed = true;
+            continue;
+        }
+        for (const fileName of roster.names) {
+            const outcome = await convergeFile(kind, fileName, { claudeDir, learning, warn, root, focuses });
+            if (outcome === 'rewritten')
+                rewritten[kind].push(fileName);
+            else if (outcome === 'unchanged')
+                unchanged++;
+            else if (outcome === 'not-installed')
+                notInstalled++;
+            else
+                failed = true;
+        }
+    }
+    // Evaluated unconditionally, after the files: a failed prompt never skips the skill
+    // (one failure must not leave the rest of the fan-out half-converged).
+    const skill = await convergeSkills(opts);
+    if (skill === 'failed')
+        failed = true;
+    return {
+        converged: !failed,
+        commandsRewritten: rewritten.commands,
+        agentsRewritten: rewritten.agents,
+        unchanged,
+        notInstalled,
+        skill,
+    };
+}
+// ── The toggle ─────────────────────────────────────────────────────────────
+/** The running package's version, or null when its package.json cannot be read or holds none. */
+export async function readRunningVersion(packageRoot = getPackageRoot()) {
+    try {
+        const pkg = JSON.parse(await fs.readFile(path.join(packageRoot, 'package.json'), 'utf-8'));
+        return typeof pkg.version === 'string' && pkg.version !== '' ? pkg.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * One line for what a converge changed, or null when it changed nothing.
+ *
+ * The caller prints it only on a toggle: a run that moved nothing says nothing.
+ */
+export function describeLearningConverge(result, learning) {
+    const parts = [];
+    const prompts = result.commandsRewritten.length + result.agentsRewritten.length;
+    if (prompts > 0) {
+        parts.push(`${result.commandsRewritten.length} command(s) and ${result.agentsRewritten.length} agent(s) ` +
+            `rewritten for the learning-${learning ? 'on' : 'off'} variant`);
+    }
+    if (result.skill === 'installed')
+        parts.push('the apply-decisions skill installed');
+    if (result.skill === 'removed')
+        parts.push('the apply-decisions skill removed');
+    return parts.length === 0 ? null : parts.join('; ');
+}
+/**
+ * The version-skew check, apart from the I/O so it is provable by itself: null when
+ * the installed prompts and this package agree, else the message to print.
+ */
+export function learningToggleSkew(installedVersion, runningVersion, learning) {
+    if (runningVersion !== null && installedVersion === runningVersion)
+        return null;
+    return (`The installed prompts come from devflow ${installedVersion} and this CLI is ${runningVersion ?? 'of unknown version'}, ` +
+        `so the learning-${learning ? 'on' : 'off'} variants were not applied. Run \`devflow init\` to apply them.`);
+}
+/**
+ * What `devflow learning --enable/--disable` does after the switch is written:
+ * converge the installed tree onto the new value, then reapply the saved agent
+ * model and effort mapping.
+ *
+ * The converge carries each installed agent's model and effort into the variant it
+ * writes (D-AGENT-OVERRIDE-CARRY), so the overrides are already on the file and this
+ * reapply is the authority behind that carry, not a repair of a default window: it
+ * re-reads agent-models.json and corrects any agent whose installed values had
+ * drifted from it. It runs only when the converge rewrote an agent, and a failure
+ * there is a warning like every other failure here.
+ *
+ * Never throws.
+ */
+export async function applyLearningToggle(opts) {
+    const { claudeDir, devflowDir, learning, runningVersion, warn } = opts;
+    const manifest = await readManifest(devflowDir);
+    if (manifest === null) {
+        return {
+            kind: 'skipped',
+            reason: 'no-manifest',
+            message: 'No readable install manifest, so the learning variants were not applied. Run `devflow init`.',
+        };
+    }
+    const skew = learningToggleSkew(manifest.version, runningVersion, learning);
+    if (skew !== null)
+        return { kind: 'skipped', reason: 'version-skew', message: skew };
+    const selection = new Set(manifest.plugins);
+    const result = await convergeLearningVariants({
+        claudeDir,
+        devflowDir,
+        learning,
+        plugins: DEVFLOW_PLUGINS.filter(plugin => selection.has(plugin.name)),
+        warn,
+        packageRoot: opts.packageRoot,
+    });
+    let agentMappingReapplied = false;
+    if (result.agentsRewritten.length > 0) {
+        try {
+            await reapplyAgentMapping({
+                proxyEnabled: await isProxyEnabled(devflowDir),
+                installDir: path.join(claudeDir, 'agents', 'devflow'),
+                devflowDir,
+                onWarning: warn,
+            });
+            agentMappingReapplied = true;
+        }
+        catch (err) {
+            warn(`learning variants: could not reapply the agent model mapping — ${String(err)}`);
+        }
+    }
+    return { kind: 'converged', result, agentMappingReapplied };
+}
+//# sourceMappingURL=learning-install.js.map