devflow-kit 3.9.0 → 3.10.0

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

@@ -0,0 +1,64 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { LEGACY_COMMAND_NAMES, LEGACY_RULE_NAMES } from '../../core/plugins.js';
+import { isUnrealFolder } from '../../targets/claude-code/linked-folder.js';
+/**
+ * Whether the sweep may remove files from `dir`: the install did not refuse it, 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, dir) {
+    return !report.refusedFolders.includes(dir) && !(await isUnrealFolder(dir));
+}
+/**
+ * Remove the files that earlier releases installed into `commands/devflow` and `rules/devflow` and
+ * that no release installs now: the legacy command and rule names, and every `*-teams.md` command.
+ * Runs on every install shape, since the full install's pre-clean covers only a full install.
+ *
+ * A folder the install refused (`report.refusedFolders`) or that is a link now is skipped whole: the
+ * sweep reads and removes nothing there, and the folder it points to is left as it is. Never throws.
+ *
+ * @param opts.legacyCommands - Legacy command names; defaults to the registry list.
+ * @param opts.legacyRules - Legacy rule names; defaults to the registry list.
+ */
+export async function sweepLegacyDevflowFiles(opts) {
+    const { claudeDir, report } = opts;
+    const legacyCommands = opts.legacyCommands ?? LEGACY_COMMAND_NAMES;
+    const legacyRules = opts.legacyRules ?? LEGACY_RULE_NAMES;
+    const result = { staleCommandsRemoved: 0, staleRulesRemoved: 0 };
+    const commandsDir = path.join(claudeDir, 'commands', 'devflow');
+    if (await mayRemoveFrom(report, commandsDir)) {
+        for (const legacy of legacyCommands) {
+            try {
+                await fs.rm(path.join(commandsDir, `${legacy}.md`));
+                result.staleCommandsRemoved++;
+            }
+            catch { /* absent — expected for most entries */ }
+        }
+        // Orphaned *-teams.md workflow command variants left by the Agent Teams refactor. None is ever
+        // re-installed, so a blanket sweep is safe on any install type.
+        try {
+            for (const entry of await fs.readdir(commandsDir)) {
+                if (!entry.endsWith('-teams.md'))
+                    continue;
+                try {
+                    await fs.rm(path.join(commandsDir, entry));
+                    result.staleCommandsRemoved++;
+                }
+                catch { /* already gone */ }
+            }
+        }
+        catch { /* commands folder absent — nothing to sweep */ }
+    }
+    const rulesDir = path.join(claudeDir, 'rules', 'devflow');
+    if (await mayRemoveFrom(report, rulesDir)) {
+        for (const legacy of legacyRules) {
+            try {
+                await fs.rm(path.join(rulesDir, `${legacy}.md`));
+                result.staleRulesRemoved++;
+            }
+            catch { /* absent — expected for most entries */ }
+        }
+    }
+    return result;
+}
+//# 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,8 @@ 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, removeReportingLink } from '../../targets/claude-code/linked-folder.js';
+import { formatLinksSummary } from './install-report.js';
 /**
  * Check whether a rule has a user shadow file at ~/.devflow/rules/{name}.md.
  */
@@ -213,17 +215,24 @@ export async function runRulesEnable(claudeDir, devflowDir) {
     }
     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 });
+    // Wipe stale rules from previously uninstalled plugins before re-installing. A rules folder that is
+    // a link is unlinked and replaced by a real folder, never emptied through, and the link is reported.
+    const links = newLinkReport();
+    links.replacedLinks.push(...await removeReportingLink(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 +248,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,7 +266,7 @@ export async function runRulesEnable(claudeDir, devflowDir) {
             claudeDir,
             devflowDir,
             manifest,
-            warn: (msg) => p.log.warn(msg),
+            warn: warnConverge,
             rulesEnabledOverride: !installFailed,
         });
     }
@@ -265,7 +282,7 @@ export async function runRulesEnable(claudeDir, devflowDir) {
             claudeDir,
             devflowDir,
             manifest,
-            warn: (msg) => p.log.warn(msg),
+            warn: warnConverge,
             rulesEnabledOverride: !installFailed,
         });
     }

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