devflow-kit 3.8.0 → 3.10.0

package/dist/cli/commands/memory.js

@@ -8,8 +8,11 @@ import { writeSettingsFileAtomic } from '../../core/fs-atomic.js';
 import { discoverProjectGitRoots } from '../../targets/claude-code/post-install.js';
 import { getGitRoot } from '../../core/git.js';
 import { firstSymbolicLink } from '../../core/linked-path.js';
+import { pooled } from '../../core/pool.js';
 import { getMemoryDir, getPendingTurnsPath, getPendingTurnsProcessingPath, } from '../../core/project-paths.js';
 import { drainQueueFiles, formatRefusedDrain } from '../../core/queue-drain.js';
+import { AREA_PAUSE_NOTICE } from '../../core/area-pause-notice.js';
+import { probeTrackedArea } from '../../core/tracked-areas.js';
 import { HOOKS_DIR_SUFFIX, devflowHookOwner, endsWithAny, ensureHook, hasHook, removeHooks, runHookCommand, runHookSuffix, } from '../../targets/claude-code/hooks.js';
 import { readMachineFeature, writeMachineFeature } from '../../core/feature-switch.js';
 import { loadSettingsModule, narrowedSwitchLabel, personalConfigTrackedWarning } from '../../core/evidence-policy.js';
@@ -159,21 +162,42 @@ export function convergeMemoryHooks(settingsJson, enabled, devflowDir) {
     const cleaned = removeMemoryHooks(settingsJson);
     return enabled ? addMemoryHooks(cleaned, devflowDir) : cleaned;
 }
+/**
+ * Why the memory area at `projectRoot` is paused, or null when git tracks nothing in the
+ * memory folder there. The area is paused when git tracks files in the memory folder, or
+ * a `.git` entry stands and git did not answer (`unknown`); a root with no `.git` entry
+ * makes no git call. The root is the checkout's toplevel, where the memory hooks work.
+ */
+async function memoryPauseReason(projectRoot) {
+    const { answer } = await probeTrackedArea(projectRoot, 'memory');
+    return answer === 'untracked' ? null : answer;
+}
 /**
  * Drain a project's pending memory queue (and a claimed batch) so stale turns
  * are not processed when memory is next switched on. Shared by `devflow init
- * --no-memory` and `devflow memory --disable`. Refused, deleting nothing, when
- * `.devflow` or `.devflow/memory` under `projectRoot` is a symbolic link
- * (D-CLI-NO-SYMLINK). ENOENT-tolerant; any other error propagates to the command
- * boundary, like drainCurationQueue.
+ * --no-memory` and `devflow memory --disable`. Deletes nothing, and answers
+ * `skipped`, when git tracks files in the memory folder or a `.git` entry stands and
+ * git does not answer: a folder that git tracks is the repository's content. Refused,
+ * deleting nothing, when `.devflow` or `.devflow/memory` under `projectRoot` is a
+ * symbolic link (D-CLI-NO-SYMLINK). ENOENT-tolerant; any other error propagates to the
+ * command boundary, like drainCurationQueue.
  */
 export async function drainMemoryQueue(projectRoot) {
+    const skipped = await memoryPauseReason(projectRoot);
+    if (skipped !== null)
+        return { drained: false, skipped };
     const memoryDir = getMemoryDir(projectRoot);
     return drainQueueFiles([path.dirname(memoryDir), memoryDir], [
         getPendingTurnsPath(projectRoot),
         getPendingTurnsProcessingPath(projectRoot),
     ]);
 }
+/** The line a caller prints for a memory drain that deleted nothing: the fixed notice of a paused area, or the refusal at a link. */
+export function formatMemoryNotDrained(drain) {
+    if (!('skipped' in drain))
+        return formatRefusedDrain('memory', drain.linkedFolder);
+    return `The memory queue was not drained. ${AREA_PAUSE_NOTICE.memory[drain.skipped]}`;
+}
 /**
  * Returns true if the given project root contains a `.devflow/memory/` directory.
  * Treats unexpected errors (e.g. EACCES) as absent to avoid false positives.
@@ -200,15 +224,23 @@ export async function filterProjectsWithMemory(gitRoots) {
     const checks = await Promise.all(gitRoots.map(async (root) => ({ root, has: await hasMemoryDir(root) })));
     return checks.filter((c) => c.has).map((c) => c.root);
 }
+/** At most this many projects are checked and cleaned at once, so `memory --clear` starts few git processes. */
+export const CLEAN_QUEUE_POOL_LIMIT = 8;
 /**
  * Clean up memory queue files from the given project paths.
  * Skips projects where the background updater lock is held to avoid data loss,
- * and refuses, deleting nothing there, a project whose `.devflow` or
- * `.devflow/memory` is a symbolic link (D-CLI-NO-SYMLINK); `refused` names each
- * such link. Returns the count of projects from which at least one file was removed.
+ * leaves a project whose memory area is paused alone (git tracks files in the memory
+ * folder, or a `.git` entry stands and git did not answer; `paused` names each such
+ * project with the reason), and refuses, deleting nothing there, a project whose
+ * `.devflow` or `.devflow/memory` is a symbolic link (D-CLI-NO-SYMLINK); `refused` names
+ * each such link. At most {@link CLEAN_QUEUE_POOL_LIMIT} projects are handled at once.
+ * Returns the count of projects from which at least one file was removed.
  */
 export async function cleanQueueFiles(projectPaths) {
-    const results = await Promise.all(projectPaths.map(async (project) => {
+    const settled = await pooled(projectPaths, CLEAN_QUEUE_POOL_LIMIT, async (project) => {
+        const reason = await memoryPauseReason(project);
+        if (reason !== null)
+            return { paused: reason, project };
         const memDir = getMemoryDir(project);
         let linkedFolder;
         try {
@@ -234,10 +266,16 @@ export async function cleanQueueFiles(projectPaths) {
             fs.unlink(getPendingTurnsProcessingPath(project)).then(() => true).catch(() => false),
         ]);
         return (q || pr) ? { cleaned: project } : null;
-    }));
+    });
+    const results = settled.map((entry) => {
+        if (entry.status === 'rejected')
+            throw entry.reason;
+        return entry.value;
+    });
     const cleanedProjects = results.flatMap((r) => (r !== null && 'cleaned' in r ? [r.cleaned] : []));
     const refused = results.flatMap((r) => (r !== null && 'refused' in r ? [r.refused] : []));
-    return { cleaned: cleanedProjects.length, projects: cleanedProjects, refused };
+    const paused = results.flatMap((r) => (r !== null && 'paused' in r ? [{ project: r.project, reason: r.paused }] : []));
+    return { cleaned: cleanedProjects.length, projects: cleanedProjects, refused, paused };
 }
 export const memoryCommand = new Command('memory')
     .description('Enable, disable, or clean up working memory (session context preservation)')
@@ -297,10 +335,13 @@ export const memoryCommand = new Command('memory')
             }
             targets = scope === 'local' && currentProject ? [currentProject] : allProjects;
         }
-        const { cleaned, projects: cleanedProjects, refused } = await cleanQueueFiles(targets);
+        const { cleaned, projects: cleanedProjects, refused, paused } = await cleanQueueFiles(targets);
         for (const project of cleanedProjects) {
             p.log.info(color.dim(`Cleaned: ${project}`));
         }
+        for (const { project, reason } of paused) {
+            p.log.warn(`The memory queue of ${project} was not cleaned. ${AREA_PAUSE_NOTICE.memory[reason]}`);
+        }
         for (const linkedFolder of refused) {
             p.log.warn(formatRefusedDrain('memory', linkedFolder));
         }
@@ -340,6 +381,12 @@ export const memoryCommand = new Command('memory')
         const narrowed = enabled ? narrowedSwitchLabel(settingsModule, { dir: process.cwd() }, 'memory') : null;
         if (narrowed !== null)
             p.log.info(`Effective here: ${color.yellow(narrowed)}`);
+        // A paused memory area (git tracks files in the memory folder, or did not answer):
+        // the fixed notice, from the checkout's toplevel, where the memory hooks work. The
+        // current directory stands in outside a git work tree, as it does for the settings line.
+        const paused = await memoryPauseReason((await getGitRoot()) ?? process.cwd());
+        if (paused !== null)
+            p.log.info(AREA_PAUSE_NOTICE.memory[paused]);
         const trackedWarning = personalConfigTrackedWarning(settingsModule, { dir: process.cwd() });
         if (trackedWarning !== null)
             p.log.warn(trackedWarning);
@@ -380,7 +427,7 @@ export const memoryCommand = new Command('memory')
     if (gitRoot) {
         const drain = await drainMemoryQueue(gitRoot);
         if (!drain.drained)
-            p.log.warn(formatRefusedDrain('memory', drain.linkedFolder));
+            p.log.warn(formatMemoryNotDrained(drain));
     }
     p.log.success('Working memory disabled in every project');
 });

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