devflow-kit 3.9.0 → 3.10.0

package/dist/targets/claude-code/installer.js

@@ -1,18 +1,23 @@
 import { promises as fs } from 'fs';
 import { existsSync } from 'fs';
 import * as path from 'path';
-import { SKILL_NAMESPACE, buildAssetMaps, prefixSkillName, unprefixSkillName, getAllSkillNames, getAllAgentNames, getAllCommandNames, FEATURE_OWNED_SKILLS, resolveSkillInstallPlan, omitCurationGatedSkills } from '../../core/plugins.js';
-import { skillsDir, agentSourceDirs, rulesDir, commandSourceDirs, scriptsDir, compiledSkillRefsDir } from '../../core/assets.js';
+import { SKILL_NAMESPACE, WORKFLOW_FOLDER_NAMES, buildAssetMaps, prefixSkillName, unprefixSkillName, getAllSkillNames, getAllAgentNames, getAllCommandNames, FEATURE_OWNED_SKILLS, resolveSkillInstallPlan, omitCurationGatedSkills, selectedWorkflowFolders, workflowFolderNames } from '../../core/plugins.js';
+import { skillsDir, agentSourceDirs, rulesDir, commandSourceDirs, scriptsDir, compiledSkillRefsDir, skillRefsSourceDir } from '../../core/assets.js';
 import { getPackageRoot, isContainedIn } from '../../core/paths.js';
+import { ALL_SWITCHES_ON, VARIANT_MANIFEST_REL_PATH, describeVariantManifestParseError, parseVariantManifest, requiredComplianceVariantFiles, } from '../../core/curation-variants.js';
 import { sweepOrphanedAssets, mdFileName, mdEntryName } from '../../core/orphan-sweep.js';
-import { generatedReferenceManifest, installedReferenceManifest, PR_HOST_DESTINATION_ROOT, SKILL_REFS_SKILL_NAME, TRACKER_DESTINATION_ROOT } from '../../core/mds-variants.js';
+import { generatedReferenceManifest, installedReferenceManifest, PR_HOST_DESTINATION_ROOT, SKILL_REFS_SKILL_NAME, TRACKER_DESTINATION_ROOT, WORKFLOW_FOLDERS } from '../../core/mds-variants.js';
 import { sweepOrphanedReferences, MAX_REFERENCE_SWEEP_DEPTH } from '../../core/reference-sweep.js';
+import { complianceOffCopyExclusions, removeComplianceOffFiles } from './compliance-off-files.js';
+import { clearLinkForWrite, directoryState, refuseUnrealFolder, removeReportingLink, unlinkLinkAt } from './linked-folder.js';
+import { installWorkflowFolder, readWorkflowFolder } from './workflow-folder-install.js';
 import { TRACKER_AGENT_NAME } from './tracker-install.js';
 import { isTrackerStampedAgent } from './tracker-servers.js';
 import { stampAgentTools } from '../../core/agent-frontmatter.js';
 import { TRACKER_MCP_SERVERS_DEFAULT, trackerServerTools } from '../../core/tracker.js';
 import { BUILTIN_OVERRIDE_AGENTS, findForeignAgentOwner } from './agent-type-owner.js';
 import { restampInstalledCommands } from './language-stamp.js';
+import { CHARTER_RELPATH, HANDOFF_SENTINEL_RELPATH, installRenderedCharter, } from './charter-render.js';
 // ---------------------------------------------------------------------------
 // Shadow validation helpers (exported — reused by Step 4 list commands)
 // ---------------------------------------------------------------------------
@@ -85,13 +90,20 @@ export async function validateRuleShadow(shadowFile) {
  * copy failures (EACCES, ENOSPC, etc.) are still isolated
  * (one bad copy does not abort the whole batch).
  * Invalid shadows still warn-and-install-source.
+ *
+ * A link at the target file is unlinked and replaced by a real file, never written through, and
+ * recorded in `links` when given. A link that cannot be removed is recorded as refused and the
+ * outcome is `skipped`.
  */
-export async function installRuleFile(ruleName, devflowDir, rulesTarget) {
+export async function installRuleFile(ruleName, devflowDir, rulesTarget, links) {
     const shadowFile = path.join(devflowDir, 'rules', mdFileName(ruleName));
     const targetFile = path.join(rulesTarget, mdFileName(ruleName));
     const ruleSource = path.join(rulesDir(), mdFileName(ruleName));
+    // Asked once, so a link that cannot be removed is recorded once.
+    let writable;
+    const mayWrite = async () => (writable ??= await clearLinkForWrite(targetFile, links));
     const shadowState = await validateRuleShadow(shadowFile);
-    if (shadowState === 'valid') {
+    if (shadowState === 'valid' && await mayWrite()) {
         try {
             await fs.copyFile(shadowFile, targetFile);
             return 'shadow';
@@ -121,6 +133,8 @@ export async function installRuleFile(ruleName, devflowDir, rulesTarget) {
     }
     // Copy is isolated: a copy failure degrades to 'skipped' so one
     // bad rule does not abort the entire installAllRules Promise.all batch.
+    if (!(await mayWrite()))
+        return 'skipped';
     try {
         await fs.copyFile(ruleSource, targetFile);
         return invalidShadowOutcome ?? 'source';
@@ -138,9 +152,9 @@ export async function installRuleFile(ruleName, devflowDir, rulesTarget) {
  * `rules --enable` (renders per-rule log lines). One place computes;
  * callers present.
  */
-export async function installAllRules(rulesMap, devflowDir, rulesTarget) {
+export async function installAllRules(rulesMap, devflowDir, rulesTarget, links) {
     return Promise.all([...rulesMap.keys()].map(async (ruleName) => {
-        const outcome = await installRuleFile(ruleName, devflowDir, rulesTarget);
+        const outcome = await installRuleFile(ruleName, devflowDir, rulesTarget, links);
         return { ruleName, outcome };
     }));
 }
@@ -148,18 +162,32 @@ export async function installAllRules(rulesMap, devflowDir, rulesTarget) {
 // Directory utilities
 // ---------------------------------------------------------------------------
 /**
- * Recursively copy a directory tree.
+ * Recursively copy a directory tree. `exclude` holds absolute SOURCE paths that the copy
+ * skips (a file, or a directory with everything below it); omitted, everything is copied.
+ *
+ * `links` is given when `dest` is inside a Devflow install folder. The copy then checks, with
+ * `lstat`, each folder and file it is about to write, and never writes through a link: the link is
+ * unlinked and a real folder or file is written in its place (recorded in `links.replacedLinks`),
+ * and a link that cannot be removed is skipped with everything below it (recorded in
+ * `links.refusedFolders`). Omitted, the copy is the plain one, for a `dest` that is the user's own
+ * content.
  */
-export async function copyDirectory(src, dest) {
+export async function copyDirectory(src, dest, exclude, links) {
+    if (links !== undefined && !(await clearLinkForWrite(dest, links)))
+        return;
     await fs.mkdir(dest, { recursive: true });
     const entries = await fs.readdir(src, { withFileTypes: true });
     for (const entry of entries) {
         const srcPath = path.join(src, entry.name);
         const destPath = path.join(dest, entry.name);
+        if (exclude?.has(srcPath))
+            continue;
         if (entry.isDirectory()) {
-            await copyDirectory(srcPath, destPath);
+            await copyDirectory(srcPath, destPath, exclude, links);
         }
         else {
+            if (links !== undefined && !(await clearLinkForWrite(destPath, links)))
+                continue;
             await fs.copyFile(srcPath, destPath);
         }
     }
@@ -830,7 +858,7 @@ async function requireGeneratedTree(sourceRoot, manifest) {
     throw new Error(`Generated skill references not found: ${sourceRoot}. ` +
         `The whole generated tree is absent, so none of the ${manifest.length} references the ` +
         `devflow:git agent is instructed to load would be installed. ` +
-        `Run \`npm run build:mds\` to regenerate dist/skills/git/references/ before install ` +
+        `Run \`npm run build:mds\` to regenerate ${sourceRoot} before install ` +
         `(\`npm run build:cli\` alone does not produce it).`);
 }
 /**
@@ -1073,6 +1101,46 @@ export async function overlayGeneratedReferences(opts) {
 }
 /** The directory inside an installed skill that the reference overlay converges. */
 const SKILL_REFERENCES_DIRNAME = 'references';
+/**
+ * Prove, with `lstat`, that the overlay can run below `gitSkillDir`.
+ *
+ * The overlay stages, prunes and sets modes below the `references` entry, and the skill copy
+ * before it writes there too. `mkdir` and `readdir` follow a link, so a link at either level
+ * would send those writes into another directory. An absent entry is fine: the install creates it.
+ * Fail closed: an entry that cannot be inspected is refused, and a link is never repaired,
+ * because the installer did not create it.
+ *
+ * One answer for every caller that has no pre-clean to replace such a link: the converge, a
+ * partial install, and a full install whose pre-clean could not remove one. `lstat` runs on
+ * `references` only below a real skill directory, since through a linked one it would follow the
+ * link. Never throws.
+ */
+export async function referencesHostState(gitSkillDir) {
+    const skill = await directoryState(gitSkillDir);
+    if (skill === 'absent')
+        return { kind: 'absent' };
+    if (skill !== 'real')
+        return { kind: 'refused', path: gitSkillDir };
+    const referencesDir = path.join(gitSkillDir, SKILL_REFERENCES_DIRNAME);
+    const references = await directoryState(referencesDir);
+    return references === 'absent' || references === 'real'
+        ? { kind: 'ready' }
+        : { kind: 'refused', path: referencesDir };
+}
+/**
+ * The report of an overlay refused as a whole: one failure per unit, as a refused converged
+ * root reports (D-CONVERGED-ROOT-REAL), each carrying the state the unit was left in.
+ * The classification reads; nothing is written.
+ */
+async function refusedOverlayFailures(refusedPath, referencesTarget, manifest) {
+    const error = `${refusedPath} is not a real directory — nothing is copied, staged, pruned or set through it. ` +
+        `Replace it with a real directory and re-run.`;
+    const failures = [];
+    for (const unit of planOverlayUnits(manifest)) {
+        failures.push({ unit: unitRef(unit), state: await classifyUntouchedUnit(unit, referencesTarget), error });
+    }
+    return failures;
+}
 /**
  * What inside an installed skill directory the reference overlay owns, and the
  * pre-clean must therefore leave standing (D-OVERLAY-OWNERSHIP).
@@ -1140,10 +1208,29 @@ export function overlayOwnedSkillPaths(manifest) {
  * An unreadable directory is left alone rather than reported: the caller already
  * swallows the errors of the `fs.rm` this stands in for, and a pre-clean that cannot
  * read its target has nothing to remove from it.
+ *
+ * The walk never goes through a link. `readdir` follows one, so a link at `dir` itself is
+ * unlinked and nothing is read from it, and below `dir` only a `Dirent` that is a real
+ * directory is entered. The folder a link points to is left as it is. A link that stands where
+ * the pre-clean expects its own folder or file (`dir`, or a path in `keep` or above one) is
+ * returned, so the caller reports it; any other link is removed like the file it stands for.
+ * A link at `dir` that cannot be removed is left in place and nothing is emptied.
+ *
+ * A link at a kept path or above one is returned as `awaitingWrite`, not as replaced: the
+ * converger that owns the path has not written there yet, and a summary that says a real file or
+ * folder stands where the link stood is true only after it has ({@link reportLinksOnceWritten}).
+ * `leaveKeptLinks` is for a kept path whose converger replaces a link itself and reports it, never
+ * writing through it (the tracker agent file): the link then stays for that converger.
+ *
+ * @returns The links at `dir` that this replaced, and the links it removed that a later write replaces.
  */
-async function emptyDirectoryExcept(dir, keep) {
+async function emptyDirectoryExcept(dir, keep, options = {}) {
+    const rootLink = await unlinkLinkAt(dir);
+    if (rootLink !== 'no-link')
+        return { replacedLinks: rootLink === 'unlinked' ? [dir] : [], awaitingWrite: [] };
     const kept = [...keep];
     const maxDepth = Math.max(0, ...kept.map(relPath => relPath.split('/').length));
+    const awaitingWrite = [];
     const walk = async (current, rel, depth) => {
         let entries;
         try {
@@ -1154,19 +1241,34 @@ async function emptyDirectoryExcept(dir, keep) {
         }
         for (const entry of entries) {
             const entryRel = rel === '' ? entry.name : `${rel}/${entry.name}`;
-            if (keep.has(entryRel) && !entry.isSymbolicLink())
+            if (keep.has(entryRel) && (!entry.isSymbolicLink() || options.leaveKeptLinks === true))
                 continue;
-            const holdsSomethingKept = entry.isDirectory()
-                && depth < maxDepth
-                && kept.some(relPath => relPath.startsWith(`${entryRel}/`));
-            if (holdsSomethingKept) {
-                await walk(path.join(current, entry.name), entryRel, depth + 1);
+            const entryPath = path.join(current, entry.name);
+            const holdsSomethingKept = kept.some(relPath => relPath.startsWith(`${entryRel}/`));
+            if (entry.isDirectory() && depth < maxDepth && holdsSomethingKept) {
+                await walk(entryPath, entryRel, depth + 1);
                 continue;
             }
-            await fs.rm(path.join(current, entry.name), { recursive: true, force: true });
+            await fs.rm(entryPath, { recursive: true, force: true });
+            if (entry.isSymbolicLink() && (holdsSomethingKept || keep.has(entryRel)))
+                awaitingWrite.push(entryPath);
         }
     };
     await walk(dir, '', 1);
+    return { replacedLinks: [], awaitingWrite };
+}
+/**
+ * Add each link in `removed` to `report.replacedLinks` once a real file or folder stands at its
+ * path. A path that is still absent, or a link again, is not a replacement and is not reported: the
+ * step that should have written there failed or was refused, and it reports that failure itself.
+ * Bounded by `removed`, which holds at most the kept paths of one pre-clean.
+ */
+async function reportLinksOnceWritten(report, removed) {
+    for (const linkPath of removed) {
+        const stat = await fs.lstat(linkPath).catch(() => undefined);
+        if (stat !== undefined && !stat.isSymbolicLink())
+            report.replacedLinks.push(linkPath);
+    }
 }
 // ---------------------------------------------------------------------------
 // Script composer
@@ -1190,6 +1292,9 @@ function collectRelativeImports(source) {
  *       under ~/.devflow/scripts/ at the same relative-to-dist/ paths
  *   (c) ~/.devflow/scripts/package.json → {"type":"module"}
  *
+ * The copy leaves out the orchestrator charter and the implement sentinel. Install the
+ * directory with {@link installScripts}, which writes both after the copy.
+ *
  * Frozen externally-referenced paths:
  *   ~/.devflow/scripts/hooks/run-hook   (hook bootstrap entry)
  *   ~/.devflow/scripts/hud.sh           (HUD entry script)
@@ -1204,9 +1309,19 @@ export async function composeScripts(scriptsTarget) {
     // mirrored dist/hud/ closure), so a re-run gave package.json an exec bit the first
     // run never did and re-init stopped being a no-op on disk (#388 AC-3). Scoping the
     // chmod to the copied entries makes the first and every later run agree.
+    //
+    // D-CHARTER-INSTALL-RENDER: the orchestrator charter and the implement sentinel are
+    // NOT part of this verbatim copy. The charter is installed as a render of the packaged
+    // source for the installed plugin set, and the sentinel exists only while implement is
+    // installed; `installRenderedCharter` is the only writer of both, so no copy here can put
+    // the full source charter or a stale sentinel back over a render.
     const srcScripts = scriptsDir();
+    const rendered = new Set([
+        path.join(srcScripts, CHARTER_RELPATH),
+        path.join(srcScripts, HANDOFF_SENTINEL_RELPATH),
+    ]);
     try {
-        await copyDirectory(srcScripts, scriptsTarget);
+        await copyDirectory(srcScripts, scriptsTarget, rendered);
         if (process.platform !== 'win32') {
             for (const entry of await fs.readdir(srcScripts, { withFileTypes: true })) {
                 const copied = path.join(scriptsTarget, entry.name);
@@ -1268,6 +1383,23 @@ export async function composeScripts(scriptsTarget) {
     }
     catch { /* already exists from prior install — leave as-is */ }
 }
+/**
+ * Install the scripts directory whole: the verbatim copy of {@link composeScripts}, then the orchestrator
+ * charter and the implement sentinel it skips.
+ *
+ * D-CHARTER-INSTALL-RENDER: a tree from `composeScripts` alone has no charter, so every caller outside this
+ * module goes through here and none pairs the two steps by hand. The render is its own step, outside the
+ * copy's catch-all, so its failure handling is the writer's own: a warning, never an abort.
+ */
+export async function installScripts(opts) {
+    await composeScripts(opts.scriptsTarget);
+    await installRenderedCharter({
+        scriptsDir: opts.scriptsTarget,
+        plugins: opts.plugins,
+        warn: opts.warn,
+        mode: 'install',
+    });
+}
 /**
  * Install one agent that carries the tracker-server stamp: the shipped source with
  * `servers` appended to its `tools:` line, written in one step so no copy of it ever sits on
@@ -1344,7 +1476,7 @@ async function firstExisting(candidates) {
  * installed in its place).
  *
  * The ONE spelling of that decision: the install loop and
- * convergeCurationVariants both call it, so a skill the curation toggle installs
+ * convergeVariantAxes both call it, so a skill the curation toggle installs
  * later is shadowed exactly as one the install installed.
  *
  * The shipped source is stat-checked FIRST, even under a valid shadow, so an
@@ -1383,8 +1515,8 @@ export async function resolveSkillSource(skillName, devflowDir, packageRoot) {
  * validateSkillShadow at install time. This only answers "did the user write
  * one?", which is what dormancy reporting turns on.
  */
-async function listShadowedSkills(devflowDir) {
-    const registry = new Set(getAllSkillNames());
+async function listShadowedSkills(devflowDir, folderWorkflows) {
+    const registry = new Set(getAllSkillNames(folderWorkflows));
     let entries;
     try {
         entries = await fs.readdir(path.join(devflowDir, 'skills'));
@@ -1432,16 +1564,118 @@ async function removeDeselectedSkills(skillsDir, names) {
     }
     return { removed, failed };
 }
+/** The most variant files a refusal names; the count says how many more there are. */
+const MAX_REPORTED_MISSING_VARIANTS = 5;
+/** The names a refusal lists: at most {@link MAX_REPORTED_MISSING_VARIANTS}, then a count of the rest. */
+function namedVariantFiles(items) {
+    const named = items.slice(0, MAX_REPORTED_MISSING_VARIANTS).join(', ');
+    const more = items.length > MAX_REPORTED_MISSING_VARIANTS ? ` and ${items.length - MAX_REPORTED_MISSING_VARIANTS} more` : '';
+    return `${named}${more}`;
+}
+/**
+ * The source lists the copy reads, most-preferred first. The check in
+ * {@link requireComplianceVariantFiles} and the copy in {@link installCommandsAndAgents}
+ * both take their lists from here, so the check looks at the files the copy takes.
+ * An injected agent list wins as given.
+ */
+function copySourceDirs(opts) {
+    const { curation, compliance, packageRoot } = opts;
+    return {
+        commands: commandSourceDirs({ curation, compliance }, packageRoot),
+        agents: opts.agentSourceDirs ?? agentSourceDirs(packageRoot, { curation, compliance }),
+    };
+}
+/**
+ * Refuse a compliance-off install that cannot be trusted to carry the right text, before
+ * any file is written. Compliance on reads nothing and returns.
+ *
+ * With compliance off, the installer must know which compiled prompts carry a compliance
+ * arm: the build records that in dist/variant-axes.json, and the installer reads it here
+ * rather than guess from the files it finds. A prompt with a compliance arm has no safe
+ * fall-through, because its normal file, and on a both-off machine its curation-off file,
+ * carry the compliance text the machine has switched off. So the install is refused when
+ *   - the manifest is absent, unreadable or not valid (the build has not run, or only
+ *     `build:cli` did); or
+ *   - a compliance-armed prompt has no file for the machine's EXACT switches
+ *     (requiredComplianceVariantFiles names the file: a both-off machine needs the file
+ *     built for both axes, never the curation-off one); or
+ *   - the copy would take another file for that prompt: the first existing file of its
+ *     kind and name over the copy's own source list (copySourceDirs) is not the required
+ *     file. A prompt whose list holds no file at all is left to the copy's own refusal.
+ * A prompt with no compliance arm is not checked: it falls through to its normal file.
+ *
+ * The same refusal shape as {@link requireGeneratedTree}: one throw, before the unit loop,
+ * naming the build step. Only the file reads, so it leaves no partial install behind.
+ */
+async function requireComplianceVariantFiles(opts) {
+    const { curation, compliance, packageRoot } = opts;
+    if (compliance)
+        return;
+    const manifestFile = path.join(packageRoot, ...VARIANT_MANIFEST_REL_PATH.split('/'));
+    const remedy = `Run \`npm run build:mds\` to regenerate ${VARIANT_MANIFEST_REL_PATH} and the variant trees before install ` +
+        `(\`npm run build:cli\` alone does not produce them).`;
+    let text;
+    try {
+        text = await fs.readFile(manifestFile, 'utf-8');
+    }
+    catch (err) {
+        const reason = err.code === 'ENOENT' ? 'does not exist' : `cannot be read (${String(err)})`;
+        throw new Error(`Variant manifest ${reason}: ${manifestFile}. ` +
+            `With compliance off the installer needs it to find the prompts that carry a compliance arm, so no file was written. ${remedy}`);
+    }
+    const parsed = parseVariantManifest(text);
+    if (!parsed.ok) {
+        throw new Error(`Variant manifest is not valid: ${manifestFile} (${describeVariantManifestParseError(parsed.error)}). ` +
+            `No file was written. ${remedy}`);
+    }
+    const sourceDirs = copySourceDirs({ curation, compliance, packageRoot, agentSourceDirs: opts.agentSourceDirs });
+    const machine = `curation ${curation ? 'on' : 'off'} and compliance off`;
+    const missing = [];
+    const shadowed = [];
+    for (const host of parsed.value) {
+        const [rel] = requiredComplianceVariantFiles({ curation, compliance }, [host]);
+        if (rel === undefined)
+            continue;
+        const required = path.join(packageRoot, ...rel.split('/'));
+        let present = false;
+        try {
+            present = (await fs.stat(required)).isFile();
+        }
+        catch { /* absent — reported below */ }
+        if (!present) {
+            missing.push(rel);
+            continue;
+        }
+        const dirs = host.kind === 'commands' ? sourceDirs.commands : sourceDirs.agents;
+        const taken = await firstExisting(dirs.map(dir => path.join(dir, mdFileName(host.name))));
+        if (taken !== undefined && path.resolve(taken) !== path.resolve(required)) {
+            shadowed.push(`${rel} (the copy would take ${path.relative(packageRoot, taken).split(path.sep).join('/')})`);
+        }
+    }
+    if (missing.length > 0) {
+        throw new Error(`Variant file not found for ${missing.length} prompt(s) that carry a compliance arm, on a machine with ` +
+            `${machine}: ${namedVariantFiles(missing)}. ` +
+            `Another variant of the same prompt would carry the wrong text, so no file was written. ${remedy}`);
+    }
+    if (shadowed.length > 0) {
+        throw new Error(`Another file comes first for ${shadowed.length} prompt(s) that carry a compliance arm, on a machine with ` +
+            `${machine}: ${namedVariantFiles(shadowed)}. ` +
+            `The install would carry the wrong text, so no file was written. ${remedy}`);
+    }
+}
 /**
  * Write the commands and the agents of `plugins` into `claudeDir`, and nothing else:
  * no sweep, no stamp, no skills. The one copy path shared by `installViaFileCopy` and
  * the selective uninstall, which rewrites the files of the plugins that stay installed
  * after it removed a retired agent.
  *
- * Commands come from dist/commands/{name}.md, or — with curation off — the curation-off
- * variant dist/curation-off/commands/{name}.md when the host has one
+ * Commands come from dist/commands/{name}.md, or — with an axis off — the off variant of
+ * the host when it has one, such as dist/curation-off/commands/{name}.md
  * (D-LEARNING-VARIANT-INSTALL; commandSourceDirs owns the order). A declared command
- * with no compiled source file is a hard error, not a skip.
+ * with no compiled source file is a hard error, not a skip. With compliance off the copy
+ * first checks that every compliance-armed prompt has its file for the machine's exact
+ * switches and that the copy takes that file, and refuses before it writes anything
+ * otherwise ({@link requireComplianceVariantFiles}).
  *
  * Agents resolve dist-first with a src fallback: dist/agents/{name}.md (compiled from an
  * .mds generator host) wins over src/assets/agents/{name}.md. A declared agent absent from
@@ -1458,32 +1692,45 @@ async function removeDeselectedSkills(skillsDir, names) {
  * known and leaves it alone.
  */
 export async function installCommandsAndAgents(opts) {
-    const { plugins, agentsMap, claudeDir, curation, trackerServers, warn } = opts;
+    const { plugins, agentsMap, claudeDir, curation, compliance, trackerServers, warn } = opts;
+    const skip = opts.skip ?? {};
+    const packageRoot = opts.packageRoot ?? getPackageRoot();
+    // Before the first write. installViaFileCopy checks earlier still, ahead of its pre-clean;
+    // this call covers the caller that reaches the copy alone (the selective uninstall).
+    await requireComplianceVariantFiles({ curation, compliance, packageRoot, agentSourceDirs: opts.agentSourceDirs });
+    const { commands: commandDirs, agents: agentDirs } = copySourceDirs({
+        curation,
+        compliance,
+        packageRoot,
+        agentSourceDirs: opts.agentSourceDirs,
+    });
     const commandsTarget = path.join(claudeDir, 'commands', 'devflow');
-    const commandDirs = commandSourceDirs(curation);
+    const folderWorkflows = opts.folderWorkflows ?? WORKFLOW_FOLDER_NAMES;
     const commandsSourceNames = new Set();
     for (const plugin of plugins) {
         for (const cmd of plugin.commands) {
             const name = cmd.startsWith('/') ? cmd.slice(1) : cmd;
-            commandsSourceNames.add(name);
+            // D-WORKFLOW-FOLDER-INSTALL: a workflow that ships as a skill folder has no command file.
+            if (!folderWorkflows.has(name))
+                commandsSourceNames.add(name);
         }
     }
-    if (commandsSourceNames.size > 0) {
+    if (commandsSourceNames.size > 0 && skip.commands !== true) {
         await fs.mkdir(commandsTarget, { recursive: true });
         for (const name of commandsSourceNames) {
             const srcFile = await firstExisting(commandDirs.map(dir => path.join(dir, mdFileName(name))));
             if (srcFile === undefined) {
                 // The error names the curation-ON path: that file exists for every declared
                 // command, while a curation-off file exists only for a host with an arm.
-                throw new Error(`Command source not found for declared command "${name}": ${path.join(commandSourceDirs(true)[0], mdFileName(name))}. ` +
+                throw new Error(`Command source not found for declared command "${name}": ${path.join(commandSourceDirs(ALL_SWITCHES_ON, packageRoot)[0], mdFileName(name))}. ` +
                     `Ensure build:mds ran successfully before install.`);
             }
-            await fs.copyFile(srcFile, path.join(commandsTarget, mdFileName(name)));
+            const commandTarget = path.join(commandsTarget, mdFileName(name));
+            if (await clearLinkForWrite(commandTarget, opts.links))
+                await fs.copyFile(srcFile, commandTarget);
         }
     }
     const agentsTarget = path.join(claudeDir, 'agents', 'devflow');
-    // Curation-aware (D-LEARNING-VARIANT-INSTALL). An injected list wins as given.
-    const agentDirs = opts.agentSourceDirs ?? agentSourceDirs(undefined, curation);
     const allAgentNames = new Set();
     for (const plugin of plugins) {
         for (const agent of plugin.agents) {
@@ -1494,7 +1741,7 @@ export async function installCommandsAndAgents(opts) {
             }
         }
     }
-    if (allAgentNames.size > 0) {
+    if (allAgentNames.size > 0 && skip.agents !== true) {
         await fs.mkdir(agentsTarget, { recursive: true });
         for (const agentName of allAgentNames) {
             if (await skipsForUserOwnedType(agentName, claudeDir, agentsTarget, warn))
@@ -1502,11 +1749,13 @@ export async function installCommandsAndAgents(opts) {
             const candidates = agentDirs.map(dir => path.join(dir, mdFileName(agentName)));
             const srcFile = await firstExisting(candidates);
             if (srcFile === undefined) {
-                throw new Error(`Agent source not found for declared agent "${agentName}": ${path.join(opts.agentSourceDirs?.[0] ?? agentSourceDirs()[0], mdFileName(agentName))}. ` +
+                throw new Error(`Agent source not found for declared agent "${agentName}": ${path.join(opts.agentSourceDirs?.[0] ?? agentSourceDirs(packageRoot)[0], mdFileName(agentName))}. ` +
                     `Run \`npm run build:mds\` if it is compiled from an .mds generator host, otherwise ` +
                     `ensure the agent file exists in src/assets/agents/ (searched: ${candidates.join(', ')}).`);
             }
             const agentTarget = path.join(agentsTarget, mdFileName(agentName));
+            if (!(await clearLinkForWrite(agentTarget, opts.links)))
+                continue;
             if (isTrackerStampedAgent(agentName)) {
                 await writeStampedAgent(srcFile, agentTarget, trackerServers, warn);
             }
@@ -1524,7 +1773,48 @@ export async function installCommandsAndAgents(opts) {
  * Returns an InstallReport describing which shadows were applied and which were skipped.
  */
 export async function installViaFileCopy(options) {
-    const { plugins, claudeDir, devflowDir, skillsMap, agentsMap, rulesMap = new Map(), isPartialInstall, spinner, curation, trackerServers = TRACKER_MCP_SERVERS_DEFAULT, warn = () => { }, } = options;
+    const { plugins, claudeDir, devflowDir, skillsMap, agentsMap, rulesMap = new Map(), isPartialInstall, spinner, curation, compliance, trackerServers = TRACKER_MCP_SERVERS_DEFAULT, warn = () => { }, } = options;
+    const packageRoot = options.packageRoot ?? getPackageRoot();
+    // D-WORKFLOW-FOLDER-INSTALL: the workflows that ship as skill folders. The default registry is
+    // empty, and with it every folder step below is a no-op over an empty set.
+    const folderRegistry = options.workflowFolders ?? WORKFLOW_FOLDERS;
+    const folderWorkflows = workflowFolderNames(folderRegistry);
+    const folderSwitches = { curation, compliance };
+    const folderFiles = new Map();
+    /** The files of one registered folder, read once. A failed read is a reason and never a throw. */
+    const readFolder = async (folder) => {
+        const cached = folderFiles.get(folder.name);
+        if (cached !== undefined)
+            return { ok: true, files: cached };
+        const read = await readWorkflowFolder(folder, folderSwitches, options.workflowFoldersRoot ?? packageRoot);
+        if (read.ok)
+            folderFiles.set(folder.name, read.files);
+        return read;
+    };
+    const readFolders = async (names) => {
+        for (const folder of folderRegistry) {
+            if (!names.has(folder.name))
+                continue;
+            const read = await readFolder(folder);
+            if (!read.ok)
+                throw new Error(read.reason);
+        }
+    };
+    // The compliance-off refusal comes first, ahead of the pre-clean below: a refused install
+    // must leave the installed tree as it found it.
+    await requireComplianceVariantFiles({ curation, compliance, packageRoot, agentSourceDirs: options.agentSourceDirs });
+    // The folders this run installs are read from the exact-key tree before the pre-clean for the
+    // same reason, so a build that lacks one refuses the install and leaves the installed tree alone.
+    await readFolders(selectedWorkflowFolders(plugins, folderWorkflows));
+    // The references the machine's compliance switch installs: the manifest, and the ONE source
+    // root they are overlaid from. With compliance off the root is the compliance-off tree, and its
+    // absence refuses the install here, before the pre-clean, so a refused install leaves the
+    // installed tree as it found it and never falls through to the compliance-on references (AC-50).
+    const refsManifest = installedReferenceManifest({ compliance });
+    const refsSourceRoot = skillRefsSourceDir(compliance, packageRoot);
+    if (omitCurationGatedSkills(skillsMap, curation).has(SKILL_REFS_SKILL_NAME)) {
+        await requireGeneratedTree(refsSourceRoot, refsManifest);
+    }
     const report = {
         shadowedSkills: [],
         shadowedRules: [],
@@ -1534,6 +1824,8 @@ export async function installViaFileCopy(options) {
         overlaidRefs: [],
         unchangedRefs: [],
         overlayFailures: [],
+        replacedLinks: [],
+        refusedFolders: [],
         removedSkills: [],
         dormantShadows: [],
     };
@@ -1551,9 +1843,18 @@ export async function installViaFileCopy(options) {
     const skillPlan = resolveSkillInstallPlan({
         effectivePlugins: options.effectivePlugins ?? plugins,
         isPartialInstall,
-        shadowedSkills: await listShadowedSkills(devflowDir),
+        shadowedSkills: await listShadowedSkills(devflowDir, folderWorkflows),
+        folderWorkflows,
     });
     report.dormantShadows = [...skillPlan.dormantShadows];
+    // D-WORKFLOW-SHADOW-REFUSAL, install half: a folder installs from the build and has no source to
+    // overlay, so a shadow of its name is ignored and kept. The warning says so; it is not dormant.
+    for (const name of skillPlan.ignoredFolderShadows) {
+        warn(`The shadow of skill "${name}" is ignored: it ships as a skill folder from the build, which a shadow cannot replace. The shadow was kept.`);
+    }
+    // Links the pre-clean removed at a path that a later step of this install writes. Each is reported
+    // as replaced only once a real file or folder stands there (reportLinksOnceWritten).
+    const awaitingWrite = [];
     // Clean old Devflow files before installing
     spinner.message('Cleaning old files...');
     if (!isPartialInstall) {
@@ -1566,7 +1867,7 @@ export async function installViaFileCopy(options) {
         ];
         for (const dir of oldDirs) {
             try {
-                await fs.rm(dir, { recursive: true, force: true });
+                report.replacedLinks.push(...await removeReportingLink(dir));
             }
             catch { /* ignore */ }
         }
@@ -1579,11 +1880,28 @@ export async function installViaFileCopy(options) {
         // exactly as the unconditional wipe removed it, and the file is still
         // converged on this run — drift in it is restored, so preserving it strands
         // nothing.
+        //
+        // A link at that file is left standing: the converge replaces it with a real file and reports it
+        // once it has written, so the install does not claim a replacement the converge may not make.
         try {
-            await emptyDirectoryExcept(path.join(claudeDir, 'agents', 'devflow'), new Set([mdFileName(TRACKER_AGENT_NAME)]));
+            const emptied = await emptyDirectoryExcept(path.join(claudeDir, 'agents', 'devflow'), new Set([mdFileName(TRACKER_AGENT_NAME)]), { leaveKeptLinks: true });
+            report.replacedLinks.push(...emptied.replacedLinks);
+            awaitingWrite.push(...emptied.awaitingWrite);
         }
         catch { /* ignore */ }
     }
+    // The commands, agents and rules folders, each proved a real folder (or absent) before any write
+    // below. A full install's pre-clean replaced a link at each of them. A partial install has no
+    // pre-clean, and a link the pre-clean could not remove is still standing, so every write below
+    // would go through it into another directory: the sweeps, the copies and the restamp. A refused
+    // folder is skipped by all of them and reported in `refusedFolders`. The rules folder is written
+    // only when the selection has a rule, so only then is it proved.
+    const commandsTarget = path.join(claudeDir, 'commands', 'devflow');
+    const agentsTarget = path.join(claudeDir, 'agents', 'devflow');
+    const rulesTarget = path.join(claudeDir, 'rules', 'devflow');
+    const commandsRefused = await refuseUnrealFolder(report, commandsTarget);
+    const agentsRefused = await refuseUnrealFolder(report, agentsTarget);
+    const rulesRefused = rulesMap.size > 0 && await refuseUnrealFolder(report, rulesTarget);
     // Sweep stale devflow:* skill dirs — ungated: runs on every install shape,
     // including partial installs, so renamed/deleted skills are pruned promptly.
     // knownNames spans ALL plugins (getAllSkillNames) so skills from uninstalled
@@ -1596,7 +1914,7 @@ export async function installViaFileCopy(options) {
     // are never swept here. Their lifecycle is managed by convergeComplianceArtifacts, which
     // runs after installViaFileCopy in init.ts. Before I09 the compliance skill was swept and
     // then re-materialized by converge, creating a false-orphan report on every install.
-    recordSweep(report, 'skill', await sweepOrphanedAssets(path.join(claudeDir, 'skills'), new Set([...getAllSkillNames(), ...FEATURE_OWNED_SKILLS]), (entry) => entry.startsWith(SKILL_NAMESPACE) ? unprefixSkillName(entry) : null));
+    recordSweep(report, 'skill', await sweepOrphanedAssets(path.join(claudeDir, 'skills'), new Set([...getAllSkillNames(folderWorkflows), ...FEATURE_OWNED_SKILLS]), (entry) => entry.startsWith(SKILL_NAMESPACE) ? unprefixSkillName(entry) : null));
     // Pre-clean the prefixed install targets before re-copying so stale content
     // never bleeds into a fresh install. Bare pre-namespace dirs at
     // ~/.claude/skills/{name} are owned solely by the frozen LEGACY_SKILL_NAMES
@@ -1632,22 +1950,35 @@ export async function installViaFileCopy(options) {
     // Everything else in the directory is still emptied, so a stale hand-authored skill
     // file — including a reference at the references ROOT, which the overlay may replace
     // but never delete (D-OVERLAY-FLAT-UNIT) — does not survive a full install.
+    //
+    // A target that is a link is unlinked and reported in `replacedLinks`, never emptied
+    // through: the folder it points to is not Devflow's, and the install below writes a real
+    // folder in its place.
     if (!isPartialInstall) {
-        const overlayOwned = overlayOwnedSkillPaths(installedReferenceManifest());
+        const overlayOwned = overlayOwnedSkillPaths(refsManifest);
         for (const skill of skillsMap.keys()) {
             // Empty the prefixed directory (its contents are re-created during the install
             // phase), minus whatever another converger owns inside it.
             const target = path.join(claudeDir, 'skills', prefixSkillName(skill));
             try {
                 if (skill === SKILL_REFS_SKILL_NAME) {
-                    await emptyDirectoryExcept(target, overlayOwned);
+                    const emptied = await emptyDirectoryExcept(target, overlayOwned);
+                    report.replacedLinks.push(...emptied.replacedLinks);
+                    awaitingWrite.push(...emptied.awaitingWrite);
                 }
                 else {
-                    await fs.rm(target, { recursive: true, force: true });
+                    report.replacedLinks.push(...await removeReportingLink(target));
                 }
             }
             catch { /* ignore */ }
         }
+        // A folder is replaced whole by its install, so the pre-clean only unlinks a link at it, as it does
+        // for a skill. A link it cannot remove is refused by the install below.
+        for (const name of selectedWorkflowFolders(plugins, folderWorkflows)) {
+            const target = path.join(claudeDir, 'skills', prefixSkillName(name));
+            if ((await unlinkLinkAt(target)) === 'unlinked')
+                report.replacedLinks.push(target);
+        }
     }
     // Remove the skills no selected plugin owns or requires — the deselection half
     // of the scoped install. Empty on a partial install by construction
@@ -1655,7 +1986,7 @@ export async function installViaFileCopy(options) {
     // (AC-22). Failures are per-item and non-fatal. `removedSkills` lists only what
     // was on disk and is now gone: the plan is registry arithmetic and mostly names
     // skills that were never installed.
-    const deselected = await removeDeselectedSkills(path.join(claudeDir, 'skills'), skillPlan.remove);
+    const deselected = await removeDeselectedSkills(path.join(claudeDir, 'skills'), [...skillPlan.remove, ...skillPlan.removeFolders]);
     report.removedSkills.push(...deselected.removed);
     for (const failure of deselected.failed) {
         warn(`Could not remove deselected skill "${prefixSkillName(failure.name)}" — ${String(failure.error)}`);
@@ -1668,8 +1999,9 @@ export async function installViaFileCopy(options) {
     // Ungated: runs on every install shape. knownNames spans ALL plugins
     // (getAllAgentNames) so agents from uninstalled plugins survive a partial run. Only
     // names absent from the full registry are removed.
-    const agentsTarget = path.join(claudeDir, 'agents', 'devflow');
-    const agentSweep = await sweepOrphanedAssets(agentsTarget, new Set(getAllAgentNames()), mdEntryName);
+    const agentSweep = agentsRefused
+        ? { scanned: 0, removed: [], failed: [] }
+        : await sweepOrphanedAssets(agentsTarget, new Set(getAllAgentNames()), mdEntryName);
     recordSweep(report, 'agent', agentSweep);
     // A partial install writes the selected plugins' commands and agents and leaves every
     // other plugin's files alone, which is only safe while those files still name agents
@@ -1688,26 +2020,37 @@ export async function installViaFileCopy(options) {
         agentsMap: commandAgentMap,
         claudeDir,
         curation,
+        compliance,
+        packageRoot,
         trackerServers,
         agentSourceDirs: options.agentSourceDirs,
+        skip: { commands: commandsRefused, agents: agentsRefused },
+        links: report,
+        folderWorkflows,
         warn,
     });
     // Sweep stale command files — ungated: runs on every install shape.
     // knownNames spans ALL plugins (getAllCommandNames) so commands from uninstalled
     // plugins survive a partial run. Only names absent from the full registry are removed.
-    recordSweep(report, 'command', await sweepOrphanedAssets(path.join(claudeDir, 'commands', 'devflow'), new Set(getAllCommandNames()), mdEntryName));
+    // A workflow that ships as a skill folder is not in the set, so its stale command file is swept.
+    if (!commandsRefused) {
+        recordSweep(report, 'command', await sweepOrphanedAssets(commandsTarget, new Set(getAllCommandNames(folderWorkflows)), mdEntryName));
+    }
     // D-LANGUAGE-FOCUS-STAMP: record the language focuses the EFFECTIVE selection installs on the
     // installed /code-review, on every install shape. This is the language gate the command reads
     // (no run-time probe of Claude Code's directory), so it runs after the copy and the sweep and
     // whether or not code-review's own plugin is in this run: `--plugin=devflow-typescript` copies no
     // command, yet must update a code-review an earlier run installed. The copy above wrote the shipped
     // `(none)` line; the rewrite compares against what is on disk now, so neither that copy nor the
-    // pre-clean can defeat it. A failure is a warning, never an abort.
-    await restampInstalledCommands({
-        claudeDir,
-        effectivePlugins: options.effectivePlugins ?? plugins,
-        warn,
-    });
+    // pre-clean can defeat it. A failure is a warning, never an abort. A refused commands folder is not
+    // restamped: the rewrite would go through the link.
+    if (!commandsRefused) {
+        await restampInstalledCommands({
+            claudeDir,
+            effectivePlugins: options.effectivePlugins ?? plugins,
+            warn,
+        });
+    }
     // Install skills from ALL plugins (skillsMap covers all plugins, not just selected).
     // Resolved from flat src/assets/skills/{name}/ (no per-plugin subdirectory).
     // A declared skill whose source directory is absent is a build/packaging failure
@@ -1716,12 +2059,32 @@ export async function installViaFileCopy(options) {
     // D-LEARNING-VARIANT-INSTALL: a curation-off machine skips the curation-gated
     // skills here. The pre-clean above walked the UNFILTERED map, so on a full
     // install a leftover copy is already gone; a partial install leaves removal to
-    // convergeCurationVariants, which init runs straight after this call.
+    // convergeVariantAxes, which init runs straight after this call.
     spinner.message('Installing skills...');
     for (const [skillName] of omitCurationGatedSkills(skillsMap, curation)) {
-        const resolved = await resolveSkillSource(skillName, devflowDir);
         const skillTarget = path.join(claudeDir, 'skills', prefixSkillName(skillName));
-        await copyDirectory(resolved.dir, skillTarget);
+        // A full install's pre-clean replaced a link at the skill or its references entry. A partial
+        // install has no pre-clean, and a link the pre-clean could not remove is still standing, so the
+        // copy and the overlay below would write through such a link into another directory: the whole
+        // skill is refused instead and listed in `refusedFolders`. The references skill is also reported
+        // like a refused overlay, one failure for each unit.
+        if (skillName === SKILL_REFS_SKILL_NAME) {
+            const host = await referencesHostState(skillTarget);
+            if (host.kind === 'refused') {
+                report.refusedFolders.push(host.path);
+                report.overlayFailures.push(...await refusedOverlayFailures(host.path, path.join(skillTarget, SKILL_REFERENCES_DIRNAME), refsManifest));
+                continue;
+            }
+        }
+        else if (await refuseUnrealFolder(report, skillTarget)) {
+            continue;
+        }
+        // With compliance off the copy leaves out the posting files of COMPLIANCE_OFF_REMOVED_SKILL_FILES.
+        // They are named below the source the copy reads, shadow or shipped, so the posting text is never
+        // on the machine, even when the install stops or a removal is refused later. With compliance on
+        // nothing is excluded.
+        const resolved = await resolveSkillSource(skillName, devflowDir);
+        await copyDirectory(resolved.dir, skillTarget, compliance ? undefined : complianceOffCopyExclusions(skillName, resolved.dir), report);
         if (resolved.shadow === 'valid') {
             report.shadowedSkills.push(skillName);
         }
@@ -1737,7 +2100,9 @@ export async function installViaFileCopy(options) {
                 referencesTarget: path.join(skillTarget, 'references'),
                 // Every provider's mechanics (D-INSTALL-ALL-PROVIDERS). The overlay
                 // converges rather than merges, so a retired generated document is pruned.
-                manifest: installedReferenceManifest(),
+                // The manifest and the source root follow the machine compliance switch together.
+                sourceRoot: refsSourceRoot,
+                manifest: refsManifest,
                 warn,
             });
             report.overlaidRefs.push(...overlay.overlaidRefs);
@@ -1746,13 +2111,47 @@ export async function installViaFileCopy(options) {
             recordSweep(report, 'reference', overlay.pruned);
         }
     }
+    // The skill copy and the overlay have written. A link the pre-clean removed at a path they write is
+    // reported now if a real file or folder stands there, and not at all if a unit failed or was refused.
+    await reportLinksOnceWritten(report, awaitingWrite);
+    // With compliance off, the flat skill files that only the posting steps load are removed by
+    // exact name (COMPLIANCE_OFF_REMOVED_SKILL_FILES), on every install shape. The copy above wrote
+    // none of them; this step removes the ones an earlier compliance-on install left, which a partial
+    // install copies over without clearing. A removal that was refused is a reported failure and
+    // never an abort; the compliance converge that init runs next fails closed on the same files.
+    if (!compliance) {
+        const removal = await removeComplianceOffFiles(path.join(claudeDir, 'skills'));
+        for (const refusal of removal.refused) {
+            report.sweepFailures.push({ kind: 'reference', name: refusal.entry, error: refusal.reason });
+        }
+    }
+    // D-WORKFLOW-FOLDER-INSTALL: the workflow skill folders of the plugins whose commands this run
+    // writes, each from the exact-key tree read above. Before the scripts step, so the hand-off
+    // sentinel that step installs never stands without the folder it names. A widened run may add a
+    // folder the early read did not cover. Each folder is read, installed and reported on its own, and
+    // a read failure is a warning, since the pre-clean has run: one broken folder never hides the next.
+    const foldersToInstall = selectedWorkflowFolders(commandAgentPlugins, folderWorkflows);
+    if (foldersToInstall.size > 0)
+        spinner.message('Installing workflow skills...');
+    for (const folder of folderRegistry) {
+        if (!foldersToInstall.has(folder.name))
+            continue;
+        const read = await readFolder(folder);
+        if (!read.ok) {
+            warn(`workflow skill folder: ${read.reason}`);
+            continue;
+        }
+        const installed = await installWorkflowFolder({ claudeDir, name: folder.name, files: read.files, links: report });
+        if (installed.outcome === 'failed') {
+            warn(`workflow skill folder: could not install ${prefixSkillName(folder.name)} (${installed.reason ?? 'unknown error'})`);
+        }
+    }
     // Install rules from selected plugins (rulesMap covers selected plugins only).
     // Rules are flat .md files resolved from src/assets/rules/{name}.md (no per-plugin subdir).
     spinner.message('Installing rules...');
-    const rulesTarget = path.join(claudeDir, 'rules', 'devflow');
-    if (rulesMap.size > 0) {
+    if (rulesMap.size > 0 && !rulesRefused) {
         await fs.mkdir(rulesTarget, { recursive: true });
-        const outcomes = await installAllRules(rulesMap, devflowDir, rulesTarget);
+        const outcomes = await installAllRules(rulesMap, devflowDir, rulesTarget, report);
         for (const { ruleName, outcome } of outcomes) {
             if (outcome === 'shadow') {
                 report.shadowedRules.push(ruleName);
@@ -1769,7 +2168,13 @@ export async function installViaFileCopy(options) {
     // (no dev tooling, no raw TypeScript).
     spinner.message('Installing scripts...');
     const scriptsTarget = path.join(devflowDir, 'scripts');
-    await composeScripts(scriptsTarget);
+    // The charter and the sentinel render from the EFFECTIVE selection (a partial install
+    // keeps what earlier runs installed).
+    await installScripts({
+        scriptsTarget,
+        plugins: options.effectivePlugins ?? plugins,
+        warn,
+    });
     spinner.stop('Components installed via file copy');
     return report;
 }