devflow-kit 3.9.0 → 3.11.0

package/dist/targets/claude-code/charter-render.js

@@ -0,0 +1,374 @@
+/**
+ * Install-time render of the ambient orchestrator charter, and the implement sentinel.
+ *
+ * D-CHARTER-INSTALL-RENDER: the packaged charter (src/assets/scripts/hooks/assets/orchestrator-charter.md)
+ * is the FULL text. It routes to workflows and agents that a machine may not install, so `devflow init`
+ * writes a copy with the lines of every uninstalled owner deleted, and the session-start hook injects that
+ * copy whole. Decided here:
+ *
+ *   - The render only deletes. It inserts no text and reads no name into the output: the inventory (which
+ *     commands and agents the selection installs) is used for presence checks alone. The full source is
+ *     also the fallback, so a render that cannot run installs the full charter and warns; it never aborts
+ *     the install.
+ *   - The span table is the whole contract between the charter text and this module. Every span is counted
+ *     in the ORIGINAL source before any removal, and a span that occurs 0 or more than 1 times fails the
+ *     render, so wording drift in the charter surfaces at install time and in the test, never as a
+ *     silently wrong charter. The edits are ranges of the original source applied once, and two chosen
+ *     ranges that share bytes fail the render rather than cut through each other.
+ *   - The two debug-command spans overlap on `, else ` by design (`devflow:debug, else Explore ...`). They
+ *     share one owner with opposite polarity, so a render removes exactly one of them: the fallback
+ *     sentence when debug is installed, the command mention when it is not.
+ *   - devflow-ambient's agents count as installed whatever the selection says. The charter belongs to that
+ *     plugin, and the hooks inject it only while ambient mode is on, which is when `devflow init` installs
+ *     the plugin; `devflow ambient --enable` warns when it is not installed.
+ *   - The sentinel (`hooks/assets/implement-installed`) exists exactly when devflow-implement is installed.
+ *     The per-prompt preamble branches on its existence with a shell builtin, so the plan-handoff directive
+ *     runs only where the workflow it names exists. This module is the only writer of the charter and the
+ *     sentinel at install time; the verbatim script copy skips both.
+ *   - `mode: 'uninstall'` is the uninstall mode. An uninstall re-renders a charter that is installed from the
+ *     manifest record and may take the sentinel away, but never creates a file. With no record to render
+ *     from, `removeHandoffSentinel` takes the sentinel away alone and the charter stays as it is.
+ *   - A change guard is asked about a file before the file is read, and every write or removal follows it.
+ *   - After a package upgrade the installed charter stays as rendered until the next `devflow init`.
+ *
+ * Never throws: every failure is a warning and a `failed` outcome, because the install must not die on a
+ * charter. Silent on success.
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { scriptsDir as packagedScriptsDir } from '../../core/assets.js';
+import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
+import { DEVFLOW_PLUGINS, registeredPluginNames } from '../../core/plugins.js';
+/** The charter, relative to the scripts directory (packaged and installed alike). */
+export const CHARTER_RELPATH = 'hooks/assets/orchestrator-charter.md';
+/** The sentinel, relative to the scripts directory. It exists exactly when devflow-implement is installed. */
+export const HANDOFF_SENTINEL_RELPATH = 'hooks/assets/implement-installed';
+/** The plugin whose agents the charter always treats as installed. */
+const AMBIENT_PLUGIN = 'devflow-ambient';
+/** The permission bits of an installed charter or sentinel: the hooks directory is installed executable. */
+const INSTALLED_MODE = 0o755;
+/** The command whose presence the sentinel records. */
+const HANDOFF_COMMAND = 'implement';
+/** The workflow list's items, in the order the charter joins them with `, `. */
+export const CHARTER_WORKFLOW_ITEMS = [
+    { text: 'devflow:implement', owner: { kind: 'command', name: 'implement' } },
+    { text: 'devflow:plan', owner: { kind: 'command', name: 'plan' } },
+    { text: 'devflow:research', owner: { kind: 'command', name: 'research' } },
+    { text: 'devflow:explore', owner: { kind: 'command', name: 'explore' } },
+    { text: 'devflow:code-review', owner: { kind: 'command', name: 'code-review' } },
+    { text: 'devflow:resolve', owner: { kind: 'command', name: 'resolve' } },
+    {
+        text: 'devflow:bug-analysis (hunt bugs in a branch before merge)',
+        owner: { kind: 'command', name: 'bug-analysis' },
+    },
+];
+/** The joined list as the charter spells it: it occurs once, on the workflow bullet. */
+export const CHARTER_WORKFLOW_LIST = CHARTER_WORKFLOW_ITEMS.map(item => item.text).join(', ');
+/** Every other span: removal-only, each tied to one owner. */
+export const CHARTER_SPANS = [
+    {
+        shape: 'text',
+        text: 'Fix (`OPERATION:` `validation-fix`, `alignment-fix`, `qa-fix` or `ci-fix`), else ',
+        owner: { kind: 'agent', name: 'fix' },
+        removedWhen: 'absent',
+    },
+    {
+        shape: 'text',
+        text: 'devflow:debug, else ',
+        owner: { kind: 'command', name: 'debug' },
+        removedWhen: 'absent',
+    },
+    {
+        shape: 'text',
+        text: ', else Explore investigates and Code fixes',
+        owner: { kind: 'command', name: 'debug' },
+        removedWhen: 'present',
+    },
+    {
+        shape: 'text',
+        text: '; never the Debug agent',
+        owner: { kind: 'agent', name: 'debug' },
+        removedWhen: 'absent',
+    },
+    {
+        shape: 'line',
+        text: '- Plan handoff: ',
+        owner: { kind: 'command', name: HANDOFF_COMMAND },
+        removedWhen: 'absent',
+    },
+];
+/**
+ * The commands and agents a plugin selection installs.
+ *
+ * Only names in DEVFLOW_PLUGINS count: a manifest is file content, so an unknown, deleted or hostile name
+ * selects nothing, and a name that reaches here from a legacy install maps to its current plugin
+ * ({@link registeredPluginNames}). Every caller reaches this check, so it holds whatever the caller filtered.
+ * devflow-ambient's agents are always included. The names are used for presence checks only and never reach
+ * the rendered text.
+ */
+export function charterInventory(pluginNames) {
+    const selected = new Set(registeredPluginNames(pluginNames));
+    const commands = new Set();
+    const agents = new Set();
+    for (const plugin of DEVFLOW_PLUGINS) {
+        if (plugin.name === AMBIENT_PLUGIN) {
+            for (const agent of plugin.agents)
+                agents.add(agent);
+        }
+        if (!selected.has(plugin.name))
+            continue;
+        for (const command of plugin.commands)
+            commands.add(command.startsWith('/') ? command.slice(1) : command);
+        for (const agent of plugin.agents)
+            agents.add(agent);
+    }
+    return { commands, agents };
+}
+/** How many times `needle` occurs in `haystack`, overlapping occurrences included. Bounded by the haystack length. */
+function occurrencesOf(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    for (let from = haystack.indexOf(needle); from !== -1; from = haystack.indexOf(needle, from + 1))
+        count++;
+    return count;
+}
+/** The range of the whole line that holds `index`, its newline included. */
+function lineRangeAt(source, index) {
+    const start = index === 0 ? 0 : source.lastIndexOf('\n', index - 1) + 1;
+    const newline = source.indexOf('\n', index);
+    return { start, end: newline === -1 ? source.length : newline + 1 };
+}
+/** The one place `span` sits in `source`, or the way it fails to. */
+function locateSpan(source, span) {
+    if (span.shape === 'text') {
+        const count = occurrencesOf(source, span.text);
+        if (count !== 1)
+            return { reason: count === 0 ? 'missing' : 'repeated' };
+        const start = source.indexOf(span.text);
+        return { start, end: start + span.text.length };
+    }
+    const starts = [];
+    let lineStart = 0;
+    for (const line of source.split('\n')) {
+        if (line.startsWith(span.text))
+            starts.push(lineStart);
+        lineStart += line.length + 1;
+    }
+    if (starts.length !== 1)
+        return { reason: starts.length === 0 ? 'missing' : 'repeated' };
+    return lineRangeAt(source, starts[0]);
+}
+/**
+ * `source` with the spans of every uninstalled owner deleted.
+ *
+ * Pure. Counts every span in the original source first and fails on a span that occurs 0 or more than 1
+ * times; a render that cannot be trusted returns `{ok: false}` and the caller keeps the full source. The
+ * workflow list keeps its installed items in order (with none kept, the whole bullet line goes), every
+ * other span goes when its owner is absent (or, for the debug fallback, present).
+ */
+export function renderCharter(source, installedCommands, installedAgents) {
+    const installed = (owner) => (owner.kind === 'command' ? installedCommands : installedAgents).has(owner.name);
+    // 1. Place every span in the original source, before anything is removed.
+    const listCount = occurrencesOf(source, CHARTER_WORKFLOW_LIST);
+    if (listCount !== 1) {
+        return { ok: false, reason: listCount === 0 ? 'missing' : 'repeated', span: CHARTER_WORKFLOW_LIST };
+    }
+    const listStart = source.indexOf(CHARTER_WORKFLOW_LIST);
+    const placed = [];
+    for (const span of CHARTER_SPANS) {
+        const at = locateSpan(source, span);
+        if ('reason' in at)
+            return { ok: false, reason: at.reason, span: span.text };
+        placed.push({ span, at });
+    }
+    // 2. Decide the edits, all against the original source.
+    const edits = [];
+    const kept = CHARTER_WORKFLOW_ITEMS.filter(item => installed(item.owner));
+    if (kept.length === 0) {
+        edits.push({ ...lineRangeAt(source, listStart), replacement: '', span: CHARTER_WORKFLOW_LIST });
+    }
+    else if (kept.length < CHARTER_WORKFLOW_ITEMS.length) {
+        edits.push({
+            start: listStart,
+            end: listStart + CHARTER_WORKFLOW_LIST.length,
+            replacement: kept.map(item => item.text).join(', '),
+            span: CHARTER_WORKFLOW_LIST,
+        });
+    }
+    for (const { span, at } of placed) {
+        const present = installed(span.owner);
+        if (span.removedWhen === 'absent' ? !present : present) {
+            edits.push({ start: at.start, end: at.end, replacement: '', span: span.text });
+        }
+    }
+    // 3. Apply them once, left to right. Two edits that share bytes cannot both be right.
+    edits.sort((a, b) => a.start - b.start);
+    let out = '';
+    let at = 0;
+    for (const edit of edits) {
+        if (edit.start < at)
+            return { ok: false, reason: 'overlap', span: edit.span };
+        out += source.slice(at, edit.start) + edit.replacement;
+        at = edit.end;
+    }
+    return { ok: true, content: out + source.slice(at) };
+}
+/** The file's bytes, or null when there is no such file. Any other failure throws to the caller's catch. */
+async function readIfPresent(file) {
+    try {
+        return await fs.readFile(file);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+/** Whether the change guard lets this run touch `file`; with no guard, every file may change. */
+async function permitted(file, mayChange) {
+    return mayChange === undefined || (await mayChange(file));
+}
+/** `warn`, made safe to call: a closed sink must not fail the install. */
+function quietly(warn) {
+    return msg => {
+        try {
+            warn(msg);
+        }
+        catch { /* a closed sink must not fail the install */ }
+    };
+}
+/** Write `text` unless `current` already holds exactly those bytes, atomically and executable. The caller has asked the change guard. */
+async function writeIfChanged(file, current, text) {
+    if (current !== null && current.equals(Buffer.from(text, 'utf-8')))
+        return 'unchanged';
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await writeFileAtomicExclusive(file, text, INSTALLED_MODE);
+    // A create mode passes through the umask, while composeScripts sets every file under hooks/ to 0755 on
+    // the next run whatever the umask is. Set the mode here too, or a second init changes it on disk.
+    if (process.platform !== 'win32')
+        await fs.chmod(file, INSTALLED_MODE);
+    return 'rewritten';
+}
+/**
+ * Remove the sentinel behind the change guard, without reading it; a file that is already gone is not an
+ * error. A failure is a warning and `failed`.
+ */
+async function removeSentinel(sentinelTarget, mayChange, warn) {
+    try {
+        if (!(await permitted(sentinelTarget, mayChange)))
+            return 'failed';
+        await fs.unlink(sentinelTarget);
+        return 'rewritten';
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return 'absent';
+        warn(`charter render: could not sync the implement sentinel (${sentinelTarget}) — ${String(err)}`);
+        return 'failed';
+    }
+}
+/** Why a render failed, in a sentence for the warning. */
+function describeFailure(result) {
+    const problem = {
+        missing: 'is missing from',
+        repeated: 'occurs more than once in',
+        overlap: 'overlaps another span in',
+    }[result.reason];
+    return `the span "${result.span}" ${problem} the packaged charter, so the full charter was installed.`;
+}
+/**
+ * Write the charter rendered for `plugins`, and sync the implement sentinel with it.
+ *
+ * Called by installScripts after the script copy (which installViaFileCopy and `init --hud-only` both
+ * run), and by the selective uninstall phase. The two files are independent: each has its own try/catch,
+ * so a failure on one never costs the other. Each file is checked with the change guard before it is read.
+ * Bytes are compared with the bytes on disk at the moment of writing, so a rerun that changes nothing
+ * writes nothing.
+ */
+export async function installRenderedCharter(opts) {
+    const { scriptsDir: target, plugins, mayChange, mode } = opts;
+    const warn = quietly(opts.warn);
+    // Precondition, asserted in production code: a relative scriptsDir would resolve against the working directory.
+    if (!path.isAbsolute(target)) {
+        warn(`charter render: scriptsDir is not an absolute path ("${target}") — the installed charter was not rendered`);
+        return { charter: 'failed', sentinel: 'failed' };
+    }
+    const inventory = charterInventory(plugins.map(plugin => (typeof plugin === 'string' ? plugin : plugin.name)));
+    const charterTarget = path.join(target, CHARTER_RELPATH);
+    const sentinelTarget = path.join(target, HANDOFF_SENTINEL_RELPATH);
+    const packagedRoot = () => {
+        try {
+            return opts.packagedScriptsDir ?? packagedScriptsDir();
+        }
+        catch (err) {
+            warn(`charter render: cannot find the packaged scripts — ${String(err)}`);
+            return null;
+        }
+    };
+    const installCharter = async () => {
+        try {
+            if (!(await permitted(charterTarget, mayChange)))
+                return 'failed';
+            const current = await readIfPresent(charterTarget);
+            if (current === null && mode === 'uninstall')
+                return 'absent';
+            const root = packagedRoot();
+            if (root === null)
+                return 'failed';
+            const source = await fs.readFile(path.join(root, CHARTER_RELPATH), 'utf-8');
+            const rendered = renderCharter(source, inventory.commands, inventory.agents);
+            if (!rendered.ok)
+                warn(`charter render: ${describeFailure(rendered)}`);
+            return await writeIfChanged(charterTarget, current, rendered.ok ? rendered.content : source);
+        }
+        catch (err) {
+            warn(`charter render: could not install the charter (${charterTarget}) — ${String(err)}`);
+            return 'failed';
+        }
+    };
+    const syncSentinel = async () => {
+        if (!inventory.commands.has(HANDOFF_COMMAND))
+            return removeSentinel(sentinelTarget, mayChange, warn);
+        try {
+            if (!(await permitted(sentinelTarget, mayChange)))
+                return 'failed';
+            const current = await readIfPresent(sentinelTarget);
+            if (mode === 'uninstall')
+                return current === null ? 'absent' : 'unchanged';
+            const root = packagedRoot();
+            if (root === null)
+                return 'failed';
+            const text = await fs.readFile(path.join(root, HANDOFF_SENTINEL_RELPATH), 'utf-8');
+            return await writeIfChanged(sentinelTarget, current, text);
+        }
+        catch (err) {
+            warn(`charter render: could not sync the implement sentinel (${sentinelTarget}) — ${String(err)}`);
+            return 'failed';
+        }
+    };
+    const charter = await installCharter();
+    const sentinel = await syncSentinel();
+    return { charter, sentinel };
+}
+/**
+ * Take the implement sentinel away when the removed plugins include the owner of the handoff command, and
+ * touch nothing else. For an uninstall with no manifest record: the charter has nothing to be rendered
+ * from and stays as it is, but the sentinel needs no record, and without it the per-prompt preamble falls
+ * back to the generic reminder instead of naming a workflow that is gone.
+ *
+ * `rewritten` when the sentinel was removed, `absent` when there was none, `unchanged` when the removed
+ * plugins leave implement installed, `failed` when the guard refused or a warning says what went wrong.
+ * Never throws.
+ */
+export async function removeHandoffSentinel(opts) {
+    const warn = quietly(opts.warn);
+    if (!path.isAbsolute(opts.scriptsDir)) {
+        warn(`charter render: scriptsDir is not an absolute path ("${opts.scriptsDir}") — the implement sentinel was not removed`);
+        return 'failed';
+    }
+    if (!charterInventory(opts.removedPlugins).commands.has(HANDOFF_COMMAND))
+        return 'unchanged';
+    return removeSentinel(path.join(opts.scriptsDir, HANDOFF_SENTINEL_RELPATH), opts.mayChange, warn);
+}
+//# sourceMappingURL=charter-render.js.map

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

@@ -24,7 +24,9 @@ import * as path from 'path';
 import { skillsDir, rulesDir } from '../../core/assets.js';
 import { ALWAYS_PRESENT_REFS, COMPLIANCE_FRAMEWORKS, normalizeFrameworks } from '../../core/compliance.js';
 import { parseComplianceFragment, composeComplianceSkill, composeComplianceRule } from '../../core/compliance-compose.js';
-import { validateSkillShadow, validateRuleShadow } from './installer.js';
+import { swapFolderIn } from './folder-swap.js';
+import { copyDirectory, validateSkillShadow, validateRuleShadow } from './installer.js';
+import { newLinkReport, refuseUnrealFolder, warnLinkReport, writeFileReplacingLink } from './linked-folder.js';
 // ── Path helpers ───────────────────────────────────────────────────────────
 /** Every registry framework id — the reference set every install carries. */
 const ALL_FRAMEWORK_IDS = COMPLIANCE_FRAMEWORKS.map(fw => fw.id);
@@ -32,6 +34,14 @@ const ALL_FRAMEWORK_IDS = COMPLIANCE_FRAMEWORKS.map(fw => fw.id);
 function skillTarget(claudeDir) {
     return path.join(claudeDir, 'skills', 'devflow:compliance');
 }
+/** The folder the compliance skill is built in before it is renamed into place: {claudeDir}/skills/devflow:compliance.tmp */
+export function complianceSkillTempPath(claudeDir) {
+    return `${skillTarget(claudeDir)}.tmp`;
+}
+/** Where the compliance skill folder waits while the new one is renamed in: {claudeDir}/skills/devflow:compliance.old */
+export function complianceSkillAsidePath(claudeDir) {
+    return `${skillTarget(claudeDir)}.old`;
+}
 /** Installed compliance rule file: {claudeDir}/rules/devflow/compliance.md */
 function ruleTarget(claudeDir) {
     return path.join(claudeDir, 'rules', 'devflow', 'compliance.md');
@@ -92,13 +102,22 @@ async function loadComplianceFragments(canonicalSrc, frameworks, warn) {
  * `fragments` is loaded once by convergeComplianceArtifacts and shared with the rule
  * installer — the SKILL.md and the rule compose from the same parsed set.
  *
- * Build under a .tmp sibling, remove old target, rename.
+ * Build under a .tmp sibling, then swap it in: the old target waits in a .old sibling while the new one
+ * is renamed in. A file in the old target that devflow did not ship moves to the backup folder first;
+ * if one cannot move, nothing is swapped and the shipped files are written into the old target (see
+ * {@link swapFolderIn}). An old target that is a link is moved aside as the link itself, never
+ * followed, so what it points to is left as it was; the link is recorded in `links`.
  * Unexpected I/O failures are reported via warn; never thrown.
  */
-async function installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments, warn) {
+async function installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments, warn, links, backups) {
     const canonicalSrc = path.join(skillsDir(), 'compliance');
     const target = skillTarget(claudeDir);
-    const tmpTarget = `${target}.tmp`;
+    const tmpTarget = complianceSkillTempPath(claudeDir);
+    // A skills folder that is a link or not a folder is refused before anything is built: the swap
+    // would move and remove below it, in the folder the link points to. The refusal is recorded in
+    // `links`, and the converge is not clean.
+    if (await refuseUnrealFolder(links, path.dirname(target)))
+        return;
     // Determine SKILL.md source: prefer a valid shadow, else use canonical.
     const skillShadowDir = path.join(devflowDir, 'skills', 'compliance');
     const shadowState = await validateSkillShadow(skillShadowDir);
@@ -148,9 +167,18 @@ async function installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments
                 warn(`compliance: reference "${fw}.md" not installed — ${String(err)}`);
             }
         }
-        // Swap: remove old target, rename tmp into place (two calls, not atomic).
-        await fs.rm(target, { recursive: true, force: true });
-        await fs.rename(tmpTarget, target);
+        // Swap: the old target waits aside, the tmp folder is renamed into place. The link is recorded
+        // once the real folder stands in its place, so the report matches its wording.
+        await swapFolderIn({
+            backups,
+            target,
+            staged: tmpTarget,
+            aside: complianceSkillAsidePath(claudeDir),
+            links,
+            mergeInto: () => copyDirectory(tmpTarget, target, undefined, links),
+        });
+        // The tmp folder is gone after a swap; a merge leaves it behind.
+        await fs.rm(tmpTarget, { recursive: true, force: true });
     }
     catch (err) {
         // Clean up tmp on failure (best-effort) so no orphan is left behind.
@@ -174,9 +202,11 @@ async function installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments
  * source (never the shadow — fragments are registry-owned) and shared with the skill
  * installer.
  *
- * I/O failures are reported via warn; never thrown.
+ * I/O failures are reported via warn; never thrown. The caller has proved that `rules/devflow` is a
+ * real folder or absent. A link at the rule file is replaced by the rename of the atomic write,
+ * never followed, and recorded in `links`.
  */
-async function installRuleFile(claudeDir, devflowDir, frameworks, fragments, warn) {
+async function installRuleFile(claudeDir, devflowDir, frameworks, fragments, warn, links) {
     const ruleShadowFile = path.join(devflowDir, 'rules', 'compliance.md');
     const canonicalRuleSrc = path.join(rulesDir(), 'compliance.md');
     const target = ruleTarget(claudeDir);
@@ -188,7 +218,7 @@ async function installRuleFile(claudeDir, devflowDir, frameworks, fragments, war
         for (const w of warnings)
             warn(`compliance: ${w}`);
         await fs.mkdir(path.dirname(target), { recursive: true });
-        await fs.writeFile(target, composed, 'utf-8');
+        await writeFileReplacingLink(target, composed, links);
     }
     catch (err) {
         warn(`compliance: rule install failed — ${String(err)}`);
@@ -213,13 +243,13 @@ async function installRuleFile(claudeDir, devflowDir, frameworks, fragments, war
  * principle in engineering.md.
  */
 export async function convergeComplianceArtifacts(opts) {
-    const { claudeDir, devflowDir, enabled, frameworks, rulesEnabled, warn } = opts;
+    const { claudeDir, devflowDir, enabled, frameworks, rulesEnabled, warn, backups } = opts;
     // S78: claudeDir precondition — reliability rule: assert invariants in production code.
     // An empty or relative claudeDir would make skillTarget/ruleTarget resolve to unexpected
     // locations. Warn and bail rather than running fs.rm with a potentially wrong path.
     if (!path.isAbsolute(claudeDir)) {
         warn(`compliance: claudeDir is not an absolute path ("${claudeDir}") — skipping convergence`);
-        return { removedPreexisting: false, converged: false };
+        return { removedPreexisting: false, converged: false, replacedLinks: [], refusedFolders: [] };
     }
     // Trust boundary. `frameworks` reaches here straight from the manifest on every
     // caller's bare --enable path, and normalizeComplianceFeature only type-checks it.
@@ -244,10 +274,24 @@ export async function convergeComplianceArtifacts(opts) {
     // The skill and the rule are independent operations. An error in
     // installSkillDir is caught internally and reported via trackingWarn, so
     // execution always continues to the rule step.
-    await installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments, trackingWarn);
+    const links = newLinkReport();
+    await installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments, trackingWarn, links, backups);
+    // The rule folder is proven before the rule is written or removed: a link there sends both into
+    // another place. The skill folder is swapped whole above, and a swap never follows a link.
+    const finish = (removedPreexisting) => {
+        warnLinkReport(links, warn);
+        return {
+            removedPreexisting,
+            converged: converged && links.refusedFolders.length === 0,
+            replacedLinks: links.replacedLinks,
+            refusedFolders: links.refusedFolders,
+        };
+    };
+    if (await refuseUnrealFolder(links, path.dirname(ruleTarget(claudeDir))))
+        return finish(false);
     if (enabled && rulesEnabled) {
-        await installRuleFile(claudeDir, devflowDir, safeFrameworks, fragments, trackingWarn);
-        return { removedPreexisting: false, converged };
+        await installRuleFile(claudeDir, devflowDir, safeFrameworks, fragments, trackingWarn, links);
+        return finish(false);
     }
     // Compliance off, or rules off: no rule. Probe first so a disable convergence
     // can report that it removed one; absence is already the desired end state.
@@ -260,7 +304,7 @@ export async function convergeComplianceArtifacts(opts) {
             trackingWarn(`compliance: failed to remove rule — ${String(err)}`);
         }
     }
-    return { removedPreexisting: !enabled && ruleExisted, converged };
+    return finish(!enabled && ruleExisted);
 }
 // ── Manifest-slice wrapper ─────────────────────────────────────────────────
 /**
@@ -278,7 +322,7 @@ export async function convergeComplianceArtifacts(opts) {
  *   than the value stored in the manifest.
  */
 export async function convergeFromManifest(opts) {
-    const { claudeDir, devflowDir, manifest, warn, rulesEnabledOverride } = opts;
+    const { claudeDir, devflowDir, manifest, warn, rulesEnabledOverride, backups } = opts;
     return convergeComplianceArtifacts({
         claudeDir,
         devflowDir,
@@ -286,6 +330,7 @@ export async function convergeFromManifest(opts) {
         frameworks: manifest.features.compliance.frameworks,
         rulesEnabled: rulesEnabledOverride ?? manifest.features.rules,
         warn,
+        backups,
     });
 }
 //# sourceMappingURL=compliance-install.js.map