devflow-kit 3.9.0 → 3.11.0

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

@@ -1,28 +1,36 @@
 /**
- * Curation-variant installer for the Claude Code target.
+ * Prompt-variant installer for the Claude Code target: the curation and compliance switches.
  *
- * D-LEARNING-VARIANT-INSTALL: the install follows the machine's curation switch
- * (`features.curation` in ~/.devflow/manifest.json) and nothing else. When the
- * switch is off, every command and agent that has a curation-off variant
- * (dist/curation-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
- * curation-on files and the skill are installed. Three pieces carry it:
+ * D-LEARNING-VARIANT-INSTALL: the install follows the machine's two switches
+ * (`features.curation` and `features.compliance` in ~/.devflow/manifest.json) and
+ * nothing else. Each command and agent that has an arm for a switch that is off is
+ * installed from the build tree of the machine's exact switch combination
+ * (dist/{curation-off,compliance-off,curation-compliance-off}/{commands,agents}, built by
+ * D-LEARNING-VARIANTS), and the apply-decisions skill is not installed when curation is
+ * off, so the decisions text reaches no prompt and the skill has no reader. With a switch on,
+ * its on files are installed. A compliance-off machine carries no posting step in any prompt
+ * that has a compliance arm. Three pieces carry it:
  *
  *   - the source order (src/core/assets.ts commandSourceDirs / agentSourceDirs):
- *     with curation off the curation-off directory is consulted first, then the
+ *     an off combination takes its own tree, and only the all-on combination takes the
  *     normal order, so a host with no arm installs its one file as before;
  *   - the skill condition (CURATION_GATED_SKILLS in src/core/plugins.ts):
  *     installViaFileCopy leaves the skill out when curation is off;
- *   - {@link convergeCurationVariants}, below: the converge that makes an
- *     ALREADY-installed tree match the switch, run by `devflow init` after the
- *     file copy and by `devflow curation --enable/--disable` after the switch is
- *     written ({@link applyCurationToggle}).
+ *   - {@link convergeVariantAxes}, below: the one converge that makes an
+ *     ALREADY-installed tree match both switches, run by `devflow init` after the
+ *     file copy and by `devflow curation` and `devflow compliance` after the switch is
+ *     written ({@link applyVariantToggle}).
  *
  * The converge, decided in turn:
- *   - Its roster is the files that exist under dist/curation-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.
+ *   - Its roster is the files that exist under the off trees, joined with the hosts the build
+ *     manifest (dist/variant-axes.json) says carry an arm, 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 fails closed on the posting question. With compliance off, an installed
+ *     compliance-armed prompt that could not be converged is named in `posting`, and a build
+ *     manifest that cannot name those hosts leaves `posting` unknown. Callers decide the cost:
+ *     `devflow compliance` exits non-zero, init and curation warn.
+ *   - After a clean converge, {@link applyVariantToggle} and init record which variants are
+ *     installed (`installedVariants` in the manifest, see src/core/installed-variants.ts).
  *   - 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
@@ -47,13 +55,14 @@
  *     applied again the moment curation 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 applyCurationToggle} skips the
- *     converge and says to run `devflow init`.
+ *     ones this package would rewrite, so {@link applyVariantToggle} skips the
+ *     converge and says to run `devflow init`. For a compliance-off toggle the message also
+ *     says that posting steps remain installed until then.
  *   - 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 applyCurationToggle} still runs reapplyAgentMapping straight after a
+ *     {@link applyVariantToggle} 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
@@ -69,17 +78,25 @@
  */
 import { promises as fs } from 'fs';
 import * as path from 'path';
-import { agentSourceDirs, commandSourceDirs, curationOffDir, } from '../../core/assets.js';
+import { agentSourceDirs, bothOffDir, commandSourceDirs, complianceOffDir, curationOffDir, } from '../../core/assets.js';
 import { carryStampedTools } from '../../core/agent-frontmatter.js';
 import { carryAgentOverrides, reapplyAgentMapping } from '../../core/agent-models.js';
 import { describeEchoedValue } from '../../core/echo-value.js';
-import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
-import { readManifest } from '../../core/manifest.js';
+import { ALL_SWITCHES_ON, VARIANT_MANIFEST_REL_PATH, describeVariantManifestParseError, machineVariantKey, parseVariantManifest, variantOffRelPath, } from '../../core/curation-variants.js';
+import { readInstalledVariants } from '../../core/installed-variants.js';
+import { readManifest, writeManifest } from '../../core/manifest.js';
+import { withManifestLock } from '../../core/manifest-lock.js';
 import { getPackageRoot } from '../../core/paths.js';
 import { isProxyEnabled } from '../../core/proxy-state.js';
-import { DEVFLOW_PLUGINS, CURATION_GATED_SKILLS, installedLanguageFocuses, prefixSkillName, skillsOf, } from '../../core/plugins.js';
+import { WORKFLOW_FOLDERS } from '../../core/mds-variants.js';
+import { DEVFLOW_PLUGINS, CURATION_GATED_SKILLS, installedLanguageFocuses, prefixSkillName, selectedWorkflowFolders, skillsOf, workflowFolderNames, } from '../../core/plugins.js';
+import { convergeFromManifest } from './compliance-install.js';
+import { swapFolderIn } from './folder-swap.js';
 import { copyDirectory, resolveSkillSource } from './installer.js';
 import { LANGUAGE_STAMPED_COMMANDS, stampForConverge } from './language-stamp.js';
+import { directoryState, newLinkReport, refuseUnrealFolder, refusedFolderMessage, unlinkLinkAt, warnLinkReport, writeFileReplacingLink } from './linked-folder.js';
+import { convergeReferences } from './reference-converge.js';
+import { installWorkflowFolder, readWorkflowFolder } from './workflow-folder-install.js';
 // ── Bounds ─────────────────────────────────────────────────────────────────
 /**
  * The most variant files one kind may carry. The shipped roster is 14 commands and
@@ -92,38 +109,113 @@ 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'];
+const POSTING_CLEAR = { kind: 'clear' };
 // ── Internals ──────────────────────────────────────────────────────────────
 function installedFile(claudeDir, kind, fileName) {
     return path.join(claudeDir, kind, 'devflow', fileName);
 }
-/** The curation-ON source directories for a kind, most-preferred first. */
+/**
+ * The both-axes-ON source directories for a kind, most-preferred first: the files a host
+ * with no off variant for the machine installs.
+ */
 function onSourceDirs(kind, root) {
-    return kind === 'commands' ? commandSourceDirs(true, root) : agentSourceDirs(root, true);
+    return kind === 'commands' ? commandSourceDirs(ALL_SWITCHES_ON, root) : agentSourceDirs(root, ALL_SWITCHES_ON);
+}
+/** The roster-shaped file names directly under `dir`, `'absent'` when it does not exist and `'unreadable'` (warned) when it cannot be read. */
+async function listVariantDir(dir, kind, warn) {
+    try {
+        return (await fs.readdir(dir)).filter(entry => ROSTER_NAME_RE.test(entry));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return 'absent';
+        warn(`prompt variants: cannot read the ${kind} variants under ${dir} — ${String(err)}`);
+        return 'unreadable';
+    }
 }
 /**
- * The roster of one kind: the `.md` files under dist/curation-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.
+ * The compiled prompts the build says carry an arm, read from its variant manifest. An error names the
+ * cause in a line a person can act on. Compliance on never reads it: only a compliance-off machine needs
+ * the manifest to know which prompts it must not leave unconverged.
  */
-async function readRoster(kind, root, warn) {
-    let entries;
+async function readVariantHosts(root) {
+    const file = path.join(root, ...VARIANT_MANIFEST_REL_PATH.split('/'));
+    let text;
     try {
-        entries = await fs.readdir(curationOffDir(kind, root));
+        text = await fs.readFile(file, 'utf-8');
     }
     catch (err) {
-        if (err.code === 'ENOENT')
-            return { names: [], present: false };
-        warn(`curation variants: cannot read the ${kind} variants — ${String(err)}`);
-        return { names: [], present: false };
+        const cause = err.code === 'ENOENT' ? 'does not exist' : `cannot be read (${String(err)})`;
+        return { ok: false, reason: `the variant manifest ${cause}: ${file}` };
+    }
+    const parsed = parseVariantManifest(text);
+    if (!parsed.ok)
+        return { ok: false, reason: `the variant manifest is not valid: ${file} (${describeVariantManifestParseError(parsed.error)})` };
+    const hosts = new Map();
+    for (const host of parsed.value)
+        hosts.set(`${host.kind}/${host.name}.md`, { file: `${host.name}.md`, axes: host.axes });
+    return { ok: true, hosts };
+}
+/**
+ * The roster of one kind: the prompts that differ on an axis, sorted by file name.
+ *
+ * The files under the three off trees name them (the build owns which hosts have an arm), and a host the
+ * build manifest lists is added, so a tree removed from the package still leaves its hosts in the roster.
+ * An arm comes from the manifest entry, or from the trees the file is in when the manifest does not list it
+ * (a curation arm has a file under curation-off or both-off, a compliance arm under compliance-off or
+ * both-off).
+ *
+ * `present` is false when no tree holds this kind and the manifest lists none (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.
+ * `incomplete` says the roster was read in part, already warned: a tree could not be listed
+ * (`unreadable`), or the roster passed {@link MAX_CURATION_ROSTER} and the hosts after it were left out
+ * (`truncated`). `refused` lists the manifest hosts whose name {@link ROSTER_NAME_RE} does not hold (the
+ * build accepts a wider name), already warned: they are left out of `hosts` and the caller fails closed.
+ */
+async function readRoster(kind, root, manifestHosts, warn) {
+    const listings = {
+        curation: await listVariantDir(curationOffDir(kind, root), kind, warn),
+        compliance: await listVariantDir(complianceOffDir(kind, root), kind, warn),
+        both: await listVariantDir(bothOffDir(kind, root), kind, warn),
+    };
+    const inferred = new Map();
+    const note = (names, axes) => {
+        if (typeof names === 'string')
+            return;
+        for (const name of names) {
+            const arms = inferred.get(name) ?? { curation: false, compliance: false };
+            inferred.set(name, {
+                curation: arms.curation || axes.includes('curation'),
+                compliance: arms.compliance || axes.includes('compliance'),
+            });
+        }
+    };
+    note(listings.curation, ['curation']);
+    note(listings.compliance, ['compliance']);
+    note(listings.both, ['curation', 'compliance']);
+    const files = new Map();
+    const refused = [];
+    for (const [file, axes] of inferred)
+        files.set(file, { file, axes });
+    for (const [key, host] of manifestHosts ?? []) {
+        if (!key.startsWith(`${kind}/`) || !(host.axes.curation || host.axes.compliance))
+            continue;
+        if (ROSTER_NAME_RE.test(host.file)) {
+            files.set(host.file, host);
+        }
+        else {
+            warn(`prompt variants: the build manifest lists ${kind}/${host.file}, a name the converge cannot hold; it was not converged`);
+            refused.push(host);
+        }
     }
-    const names = entries.filter(entry => ROSTER_NAME_RE.test(entry)).sort();
-    if (names.length > MAX_CURATION_ROSTER) {
-        warn(`curation variants: ${names.length} ${kind} variants exceed the bound of ${MAX_CURATION_ROSTER}; converging the first ${MAX_CURATION_ROSTER}`);
-        return { names: names.slice(0, MAX_CURATION_ROSTER), present: true };
+    const hosts = [...files.values()].sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+    const present = hosts.length > 0 || Object.values(listings).some(listing => typeof listing !== 'string');
+    if (hosts.length > MAX_CURATION_ROSTER) {
+        warn(`prompt variants: ${hosts.length} ${kind} variants exceed the bound of ${MAX_CURATION_ROSTER}; converging the first ${MAX_CURATION_ROSTER}`);
+        return { hosts: hosts.slice(0, MAX_CURATION_ROSTER), present: true, incomplete: 'truncated', refused };
     }
-    return { names, present: true };
+    const unreadable = Object.values(listings).some(listing => listing === 'unreadable');
+    return { hosts, present, incomplete: unreadable ? 'unreadable' : null, refused };
 }
 async function readIfPresent(file) {
     try {
@@ -183,29 +275,38 @@ function withInstalledState(kind, fileName, source, installed, focuses) {
         : source;
 }
 /**
- * Converge ONE installed prompt onto the variant the switch wants.
+ * Converge ONE installed prompt onto the variant the machine's switches want.
+ *
+ * The file is the one built for the machine's exact switches (`machineVariantKey`): an off
+ * variant is read from its own tree and no other, so a host with a compliance arm on a
+ * compliance-off machine never falls through to a file that carries the posting steps. A host
+ * the machine needs no off variant for comes from the normal source order.
  *
  * 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, curation, warn, root, focuses } = opts;
+async function convergeFile(kind, host, opts) {
+    const { claudeDir, switches, warn, root, focuses, folderRefused, links } = opts;
+    const fileName = host.file;
     const target = installedFile(claudeDir, kind, fileName);
     const installed = await readIfPresent(target);
     if (installed === 'absent')
         return 'not-installed';
+    // Reading through a link is harmless and tells a prompt that is there from one that is not. It is
+    // left as it is: the folder is reported once, by the caller.
+    if (folderRefused)
+        return 'failed';
     if (installed === 'unreadable') {
-        warn(`curation variants: cannot read the installed ${kind}/${fileName} (${target}) — left as it is`);
+        warn(`prompt variants: cannot read the installed ${kind}/${fileName} (${target}) — left as it is`);
         return 'failed';
     }
-    // Curation off: the variant is the roster file itself. Curation on: the normal
-    // source order, which is where the curation-on file of that host lives.
-    const candidates = curation
+    const key = machineVariantKey(switches, host.axes);
+    const candidates = key === 'on'
         ? onSourceDirs(kind, root).map(dir => path.join(dir, fileName))
-        : [path.join(curationOffDir(kind, root), fileName)];
+        : [path.join(root, ...variantOffRelPath(key, kind, fileName).split('/'))];
     const source = await firstReadable(candidates);
     if (source === undefined) {
-        warn(`curation variants: no source for ${kind}/${fileName} (searched: ${candidates.join(', ')}) — left as it is`);
+        warn(`prompt variants: no source for ${kind}/${fileName} (searched: ${candidates.join(', ')}) — left as it is`);
         return 'failed';
     }
     const wanted = withInstalledState(kind, fileName, source.bytes, installed, focuses);
@@ -215,11 +316,11 @@ async function convergeFile(kind, fileName, opts) {
         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'));
+        // target's permission mode. A link at the target is replaced by the rename, never followed.
+        await writeFileReplacingLink(target, wanted.toString('utf-8'), links);
     }
     catch (err) {
-        warn(`curation variants: could not rewrite ${kind}/${fileName} (${target}) — ${String(err)}`);
+        warn(`prompt variants: could not rewrite ${kind}/${fileName} (${target}) — ${String(err)}`);
         return 'failed';
     }
     return 'rewritten';
@@ -280,50 +381,98 @@ async function pathExists(p) {
         return false;
     }
 }
+/**
+ * The two folders a skill swap uses, both directly under `claudeDir`: the staging copy, and the
+ * backup the old skill folder waits in while the copy is renamed into place.
+ *
+ * @param now - The clock reading that makes the name unique, in milliseconds.
+ */
+export function curationSwapPaths(claudeDir, now) {
+    const staging = path.join(claudeDir, `.devflow-curation-${process.pid}-${now.toString(36)}.tmp`);
+    return { staging, backup: `${staging}.old` };
+}
 /**
  * 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.
+ *
+ * A file in the old directory that devflow did not ship moves to the backup folder first. If one
+ * cannot move, nothing is swapped: the shipped files are written into the old directory and the
+ * file stays (see {@link swapFolderIn}).
+ *
+ * A target that is a link is moved aside as the link itself, never followed, so what it points to is
+ * left as it was; the link is recorded in `links` once the real folder stands in its place.
  */
-async function swapInSkillDirectory(claudeDir, sourceDir, target) {
-    const staging = path.join(claudeDir, `.devflow-curation-${process.pid}-${Date.now().toString(36)}.tmp`);
-    const backup = `${staging}.old`;
+async function swapInSkillDirectory(claudeDir, sourceDir, target, links, backups) {
+    const { staging, backup } = curationSwapPaths(claudeDir, Date.now());
     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;
-        }
+        await swapFolderIn({
+            backups,
+            target,
+            staged: staging,
+            aside: backup,
+            links,
+            mergeInto: () => copyDirectory(staging, target, undefined, links),
+        });
     }
     finally {
         await fs.rm(staging, { recursive: true, force: true }).catch(() => undefined);
-        await fs.rm(backup, { recursive: true, force: true }).catch(() => undefined);
     }
 }
-/** Converge the curation-gated skill directories. Never throws. */
-async function convergeSkills(opts) {
+/**
+ * Remove a curation-gated skill folder. The files devflow shipped go by the session's list, anything
+ * else moves to the backup folder first, and the folder goes with a plain `rmdir`: 'kept' means it
+ * still stands because a file could not move. A link is unlinked and a file in its place moves aside.
+ */
+async function removeSkillFolder(target, backups) {
+    const state = await directoryState(target);
+    switch (state) {
+        case 'absent':
+            return 'absent';
+        case 'link':
+            return (await unlinkLinkAt(target)) === 'unlinked' ? 'removed' : 'kept';
+        case 'unusable': {
+            const moved = await backups.moveWhole(target);
+            return moved.status === 'moved' ? 'removed' : moved.status === 'absent' ? 'absent' : 'kept';
+        }
+        case 'real': {
+            await backups.prepass([target]);
+            return (await backups.removeListed(target)).folderRemoved ? 'removed' : 'kept';
+        }
+        default: {
+            const unreachable = state;
+            void unreachable;
+            return 'kept';
+        }
+    }
+}
+/** Converge the curation-gated skill directories. A skill folder that was a link and was swapped is recorded in `links`. Never throws. */
+async function convergeSkills(opts, links) {
     const { claudeDir, devflowDir, curation, plugins, warn } = opts;
     const selected = skillsOf(plugins);
     let state = 'unchanged';
+    // A skills folder that is a link or not a folder is refused once. The removal and the swap below
+    // would reach the folder the link points to: `directoryState` of a skill folder follows the link
+    // above it. The refusal is recorded in `links`, and the converge is not clean.
+    if (await refuseUnrealFolder(links, path.join(claudeDir, 'skills')))
+        return 'failed';
     // Every gated skill is converged: a failure on one must not skip the next.
     for (const skill of CURATION_GATED_SKILLS) {
         const target = path.join(claudeDir, 'skills', prefixSkillName(skill));
         try {
             if (!curation) {
-                if (!(await pathExists(target)))
-                    continue;
-                await fs.rm(target, { recursive: true });
-                state = 'removed';
+                const removal = await removeSkillFolder(target, opts.backups);
+                if (removal === 'removed') {
+                    state = 'removed';
+                }
+                else if (removal === 'kept') {
+                    warn(`curation variants: the ${prefixSkillName(skill)} skill folder (${target}) still holds a file that could not be moved aside, so it was not removed`);
+                    state = 'failed';
+                }
                 continue;
             }
             if (!selected.has(skill)) {
@@ -334,7 +483,7 @@ async function convergeSkills(opts) {
             const resolved = await resolveSkillSource(skill, devflowDir, opts.packageRoot);
             if ((await pathExists(target)) && (await treesIdentical(resolved.dir, target)))
                 continue;
-            await swapInSkillDirectory(claudeDir, resolved.dir, target);
+            await swapInSkillDirectory(claudeDir, resolved.dir, target, links, opts.backups);
             state = 'installed';
         }
         catch (err) {
@@ -344,65 +493,311 @@ async function convergeSkills(opts) {
     }
     return state;
 }
-// ── Convergence ────────────────────────────────────────────────────────────
+/** The result of a converge that did not run: nothing changed and, with compliance off, nothing is proven. */
+function notRun(switches, reason) {
+    return {
+        converged: false,
+        commandsRewritten: [],
+        agentsRewritten: [],
+        unchanged: 0,
+        notInstalled: 0,
+        posting: switches.compliance ? POSTING_CLEAR : { kind: 'unknown', reason },
+        replacedLinks: [],
+        refusedFolders: [],
+    };
+}
 /**
- * Make the installed commands, agents and apply-decisions skill match the
- * machine's curation switch.
+ * Make the installed commands and agents match the machine's two switches: the per-kind
+ * converge of the prompts.
+ *
+ * Each roster host is rewritten to the file built for the machine's exact switches (see
+ * {@link convergeFile}). With compliance off the converge also answers the fail-closed
+ * question: the build manifest names the hosts that carry a compliance arm, and an installed one
+ * that could not be converged is listed in `posting` as still posting. A compliance-off machine whose
+ * build manifest is unusable answers `unknown`, because it cannot name those hosts.
  *
- * 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.
+ * A kind's `devflow` folder that is a link, or not a folder, is refused: nothing is written in it, the
+ * installed prompts there count as not converged, and the folder is named in `refusedFolders` and in
+ * a warning. A prompt that is a link in a real folder is replaced by a real file, and named in
+ * `replacedLinks` and in a warning.
+ *
+ * Never throws. A caller reads `converged` and `posting`; it does not catch.
  */
-export async function convergeCurationVariants(opts) {
-    const { claudeDir, curation, warn } = opts;
-    const empty = {
-        converged: false, commandsRewritten: [], agentsRewritten: [], unchanged: 0, notInstalled: 0, skill: 'unchanged',
-    };
+export async function convergePromptVariants(opts) {
+    const { claudeDir, switches, warn } = opts;
     // Precondition, asserted in production code: a relative claudeDir would resolve
     // the install targets somewhere unexpected.
     if (!path.isAbsolute(claudeDir)) {
-        warn(`curation variants: claudeDir is not an absolute path ("${claudeDir}") — skipping convergence`);
-        return empty;
+        warn(`prompt variants: claudeDir is not an absolute path ("${claudeDir}") — skipping convergence`);
+        return notRun(switches, 'the Claude directory is not an absolute path');
     }
     const root = opts.packageRoot ?? getPackageRoot();
     const focuses = installedLanguageFocuses(opts.plugins);
     let failed = false;
+    let unknownReason = null;
+    let manifestHosts = null;
+    if (!switches.compliance) {
+        const manifest = await readVariantHosts(root);
+        if (manifest.ok) {
+            manifestHosts = manifest.hosts;
+        }
+        else {
+            warn(`prompt variants: ${manifest.reason} — the installed prompts that still post cannot be named. Run \`npm run build:mds\`, then \`devflow init\`.`);
+            unknownReason = manifest.reason;
+            failed = true;
+        }
+    }
     let unchanged = 0;
     let notInstalled = 0;
+    const stillPosting = [];
     const rewritten = { commands: [], agents: [] };
+    const links = newLinkReport();
     for (const kind of KINDS) {
-        const roster = await readRoster(kind, root, warn);
+        // A link at the folder sends every write below it into another place, so the folder is proven first.
+        const folderRefused = await refuseUnrealFolder(links, path.join(claudeDir, kind, 'devflow'));
+        if (folderRefused)
+            failed = true;
+        const roster = await readRoster(kind, root, manifestHosts, warn);
+        // A roster read in part is a failed converge. Past the bound, a host left out may carry a
+        // compliance arm, so a compliance-off machine can no longer name every prompt that still posts.
+        if (roster.incomplete !== null)
+            failed = true;
+        if (roster.incomplete === 'truncated' && !switches.compliance && unknownReason === null) {
+            unknownReason = `more than ${MAX_CURATION_ROSTER} ${kind} carry a variant, and the ones past the bound were not converged`;
+        }
+        // A manifest host the roster cannot hold was never converged. If it carries a compliance arm, it may still post.
+        if (roster.refused.length > 0)
+            failed = true;
+        const refusedPosting = roster.refused.find(host => host.axes.compliance);
+        if (refusedPosting !== undefined && !switches.compliance && unknownReason === null) {
+            unknownReason = `the build manifest lists ${kind}/${refusedPosting.file}, a name the converge cannot hold, so it was not converged`;
+        }
         if (!roster.present) {
-            warn(`curation variants: no ${kind} variants under ${curationOffDir(kind, root)} — run \`npm run build:mds\`; installed ${kind} left as they are`);
+            warn(`prompt variants: no ${kind} variants under ${curationOffDir(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, curation, warn, root, focuses });
+        for (const host of roster.hosts) {
+            const outcome = await convergeFile(kind, host, { claudeDir, switches, warn, root, focuses, folderRefused, links });
             if (outcome === 'rewritten')
-                rewritten[kind].push(fileName);
+                rewritten[kind].push(host.file);
             else if (outcome === 'unchanged')
                 unchanged++;
             else if (outcome === 'not-installed')
                 notInstalled++;
-            else
+            else {
                 failed = true;
+                if (!switches.compliance && host.axes.compliance)
+                    stillPosting.push(installedFile(claudeDir, kind, host.file));
+            }
         }
     }
-    // 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;
+    let posting = POSTING_CLEAR;
+    if (unknownReason !== null)
+        posting = { kind: 'unknown', reason: unknownReason };
+    else if (stillPosting.length > 0)
+        posting = { kind: 'left', files: stillPosting };
+    warnLinkReport(links, warn);
     return {
         converged: !failed,
         commandsRewritten: rewritten.commands,
         agentsRewritten: rewritten.agents,
         unchanged,
         notInstalled,
+        posting,
+        replacedLinks: links.replacedLinks,
+        refusedFolders: links.refusedFolders,
+    };
+}
+/**
+ * Run one per-kind converge and fold an unexpected throw into its fallback result, so the
+ * composed converge never throws and a failed kind never skips the next.
+ */
+async function attempt(label, warn, fallback, run) {
+    try {
+        return await run();
+    }
+    catch (err) {
+        warn(`${label}: the converge failed — ${err instanceof Error ? err.message : String(err)}`);
+        return fallback;
+    }
+}
+/**
+ * Converge the workflow skill folders of the selected plugins onto the machine's switches.
+ *
+ * D-WORKFLOW-FOLDER-INSTALL: a folder is complete under every variant key, so a switch of either axis
+ * moves it to the folder of the new exact key (the same read and the same swap as the install), and a
+ * folder that already holds that key's files is left alone. A switch to compliance off writes the
+ * compliance-off folder, which leaves out the files its file list omits, so none of them stays. A
+ * workflow whose plugin is not selected is not installed here and is not removed either: a full
+ * install owns the removal. Never throws.
+ */
+async function convergeWorkflowFolders(opts) {
+    const { claudeDir, switches, plugins, folders, root, warn, backups } = opts;
+    const installed = [];
+    const unchanged = [];
+    const failures = [];
+    const stalled = [];
+    const owned = selectedWorkflowFolders(plugins, workflowFolderNames(folders));
+    for (const folder of folders) {
+        if (!owned.has(folder.name))
+            continue;
+        const target = path.join(claudeDir, 'skills', prefixSkillName(folder.name));
+        const fail = (message) => {
+            warn(`workflow folders: ${message}`);
+            failures.push(message);
+            stalled.push(target);
+        };
+        const read = await readWorkflowFolder(folder, switches, root);
+        if (!read.ok) {
+            fail(read.reason);
+            continue;
+        }
+        const links = newLinkReport();
+        const result = await installWorkflowFolder({ claudeDir, name: folder.name, files: read.files, links, backups });
+        switch (result.outcome) {
+            case 'installed':
+                installed.push(folder.name);
+                break;
+            case 'unchanged':
+                unchanged.push(folder.name);
+                break;
+            case 'refused':
+                fail(refusedFolderMessage(links.refusedFolders[0] ?? target));
+                break;
+            case 'failed':
+                fail(`could not converge ${prefixSkillName(folder.name)} (${result.reason ?? 'unknown error'})`);
+                break;
+            default: {
+                const unhandled = result.outcome;
+                fail(`unhandled folder outcome ${String(unhandled)}`);
+            }
+        }
+    }
+    return { converged: failures.length === 0, installed, unchanged, failures, stalled };
+}
+/**
+ * The posting answer of the workflow-folder converge. Compliance on is clear. With compliance off, a
+ * folder that was not converged still holds the text of the previous key, which may post, so it is named.
+ * A converge that did not finish and names no folder (it threw) cannot say which folders post, so it is
+ * `unknown` and never `clear`.
+ */
+export function workflowFoldersPosting(folders, compliance) {
+    if (compliance)
+        return POSTING_CLEAR;
+    if (folders.stalled.length > 0)
+        return { kind: 'left', files: folders.stalled };
+    if (!folders.converged)
+        return { kind: 'unknown', reason: `the workflow folders: ${folders.failures.join('; ')}` };
+    return POSTING_CLEAR;
+}
+/**
+ * The one converge for both switches: it makes the installed tree match the machine's curation
+ * and compliance switches. `devflow init`, `devflow curation` and `devflow compliance` all call it.
+ *
+ * It composes five per-kind converges, each a result and never a throw:
+ *   - {@link convergePromptVariants}: the commands and agents, for both axes;
+ *   - the apply-decisions skill, which follows the curation switch;
+ *   - {@link convergeFromManifest}: the compliance skill and rule, the one place the manifest
+ *     becomes compliance options;
+ *   - {@link convergeReferences}: the `devflow:git` references, which follow the compliance switch
+ *     (the overlay from the one source root of the switch, then the removal list or the restore);
+ *   - the workflow skill folders, which follow both switches (the folder of the exact key).
+ * A failed kind is a warning and `converged: false`, and the next kind still runs. A compliance-off
+ * machine that still has a prompt or a reference file that posts, or cannot name one, is `posting`
+ * and never `clear`: the caller decides what that costs (the compliance command exits non-zero,
+ * init and curation warn).
+ *
+ * Never throws.
+ */
+export async function convergeVariantAxes(opts) {
+    const { claudeDir, devflowDir, manifest, plugins, warn, packageRoot, backups } = opts;
+    const switches = { curation: manifest.features.curation, compliance: manifest.features.compliance.enabled };
+    // Precondition, asserted in production code: a relative claudeDir would resolve
+    // every install target somewhere unexpected, the skill removal included.
+    if (!path.isAbsolute(claudeDir)) {
+        warn(`prompt variants: claudeDir is not an absolute path ("${claudeDir}") — skipping convergence`);
+        return {
+            ...notRun(switches, 'the Claude directory is not an absolute path'),
+            skill: 'unchanged',
+            compliance: { removedPreexisting: false, converged: false, replacedLinks: [], refusedFolders: [] },
+            references: {
+                converged: false,
+                rewritten: [],
+                removed: [],
+                restored: [],
+                failures: ['the Claude directory is not an absolute path'],
+                stillPosting: [],
+                unproven: !switches.compliance,
+            },
+            workflowFolders: { converged: false, installed: [], unchanged: [], failures: ['the Claude directory is not an absolute path'], stalled: [] },
+        };
+    }
+    const prompts = await attempt('prompt variants', warn, notRun(switches, 'the prompt converge failed'), () => convergePromptVariants({ claudeDir, switches, plugins, warn, packageRoot }));
+    const skillLinks = newLinkReport();
+    const skill = await attempt('curation variants', warn, 'failed', () => convergeSkills({ claudeDir, devflowDir, curation: switches.curation, plugins, warn, packageRoot, backups }, skillLinks));
+    warnLinkReport(skillLinks, warn);
+    const compliance = await attempt('compliance artifacts', warn, { removedPreexisting: false, converged: false, replacedLinks: [], refusedFolders: [] }, () => convergeFromManifest({ claudeDir, devflowDir, manifest, warn, backups }));
+    const references = await attempt('reference converge', warn, {
+        converged: false,
+        rewritten: [],
+        removed: [],
+        restored: [],
+        failures: ['the reference converge failed'],
+        stillPosting: [],
+        unproven: !switches.compliance,
+    }, () => convergeReferences({ claudeDir, devflowDir, compliance: switches.compliance, warn, packageRoot, backups }));
+    const workflowFolders = await attempt('workflow folders', warn, { converged: false, installed: [], unchanged: [], failures: ['the workflow folder converge failed'], stalled: [] }, () => convergeWorkflowFolders({
+        claudeDir,
+        switches,
+        plugins,
+        folders: opts.workflowFolders ?? WORKFLOW_FOLDERS,
+        root: opts.workflowFoldersRoot ?? packageRoot ?? getPackageRoot(),
+        warn,
+        backups,
+    }));
+    return {
+        converged: prompts.converged && skill !== 'failed' && compliance.converged && references.converged && workflowFolders.converged,
+        commandsRewritten: prompts.commandsRewritten,
+        agentsRewritten: prompts.agentsRewritten,
+        unchanged: prompts.unchanged,
+        notInstalled: prompts.notInstalled,
         skill,
+        compliance,
+        references,
+        workflowFolders,
+        posting: mergePosting(mergePosting(prompts.posting, referencesPosting(references)), workflowFoldersPosting(workflowFolders, switches.compliance)),
+        replacedLinks: [...prompts.replacedLinks, ...skillLinks.replacedLinks, ...compliance.replacedLinks],
+        refusedFolders: [...prompts.refusedFolders, ...compliance.refusedFolders],
     };
 }
+/**
+ * The posting answer of the references converge. Compliance on, and a converge that finished, are clear.
+ * A failure that left the overlay unproven cannot name the files that post, so it is `unknown`; a failure
+ * that only left named files in place is `left`.
+ */
+function referencesPosting(references) {
+    if (references.unproven)
+        return { kind: 'unknown', reason: `the installed references: ${references.failures.join('; ')}` };
+    if (references.stillPosting.length > 0)
+        return { kind: 'left', files: references.stillPosting };
+    return POSTING_CLEAR;
+}
+/**
+ * Join the posting answers of two kinds. `unknown` wins, because a file list that leaves a kind out
+ * would claim more than was proven; two unknowns keep both reasons; two lists join.
+ */
+function mergePosting(a, b) {
+    if (a.kind === 'unknown' && b.kind === 'unknown')
+        return { kind: 'unknown', reason: `${a.reason}; ${b.reason}` };
+    if (a.kind === 'unknown')
+        return a;
+    if (b.kind === 'unknown')
+        return b;
+    if (a.kind === 'left' && b.kind === 'left')
+        return { kind: 'left', files: [...a.files, ...b.files] };
+    return a.kind === 'left' ? a : b;
+}
 // ── 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()) {
@@ -420,18 +815,57 @@ export async function readRunningVersion(packageRoot = getPackageRoot()) {
  * The caller prints it only on a toggle: a run that moved nothing says nothing.
  */
 export function describeCurationConverge(result, curation) {
+    return describeVariantConverge(result, 'curation', curation);
+}
+/**
+ * One line for what a converge changed on an axis, or null when it changed nothing: the prompts
+ * rewritten for the variant the axis now holds and, for curation, the skill it installed or removed.
+ */
+export function describeVariantConverge(result, axis, enabled) {
     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 curation-${curation ? 'on' : 'off'} variant`);
+            `rewritten for the ${axis}-${enabled ? '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');
+    const references = result.references;
+    if (references !== undefined) {
+        const changed = references.rewritten.length + references.restored.length;
+        if (changed > 0)
+            parts.push(`${changed} reference file(s) written`);
+        if (references.removed.length > 0)
+            parts.push(`${references.removed.length} reference file(s) removed`);
+    }
     return parts.length === 0 ? null : parts.join('; ');
 }
+/**
+ * The lines that say a compliance-off machine may still hold a prompt that posts, or none when
+ * the converge proved it clear. The files are the installed ones that could not be converged.
+ */
+export function describePostingLeft(posting) {
+    switch (posting.kind) {
+        case 'clear':
+            return [];
+        case 'left':
+            return [
+                `${posting.files.length} installed file(s) still post: ${posting.files.join(', ')}`,
+                'Run `devflow init` to install the compliance-off files. If init cannot remove one, delete it by hand.',
+            ];
+        case 'unknown':
+            return [
+                `The installed files that still post cannot be named: ${posting.reason}`,
+                'Run `devflow init` to install the compliance-off files.',
+            ];
+        default: {
+            const unhandled = posting;
+            return [`unhandled posting state ${JSON.stringify(unhandled)}`];
+        }
+    }
+}
 /**
  * Whether the version the manifest records is the version of the running package.
  * Pure. An unknown running version (null) never matches: the installed files are then
@@ -448,10 +882,27 @@ export function installedVersionMatches(installedVersion, runningVersion) {
  * `describeEchoedValue`.
  */
 export function curationToggleSkew(installedVersion, runningVersion, curation) {
+    return variantToggleSkew(installedVersion, runningVersion, 'curation', curation);
+}
+/**
+ * The version-skew check for a toggle of either axis. A compliance-off toggle also says that posting
+ * steps remain installed, because that is the unsafe side of the mismatch: the installed prompts are
+ * the ones that carry them.
+ */
+export function variantToggleSkew(installedVersion, runningVersion, axis, enabled) {
     if (installedVersionMatches(installedVersion, runningVersion))
         return null;
-    return (`The installed prompts come from devflow ${describeEchoedValue(installedVersion)} and this CLI is ${runningVersion ?? 'of unknown version'}, ` +
-        `so the curation-${curation ? 'on' : 'off'} variants were not applied. Run \`devflow init\` to apply them.`);
+    const skew = `The installed prompts come from devflow ${describeEchoedValue(installedVersion)} and this CLI is ${runningVersion ?? 'of unknown version'}, ` +
+        `so the ${axis}-${enabled ? 'on' : 'off'} variants were not applied`;
+    return axis === 'compliance' && !enabled
+        ? `${skew}, and posting steps remain installed until devflow init. Run \`devflow init\` to apply them.`
+        : `${skew}. Run \`devflow init\` to apply them.`;
+}
+/** The line for a toggle that found no readable install manifest. */
+function unreadableManifestMessage(axis, enabled) {
+    return axis === 'compliance' && !enabled
+        ? 'No readable install manifest, so the compliance-off variants were not applied, and posting steps remain installed until devflow init. Run `devflow init`.'
+        : `No readable install manifest, so the ${axis} variants were not applied. Run \`devflow init\`.`;
 }
 /**
  * The version-skew line for a command that writes curation data, or null when the
@@ -474,9 +925,66 @@ export async function installedScriptsSkew(devflowDir, packageRoot) {
         `${running ?? 'of unknown version'}. Run \`devflow init\` first. Nothing was written.`);
 }
 /**
- * What `devflow curation --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.
+ * Record the variants the installed prompts now hold in the manifest, after a converge that
+ * finished clean (AC-29). A record that already says so is left alone, so a toggle to the value
+ * already installed writes nothing. A failed write is a warning: the status line then reads
+ * the record as it stood, which says `mismatch` or `unknown` and names `devflow init`.
+ *
+ * The read and the write run under the manifest lock, as the switch writers do, so a switch that
+ * another devflow run writes in between is never overwritten with the older copy read here. The
+ * record is written only when the manifest's switches are still the ones the run converged to: if
+ * they changed during the run, nothing is recorded, the record that stood is removed in the same
+ * locked write (the status then reads unknown) and a warning says so. A lock that cannot be
+ * taken, or is lost before the write, withholds the record with a warning.
+ */
+async function recordInstalledVariants(devflowDir, switches, warn) {
+    try {
+        const locked = await withManifestLock(devflowDir, {}, async (lock) => {
+            const manifest = await readManifest(devflowDir);
+            if (manifest === null)
+                return 'no-manifest';
+            if (manifest.features.curation !== switches.curation || manifest.features.compliance.enabled !== switches.compliance) {
+                // The record names switches that no longer hold: remove it, so the status reads unknown.
+                if (!Object.hasOwn(manifest, 'installedVariants'))
+                    return 'switches-changed';
+                if (!(await lock.stillHeld()))
+                    return 'lock-lost';
+                const { installedVariants: _stale, ...unrecorded } = manifest;
+                await writeManifest(devflowDir, unrecorded);
+                return 'switches-changed';
+            }
+            const recorded = readInstalledVariants(manifest.installedVariants);
+            if (recorded !== null && recorded.curation === switches.curation && recorded.compliance === switches.compliance)
+                return 'current';
+            if (!(await lock.stillHeld()))
+                return 'lock-lost';
+            await writeManifest(devflowDir, { ...manifest, installedVariants: { curation: switches.curation, compliance: switches.compliance } });
+            return 'written';
+        });
+        if (!locked.ok || locked.value === 'lock-lost') {
+            warn('install record: the install manifest lock could not be held, so the installed variants were not recorded. Run `devflow init`.');
+        }
+        else if (locked.value === 'no-manifest') {
+            warn('install record: no readable install manifest, so the installed variants were not recorded. Run `devflow init`.');
+        }
+        else if (locked.value === 'switches-changed') {
+            warn('install record: the switches changed during the run, so the installed variants were not recorded. Run `devflow init`.');
+        }
+    }
+    catch (err) {
+        warn(`install record: could not record the installed variants — ${String(err)}`);
+    }
+}
+/**
+ * What `devflow curation --enable/--disable` and `devflow compliance` do after the switch is
+ * written: converge the installed tree onto both switches with the one converge, record the
+ * installed variants when it finished clean, then reapply the saved agent model and effort mapping.
+ *
+ * The switch of the toggled axis is the value the caller just set. The other axis and the
+ * compliance frameworks come from the manifest, which the caller has already written.
+ *
+ * A version skew keeps the check this toggle has always had: the installed prompts are not the
+ * ones this package would rewrite, so nothing is converged and the outcome is `skipped`.
  *
  * 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
@@ -487,28 +995,35 @@ export async function installedScriptsSkew(devflowDir, packageRoot) {
  *
  * Never throws.
  */
-export async function applyCurationToggle(opts) {
-    const { claudeDir, devflowDir, curation, runningVersion, warn } = opts;
+export async function applyVariantToggle(opts) {
+    const { claudeDir, devflowDir, axis, enabled, runningVersion, warn } = opts;
     const manifest = await readManifest(devflowDir);
     if (manifest === null) {
-        return {
-            kind: 'skipped',
-            reason: 'no-manifest',
-            message: 'No readable install manifest, so the curation variants were not applied. Run `devflow init`.',
-        };
+        return { kind: 'skipped', reason: 'no-manifest', message: unreadableManifestMessage(axis, enabled) };
     }
-    const skew = curationToggleSkew(manifest.version, runningVersion, curation);
+    const skew = variantToggleSkew(manifest.version, runningVersion, axis, enabled);
     if (skew !== null)
         return { kind: 'skipped', reason: 'version-skew', message: skew };
     const selection = new Set(manifest.plugins);
-    const result = await convergeCurationVariants({
+    const state = {
+        features: {
+            curation: axis === 'curation' ? enabled : manifest.features.curation,
+            compliance: axis === 'compliance' ? { ...manifest.features.compliance, enabled } : manifest.features.compliance,
+            rules: manifest.features.rules,
+        },
+    };
+    const result = await convergeVariantAxes({
         claudeDir,
         devflowDir,
-        curation,
+        manifest: state,
         plugins: DEVFLOW_PLUGINS.filter(plugin => selection.has(plugin.name)),
         warn,
         packageRoot: opts.packageRoot,
+        backups: opts.backups,
     });
+    if (result.converged) {
+        await recordInstalledVariants(devflowDir, { curation: state.features.curation, compliance: state.features.compliance.enabled }, warn);
+    }
     let agentMappingReapplied = false;
     if (result.agentsRewritten.length > 0) {
         try {
@@ -521,7 +1036,7 @@ export async function applyCurationToggle(opts) {
             agentMappingReapplied = true;
         }
         catch (err) {
-            warn(`curation variants: could not reapply the agent model mapping — ${String(err)}`);
+            warn(`prompt variants: could not reapply the agent model mapping — ${String(err)}`);
         }
     }
     return { kind: 'converged', result, agentMappingReapplied };