devflow-kit 3.9.0 → 3.11.0

package/dist/targets/claude-code/shipped-set.js

@@ -0,0 +1,160 @@
+/**
+ * The shipped set: every file path, relative to the Claude dir, that some install of this build
+ * can write into `commands/devflow`, `agents/devflow`, `rules/devflow` and `skills/devflow:*`.
+ *
+ * The backup session moves a file out of those folders unless the set names it, so the set errs
+ * toward too large. It comes from the full registries and all four variants (compliance on and
+ * off, curation on and off), never from the selection of one run and never from what an earlier
+ * install left on disk:
+ *
+ *   - commands: every plugin command, also a workflow that ships as a skill folder, since the
+ *     old command file of such a workflow is removed as a shipped file and never moved;
+ *   - agents and rules: every plugin entry, the feature-owned rules and the tracker agent;
+ *   - skills: the files of each registry skill in the package source, the generated references
+ *     of the compliance-on manifest, the compliance skill the converge writes, and the files only
+ *     a compliance-on install writes;
+ *   - workflow folders: the files of each registered folder under all four variant keys;
+ *   - shadows: the listing of a valid skill shadow counts beside the listing it replaces.
+ *
+ * {@link buildShippedSet} is pure. {@link loadShippedSet} reads the package and the shadows from
+ * disk, within fixed bounds, and answers with a reason instead of a smaller set when it cannot.
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { skillsDir } from '../../core/assets.js';
+import { complianceSkillFiles } from '../../core/compliance.js';
+import { COMPLIANCE_OFF_REMOVED_SKILL_FILES } from '../../core/compliance-off-files.js';
+import { VARIANT_KEYS } from '../../core/curation-variants.js';
+import { SKILL_REFS_SKILL_NAME, installedReferenceManifest, workflowFolderFiles, } from '../../core/mds-variants.js';
+import { createPathSet } from '../../core/path-set.js';
+import { FEATURE_OWNED_RULES, getAllAgentNames, getAllCommandNames, getAllRuleNames, getAllSkillNames, prefixSkillName, } from '../../core/plugins.js';
+import { validateSkillShadow } from './installer.js';
+import { TRACKER_AGENT_NAME } from './tracker-install.js';
+/** The most files one listed skill folder may hold. A folder past it is a failed listing. */
+export const MAX_LISTED_FILES = 2_000;
+/** The deepest level a listed folder may reach, counting the listed root as 0. */
+export const MAX_LISTED_DEPTH = 6;
+/** The most folders one listing may visit. */
+export const MAX_LISTED_FOLDERS = 500;
+const IGNORED_FILE_NAME = '.DS_Store';
+const commandPath = (name) => `commands/devflow/${name}.md`;
+const agentPath = (name) => `agents/devflow/${name}.md`;
+const rulePath = (name) => `rules/devflow/${name}.md`;
+const skillPath = (skill, file) => `skills/${prefixSkillName(skill)}/${file}`;
+/**
+ * The file paths of the shipped set. Pure: the registries are constants, and the package and
+ * shadow listings come in as inputs.
+ */
+export function shippedPaths(inputs) {
+    const paths = new Set();
+    for (const name of getAllCommandNames(new Set()))
+        paths.add(commandPath(name));
+    for (const name of [...getAllAgentNames(), TRACKER_AGENT_NAME])
+        paths.add(agentPath(name));
+    for (const name of [...getAllRuleNames(), ...FEATURE_OWNED_RULES])
+        paths.add(rulePath(name));
+    for (const [skill, files] of inputs.packageSkillFiles) {
+        for (const file of files)
+            paths.add(skillPath(skill, file));
+    }
+    for (const [skill, files] of inputs.shadowListings ?? []) {
+        for (const file of files)
+            paths.add(skillPath(skill, file));
+    }
+    for (const rel of installedReferenceManifest({ compliance: true })) {
+        paths.add(skillPath(SKILL_REFS_SKILL_NAME, `references/${rel}`));
+    }
+    for (const entry of COMPLIANCE_OFF_REMOVED_SKILL_FILES)
+        paths.add(`skills/${entry}`);
+    for (const file of complianceSkillFiles())
+        paths.add(skillPath('compliance', file));
+    for (const folder of inputs.workflowFolders) {
+        for (const key of VARIANT_KEYS) {
+            for (const file of workflowFolderFiles(folder, key))
+                paths.add(skillPath(folder.name, file));
+        }
+    }
+    return paths;
+}
+/** The shipped set of {@link shippedPaths}, ready for the backup session. */
+export function buildShippedSet(inputs) {
+    return createPathSet(shippedPaths(inputs));
+}
+/**
+ * The files below `root` as POSIX paths, sorted per folder. Folders are entered only as real
+ * folders (a link is listed as a file and never entered). The listing is bounded by
+ * {@link MAX_LISTED_FILES}, {@link MAX_LISTED_DEPTH} and {@link MAX_LISTED_FOLDERS}; a breach or a
+ * read error is a failed listing, since a smaller listing would be a smaller set.
+ */
+async function listFiles(root) {
+    const files = [];
+    const pending = [
+        { dir: root, rel: '', depth: 0 },
+    ];
+    for (let visited = 0; visited < MAX_LISTED_FOLDERS; visited++) {
+        const next = pending.pop();
+        if (next === undefined)
+            return { ok: true, files };
+        let entries;
+        try {
+            entries = await fs.readdir(next.dir, { withFileTypes: true });
+        }
+        catch (err) {
+            const code = err.code;
+            return { ok: false, reason: `could not read ${next.dir} (${typeof code === 'string' ? code : 'error'})` };
+        }
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            const rel = next.rel === '' ? entry.name : `${next.rel}/${entry.name}`;
+            if (entry.isDirectory()) {
+                if (next.depth + 1 > MAX_LISTED_DEPTH)
+                    return { ok: false, reason: `${root} is deeper than ${MAX_LISTED_DEPTH} levels` };
+                pending.push({ dir: path.join(next.dir, entry.name), rel, depth: next.depth + 1 });
+            }
+            else if ((entry.isFile() || entry.isSymbolicLink()) && entry.name !== IGNORED_FILE_NAME) {
+                if (files.length >= MAX_LISTED_FILES)
+                    return { ok: false, reason: `${root} holds more than ${MAX_LISTED_FILES} files` };
+                files.push(rel);
+            }
+        }
+    }
+    return pending.length === 0
+        ? { ok: true, files }
+        : { ok: false, reason: `${root} holds more than ${MAX_LISTED_FOLDERS} folders` };
+}
+/**
+ * Build the shipped set from the registries, the package skill source and the skill shadows.
+ *
+ * Every registry skill is listed from `skillsDir(packageRoot)`. A skill whose source is missing is
+ * a failed load, not a smaller set: the caller then runs no scan, because a set that lacks a
+ * shipped file would send that file to the backup folder.
+ */
+export async function loadShippedSet(options) {
+    const skills = getAllSkillNames(new Set());
+    const packageSkillFiles = new Map();
+    for (const skill of skills) {
+        const listed = await listFiles(path.join(skillsDir(options.packageRoot), skill));
+        if (!listed.ok)
+            return { ok: false, reason: `skill "${skill}": ${listed.reason}` };
+        packageSkillFiles.set(skill, listed.files);
+    }
+    let shadowListings = options.shadowListings;
+    if (shadowListings === undefined) {
+        const found = new Map();
+        for (const skill of skills) {
+            const shadowDir = path.join(options.devflowDir, 'skills', skill);
+            if ((await validateSkillShadow(shadowDir)) !== 'valid')
+                continue;
+            const listed = await listFiles(shadowDir);
+            if (!listed.ok)
+                return { ok: false, reason: `shadow of skill "${skill}": ${listed.reason}` };
+            found.set(skill, listed.files);
+        }
+        shadowListings = found;
+    }
+    return {
+        ok: true,
+        shipped: buildShippedSet({ packageSkillFiles, shadowListings, workflowFolders: options.workflowFolders }),
+    };
+}
+//# sourceMappingURL=shipped-set.js.map

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

@@ -15,6 +15,7 @@ import { stampAgentTools } from '../../core/agent-frontmatter.js';
 import { agentSourceDirs } from '../../core/assets.js';
 import { mdFileName } from '../../core/orphan-sweep.js';
 import { TRACKER_MCP_SERVERS_DEFAULT, trackerServerTools } from '../../core/tracker.js';
+import { newLinkReport, refuseUnrealFolder, warnLinkReport, writeFileReplacingLink } from './linked-folder.js';
 /**
  * The agent this module owns.
  *
@@ -97,55 +98,67 @@ async function writeWouldChangeNothing(wanted, target) {
  * nothing reports `unchanged` and the summary stays quiet
  * (see {@link writeWouldChangeNothing}).
  *
+ * An `agents/devflow` that is a link, or not a folder, is refused: nothing is written there, and the
+ * folder is named in `refusedFolders` and in a warning. A `tracker.md` that is a link is replaced by a
+ * real file, and named in `replacedLinks` and in a warning.
+ *
  * Never throws. A caller reads `converged`; it does not catch. The one refusal
  * that is not an I/O degradation — 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 convergeTrackerArtifacts(opts) {
     const { claudeDir, warn } = opts;
+    const links = newLinkReport();
+    const finish = (converged, agent) => {
+        warnLinkReport(links, warn);
+        return { converged, agent, replacedLinks: links.replacedLinks, refusedFolders: links.refusedFolders };
+    };
     // Precondition, asserted in production code rather than only in tests: an
     // empty or relative claudeDir would make the target resolve somewhere
     // unexpected.
     if (!path.isAbsolute(claudeDir)) {
         warn(`tracker: claudeDir is not an absolute path ("${claudeDir}") — skipping convergence`);
-        return { converged: false, agent: 'unchanged' };
+        return finish(false, 'unchanged');
     }
     const target = agentTarget(claudeDir);
+    // A link at the folder sends the write into another place, so the folder is proven first.
+    if (await refuseUnrealFolder(links, path.dirname(target)))
+        return finish(false, 'unchanged');
     const dirs = opts.agentSourceDirs ?? agentSourceDirs();
     const candidates = dirs.map(dir => path.join(dir, mdFileName(TRACKER_AGENT_NAME)));
     const source = await firstExisting(candidates);
     if (source === undefined) {
         warn(`tracker: agent source not found for "${TRACKER_AGENT_NAME}" (searched: ${candidates.join(', ')}) — ` +
             `run \`npm run build:mds\` if it is compiled from an .mds generator host`);
-        return { converged: false, agent: 'unchanged' };
+        return finish(false, 'unchanged');
     }
     let wanted;
     try {
         const stamped = stampAgentTools(await fs.readFile(source, 'utf-8'), trackerServerTools(opts.servers ?? TRACKER_MCP_SERVERS_DEFAULT));
         if (!stamped.ok) {
             warn(`tracker: the Tracker agent source could not take the tracker servers (${stamped.error}) — not installed`);
-            return { converged: false, agent: 'unchanged' };
+            return finish(false, 'unchanged');
         }
         wanted = stamped.value.content;
     }
     catch (err) {
         warn(`tracker: cannot read the Tracker agent source (${source}) — ${String(err)}`);
-        return { converged: false, agent: 'unchanged' };
+        return finish(false, 'unchanged');
     }
     // Already converged — nothing to write, and nothing for the summary to announce.
     // The directory is not created either: an identical file at the target means it is
     // already there (see {@link writeWouldChangeNothing}).
     if (await writeWouldChangeNothing(wanted, target)) {
-        return { converged: true, agent: 'unchanged' };
+        return finish(true, 'unchanged');
     }
     try {
         await fs.mkdir(path.dirname(target), { recursive: true });
-        await fs.writeFile(target, wanted);
+        await writeFileReplacingLink(target, wanted, links);
     }
     catch (err) {
         warn(`tracker: failed to install the Tracker agent (${target}) — ${String(err)}`);
-        return { converged: false, agent: 'unchanged' };
+        return finish(false, 'unchanged');
     }
-    return { converged: true, agent: 'installed' };
+    return finish(true, 'installed');
 }
 //# sourceMappingURL=tracker-install.js.map

package/dist/targets/claude-code/tracker-servers.js

@@ -17,7 +17,7 @@
  *          a `--plugin` run that does not install Git leaves the installed, stamped copy alone.
  *       2. `convergeTrackerArtifacts` stamps Tracker as it writes it, and compares the STAMPED text
  *          with the installed file, so a steady-state run reports `unchanged`.
- *       3. `convergeCurationVariants` (init, `devflow curation --enable/--disable`) carries the
+ *       3. `convergeVariantAxes` (init, `devflow curation` and `devflow compliance`) carries the
  *          installed stamp onto the variant it writes (`carryStampedTools`), the way it carries
  *          `model:` and `effort:`, so a variant switch keeps the list and a repeat run is byte-equal.
  *       4. `devflow tracker --servers` re-stamps the installed copies at once ({@link restampTrackerAgents}).
@@ -34,9 +34,9 @@
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import { stampAgentTools } from '../../core/agent-frontmatter.js';
-import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
 import { mdFileName } from '../../core/orphan-sweep.js';
 import { trackerServerTools } from '../../core/tracker.js';
+import { newLinkReport, refuseUnrealFolder, warnLinkReport, writeFileReplacingLink } from './linked-folder.js';
 import { TRACKER_AGENT_NAME } from './tracker-install.js';
 /** The registry name of the Git agent. */
 export const GIT_AGENT_NAME = 'git';
@@ -51,7 +51,10 @@ export function isTrackerStampedAgent(agentName) {
  *
  * Rewrites only an installed copy (an absent one stays absent), compares against the bytes on
  * disk at the moment of writing, and writes atomically only when they differ, so a run that
- * changes nothing writes nothing. Never throws.
+ * changes nothing writes nothing. An `agents/devflow` that is a link, or not a folder, is refused:
+ * nothing is written there, both agents are `failed`, and the folder is named in `refusedFolders` and
+ * in a warning. An agent file that is a link is replaced by a real file, and named in `replacedLinks`
+ * and in a warning. Never throws.
  */
 export async function restampTrackerAgents(opts) {
     const { claudeDir, servers, warn } = opts;
@@ -59,11 +62,22 @@ export async function restampTrackerAgents(opts) {
     const unchanged = [];
     const absent = [];
     const failed = [];
+    const links = newLinkReport();
+    const finish = () => {
+        warnLinkReport(links, warn);
+        return { rewritten, unchanged, absent, failed, replacedLinks: links.replacedLinks, refusedFolders: links.refusedFolders };
+    };
     // Precondition, asserted in production code: a relative claudeDir would resolve the targets
     // against the working directory.
     if (!path.isAbsolute(claudeDir)) {
         warn(`tracker servers: claudeDir is not an absolute path ("${claudeDir}") — the installed agents were not stamped`);
-        return { rewritten, unchanged, absent, failed: [...TRACKER_STAMPED_AGENTS] };
+        failed.push(...TRACKER_STAMPED_AGENTS);
+        return finish();
+    }
+    // A link at the folder sends every write below it into another place, so the folder is proven first.
+    if (await refuseUnrealFolder(links, path.join(claudeDir, 'agents', 'devflow'))) {
+        failed.push(...TRACKER_STAMPED_AGENTS);
+        return finish();
     }
     const tools = trackerServerTools(servers);
     for (const agent of TRACKER_STAMPED_AGENTS) {
@@ -94,7 +108,7 @@ export async function restampTrackerAgents(opts) {
             continue;
         }
         try {
-            await writeFileAtomicExclusive(target, stamped.value.content);
+            await writeFileReplacingLink(target, stamped.value.content, links);
             rewritten.push(agent);
         }
         catch (err) {
@@ -102,6 +116,6 @@ export async function restampTrackerAgents(opts) {
             failed.push(agent);
         }
     }
-    return { rewritten, unchanged, absent, failed };
+    return finish();
 }
 //# sourceMappingURL=tracker-servers.js.map

package/dist/targets/claude-code/workflow-folder-install.js

@@ -0,0 +1,251 @@
+/**
+ * Install of a workflow skill folder: `skills/devflow:<name>/`, from the build tree of the
+ * machine's exact variant key.
+ *
+ * D-WORKFLOW-FOLDER-INSTALL: the install (installViaFileCopy) and the converge
+ * (convergeVariantAxes, for init, `devflow curation` and `devflow compliance`) both call
+ * {@link installWorkflowFolder} after {@link readWorkflowFolder}, so a folder the install writes
+ * and a folder the converge writes after a switch are the same bytes. Three rules hold:
+ *
+ *   - ONE source root: the tree built for exactly the machine's two switches
+ *     (workflowFoldersSourceDir). A key whose tree lacks the folder, or lacks a file of its own
+ *     file list, is a failed read. Nothing falls through to another key, so a compliance-off
+ *     machine never receives the text of the compliance-on tree.
+ *   - EXACTLY the key's file list (workflowFolderFiles): the installed folder holds those files
+ *     and no others. A file the list omits for the key, and any other file below the folder, is
+ *     pruned by the swap, so a switch to compliance off leaves no file the compliance-off list omits.
+ *   - ONE swap: the folder is staged beside the skills folder and moved into place, and the old
+ *     folder is restored if the move fails. If the restore fails too, the old folder is kept where
+ *     it was moved to and the result names that path (`recoveryPath`); nothing deletes a backup
+ *     that the result names as the way back. A folder that already holds the exact files is not
+ *     touched, so an install that changes nothing writes nothing.
+ *   - NO LOSS of the user's files: before any rename, the backup session moves every file of the
+ *     old folder that devflow did not ship (the files of all four variant keys count as shipped)
+ *     to the backup folder. If one cannot move, the result is `failed` and the folder stays as it
+ *     is. After the swap the displaced folder is scanned again, its shipped files are removed by the
+ *     session's list, and it goes with a plain `rmdir`; no folder is removed with a recursive `rm`
+ *     except the staging folder, which holds only the copies this call wrote.
+ *
+ * A link at the skills folder or at the folder, or anything there that is not a folder, is refused
+ * and recorded in `links.refusedFolders`; a link is never followed and never written through.
+ * The folder name is checked at both entry points (the read and the install) with the output-name
+ * rule of the registry, because it is joined onto paths, one of them removed recursively.
+ * Nothing here throws: a failure is a result with a reason.
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { workflowFoldersSourceDir } from '../../core/assets.js';
+import { describeBuildIdCheckError, describeWorkflowFolderError, validateOutputName, verifyFolderBuildId, workflowFolderFiles, workflowFolderKey, } from '../../core/mds-variants.js';
+import { isContainedIn } from '../../core/paths.js';
+import { prefixSkillName } from '../../core/plugins.js';
+import { discardDisplacedFolder } from './folder-swap.js';
+import { formatCappedList } from './install-backup.js';
+import { directoryState, refuseUnrealFolder } from './linked-folder.js';
+/** The deepest level of a folder that is read or compared: `references/<file>` is level 1. */
+const MAX_FOLDER_DEPTH = 4;
+/** The folder inside the staging folder that is moved into place. */
+const STAGED_FOLDER = 'folder';
+/** Where the old folder waits while the new one is moved in: beside its staging folder. */
+export const backupOf = (staging) => `${staging}.old`;
+/** The prefix of the staging folder of one folder install; `mkdtemp` adds six random characters. */
+export const stagingPrefixOf = (claudeDir, name) => path.join(claudeDir, `.devflow-workflow-${name}-${process.pid}-`);
+const errorMessage = (err) => (err instanceof Error ? err.message : String(err));
+/**
+ * Read the files one folder holds under the exact variant key of `switches`.
+ *
+ * Fails, with a reason that names the folder, when its name is not a plain folder name, when the
+ * key's tree lacks the folder, when the folder is a link or not a folder, when a file of the key's
+ * list is missing or is not a plain file, when the stamped files do not carry one build id (a build
+ * that stopped half-way), or when that id is not the id of the files as read (a file from another
+ * build, or one changed after the build). The id is recomputed over every file of the key's list.
+ *
+ * @param root - Package root the build tree is read from.
+ */
+export async function readWorkflowFolder(folder, switches, root) {
+    const named = validateOutputName(folder.name);
+    if (!named.ok) {
+        return { ok: false, reason: describeWorkflowFolderError({ kind: 'bad-folder-name', folder: folder.name, error: named.error }) };
+    }
+    const key = workflowFolderKey(switches);
+    const dir = path.join(workflowFoldersSourceDir(switches, root), folder.name);
+    if ((await directoryState(dir)) !== 'real') {
+        return {
+            ok: false,
+            reason: `workflow folder '${folder.name}' is not built for the variant key '${key}' (${dir}). Ensure build:mds ran successfully before install.`,
+        };
+    }
+    const files = [];
+    for (const rel of workflowFolderFiles(folder, key)) {
+        if (!isContainedIn(dir, rel)) {
+            return { ok: false, reason: `workflow folder '${folder.name}' names the file '${rel}', which leaves the folder` };
+        }
+        const source = path.join(dir, ...rel.split('/'));
+        try {
+            if (!(await fs.lstat(source)).isFile()) {
+                return { ok: false, reason: `${source} is not a plain file` };
+            }
+            files.push({ file: rel, bytes: await fs.readFile(source) });
+        }
+        catch (err) {
+            return { ok: false, reason: `${source} could not be read (${errorMessage(err)})` };
+        }
+    }
+    const ids = verifyFolderBuildId(files.map(({ file, bytes }) => ({ file, body: bytes.toString('utf-8') })));
+    if (!ids.ok) {
+        return { ok: false, reason: `workflow folder '${folder.name}' (${key}): ${describeBuildIdCheckError(ids.error)}` };
+    }
+    return { ok: true, files };
+}
+/**
+ * Every entry below `dir` as sorted POSIX paths: a file as `a/b.md`, a folder as `a/`. Null when
+ * anything is neither a plain file nor a folder (a link, a socket), or the walk is deeper than the bound.
+ */
+async function listEntries(dir, prefix = '', depth = 0) {
+    if (depth > MAX_FOLDER_DEPTH)
+        return null;
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    const out = [];
+    for (const entry of entries) {
+        const rel = `${prefix}${entry.name}`;
+        if (entry.isDirectory()) {
+            const nested = await listEntries(path.join(dir, entry.name), `${rel}/`, depth + 1);
+            if (nested === null)
+                return null;
+            out.push(`${rel}/`, ...nested);
+        }
+        else if (entry.isFile()) {
+            out.push(rel);
+        }
+        else {
+            return null;
+        }
+    }
+    return out.sort();
+}
+/** The entries a folder of exactly these files holds: the files and the folders that hold them. */
+function expectedEntries(files) {
+    const entries = new Set();
+    for (const { file } of files) {
+        entries.add(file);
+        const parts = file.split('/');
+        for (let i = 1; i < parts.length; i++)
+            entries.add(`${parts.slice(0, i).join('/')}/`);
+    }
+    return [...entries].sort();
+}
+/** True only when `target` holds exactly these files with exactly these bytes. Any error answers false. */
+async function folderHolds(target, files) {
+    const listed = await listEntries(target);
+    const wanted = expectedEntries(files);
+    if (listed === null || listed.length !== wanted.length || listed.some((entry, i) => entry !== wanted[i]))
+        return false;
+    for (const { file, bytes } of files) {
+        try {
+            if (!bytes.equals(await fs.readFile(path.join(target, ...file.split('/')))))
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Write `skills/devflow:<name>/` as exactly `files`: move the user's files aside, stage, then swap
+ * in. See the module comment.
+ *
+ * The staging folder sits under `claudeDir`, not under `skills/`, so a folder a crash leaves
+ * behind never looks like a second skill to Claude Code. It is made by `mkdtemp`, an exclusive
+ * create, so nothing that stands at a guessed name is written through; its name carries the
+ * unit kind, the folder name and the process id, and `mkdtemp` adds the random token. The folder
+ * is built in a folder inside it, which keeps the default mode of a folder this process makes.
+ * Never throws.
+ */
+export async function installWorkflowFolder(opts) {
+    const { claudeDir, name, files, links, backups } = opts;
+    if (!path.isAbsolute(claudeDir)) {
+        return { name, outcome: 'failed', reason: `claudeDir is not an absolute path ("${claudeDir}")` };
+    }
+    const named = validateOutputName(name);
+    if (!named.ok) {
+        return { name, outcome: 'failed', reason: describeWorkflowFolderError({ kind: 'bad-folder-name', folder: name, error: named.error }) };
+    }
+    const skillsDir = path.join(claudeDir, 'skills');
+    const target = path.join(skillsDir, prefixSkillName(name));
+    const escaping = files.find(({ file }) => !isContainedIn(target, file));
+    if (escaping !== undefined) {
+        return { name, outcome: 'failed', reason: `workflow folder '${name}' names the file '${escaping.file}', which leaves the folder` };
+    }
+    if (await refuseUnrealFolder(links, skillsDir))
+        return { name, outcome: 'refused' };
+    if (await refuseUnrealFolder(links, target))
+        return { name, outcome: 'refused' };
+    let staging = null;
+    try {
+        if ((await directoryState(target)) === 'real') {
+            // Before any rename: what devflow did not ship moves out of the folder, whichever key's files it holds.
+            await backups.prepass([target]);
+            const kept = backups.keptUnder(target);
+            if (kept.length > 0) {
+                return {
+                    name,
+                    outcome: 'failed',
+                    reason: `${kept.length} file(s) in ${target} could not be moved aside, so the folder was left as it is: ${formatCappedList(kept)}`,
+                };
+            }
+            if (await folderHolds(target, files))
+                return { name, outcome: 'unchanged' };
+        }
+        await fs.mkdir(claudeDir, { recursive: true });
+        staging = await fs.mkdtemp(stagingPrefixOf(claudeDir, name));
+        const staged = path.join(staging, STAGED_FOLDER);
+        await fs.mkdir(staged);
+        for (const { file, bytes } of files) {
+            const stagedFile = path.join(staged, ...file.split('/'));
+            await fs.mkdir(path.dirname(stagedFile), { recursive: true });
+            await fs.writeFile(stagedFile, bytes);
+        }
+        await fs.mkdir(skillsDir, { recursive: true });
+        const hadTarget = (await directoryState(target)) === 'real';
+        const backup = backupOf(staging);
+        if (hadTarget)
+            await fs.rename(target, backup);
+        try {
+            await fs.rename(staged, target);
+        }
+        catch (err) {
+            if (!hadTarget)
+                throw err;
+            try {
+                await fs.rename(backup, target);
+            }
+            catch (restoreErr) {
+                return {
+                    name,
+                    outcome: 'failed',
+                    reason: `${errorMessage(err)}; the previous folder could not be put back (${errorMessage(restoreErr)}) and is kept at ${backup}`,
+                    recoveryPath: backup,
+                };
+            }
+            throw err;
+        }
+        // The displaced folder is scanned again, because a file can arrive after the first scan.
+        if (hadTarget)
+            await discardDisplacedFolder(backups, backup, target);
+        return { name, outcome: 'installed' };
+    }
+    catch (err) {
+        return { name, outcome: 'failed', reason: errorMessage(err) };
+    }
+    finally {
+        if (staging !== null)
+            await fs.rm(staging, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+//# sourceMappingURL=workflow-folder-install.js.map

package/dist/variant-axes.json

@@ -0,0 +1,109 @@
+{
+  "version": 1,
+  "hosts": {
+    "agents/code": {
+      "curation": true,
+      "compliance": false
+    },
+    "agents/debug": {
+      "curation": true,
+      "compliance": false
+    },
+    "agents/design": {
+      "curation": true,
+      "compliance": false
+    },
+    "agents/fix": {
+      "curation": true,
+      "compliance": false
+    },
+    "agents/git": {
+      "curation": false,
+      "compliance": true
+    },
+    "agents/harden": {
+      "curation": true,
+      "compliance": false
+    },
+    "agents/knowledge": {
+      "curation": true,
+      "compliance": false
+    },
+    "agents/refactor": {
+      "curation": true,
+      "compliance": false
+    },
+    "agents/research": {
+      "curation": true,
+      "compliance": false
+    },
+    "agents/review": {
+      "curation": true,
+      "compliance": false
+    },
+    "agents/skim": {
+      "curation": true,
+      "compliance": false
+    },
+    "agents/triage": {
+      "curation": true,
+      "compliance": true
+    },
+    "commands/bug-analysis": {
+      "curation": true,
+      "compliance": true
+    },
+    "commands/code-review": {
+      "curation": true,
+      "compliance": true
+    },
+    "commands/debug": {
+      "curation": true,
+      "compliance": false
+    },
+    "commands/dynamic-build": {
+      "curation": true,
+      "compliance": true
+    },
+    "commands/dynamic-plan": {
+      "curation": true,
+      "compliance": false
+    },
+    "commands/dynamic-profile": {
+      "curation": true,
+      "compliance": false
+    },
+    "commands/dynamic-tickets": {
+      "curation": true,
+      "compliance": true
+    },
+    "commands/explore": {
+      "curation": true,
+      "compliance": false
+    },
+    "commands/implement": {
+      "curation": true,
+      "compliance": true
+    },
+    "commands/plan": {
+      "curation": true,
+      "compliance": true
+    },
+    "commands/release": {
+      "curation": true,
+      "compliance": true
+    },
+    "commands/research": {
+      "curation": true,
+      "compliance": false
+    },
+    "commands/resolve": {
+      "curation": true,
+      "compliance": true
+    },
+    "commands/self-review": {
+      "curation": true,
+      "compliance": false
+    }
+  }
+}