devflow-kit 3.9.0 → 3.11.0

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

@@ -1,18 +1,24 @@
 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 { discardDisplacedFolder } from './folder-swap.js';
+import { clearLinkForWrite, directoryState, refuseUnrealFolder, 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 +91,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 +134,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 +153,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 +163,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);
         }
     }
@@ -190,8 +219,12 @@ export async function copyDirectory(src, dest) {
  * {@link composeScripts}, swallows it with the rest of its copy-and-chmod step; that tree
  * is three levels of shipped assets, so a breach there means the package itself grew a
  * shape no walk in this repo expects, and neither call site aborts an install over it.
+ *
+ * `skip` names the entries the walk leaves alone: a path it accepts keeps its mode, and a folder
+ * it accepts is not entered. The reference overlay passes the backup session's `isKept`, so a file
+ * of the user that stays because its move failed keeps the mode the user gave it.
  */
-export async function chmodRecursive(dir, mode, _depth = 0) {
+export async function chmodRecursive(dir, mode, skip, _depth = 0) {
     if (_depth > MAX_REFERENCE_SWEEP_DEPTH) {
         throw new Error(`chmodRecursive: descent into ${dir} exceeds the bound of ` +
             `${MAX_REFERENCE_SWEEP_DEPTH} levels — that subtree keeps the modes it arrived with.`);
@@ -199,8 +232,10 @@ export async function chmodRecursive(dir, mode, _depth = 0) {
     const entries = await fs.readdir(dir, { withFileTypes: true });
     for (const entry of entries) {
         const fullPath = path.join(dir, entry.name);
+        if (skip?.(fullPath) === true)
+            continue;
         if (entry.isDirectory()) {
-            await chmodRecursive(fullPath, mode, _depth + 1);
+            await chmodRecursive(fullPath, mode, skip, _depth + 1);
         }
         else if (entry.isFile()) {
             await fs.chmod(fullPath, mode);
@@ -406,7 +441,7 @@ const STAGING_TOKEN = `${process.pid}-${Date.now().toString(36)}`;
  * arm's basename is `{provider}.{token}.tmp`, which is not dot-prefixed, so a rule keyed
  * on the name would reach the other arms only.
  */
-function stagingDirFor(referencesTarget, unit) {
+export function stagingDirFor(referencesTarget, unit) {
     return `${sidecarBaseFor(referencesTarget, unit)}.${STAGING_TOKEN}.tmp`;
 }
 /**
@@ -415,7 +450,7 @@ function stagingDirFor(referencesTarget, unit) {
  * Beside the staging tree, and under `tracker/` for the same reason (property 2 of
  * {@link stagingDirFor}): a backup a crash strands is removed by a later run's prune.
  */
-function backupDirFor(referencesTarget, unit) {
+export function backupDirFor(referencesTarget, unit) {
     return `${sidecarBaseFor(referencesTarget, unit)}.old`;
 }
 /**
@@ -575,6 +610,10 @@ async function buildUnitStagingTree(unit, sourceRoot, referencesTarget, warn) {
  *     entries the overlay must never replace or delete (D-OVERLAY-FLAT-UNIT), so its
  *     files are exactly the comparison and the neighbours are none of its business.
  *
+ * A directory unit that {@link unitStaysInPlace} is promoted file by file, like a flat set,
+ * so a file of the user's that stays in its folder is no sign that the unit is stale: its
+ * files are exactly the comparison there too.
+ *
  * What it deliberately does NOT compare is file MODE. D-OVERLAY-MODE-SCOPE normalises the
  * whole references directory on every run regardless of which units promoted, so a unit
  * skipped here still has its modes converged — a skipped promotion can hide byte drift
@@ -584,9 +623,9 @@ async function buildUnitStagingTree(unit, sourceRoot, referencesTarget, warn) {
  * — answers "no". The fallback is always the promotion that was going to happen anyway,
  * so a failure to compare can only cost a write, never correctness.
  */
-async function stagedUnitIsAlreadyInstalled(unit, referencesTarget, stagingDir) {
+async function stagedUnitIsAlreadyInstalled(unit, referencesTarget, stagingDir, backups) {
     const basenameOf = (relPath) => relPath.split('/').slice(-1)[0];
-    if (unit.kind !== 'cross-cutting') {
+    if (unit.kind !== 'cross-cutting' && !unitStaysInPlace(backups, underRoot(referencesTarget, unitSubdir(unit)))) {
         const owned = new Set(unit.files.map(basenameOf));
         let installed;
         try {
@@ -631,6 +670,50 @@ async function restoreDisplacedUnit(backup, target) {
         return { ok: false, error: String(err) };
     }
 }
+/**
+ * Does a directory unit's folder hold an entry that must stay where it is?
+ *
+ * True when the backup session kept an entry at or below the folder (a move that failed, a
+ * folder it could not scan), or kept the folder or a folder above it (one over the entry
+ * cap, or a root it refused). Such a folder is never swapped out: a swap sets the whole
+ * folder aside, and what the session kept in it would go with it. The unit is written into
+ * the folder file by file instead, and the prune that follows leaves the kept entries alone.
+ */
+function unitStaysInPlace(backups, unitDir) {
+    return backups.isKept(unitDir) || backups.keptUnder(unitDir).length > 0;
+}
+/**
+ * Rename the documents a staging tree holds into `destDir`, one `rename` each, and drop the
+ * staging tree. Shared by the two promotions that write into a folder that stays in place.
+ *
+ * The directory is created rather than assumed — {@link promoteDirectoryUnit} does the same
+ * for its target's parent. The two flat directories the registry emits today exist by the time
+ * promotion runs for reasons that have nothing to do with the unit landing in them: the
+ * references root is created by {@link overlayGeneratedReferences}, and `tracker/` as a side
+ * effect of the flat arm's own staging path. A flat set landing anywhere else takes ENOENT on
+ * its first rename — a unit reported as failed for where it was asked to land rather than for
+ * anything wrong with the documents it carries.
+ *
+ * Past the first rename the set is mixed, and there is no directory to swap back
+ * (D-OVERLAY-FLAT-UNIT). The documents renamed so far carry this run's bytes; the rest still
+ * carry the previous install's. The state is recorded after each rename so a failure on the
+ * next one names both halves instead of claiming the set is untouched.
+ *
+ * Throws on the first failing rename; the caller reports the state recorded by then.
+ */
+async function renameDocumentsInto(files, destDir, stagingDir, record) {
+    await fs.mkdir(destDir, { recursive: true });
+    for (const [index, relPath] of files.entries()) {
+        const basename = relPath.split('/').slice(-1)[0];
+        await fs.rename(path.join(stagingDir, basename), path.join(destDir, basename));
+        record({
+            kind: 'partially-refreshed',
+            refreshed: files.slice(0, index + 1),
+            stale: files.slice(index + 1),
+        });
+    }
+    await fs.rm(stagingDir, { recursive: true, force: true });
+}
 /**
  * Promote the flat cross-cutting set — one `rename` per document.
  *
@@ -645,29 +728,7 @@ async function restoreDisplacedUnit(backup, target) {
  * Throws on the first failing rename; the caller reports the state recorded by then.
  */
 async function promoteCrossCuttingUnit(unit, referencesTarget, stagingDir, record) {
-    const destDir = underRoot(referencesTarget, unit.dir);
-    // The directory this set lands in, created rather than assumed — {@link promoteDirectoryUnit}
-    // does the same for its target's parent. The two flat directories the registry emits today
-    // exist by the time promotion runs for reasons that have nothing to do with the unit landing
-    // in them: the references root is created by {@link overlayGeneratedReferences}, and
-    // `tracker/` as a side effect of this arm's own staging path. A flat set landing anywhere
-    // else takes ENOENT on its first rename — a unit reported as failed for where it was asked
-    // to land rather than for anything wrong with the documents it carries.
-    await fs.mkdir(destDir, { recursive: true });
-    for (const [index, relPath] of unit.files.entries()) {
-        const basename = relPath.split('/').slice(-1)[0];
-        await fs.rename(path.join(stagingDir, basename), path.join(destDir, basename));
-        // Past the first rename the set is mixed, and there is no directory to swap back
-        // (D-OVERLAY-FLAT-UNIT). The documents renamed so far carry this run's bytes; the
-        // rest still carry the previous install's. Recorded after each rename so a failure
-        // on the next one names both halves instead of claiming the set is untouched.
-        record({
-            kind: 'partially-refreshed',
-            refreshed: unit.files.slice(0, index + 1),
-            stale: unit.files.slice(index + 1),
-        });
-    }
-    await fs.rm(stagingDir, { recursive: true, force: true });
+    await renameDocumentsInto(unit.files, underRoot(referencesTarget, unit.dir), stagingDir, record);
 }
 /**
  * Promote a directory unit (a provider, or `pr/`) — swapped whole, or not at all.
@@ -677,9 +738,17 @@ async function promoteCrossCuttingUnit(unit, referencesTarget, stagingDir, recor
  * either entirely the previous install or entirely the new one (DR-05, risk P2-g), and a
  * rename that fails half-way restores the previous one rather than leaving it empty.
  *
+ * A folder that holds an entry which must stay where it is ({@link unitStaysInPlace}), or
+ * that cannot be set aside because an earlier `.old` folder still stands beside it, is not
+ * swapped: the unit's files are renamed into it one by one, as a flat set is
+ * ({@link renameDocumentsInto}), and the prune that follows converges the rest. Nothing here
+ * removes a folder with a recursive `rm`: a displaced folder goes through the backup
+ * session, which moves what devflow did not ship, removes what it shipped by the list the
+ * scan made and ends with a plain `rmdir` ({@link discardDisplacedFolder}).
+ *
  * Throws once the state it left has been recorded; the caller reports it.
  */
-async function promoteDirectoryUnit(unit, referencesTarget, stagingDir, record) {
+async function promoteDirectoryUnit(unit, referencesTarget, stagingDir, record, backups) {
     const target = underRoot(referencesTarget, unitSubdir(unit));
     const backup = backupDirFor(referencesTarget, unit);
     await fs.mkdir(path.dirname(target), { recursive: true });
@@ -696,8 +765,15 @@ async function promoteDirectoryUnit(unit, referencesTarget, stagingDir, record)
     // either is converged away by a later run's tracker-subtree prune (both names end
     // in neither `/` nor `.md`, so no manifest entry can collide with them) — but the
     // backup this run is still relying on is exempt from this run's prune, which is
-    // what `restore-failed` carries the recovery path for.
-    await fs.rm(backup, { recursive: true, force: true });
+    // what `restore-failed` carries the recovery path for. A file of the user's in a
+    // stranded `.old` moves to the backup folder first; one that cannot move keeps the
+    // folder standing.
+    await discardDisplacedFolder(backups, backup, target);
+    if ((await directoryState(target)) === 'real'
+        && (unitStaysInPlace(backups, target) || (await directoryState(backup)) !== 'absent')) {
+        await renameDocumentsInto(unit.files, target, stagingDir, record);
+        return;
+    }
     let displaced = false;
     try {
         await fs.rename(target, backup);
@@ -722,7 +798,8 @@ async function promoteDirectoryUnit(unit, referencesTarget, stagingDir, record)
         }
         throw err;
     }
-    await fs.rm(backup, { recursive: true, force: true }).catch(() => undefined);
+    if (displaced)
+        await discardDisplacedFolder(backups, backup, target).catch(() => undefined);
 }
 /**
  * Promote a fully built staging tree into place, dispatched on what kind of unit it is.
@@ -745,7 +822,7 @@ async function promoteDirectoryUnit(unit, referencesTarget, stagingDir, record)
  * that failure selects (previous unit restored, not deleted) is exactly the one worth
  * pinning.
  */
-export async function promoteUnitStagingTree(unit, referencesTarget, stagingDir) {
+export async function promoteUnitStagingTree(unit, referencesTarget, stagingDir, backups) {
     let state = { kind: 'installed-unchanged' };
     const record = next => { state = next; };
     try {
@@ -755,7 +832,7 @@ export async function promoteUnitStagingTree(unit, referencesTarget, stagingDir)
                 break;
             case 'provider':
             case 'pr-host':
-                await promoteDirectoryUnit(unit, referencesTarget, stagingDir, record);
+                await promoteDirectoryUnit(unit, referencesTarget, stagingDir, record, backups);
                 break;
             default: {
                 const _exhaustive = unit;
@@ -830,7 +907,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).`);
 }
 /**
@@ -872,7 +949,7 @@ async function requireGeneratedTree(sourceRoot, manifest) {
  * coordinate system as the manifest that decided them and as the stranded-skip failure
  * below, which has always named its subtree from the root.
  */
-async function prunePreservingRecoveryCopies(referencesTarget, subtree, manifest, overlayFailures) {
+async function prunePreservingRecoveryCopies(referencesTarget, subtree, manifest, overlayFailures, backups) {
     const subtreeRoot = underRoot(referencesTarget, subtree);
     const prefix = `${subtree}/`;
     // Checked here rather than trusted from the unit loop: this is the call that follows
@@ -905,7 +982,7 @@ async function prunePreservingRecoveryCopies(referencesTarget, subtree, manifest
     }
     // Keyed by relative path, because `tracker/{provider}/{op}.md` is what distinguishes
     // two providers' identically named files — the reason mdEntryName cannot serve here.
-    const swept = await sweepOrphanedReferences(subtreeRoot, new Set(manifest.filter(p => p.startsWith(prefix)).map(p => p.slice(prefix.length))));
+    const swept = await sweepOrphanedReferences(subtreeRoot, new Set(manifest.filter(p => p.startsWith(prefix)).map(p => p.slice(prefix.length))), referenceSweepDelegate(backups));
     return {
         scanned: swept.scanned,
         removed: swept.removed.map(rel => `${prefix}${rel}`),
@@ -925,12 +1002,12 @@ async function prunePreservingRecoveryCopies(referencesTarget, subtree, manifest
  * `scanned` sums, which keeps it the non-vacuity counter it is everywhere else: a run
  * that scanned nothing scanned nothing in any subtree.
  */
-async function pruneConvergedSubtrees(referencesTarget, manifest, overlayFailures) {
+async function pruneConvergedSubtrees(referencesTarget, manifest, overlayFailures, backups) {
     let scanned = 0;
     const removed = [];
     const failed = [];
     for (const subtree of CONVERGED_SUBTREES) {
-        const swept = await prunePreservingRecoveryCopies(referencesTarget, subtree, manifest, overlayFailures);
+        const swept = await prunePreservingRecoveryCopies(referencesTarget, subtree, manifest, overlayFailures, backups);
         scanned += swept.scanned;
         removed.push(...swept.removed);
         failed.push(...swept.failed);
@@ -1011,6 +1088,10 @@ export async function overlayGeneratedReferences(opts) {
         if (fault !== null)
             rootFaults.set(subtree, fault);
     }
+    // A unit swap deletes the folder it displaces, and the prune below sweeps what the manifest does
+    // not name. What the user put in a converged subtree therefore moves aside first, before either.
+    // A root that is not a real folder is not scanned; the unit refusal and the prune skip it too.
+    await opts.backups.prepass(CONVERGED_SUBTREES.filter(subtree => !rootFaults.has(subtree)).map(subtree => underRoot(opts.referencesTarget, subtree)));
     for (const unit of planOverlayUnits(manifest)) {
         const fault = subtreesTouchedBy(opts.referencesTarget, unit)
             .map(subtree => rootFaults.get(subtree))
@@ -1036,19 +1117,19 @@ export async function overlayGeneratedReferences(opts) {
         // installed, so `overlaidRefs` names what this run WROTE (AC-23). The discard is the
         // same one both promotion halves perform on their way out; skipping it would leave
         // the `.tmp` residue every other path is asserted not to leave.
-        if (await stagedUnitIsAlreadyInstalled(unit, opts.referencesTarget, built.stagingDir)) {
+        if (await stagedUnitIsAlreadyInstalled(unit, opts.referencesTarget, built.stagingDir, opts.backups)) {
             await fs.rm(built.stagingDir, { recursive: true, force: true }).catch(() => undefined);
             unchangedRefs.push(...unit.files);
             continue;
         }
-        const promoted = await promoteUnitStagingTree(unit, opts.referencesTarget, built.stagingDir);
+        const promoted = await promoteUnitStagingTree(unit, opts.referencesTarget, built.stagingDir, opts.backups);
         if (!promoted.ok) {
             overlayFailures.push({ unit: unitRef(unit), state: promoted.state, error: promoted.error });
             continue;
         }
         overlaidRefs.push(...unit.files);
     }
-    const pruned = await pruneConvergedSubtrees(opts.referencesTarget, manifest, overlayFailures);
+    const pruned = await pruneConvergedSubtrees(opts.referencesTarget, manifest, overlayFailures, opts.backups);
     // D-OVERLAY-MODE-SCOPE: normalise the WHOLE references directory, not only the files
     // this run installed. copyDirectory preserves source modes, so a hand-authored
     // reference checked in with an odd mode installs with it; a reference is read-only
@@ -1059,12 +1140,13 @@ export async function overlayGeneratedReferences(opts) {
     // boundary is stated as "never replace or delete" rather than "never touch": the MODE of
     // a hand-authored reference — and of whatever a shadowed skill supplied outside
     // `tracker/` — is normalised here. The prove-you-wrote-it rule permits exactly that: the
-    // ownership guard protects deletion, not overwrite.
+    // ownership guard protects deletion, not overwrite. A file of the user that the backup session
+    // kept in place (its move failed) is the exception: its mode stays as the user set it.
     //
     // It is also the one walk that can breach chmodRecursive's descent bound. The catch is
     // that breach's reporting channel, not just an I/O guard (see {@link chmodRecursive}).
     try {
-        await chmodRecursive(opts.referencesTarget, 0o644);
+        await chmodRecursive(opts.referencesTarget, 0o644, entry => opts.backups.isKept(entry));
     }
     catch (err) {
         warn(`reference overlay: could not normalise reference file modes — ${String(err)}`);
@@ -1073,6 +1155,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).
@@ -1119,54 +1241,17 @@ export function overlayOwnedSkillPaths(manifest) {
     return owned;
 }
 /**
- * Empty a directory of everything but the paths another converger owns.
- *
- * `fs.rm(dir)` with a hole in it. `keep` holds directory-relative paths, each preserved
- * whole — a file as itself, a directory with its entire subtree. Everything else is
- * removed exactly as the unconditional pre-clean would have removed it.
- *
- * A kept path is preserved only as a real file or directory. A symlink planted at one is
- * removed like anything else (the link, never its target): the converger that owns the
- * path writes and prunes through it, so a link left standing here would hand that
- * converger someone else's directory (D-CONVERGED-ROOT-REAL). `Dirent` types are
- * lstat-based, which is what makes the check see the link rather than its target.
- *
- * Descent is bounded, and the bound is the `keep` set's own deepest path rather than a
- * constant: the walk only ever descends INTO a directory that still has a kept
- * descendant below it, so there is nothing to look for past that depth. A `keep` set of
- * depth 2 — which is what {@link overlayOwnedSkillPaths} produces for every manifest the
- * build emits — walks two levels and `fs.rm`s the rest recursively in one call.
- *
- * 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.
+ * 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 emptyDirectoryExcept(dir, keep) {
-    const kept = [...keep];
-    const maxDepth = Math.max(0, ...kept.map(relPath => relPath.split('/').length));
-    const walk = async (current, rel, depth) => {
-        let entries;
-        try {
-            entries = await fs.readdir(current, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
-        for (const entry of entries) {
-            const entryRel = rel === '' ? entry.name : `${rel}/${entry.name}`;
-            if (keep.has(entryRel) && !entry.isSymbolicLink())
-                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);
-                continue;
-            }
-            await fs.rm(path.join(current, entry.name), { recursive: true, force: true });
-        }
-    };
-    await walk(dir, '', 1);
+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 +1275,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 +1292,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 +1366,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 +1459,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 +1498,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'));
@@ -1408,29 +1523,274 @@ function recordSweep(report, kind, sweep) {
  * report which of them were actually there to remove.
  *
  * `names` is registry arithmetic (the skills no selected plugin owns), so most of
- * it is routinely absent from disk. Only the deleter can say what it deleted:
- * `fs.rm` is called WITHOUT `force`, so an absent directory rejects with ENOENT —
- * "nothing to remove", neither a removal nor a failure. Reporting the plan instead
- * would tell the user about deletions that never happened.
- *
- * Per-item failure isolation, never throws: any other rejection is recorded in
- * `failed` and the remaining names are still attempted.
+ * it is routinely absent from disk. Only the deleter can say what it deleted: an
+ * absent folder is "nothing to remove", neither a removal nor a failure. Reporting
+ * the plan instead would tell the user about deletions that never happened.
+ *
+ * A folder goes by the entries the backup session listed, then a plain `rmdir`. The
+ * pre-pass has moved every file devflow did not ship, so a folder that still holds
+ * an entry (a move that failed) stays whole and is not reported as removed. A link
+ * at the folder is unlinked and its target is left as it is; a path that is not a
+ * folder is a failure and stays.
+ *
+ * Per-item failure isolation, never throws: a failure is recorded in `failed`
+ * and the remaining names are still attempted.
  */
-async function removeDeselectedSkills(skillsDir, names) {
+async function removeDeselectedSkills(skillsDir, names, backups) {
     const removed = [];
     const failed = [];
     for (const name of names) {
+        const folder = path.join(skillsDir, prefixSkillName(name));
+        const state = await directoryState(folder);
+        switch (state) {
+            case 'absent':
+                break;
+            case 'link':
+                if ((await unlinkLinkAt(folder)) === 'unlinked')
+                    removed.push(name);
+                else
+                    failed.push({ name, error: new Error('a link that could not be removed') });
+                break;
+            case 'unusable':
+                failed.push({ name, error: new Error('not a folder, so nothing was removed') });
+                break;
+            case 'real': {
+                const result = await backups.removeListed(folder);
+                if (result.folderRemoved)
+                    removed.push(name);
+                break;
+            }
+            default: {
+                const unreachable = state;
+                void unreachable;
+            }
+        }
+    }
+    return { removed, failed };
+}
+/** The kind of the entry at `entryPath`, read with `lstat` so a link is a link; null when it cannot be read. */
+async function entryKindAt(entryPath) {
+    try {
+        const stat = await fs.lstat(entryPath);
+        if (stat.isSymbolicLink())
+            return 'link';
+        if (stat.isDirectory())
+            return 'directory';
+        return stat.isFile() ? 'file' : 'special';
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The `mayRemove` check of a flat registry-diff sweep. It admits a file or link that the backup
+ * session classifies as devflow's own (a retired or superseded file, a leftover of an interrupted
+ * write) and nothing else. An unknown entry was moved by the pre-pass or stays where it is, and a
+ * folder is never admitted: the sweep removes what this check admits with `unlink`, so an entry
+ * that turns into a folder after the check is not removed. An entry the session kept, or one in a
+ * folder it kept (over the entry cap, or one it could not scan), is not admitted either: the run
+ * said it would leave that folder whole.
+ */
+function removesOnlyDevflowFiles(backups) {
+    return async (entryPath) => {
+        if (backups.isKept(entryPath))
+            return false;
+        const kind = await entryKindAt(entryPath);
+        if (kind === null || kind === 'directory')
+            return false;
+        return backups.classifyAt(entryPath, kind) !== 'unknown';
+    };
+}
+/**
+ * The delegate the reference prune acts through: it decides, per entry the manifest does not name,
+ * between keeping a file of the user's and removing one of devflow's own.
+ *
+ * An unknown entry moves whole to the backup folder, with one rename. An entry the session
+ * classifies as devflow's own (a retired or superseded reference, a leftover of an interrupted
+ * write) is removed: a file or link by `unlink`, a folder by the files the session lists and a plain
+ * `rmdir`, after its unknown entries moved. A folder is never removed recursively. A failed move is
+ * in the session's record and the entry stays; a failed unlink reaches the sweep as a failure.
+ *
+ * An entry the session kept stays as it is, with no second attempt: a move that failed earlier in
+ * the run, or a folder over the entry cap or one the scan could not read, and everything in it.
+ */
+export function referenceSweepDelegate(backups) {
+    return {
+        async dispose(entry, isDirectory) {
+            if (backups.isKept(entry))
+                return { outcome: 'kept' };
+            const kind = isDirectory ? 'directory' : (await entryKindAt(entry)) ?? 'file';
+            if (backups.classifyAt(entry, kind) === 'unknown') {
+                const moved = await backups.moveWhole(entry);
+                return { outcome: moved.status === 'moved' ? 'moved' : 'kept' };
+            }
+            if (kind === 'directory') {
+                await backups.prepass([entry]);
+                const removal = await backups.removeListed(entry);
+                return { outcome: removal.folderRemoved ? 'removed' : 'kept' };
+            }
+            try {
+                await fs.unlink(entry);
+                return { outcome: 'removed' };
+            }
+            catch (err) {
+                if (err.code === 'ENOENT')
+                    return { outcome: 'kept' };
+                return { outcome: 'failed', error: err };
+            }
+        },
+    };
+}
+/**
+ * Whether the run may move and remove below `root`: it is a real folder. An absent root has nothing
+ * to scan. A link at a root the pre-clean replaces (`replaceLink`) is unlinked and reported, as the
+ * pre-clean always did, and its target is not walked. A link that stays, or a path that is not a
+ * folder, is a refused root: no move and no removal below it, and `refuseUnrealFolder` names it
+ * later in the run.
+ */
+async function mayChangeBelow(root, report, replaceLink) {
+    const state = await directoryState(root);
+    if (state === 'real')
+        return true;
+    if (state === 'link' && replaceLink && (await unlinkLinkAt(root)) === 'unlinked')
+        report.replacedLinks.push(root);
+    return false;
+}
+/** Whether `relative` (a path below a skill folder) is an overlay-owned path or lies below one. */
+function isUnderOverlayOwnedPath(relative, owned) {
+    for (const ownedPath of owned) {
+        if (relative === ownedPath || relative.startsWith(`${ownedPath}/`))
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether the top-level entry that `relative` starts with is a `devflow:*` skill folder outside the
+ * registry: the folders the skill registry-diff sweep would remove.
+ */
+function isUnregisteredSkillFolder(relative, registry) {
+    const top = relative.split('/', 1)[0];
+    return top.startsWith(SKILL_NAMESPACE) && !registry.has(unprefixSkillName(top));
+}
+/**
+ * Unlink a link that stands at an overlay-owned path or above one, inside the references skill
+ * `skillDir`. The overlay writes and prunes through those paths, so a link left there would hand it
+ * another folder. Each unlinked link is returned for {@link reportLinksOnceWritten}, since it is
+ * replaced only once the overlay has written a real entry. Bounded by the owned set.
+ */
+async function unlinkOverlayOwnedLinks(skillDir, owned) {
+    const paths = new Set();
+    for (const rel of owned) {
+        const segments = rel.split('/');
+        for (let depth = 1; depth <= segments.length; depth++)
+            paths.add(segments.slice(0, depth).join('/'));
+    }
+    const unlinked = [];
+    for (const rel of [...paths].sort((a, b) => a.split('/').length - b.split('/').length || (a < b ? -1 : 1))) {
+        const entry = path.join(skillDir, ...rel.split('/'));
+        if ((await unlinkLinkAt(entry)) === 'unlinked')
+            unlinked.push(entry);
+    }
+    return unlinked;
+}
+/** 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 {
-            await fs.rm(path.join(skillsDir, prefixSkillName(name)), { recursive: true });
-            removed.push(name);
+            present = (await fs.stat(required)).isFile();
         }
-        catch (err) {
-            if (err.code === 'ENOENT')
-                continue;
-            failed.push({ name, error: err });
+        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('/')})`);
         }
     }
-    return { removed, failed };
+    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:
@@ -1438,10 +1798,13 @@ async function removeDeselectedSkills(skillsDir, names) {
  * 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 +1821,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 +1870,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 +1878,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 +1902,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 = () => { }, backups, } = 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,8 +1953,11 @@ export async function installViaFileCopy(options) {
         overlaidRefs: [],
         unchangedRefs: [],
         overlayFailures: [],
+        replacedLinks: [],
+        refusedFolders: [],
         removedSkills: [],
         dormantShadows: [],
+        backups: backups.snapshot(),
     };
     // The skill decision, made in full before anything is touched — which skills
     // this selection installs, which it removes, and which shadows it leaves inert.
@@ -1551,39 +1973,122 @@ 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];
-    // Clean old Devflow files before installing
-    spinner.message('Cleaning old files...');
+    // 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 = [];
+    const skillsRoot = path.join(claudeDir, 'skills');
+    const commandsTarget = path.join(claudeDir, 'commands', 'devflow');
+    const agentsTarget = path.join(claudeDir, 'agents', 'devflow');
+    const rulesTarget = path.join(claudeDir, 'rules', 'devflow');
+    const skillFolder = (name) => path.join(skillsRoot, prefixSkillName(name));
+    const registrySkills = new Set([...getAllSkillNames(folderWorkflows), ...FEATURE_OWNED_SKILLS]);
+    const overlayOwned = overlayOwnedSkillPaths(refsManifest);
+    const trackerAgentFile = mdFileName(TRACKER_AGENT_NAME);
+    // Every root this run would change is checked first, with the same link checks the install uses
+    // for its writes, and before the first move or removal. A refused root (a link that stays, or a
+    // path that is not a folder) and everything below it get no move and no removal; the other roots
+    // go on. A full install replaces a link at a root, as its pre-clean always did, and does not walk
+    // the folder the link points to.
+    const wipedFolders = [];
+    const prepassTargets = [];
+    const skillsRootState = await directoryState(skillsRoot);
+    const mayChangeSkills = skillsRootState === 'real';
+    // A skills root that is a link or not a folder is refused once, for every step below it: the
+    // pre-pass, the sweeps, the skill copies and the overlay, the exact-name removals and the
+    // replacement of a link at a workflow folder. Each of them would move, remove or write inside the
+    // folder the link points to. The refusal is named in `refusedFolders`, and the install summary says
+    // that nothing was written there. An absent root is fine: the skill copies create it.
+    const skillsRefused = skillsRootState === 'link' || skillsRootState === 'unusable';
+    if (skillsRefused)
+        report.refusedFolders.push(skillsRoot);
     if (!isPartialInstall) {
         // Commands and agents are plugin-scoped — only wipe on full install.
         // On partial installs the registry-diff sweeps below handle stale entries
         // without discarding assets from plugins not included in this run.
-        const oldDirs = [
-            path.join(claudeDir, 'commands', 'devflow'),
-            path.join(claudeDir, 'rules', 'devflow'),
-        ];
-        for (const dir of oldDirs) {
-            try {
-                await fs.rm(dir, { recursive: true, force: true });
-            }
-            catch { /* ignore */ }
+        for (const dir of [commandsTarget, rulesTarget]) {
+            if (!(await mayChangeBelow(dir, report, true)))
+                continue;
+            prepassTargets.push({ folder: dir });
+            wipedFolders.push(dir);
         }
         // D-TRACKER-AGENT-OWNER, pre-clean half — the same split the reference tree
         // needed (D-OVERLAY-OWNERSHIP), for the same reason. The agent directory is
         // emptied AROUND the one file `convergeTrackerArtifacts` owns: taking it
         // would leave converge with nothing to byte-compare against, so a
         // steady-state re-init would re-copy the agent and announce
-        // `tracker agent installed` on every run. Everything else is removed
-        // 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.
-        try {
-            await emptyDirectoryExcept(path.join(claudeDir, 'agents', 'devflow'), new Set([mdFileName(TRACKER_AGENT_NAME)]));
+        // `tracker agent installed` on every run. The scan leaves that file out, 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.
+        if (await mayChangeBelow(agentsTarget, report, true)) {
+            prepassTargets.push({ folder: agentsTarget, include: relative => relative !== trackerAgentFile });
+            wipedFolders.push(agentsTarget);
+        }
+        // The skill folders this run reinstalls, and the ones it removes. The references skill is
+        // scanned around the paths the overlay owns (D-OVERLAY-OWNERSHIP): the overlay converges them
+        // and moves what the user put in them, so the scan leaves them out.
+        if (mayChangeSkills) {
+            for (const skill of skillsMap.keys()) {
+                const target = skillFolder(skill);
+                if (!(await mayChangeBelow(target, report, true)))
+                    continue;
+                if (skill === SKILL_REFS_SKILL_NAME) {
+                    awaitingWrite.push(...await unlinkOverlayOwnedLinks(target, overlayOwned));
+                    prepassTargets.push({ folder: target, include: relative => !isUnderOverlayOwnedPath(relative, overlayOwned) });
+                }
+                else {
+                    prepassTargets.push({ folder: target });
+                }
+                wipedFolders.push(target);
+            }
+            for (const name of [...skillPlan.remove, ...skillPlan.removeFolders]) {
+                const target = skillFolder(name);
+                if ((await directoryState(target)) === 'real')
+                    prepassTargets.push({ folder: target });
+            }
+        }
+    }
+    else {
+        // Only what the registry-diff sweeps below would remove: the unknown .md files of the commands
+        // and agents folders. Files of other kinds stay, as they always did on a partial install.
+        for (const dir of [commandsTarget, agentsTarget]) {
+            if (await mayChangeBelow(dir, report, false)) {
+                prepassTargets.push({ folder: dir, include: relative => mdEntryName(relative) !== null });
+            }
         }
-        catch { /* ignore */ }
     }
+    // The devflow:* folders outside the registry, on every shape: a retired folder goes by its listed
+    // files and anything else moves whole.
+    if (mayChangeSkills) {
+        prepassTargets.push({ folder: skillsRoot, include: relative => isUnregisteredSkillFolder(relative, registrySkills) });
+    }
+    const prepass = await backups.prepass(prepassTargets);
+    const movedFromAgents = prepass.moved.some(unit => isContainedIn(agentsTarget, unit.original));
+    // Clean old Devflow files before installing: each folder loses the entries the pre-pass listed as
+    // devflow's own, then a plain rmdir. A folder that still holds a file the pre-pass could not move stays.
+    spinner.message('Cleaning old files...');
+    for (const folder of wipedFolders)
+        await backups.removeListed(folder);
+    // 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 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,12 +2101,20 @@ 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));
-    // 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
-    // pass in init.ts (runs immediately after this call). A bare dir whose name
-    // matches a current registry skill is by construction foreign to Devflow and
+    //
+    // The pre-pass has already moved every devflow:* folder outside the registry that holds a file of
+    // the user's, so this sweep removes nothing itself: a retired folder goes by the files the session
+    // listed, and a folder the pre-pass could not move stays where it is.
+    if (mayChangeSkills) {
+        recordSweep(report, 'skill', await sweepOrphanedAssets(skillsRoot, registrySkills, (entry) => entry.startsWith(SKILL_NAMESPACE) ? unprefixSkillName(entry) : null, async (entryPath) => {
+            await backups.removeListed(entryPath);
+            return false;
+        }));
+    }
+    // The prefixed install targets were pre-cleaned above, 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 pass in init.ts (runs immediately after this call). A
+    // bare dir whose name matches a current registry skill is by construction foreign to Devflow and
     // must not be touched here.
     //
     // The pre-clean is SCOPED to what this run reinstalls and the orphan sweep
@@ -1632,21 +2145,17 @@ 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.
-    if (!isPartialInstall) {
-        const overlayOwned = overlayOwnedSkillPaths(installedReferenceManifest());
-        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);
-                }
-                else {
-                    await fs.rm(target, { recursive: true, force: true });
-                }
-            }
-            catch { /* ignore */ }
+    //
+    // 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 && !skillsRefused) {
+        // 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 = skillFolder(name);
+            if ((await unlinkLinkAt(target)) === 'unlinked')
+                report.replacedLinks.push(target);
         }
     }
     // Remove the skills no selected plugin owns or requires — the deselection half
@@ -1655,10 +2164,12 @@ 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);
-    report.removedSkills.push(...deselected.removed);
-    for (const failure of deselected.failed) {
-        warn(`Could not remove deselected skill "${prefixSkillName(failure.name)}" — ${String(failure.error)}`);
+    if (mayChangeSkills) {
+        const deselected = await removeDeselectedSkills(skillsRoot, [...skillPlan.remove, ...skillPlan.removeFolders], backups);
+        report.removedSkills.push(...deselected.removed);
+        for (const failure of deselected.failed) {
+            warn(`Could not remove deselected skill "${prefixSkillName(failure.name)}" — ${String(failure.error)}`);
+        }
     }
     // Retired agents. The sweep runs BEFORE the copy so the copy can see what it found:
     // an agent file whose name left the registry means a previous release is installed
@@ -1668,16 +2179,21 @@ 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);
+    //
+    // The sweep removes only what the backup session classifies as devflow's own (a retired name, a
+    // leftover of an interrupted write): an unknown file was moved by the pre-pass or stays.
+    const agentSweep = agentsRefused
+        ? { scanned: 0, removed: [], failed: [] }
+        : await sweepOrphanedAssets(agentsTarget, new Set(getAllAgentNames()), mdEntryName, removesOnlyDevflowFiles(backups), 'unlink');
     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
     // that exist. After a retired agent was removed they do not, so a partial install
     // writes the commands and agents of every plugin the manifest records instead. The
     // widening is conditional because an ordinary add-one run has nothing to repair and
-    // must not rewrite files the user did not ask about.
-    const widenToInstalled = isPartialInstall && agentSweep.removed.length > 0;
+    // must not rewrite files the user did not ask about. An agent file the pre-pass moved out of the
+    // folder is the same sign: it came from an earlier release, so the commands may still name it.
+    const widenToInstalled = isPartialInstall && (agentSweep.removed.length > 0 || movedFromAgents);
     const commandAgentPlugins = widenToInstalled ? (options.effectivePlugins ?? plugins) : plugins;
     const commandAgentMap = widenToInstalled ? buildAssetMaps(commandAgentPlugins).agentsMap : agentsMap;
     // Install commands and agents (D-TRACKER-AGENT-OWNER and the source-resolution rules
@@ -1688,26 +2204,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, removesOnlyDevflowFiles(backups), 'unlink'));
+    }
     // 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 +2243,36 @@ 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.
+    //
+    // A refused skills root (a link or not a folder) gets no skill: every copy, and the overlay
+    // below it, would write into the folder the link points to.
     spinner.message('Installing skills...');
-    for (const [skillName] of omitCurationGatedSkills(skillsMap, curation)) {
-        const resolved = await resolveSkillSource(skillName, devflowDir);
+    const skillsToInstall = skillsRefused ? [] : [...omitCurationGatedSkills(skillsMap, curation).keys()];
+    for (const skillName of skillsToInstall) {
         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,8 +2288,11 @@ 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,
+                backups,
             });
             report.overlaidRefs.push(...overlay.overlaidRefs);
             report.unchangedRefs.push(...overlay.unchangedRefs);
@@ -1746,13 +2300,48 @@ 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.
+    // A refused skills root is not entered: the removal would reach files in the folder a link points to.
+    if (!compliance && !skillsRefused) {
+        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, backups });
+        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,8 +2358,15 @@ 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');
+    report.backups = backups.snapshot();
     return report;
 }
 //# sourceMappingURL=installer.js.map