devflow-kit 3.9.0 → 3.11.0

package/dist/cli/commands/install-report.js

@@ -9,6 +9,8 @@
  */
 import color from 'picocolors';
 import { overlayUnitLabel } from '../../targets/claude-code/installer.js';
+import { escapeName, formatCappedList } from '../../targets/claude-code/install-backup.js';
+import { refusedFolderMessage, replacedLinkMessage } from '../../targets/claude-code/linked-folder.js';
 import { SKILL_REFS_SKILL_NAME } from '../../core/mds-variants.js';
 import { prefixSkillName } from '../../core/plugins.js';
 /**
@@ -49,6 +51,39 @@ export function formatOverlaySummary(report, skillName = SKILL_REFS_SKILL_NAME)
     }
     return lines;
 }
+/**
+ * Turn the replaced-link half of an InstallReport into summary lines, one per link.
+ *
+ * An install removes a link it finds where it keeps one of its own files or folders and writes a
+ * real file or folder there. What the link pointed to is not touched, which looks the same from the
+ * filesystem as an install that never met the link, so the line says both.
+ *
+ * Pure function — returns lines, logs nothing.
+ */
+export function formatReplacedLinksSummary(report) {
+    return report.replacedLinks.map(linkPath => ({ level: 'warn', message: replacedLinkMessage(linkPath) }));
+}
+/**
+ * Turn the refused-folder half of an InstallReport into summary lines, one per folder.
+ *
+ * An install writes nothing at a path that is a link it could not remove, or not a folder where it
+ * needs one, and leaves the entry as it was. That looks the same on disk as an install that refreshed
+ * the path, so the line says what was skipped and what to do about it.
+ *
+ * Pure function — returns lines, logs nothing.
+ */
+export function formatRefusedFoldersSummary(report) {
+    return report.refusedFolders.map(folder => ({ level: 'warn', message: refusedFolderMessage(folder) }));
+}
+/**
+ * Both halves in one list, the replaced links first: for a command that prints the links one
+ * converge met and has no other summary of its own.
+ *
+ * Pure function — returns lines, logs nothing.
+ */
+export function formatLinksSummary(report) {
+    return [...formatReplacedLinksSummary(report), ...formatRefusedFoldersSummary(report)];
+}
 /**
  * The half of an overlay warning that describes what is actually on disk.
  *
@@ -197,4 +232,98 @@ export function formatSkillScopeSummary(report, pluginListUnchanged) {
     }
     return lines;
 }
+const BACKUP_SHOWN_UNITS = 5;
+/** One moved unit as `original -> backup`; a folder carries a trailing slash. */
+function movedUnitLabel(unit) {
+    const slash = unit.kind === 'directory' ? '/' : '';
+    return `${unit.original}${slash} -> ${unit.backup}${slash}`;
+}
+function failureLine(failure) {
+    const where = escapeName(failure.path);
+    const reason = escapeName(failure.reason);
+    switch (failure.action) {
+        case 'move':
+            return { level: 'warn', message: `Could not move ${where} to the backup folder (${reason}) — it stays where it is` };
+        case 'scan':
+            return { level: 'warn', message: `Could not scan ${where} (${reason}) — nothing in it was moved or removed` };
+        case 'remove':
+            return { level: 'warn', message: `Could not remove ${where} (${reason}) — it stays where it is` };
+        default: {
+            const _exhaustive = failure.action;
+            void _exhaustive;
+            return { level: 'warn', message: `Could not finish a step on ${where} (${reason})` };
+        }
+    }
+}
+/**
+ * The lines for the bare legacy skill folders that init kept because it could not tell if devflow
+ * made them (`sweepLegacySkillFolders`): one line per folder for the first five, then one line that
+ * counts the rest. A run that kept none gives no lines. Every printed path goes through `escapeName`.
+ */
+export function formatKeptLegacySkills(kept) {
+    const lines = kept.slice(0, BACKUP_SHOWN_UNITS).map((folder) => ({
+        level: 'info',
+        message: `Kept ${escapeName(folder)}: devflow could not tell if it made this folder`,
+    }));
+    if (kept.length > BACKUP_SHOWN_UNITS) {
+        lines.push({ level: 'info', message: `Kept ${kept.length - BACKUP_SHOWN_UNITS} more folder(s) for the same reason` });
+    }
+    return lines;
+}
+/**
+ * Turn the backup session's record into summary lines: what moved aside, what stayed because it
+ * could not move, and which retired files were removed. An empty snapshot gives no lines, so a
+ * clean run prints nothing.
+ *
+ * A move is not a removal. The moved line has its own wording and counts only moved units (a moved
+ * folder is one), and it never feeds the "Removed N orphaned asset(s)" line of `formatSweepSummary`.
+ * One removed name prints on one line only, by the kind of removal:
+ *
+ *   - the retired line below lists the retired files the session removed itself, with
+ *     `BackupSession.removeListed` (the earlier releases' commands, agents, rules and skill files)
+ *     or `BackupSession.removeExact` (the legacy sweep's command and rule names, and the legacy
+ *     hook scripts);
+ *   - `formatSweepSummary` lists the names the registry-diff sweeps removed, which the install
+ *     report records in `sweptOrphans`. A sweep removes a name only after the session has not,
+ *     and the session removes no name that a sweep records.
+ *
+ * Every printed name goes through `escapeName`. Pure function — returns lines, logs nothing.
+ */
+export function formatBackupSummary(snapshot) {
+    const lines = [];
+    if (snapshot.moved.length > 0) {
+        lines.push({
+            level: 'info',
+            message: `Moved ${snapshot.moved.length} item(s) that devflow does not ship out of its folders: ` +
+                formatCappedList(snapshot.moved.map(movedUnitLabel), BACKUP_SHOWN_UNITS),
+        });
+        if (snapshot.runFolder !== null) {
+            lines.push({ level: 'info', message: `Backup folder: ${escapeName(snapshot.runFolder)}` });
+        }
+    }
+    if (snapshot.retiredRemoved.length > 0) {
+        lines.push({
+            level: 'info',
+            message: `Removed ${snapshot.retiredRemoved.length} retired devflow file(s): ` +
+                formatCappedList(snapshot.retiredRemoved, BACKUP_SHOWN_UNITS),
+        });
+    }
+    for (const failure of snapshot.failures)
+        lines.push(failureLine(failure));
+    for (const hit of snapshot.capHits) {
+        lines.push({
+            level: 'warn',
+            message: `${escapeName(hit.folder)} holds ${hit.entries} entries, more than the limit of ${hit.cap} — ` +
+                'devflow left it whole and moved nothing out of it',
+        });
+    }
+    if (snapshot.rootRefusal !== null) {
+        lines.push({
+            level: 'warn',
+            message: `Could not use the backup folder ${escapeName(snapshot.rootRefusal.path)} ` +
+                `(${escapeName(snapshot.rootRefusal.reason)}) — nothing was moved aside in this run`,
+        });
+    }
+    return lines;
+}
 //# sourceMappingURL=install-report.js.map

package/dist/cli/commands/legacy-sweep.js

@@ -0,0 +1,159 @@
+import { createHash } from 'crypto';
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { LEGACY_COMMAND_NAMES, LEGACY_RULE_NAMES } from '../../core/plugins.js';
+import { RETIRED_SHIPPED } from '../../core/retired-shipped-names.js';
+import { LEGACY_SKILL_NAMES } from '../../targets/claude-code/legacy.js';
+import { BARE_LEGACY_SKILL_HASHES } from '../../targets/claude-code/legacy-skill-hashes.js';
+import { directoryState, isUnrealFolder } from '../../targets/claude-code/linked-folder.js';
+/** The prefix of a skill folder in devflow's own namespace. A folder without it is bare. */
+const NAMESPACE_PREFIX = 'devflow:';
+/**
+ * Whether the sweep may remove files from `dir`: the install did not refuse it, nothing in it stays
+ * because a move failed or the folder was too large to scan, and `lstat` shows a real folder or
+ * nothing. `readdir` and `rm` of a path below a link act on the folder it points to.
+ */
+async function mayRemoveFrom(report, backups, dir) {
+    return !report.refusedFolders.includes(dir) && !backups.isKept(dir) && !(await isUnrealFolder(dir));
+}
+/** Each name once, in the order given. */
+const uniqueNames = (...lists) => [...new Set(lists.flat())];
+/**
+ * Remove `<folder>/<name>.md` for each name, by exact name. A name that is shipped today is never
+ * removed, and a file that stays is left for the session's record.
+ */
+async function removeRetiredMarkdown(folder, names, backups) {
+    const removed = [];
+    for (const name of names) {
+        const file = path.join(folder, `${name}.md`);
+        if (backups.classifyAt(file, 'file') === 'shipped')
+            continue;
+        if ((await backups.removeExact(file)).status === 'removed')
+            removed.push(file);
+    }
+    return removed;
+}
+/**
+ * Remove the files that earlier releases installed into `commands/devflow` and `rules/devflow` and
+ * that no release installs now: the retired command and rule names and the legacy lists, each by its
+ * exact name. Runs on every install shape, since the full install's pre-clean covers only a full
+ * install. A file whose name only looks like a retired one (a `*-teams.md` of the user's) is not
+ * matched here: the install's pre-pass moves it aside and names it.
+ *
+ * A folder the install refused (`report.refusedFolders`), that the session could not scan, or that
+ * is a link now is skipped whole: the sweep reads and removes nothing there, and the folder a link
+ * points to is left as it is. Every removal goes through `backups`, so each removed file is named
+ * once, on the retired line of its record. Never throws.
+ *
+ * @param opts.legacyCommands - Legacy command names; added to the retired commands.
+ * @param opts.legacyRules - Legacy rule names; added to the retired rules.
+ */
+export async function sweepLegacyDevflowFiles(opts) {
+    const { claudeDir, report, backups } = opts;
+    const commands = uniqueNames(RETIRED_SHIPPED.commands, opts.legacyCommands ?? LEGACY_COMMAND_NAMES);
+    const rules = uniqueNames(RETIRED_SHIPPED.rules, opts.legacyRules ?? LEGACY_RULE_NAMES);
+    const removed = [];
+    const commandsDir = path.join(claudeDir, 'commands', 'devflow');
+    if (await mayRemoveFrom(report, backups, commandsDir)) {
+        removed.push(...await removeRetiredMarkdown(commandsDir, commands, backups));
+    }
+    const rulesDir = path.join(claudeDir, 'rules', 'devflow');
+    if (await mayRemoveFrom(report, backups, rulesDir)) {
+        removed.push(...await removeRetiredMarkdown(rulesDir, rules, backups));
+    }
+    return { removed };
+}
+/** The most bytes of a `SKILL.md` the check reads. Every released copy is far smaller, so a larger file is not one. */
+const MAX_SKILL_FILE_BYTES = 1024 * 1024;
+/**
+ * Who made a bare legacy skill folder, judged from its `SKILL.md` alone:
+ *   - `devflow`: the file is a regular file whose SHA-256 is one of `released`;
+ *   - `other`: the file reads and is not one of them, or is larger than any release copy;
+ *   - `unknown`: the check cannot decide. There is no `SKILL.md`, it is not a regular file, the
+ *     folder or the file is a link, or a read fails.
+ * An `absent` folder needs no answer. Reads one file at most. Never throws.
+ */
+async function judgeBareSkillFolder(folder, released) {
+    const state = await directoryState(folder);
+    if (state === 'absent')
+        return 'absent';
+    if (state !== 'real')
+        return 'unknown';
+    try {
+        const skillFile = path.join(folder, 'SKILL.md');
+        const stat = await fs.lstat(skillFile);
+        if (!stat.isFile())
+            return 'unknown';
+        if (stat.size > MAX_SKILL_FILE_BYTES)
+            return 'other';
+        const digest = createHash('sha256').update(await fs.readFile(skillFile)).digest('hex');
+        return released.includes(digest) ? 'devflow' : 'other';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * {@link judgeBareSkillFolder} for the bare legacy skill `name`, against the released copies of that
+ * name. A name with no entry in `released` was never installed bare by a release, so a folder of
+ * that name is `other`. The one check that `devflow init` and `devflow uninstall` share.
+ *
+ * @param folder - The folder of the skill, `<skills folder>/<name>`.
+ * @param released - SHA-256 hashes of the released `SKILL.md` copies by bare name; defaults to the frozen table.
+ */
+export function judgeBareLegacySkill(folder, name, released = BARE_LEGACY_SKILL_HASHES) {
+    return judgeBareSkillFolder(folder, Object.hasOwn(released, name) ? released[name] : []);
+}
+/**
+ * Deal with the skill folders that earlier installs left under the legacy names: every name of the
+ * legacy skill list, bare and `devflow:`-prefixed.
+ *
+ * A `devflow:`-prefixed folder that no release listed moves whole, with one rename and no walk, and
+ * is named; it is never deleted. A bare folder lives in the skills folder that Claude Code and other
+ * tools share, so its name proves nothing (`python`, `plan` and `review` are names of a user's own
+ * skills too). It moves only when its `SKILL.md` is a copy that a release of devflow installed
+ * (`released`). A bare folder whose `SKILL.md` is any other file stays where it is, and nothing is
+ * said. A bare folder that the check cannot judge stays, is never deleted, and is returned in
+ * `kept`, so the caller names it. A name with a listing in `retiredFiles` (the files a release
+ * shipped in that folder) goes by the listing instead: the listed files are removed, the rest of
+ * the folder moves, and a plain `rmdir` removes the folder only when it is empty. A move that fails
+ * leaves the folder and its files where they are, and the session records it. A name that is shipped
+ * today, or that an earlier step could not move, is skipped, and so is every name when the skills
+ * folder is a link or not a folder: nothing is moved through a link. Nothing here removes a folder
+ * with recursion. Never throws.
+ *
+ * @param opts.legacySkills - Folder names to deal with; defaults to the legacy skill list.
+ * @param opts.retiredFiles - Released file listings by folder name; defaults to the retired registry.
+ * @param opts.released - SHA-256 hashes of the released `SKILL.md` copies by bare name; defaults to the frozen table.
+ */
+export async function sweepLegacySkillFolders(opts) {
+    const { backups } = opts;
+    const retiredFiles = opts.retiredFiles ?? RETIRED_SHIPPED.skillFiles;
+    const released = opts.released ?? BARE_LEGACY_SKILL_HASHES;
+    const kept = [];
+    const skillsDir = path.join(opts.claudeDir, 'skills');
+    if ((await directoryState(skillsDir)) !== 'real')
+        return { kept };
+    for (const name of opts.legacySkills ?? LEGACY_SKILL_NAMES) {
+        const folder = path.join(skillsDir, name);
+        if (backups.isKept(folder) || backups.classifyAt(folder, 'directory') === 'shipped')
+            continue;
+        const listed = Object.hasOwn(retiredFiles, name) && retiredFiles[name].length > 0;
+        if (listed && (await directoryState(folder)) === 'real') {
+            await backups.prepass([folder]);
+            await backups.removeListed(folder);
+        }
+        else if (name.startsWith(NAMESPACE_PREFIX)) {
+            await backups.moveWhole(folder);
+        }
+        else {
+            const verdict = await judgeBareLegacySkill(folder, name, released);
+            if (verdict === 'devflow')
+                await backups.moveWhole(folder);
+            else if (verdict === 'unknown')
+                kept.push(folder);
+        }
+    }
+    return { kept };
+}
+//# sourceMappingURL=legacy-sweep.js.map

package/dist/cli/commands/proxy.js

@@ -31,6 +31,7 @@ import { stripAnsi } from '../../hud/colors.js';
 import { reapplyAgentMapping, revertExternalAgents, countExternalMappedAgents, readAgentMapping, } from '../../core/agent-models.js';
 import { getExternalModelsCached, discoverExternalModels, } from '../../core/model-discovery.js';
 import { modelCacheDir } from '../../core/cache.js';
+import { formatLinksSummary } from './install-report.js';
 import { getClaudeDirectory, getDevFlowDirectory, getHomeDirectory, } from '../../targets/claude-code/claude-paths.js';
 import { devflowHookOwner, ensureHook, hasHook, removeHooks, runHookCommand, } from '../../targets/claude-code/hooks.js';
 function Ok(value) {
@@ -1389,6 +1390,8 @@ async function runEnable(portOption) {
     s.message('Warming model cache...');
     await discoverExternalModels(cacheDir, logPath).catch(() => { });
     s.stop(color.green('External model routing enabled'));
+    for (const { message } of formatLinksSummary(reapplyResult))
+        p.log.warn(message);
     // D-P4-1: applies-on-restart — env var takes effect only for new sessions
     p.log.info(color.dim('Context-window enforcement disabled for relay-routed models — applies to new Claude Code sessions'));
     if (adopted) {
@@ -1472,7 +1475,9 @@ async function runDisable() {
     // Step 3: Sync manifest
     await syncManifestFeature(devflowDir, 'proxy', false);
     // Step 4: Revert external agents to shipped defaults
-    await revertExternalAgents({ installDir, devflowDir });
+    const revertResult = await revertExternalAgents({ installDir, devflowDir });
+    for (const { message } of formatLinksSummary(revertResult))
+        p.log.warn(message);
     p.log.success('External model routing disabled');
     // Step 5: Terminate the relay process.
     // Identity is confirmed via TCP + health before signalling — a recycled PID

package/dist/cli/commands/rules.js

@@ -10,6 +10,10 @@ import { rulesDir } from '../../core/assets.js';
 import { installAllRules, validateRuleShadow } from '../../targets/claude-code/installer.js';
 import { convergeFromManifest } from '../../targets/claude-code/compliance-install.js';
 import { convergeBehaviorFromManifest } from '../../targets/claude-code/behavior-install.js';
+import { newLinkReport, refuseUnrealFolder, refusedFolderMessage } from '../../targets/claude-code/linked-folder.js';
+import { removeRulesFolder, rulesFolderRefusedMessage } from '../../targets/claude-code/rules-folder.js';
+import { openBackupSessionOrFail, runWithBackupReport } from './backup-session.js';
+import { formatLinksSummary } from './install-report.js';
 /**
  * Check whether a rule has a user shadow file at ~/.devflow/rules/{name}.md.
  */
@@ -203,27 +207,43 @@ async function handleRuleUnshadow(name, allRules, devflowDir) {
  *
  * Warn-not-throw on per-item compliance convergence failure, so a convergence
  * failure never undoes the rules install.
+ *
+ * The record of `backups` prints once, as the enable returns or throws.
  */
-export async function runRulesEnable(claudeDir, devflowDir) {
+export function runRulesEnable(claudeDir, devflowDir, backups) {
+    return runWithBackupReport(backups, printBackups => enableRules(claudeDir, devflowDir, backups, printBackups));
+}
+async function enableRules(claudeDir, devflowDir, backups, printBackups) {
     const rulesTarget = path.join(claudeDir, 'rules', 'devflow');
     const manifest = await readManifest(devflowDir);
     if (!manifest) {
         p.log.error('No manifest found. Run devflow init first.');
+        printBackups();
         process.exit(1);
     }
     const installedPlugins = DEVFLOW_PLUGINS.filter(pl => manifest.plugins.includes(pl.name));
     const rulesMap = buildRulesMap(installedPlugins);
-    // Wipe stale rules from previously uninstalled plugins before re-installing.
-    await fs.rm(rulesTarget, { recursive: true, force: true });
-    await fs.mkdir(rulesTarget, { recursive: true });
+    // Clear stale rules from previously uninstalled plugins before re-installing: the files devflow did
+    // not ship move to the backup folder, and the rest of the folder is removed by the session's list.
+    // A rules folder that is a link is unlinked and replaced by a real folder, never emptied through,
+    // and the link is reported. Something that is not a folder stays and is refused below.
+    const links = newLinkReport();
+    if ((await removeRulesFolder(rulesTarget, backups)) === 'unlinked')
+        links.replacedLinks.push(rulesTarget);
+    // A link that could not be removed is still there, and `mkdir` and every rule write would follow it.
+    // Prove the folder first; a refused folder gets no rule, no manifest write and one refusal line.
+    const rulesFolderRefused = await refuseUnrealFolder(links, rulesTarget);
     let outcomes = [];
-    let installFailed = false;
-    try {
-        outcomes = await installAllRules(rulesMap, devflowDir, rulesTarget);
-    }
-    catch (err) {
-        p.log.error(`Rules installation failed — rules directory has been cleared: ${err instanceof Error ? err.message : String(err)}`);
-        installFailed = true;
+    let installFailed = rulesFolderRefused;
+    if (!rulesFolderRefused) {
+        await fs.mkdir(rulesTarget, { recursive: true });
+        try {
+            outcomes = await installAllRules(rulesMap, devflowDir, rulesTarget, links);
+        }
+        catch (err) {
+            p.log.error(`Rules installation failed — rules directory has been cleared: ${err instanceof Error ? err.message : String(err)}`);
+            installFailed = true;
+        }
     }
     if (!installFailed) {
         const shadowedCount = outcomes.filter(o => o.outcome === 'shadow').length;
@@ -239,6 +259,14 @@ export async function runRulesEnable(claudeDir, devflowDir) {
         await writeManifest(devflowDir, manifest);
         p.log.success(`Installed ${rulesMap.size} rule(s) to ${color.dim(rulesTarget)}${shadowSuffix}`);
     }
+    for (const { message } of formatLinksSummary(links))
+        p.log.warn(message);
+    // Each converge below proves the rules folder again and names a refused one itself; the line above
+    // has already named it, so the repeat is dropped.
+    const warnConverge = (msg) => {
+        if (!(rulesFolderRefused && msg === refusedFolderMessage(rulesTarget)))
+            p.log.warn(msg);
+    };
     // Converge compliance artifacts unconditionally — convergeFromManifest handles the
     // disabled case itself (removes stale artifacts). Running this regardless of installFailed
     // prevents a rules-install failure from leaving the compliance rule in a stale state.
@@ -249,8 +277,9 @@ export async function runRulesEnable(claudeDir, devflowDir) {
             claudeDir,
             devflowDir,
             manifest,
-            warn: (msg) => p.log.warn(msg),
+            warn: warnConverge,
             rulesEnabledOverride: !installFailed,
+            backups,
         });
     }
     catch (err) {
@@ -265,7 +294,7 @@ export async function runRulesEnable(claudeDir, devflowDir) {
             claudeDir,
             devflowDir,
             manifest,
-            warn: (msg) => p.log.warn(msg),
+            warn: warnConverge,
             rulesEnabledOverride: !installFailed,
         });
     }
@@ -308,17 +337,42 @@ export const rulesCommand = new Command('rules')
     }
     // No positional action — fall through to flag-based handling
     if (options.enable) {
-        await runRulesEnable(claudeDir, devflowDir);
+        const backups = await openBackupSessionOrFail({ claudeDir, devflowDir });
+        if (backups === null)
+            return;
+        await runRulesEnable(claudeDir, devflowDir, backups);
     }
     else if (options.disable) {
-        await fs.rm(rulesTarget, { recursive: true, force: true });
-        const manifest = await readManifest(devflowDir);
-        if (manifest) {
-            manifest.features.rules = false;
-            manifest.updatedAt = new Date().toISOString();
-            await writeManifest(devflowDir, manifest);
+        const backups = await openBackupSessionOrFail({ claudeDir, devflowDir });
+        if (backups === null)
+            return;
+        const removal = await runWithBackupReport(backups, async () => {
+            const outcome = await removeRulesFolder(rulesTarget, backups);
+            const manifest = await readManifest(devflowDir);
+            if (manifest) {
+                manifest.features.rules = false;
+                manifest.updatedAt = new Date().toISOString();
+                await writeManifest(devflowDir, manifest);
+            }
+            return outcome;
+        });
+        switch (removal) {
+            case 'kept':
+                p.log.warn(`Rules disabled — ${rulesTarget} stays, because it still holds files that devflow did not remove`);
+                break;
+            case 'refused':
+                p.log.warn(`Rules disabled. ${rulesFolderRefusedMessage(rulesTarget)}`);
+                break;
+            case 'absent':
+            case 'removed':
+            case 'unlinked':
+                p.log.success('Rules disabled — removed rules directory');
+                break;
+            default: {
+                const unreachable = removal;
+                void unreachable;
+            }
         }
-        p.log.success('Rules disabled — removed rules directory');
     }
     else if (options.status) {
         let installedFiles = [];

package/dist/cli/commands/skills.js

@@ -4,7 +4,7 @@ import * as path from 'path';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
 import { getClaudeDirectory, getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
-import { getAllSkillNames, prefixSkillName, unprefixSkillName, skillOwners, FEATURE_OWNED_SKILLS } from '../../core/plugins.js';
+import { getAllSkillNames, prefixSkillName, unprefixSkillName, skillOwners, FEATURE_OWNED_SKILLS, WORKFLOW_FOLDER_NAMES } from '../../core/plugins.js';
 import { skillsDir } from '../../core/assets.js';
 import { copyDirectory, validateSkillShadow } from '../../targets/claude-code/installer.js';
 /**
@@ -42,6 +42,22 @@ export function shadowSeedDir(bareName, installedDir) {
         return sourceDir;
     return installedDir ?? sourceDir;
 }
+/**
+ * D-WORKFLOW-SHADOW-REFUSAL: why `devflow skills shadow <name>` refuses a workflow that ships as a
+ * skill folder, or null for any other name.
+ *
+ * A folder installs from the build tree of the machine's exact variant key, with no source
+ * directory to copy and no shadow to overlay, so a shadow of its name could never apply. Refusing
+ * at the command says so before the user edits a copy that does nothing; the install ignores a
+ * shadow that is already there, with a warning, and keeps it.
+ *
+ * @param folderWorkflows - The target-layer set; the default is the real set.
+ */
+export function workflowFolderShadowRefusal(bareName, folderWorkflows = WORKFLOW_FOLDER_NAMES) {
+    if (!folderWorkflows.has(bareName))
+        return null;
+    return `${bareName} ships as a skill folder built for the machine's variant, so a shadow cannot replace it. Nothing was shadowed.`;
+}
 /**
  * Check if a skill has a shadow (personal override).
  */
@@ -85,16 +101,19 @@ function buildSkillShadowTag(shadowState) {
         }
     }
 }
-export const skillsCommand = new Command('skills')
-    .description('Manage skill overrides (shadow/unshadow/list)')
-    .argument('<action>', 'Action: shadow, unshadow, or list')
-    .argument('[name]', 'Skill name (required for shadow/unshadow)')
-    .action(async (action, name) => {
+/**
+ * Run one `devflow skills` action: shadow, unshadow or list.
+ *
+ * @param folderWorkflows - The workflows that ship as skill folders; the default is the real
+ *   set. They count as known skills, `shadow` refuses them, and `list` tags a leftover shadow
+ *   of one as ignored. Tests pass a fixture set, because the real set is empty.
+ */
+export async function runSkillsAction(action, name, folderWorkflows = WORKFLOW_FOLDER_NAMES) {
     const devflowDir = getDevFlowDirectory();
     const claudeDir = getClaudeDirectory();
     // Union FEATURE_OWNED_SKILLS (compliance) so shadow/unshadow/list cover feature-managed
     // skills that left the plugin registry but still live in src/assets/skills/ (step 1.5).
-    const allSkills = [...getAllSkillNames(), ...FEATURE_OWNED_SKILLS];
+    const allSkills = [...getAllSkillNames(folderWorkflows), ...FEATURE_OWNED_SKILLS];
     if (action === 'shadow') {
         if (!name) {
             p.log.error('Skill name required. Usage: devflow skills shadow <name>');
@@ -103,6 +122,11 @@ export const skillsCommand = new Command('skills')
         }
         // Accept both bare and prefixed input
         const bareName = unprefixSkillName(name);
+        const refusal = workflowFolderShadowRefusal(bareName, folderWorkflows);
+        if (refusal !== null) {
+            p.log.error(refusal);
+            process.exit(1);
+        }
         if (!allSkills.includes(bareName)) {
             p.log.error(`Unknown skill: ${bareName}`);
             p.log.info(`Available skills: ${allSkills.join(', ')}`);
@@ -183,7 +207,11 @@ export const skillsCommand = new Command('skills')
             const provenance = installed
                 ? color.dim(`installed because: ${describeOwners(skill, ownersBySkill.get(skill))}`)
                 : color.dim(`not installed — provided by: ${describeOwners(skill, ownersBySkill.get(skill))}`);
-            return `  ${color.cyan(skill.padEnd(28))} ${buildSkillShadowTag(shadowState).padEnd(20)} ${provenance}`;
+            // A shadow of a skill folder is kept but never applied (D-WORKFLOW-SHADOW-REFUSAL).
+            const tag = workflowFolderShadowRefusal(skill, folderWorkflows) !== null && shadowState !== 'none'
+                ? color.yellow('shadow ignored — skill folder')
+                : buildSkillShadowTag(shadowState);
+            return `  ${color.cyan(skill.padEnd(28))} ${tag.padEnd(20)} ${provenance}`;
         });
         // Orphan shadows: in ~/.devflow/skills/ but not a known skill
         for (const dirName of shadowDirNames) {
@@ -200,5 +228,10 @@ export const skillsCommand = new Command('skills')
         p.log.info('Usage: devflow skills <shadow|unshadow|list> [name]');
         process.exit(1);
     }
-});
+}
+export const skillsCommand = new Command('skills')
+    .description('Manage skill overrides (shadow/unshadow/list)')
+    .argument('<action>', 'Action: shadow, unshadow, or list')
+    .argument('[name]', 'Skill name (required for shadow/unshadow)')
+    .action((action, name) => runSkillsAction(action, name));
 //# sourceMappingURL=skills.js.map

package/dist/cli/commands/tracker.js

@@ -56,12 +56,18 @@ export async function readTrackerProvenance(devflowDir, provider) {
  * every install carries them all (D-INSTALL-ALL-PROVIDERS) — rather than listing
  * the directory: the question a user asks `--status` is "can the agent load what
  * it is told to load?", and a stray file in the tree is not an answer to it.
+ *
+ * `compliance` is the machine's compliance switch, read from the install manifest by the
+ * caller and never from a repository file: a compliance-off machine installs the compliance-off
+ * manifest, which holds fewer references, so counting against the compliance-on one would read
+ * every such machine as damaged.
+ *
  * Never throws.
  */
-export async function readTrackerMechanics(claudeDir) {
+export async function readTrackerMechanics(claudeDir, compliance) {
     const root = path.join(claudeDir, 'skills', prefixSkillName(SKILL_REFS_SKILL_NAME), 'references');
     let present = 0;
-    for (const rel of installedReferenceManifest()) {
+    for (const rel of installedReferenceManifest({ compliance })) {
         try {
             await fs.access(path.join(root, ...rel.split('/')));
             present++;
@@ -292,7 +298,7 @@ export const trackerCommand = new Command('tracker')
         const selection = repoTrackerSelection(settingsModule, { dir: process.cwd() });
         const effective = selection?.provider ?? current.provider;
         const conventions = await readTrackerStatusConventions(devflowDir, effective);
-        const mechanics = await readTrackerMechanics(getClaudeDirectory());
+        const mechanics = await readTrackerMechanics(getClaudeDirectory(), manifest.features.compliance.enabled);
         // [D-F] Inspecting the status re-arms the attempt counters. --status is
         // the command a capped user reaches for to find out why nothing is being
         // learned, so it is the command that has to hand back another five