devflow-kit 3.9.0 → 3.11.0

package/dist/core/orphan-sweep.js

@@ -53,6 +53,16 @@ export function mdEntryName(entry) {
  *   For agents and commands: use {@link mdEntryName}.
  *   For skills: strip the devflow: prefix.
  *
+ * @param mayRemove - Optional check made on the full path of each orphan before
+ *   it is removed. An orphan it refuses stays where it is and is neither
+ *   removed nor failed; the check reports the refusal itself. The caller proves
+ *   that `dir` is a real folder before the call, because the sweep reads and
+ *   removes inside whatever `dir` names.
+ *
+ * @param removal - How an admitted orphan is removed ({@link SweepRemoval}). Defaults to
+ *   `recursive`. With `unlink`, an entry that has become a folder since the check stays and is
+ *   recorded in `failed`; an entry that has vanished since the check counts as removed.
+ *
  * @returns A {@link SweepResult} reporting how many entries were scanned, which
  *   registry names were removed, and which removals failed.
  *   `scanned` is the count matched by the predicate (not the removed count) —
@@ -64,7 +74,7 @@ export function mdEntryName(entry) {
  * individual removal is recorded in `failed` without aborting the sweep.
  * Never writes, only removes — no delete-then-write window.
  */
-export async function sweepOrphanedAssets(dir, knownNames, extractRegistryName) {
+export async function sweepOrphanedAssets(dir, knownNames, extractRegistryName, mayRemove, removal = 'recursive') {
     const removed = [];
     const failed = [];
     let scanned = 0;
@@ -76,8 +86,11 @@ export async function sweepOrphanedAssets(dir, knownNames, extractRegistryName)
                 continue;
             scanned++;
             if (!knownNames.has(registryName)) {
+                const entryPath = path.join(dir, entry);
                 try {
-                    await fs.rm(path.join(dir, entry), { recursive: true, force: true });
+                    if (mayRemove !== undefined && !(await mayRemove(entryPath)))
+                        continue;
+                    await removeEntry(entryPath, removal);
                     removed.push(registryName);
                 }
                 catch (err) {
@@ -89,4 +102,18 @@ export async function sweepOrphanedAssets(dir, knownNames, extractRegistryName)
     catch { /* directory absent or unreadable — not an error */ }
     return { scanned, removed, failed };
 }
+/** Remove one orphan as `removal` says. An absent entry is already removed, as `fs.rm` with `force` treats it. */
+async function removeEntry(entryPath, removal) {
+    if (removal === 'recursive') {
+        await fs.rm(entryPath, { recursive: true, force: true });
+        return;
+    }
+    try {
+        await fs.unlink(entryPath);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+}
 //# sourceMappingURL=orphan-sweep.js.map

package/dist/core/path-set.js

@@ -0,0 +1,15 @@
+/** Build a {@link PathSet} from file paths: the folder prefixes are computed once. */
+export function createPathSet(files) {
+    const all = new Set(files);
+    const folders = new Set();
+    for (const file of all) {
+        for (let cut = file.indexOf('/'); cut !== -1; cut = file.indexOf('/', cut + 1)) {
+            folders.add(file.slice(0, cut));
+        }
+    }
+    return Object.freeze({
+        files: all,
+        holds: (folder) => all.has(folder) || folders.has(folder),
+    });
+}
+//# sourceMappingURL=path-set.js.map

package/dist/core/plugins.js

@@ -1,6 +1,7 @@
 /**
  * Shared plugin registry — single source of truth for all CLI commands.
  */
+import { WORKFLOW_FOLDERS } from './mds-variants.js';
 /**
  * Namespace prefix for Devflow skills installed to ~/.claude/skills/.
  * Skills are installed as `devflow:{skill-name}` to avoid collisions with
@@ -431,6 +432,18 @@ export const LEGACY_PLUGIN_NAMES = {
     'devflow-frontend-design': 'devflow-ui-design',
     'devflow-specify': 'devflow-plan',
 };
+/**
+ * The registered plugins that `names` select: each legacy name mapped to its current plugin, and every name
+ * the registry does not have dropped. Order and repeats are kept.
+ *
+ * `names` is often file content (a manifest record), so only a name that LEGACY_PLUGIN_NAMES owns maps; a
+ * key the table inherits from Object, such as `constructor`, is an unknown name like any other.
+ */
+export function registeredPluginNames(names) {
+    return names
+        .map(name => (Object.hasOwn(LEGACY_PLUGIN_NAMES, name) ? LEGACY_PLUGIN_NAMES[name] : name))
+        .filter(name => DEVFLOW_PLUGINS.some(plugin => plugin.name === name));
+}
 /**
  * Plugin names that have been deleted from the registry.
  * Used during init to prune stale entries from users' manifests on partial
@@ -489,7 +502,7 @@ export const FEATURE_OWNED_RULES = ['compliance', 'behavior'];
  * stays OWNED and REQUIRED by its plugins in the registry — the closure guard
  * reasons over the curation-on variant, the superset — and the install drops it
  * on top of the selection: `installViaFileCopy` skips it when `curation` is false
- * and `convergeCurationVariants` installs or removes it when the switch flips.
+ * and `convergeVariantAxes` installs or removes it when the switch flips.
  *
  * This is a machine-switch condition, not a deselection: the plan
  * ({@link resolveSkillInstallPlan}) is untouched, so a curation-off machine never
@@ -498,7 +511,7 @@ export const FEATURE_OWNED_RULES = ['compliance', 'behavior'];
  *
  * Used by:
  *   - installer.ts installViaFileCopy: omits these from the install loop when curation is off
- *   - curation-install.ts convergeCurationVariants: installs or removes the directory
+ *   - curation-install.ts convergeVariantAxes: installs or removes the directory
  *   - tests: independent literal ['apply-decisions'] (avoids the EXCLUDED-as-oracle trap)
  */
 export const CURATION_GATED_SKILLS = ['apply-decisions'];
@@ -627,35 +640,71 @@ export function parsePluginSelection(input, validPlugins) {
 /**
  * Deprecated command names from old installations.
  * Used during init to clean up stale command files on upgrade.
+ *
+ * Each name is a command file that a release installed. The cleanup removes such a file with no
+ * backup, so a name that no release shipped does not belong here.
  */
 export const LEGACY_COMMAND_NAMES = [
-    'review',
     'specify',
-    'specify-teams',
 ];
+/** A command entry of a plugin without its leading `/`. */
+function commandName(cmd) {
+    return cmd.startsWith('/') ? cmd.slice(1) : cmd;
+}
+/** The set of the folders in a registry; tests pass a fixture registry to get a fixture set. */
+export function workflowFolderNames(folders) {
+    return new Set(folders.map(folder => folder.name));
+}
+/** The real set: empty until a workflow is registered as a folder. */
+export const WORKFLOW_FOLDER_NAMES = workflowFolderNames(WORKFLOW_FOLDERS);
+/**
+ * The folder workflows that some plugin of `plugins` owns as a command. A plugin that
+ * declares `/name` for a name in the set owns the folder `devflow:name`.
+ */
+export function selectedWorkflowFolders(plugins, folderWorkflows = WORKFLOW_FOLDER_NAMES) {
+    const selected = new Set();
+    for (const plugin of plugins) {
+        for (const cmd of plugin.commands) {
+            const name = commandName(cmd);
+            if (folderWorkflows.has(name))
+                selected.add(name);
+        }
+    }
+    return selected;
+}
 /**
  * Derive unique command names (without leading /) from all plugins.
  * Returns one entry per distinct command, preserving DEVFLOW_PLUGINS declaration order.
+ *
+ * A workflow in `folderWorkflows` is not a command file, so it is left out: the
+ * command sweeps then treat a stale command file of a folder workflow as an orphan.
  */
-export function getAllCommandNames() {
+export function getAllCommandNames(folderWorkflows = WORKFLOW_FOLDER_NAMES) {
     const commands = new Set();
     for (const plugin of DEVFLOW_PLUGINS) {
         for (const cmd of plugin.commands) {
-            commands.add(cmd.startsWith('/') ? cmd.slice(1) : cmd);
+            const name = commandName(cmd);
+            if (!folderWorkflows.has(name))
+                commands.add(name);
         }
     }
     return [...commands];
 }
 /**
  * Derive unique skill names from all plugins.
+ *
+ * The folders of `folderWorkflows` install as `devflow:<name>`, so they join the names
+ * the skill sweeps treat as known.
  */
-export function getAllSkillNames() {
+export function getAllSkillNames(folderWorkflows = WORKFLOW_FOLDER_NAMES) {
     const skills = new Set();
     for (const plugin of DEVFLOW_PLUGINS) {
         for (const skill of plugin.skills) {
             skills.add(skill);
         }
     }
+    for (const name of folderWorkflows)
+        skills.add(name);
     return [...skills];
 }
 /**
@@ -804,8 +853,10 @@ export function buildFullSkillsMap() {
  * nothing, and is reported so the user can tell "inert" from "ignored".
  */
 export function resolveSkillInstallPlan(input) {
+    const folderWorkflows = input.folderWorkflows ?? WORKFLOW_FOLDER_NAMES;
     const install = skillsOf(input.effectivePlugins);
     const remove = new Set();
+    const removeFolders = new Set();
     if (!input.isPartialInstall) {
         for (const skill of skillsOf(DEVFLOW_PLUGINS)) {
             if (install.has(skill))
@@ -814,11 +865,18 @@ export function resolveSkillInstallPlan(input) {
                 continue;
             remove.add(skill);
         }
+        const ownedFolders = selectedWorkflowFolders(input.effectivePlugins, folderWorkflows);
+        for (const name of folderWorkflows) {
+            if (!ownedFolders.has(name))
+                removeFolders.add(name);
+        }
     }
-    const dormantShadows = [...new Set(input.shadowedSkills)]
-        .filter(skill => !install.has(skill))
+    const shadowed = [...new Set(input.shadowedSkills)];
+    const dormantShadows = shadowed
+        .filter(skill => !install.has(skill) && !folderWorkflows.has(skill))
         .sort();
-    return { install, remove, dormantShadows };
+    const ignoredFolderShadows = shadowed.filter(skill => folderWorkflows.has(skill)).sort();
+    return { install, remove, dormantShadows, removeFolders, ignoredFolderShadows };
 }
 /**
  * Derive unique rule names from all plugins.

package/dist/core/reference-sweep.js

@@ -14,7 +14,9 @@ import * as path from 'path';
  * two providers may legitimately both carry a `comment.md`, so the registry name has to
  * be the relative PATH, and the walk has to descend.
  *
- * Never writes, only removes — no delete-then-write window.
+ * Never writes. The sweep names what stays and what goes; a {@link ReferenceSweepDelegate}
+ * acts on every entry the manifest does not name, and the sweep itself never removes a
+ * folder recursively. No delete-then-write window.
  */
 /**
  * Descent bound for every walk over the generated reference tree — this sweep and the
@@ -42,24 +44,27 @@ export const MAX_REFERENCE_SWEEP_DEPTH = 8;
  * @param root - Directory to converge (the installed `references/tracker/` tree).
  * @param knownRelPaths - POSIX paths relative to `root` that must survive. Derived from
  *   the build's own module registries by the caller — never hand-listed.
+ * @param delegate - Acts on every entry the manifest does not name. Required: a sweep with
+ *   no delegate would have to delete what it cannot name.
  *
  * @returns A {@link SweepResult} whose `removed` entries are POSIX relative paths. A
- *   directory into which no manifest path descends is removed WHOLE and reported by its
- *   own relative path — leaving it empty would be a convergence that stops one step
- *   short, and an empty provider directory is indistinguishable from a provider whose
- *   references failed to install. A subtree left unswept because it breached
+ *   directory into which no manifest path descends is handed to the delegate WHOLE and
+ *   reported by its own relative path once the delegate removed it — leaving it empty
+ *   would be a convergence that stops one step short, and an empty provider directory is
+ *   indistinguishable from a provider whose references failed to install. A subtree left
+ *   unswept because it breached
  *   {@link MAX_REFERENCE_SWEEP_DEPTH} is reported in `failed` under its own relative
  *   path, for the same reason: everything this sweep did not converge is named.
  *
  * A missing or unreadable `root` is a no-op, not an error: the overlay creates the tree
  * it converges, so an absent one simply means there is nothing to prune yet.
  */
-export async function sweepOrphanedReferences(root, knownRelPaths) {
+export async function sweepOrphanedReferences(root, knownRelPaths, delegate) {
     const acc = { scanned: 0, removed: [], failed: [] };
-    await sweepDirectory(root, '', 0, knownRelPaths, directoryPrefixes(knownRelPaths), acc);
+    await sweepDirectory(root, '', 0, knownRelPaths, directoryPrefixes(knownRelPaths), delegate, acc);
     return { scanned: acc.scanned, removed: acc.removed, failed: acc.failed };
 }
-async function sweepDirectory(dir, prefix, depth, known, knownDirPrefixes, acc) {
+async function sweepDirectory(dir, prefix, depth, known, knownDirPrefixes, delegate, acc) {
     if (depth > MAX_REFERENCE_SWEEP_DEPTH) {
         // A breached bound means this subtree is never visited, so any orphan inside it
         // survives. Report it through the same channel as a failed removal: a silent return
@@ -82,35 +87,47 @@ async function sweepDirectory(dir, prefix, depth, known, knownDirPrefixes, acc)
         const relPath = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
         const fullPath = path.join(dir, entry.name);
         // A real subdirectory is either an ancestor of something the manifest names — in
-        // which case descend — or dead weight, in which case take the whole subtree.
-        // isDirectory() is false for a symlink-to-dir, so a planted link is treated as a
-        // leaf and removed rather than followed.
+        // which case descend — or dead weight, in which case the delegate takes the whole
+        // subtree. isDirectory() is false for a symlink-to-dir, so a planted link is treated
+        // as a leaf and handed over rather than followed.
         if (entry.isDirectory()) {
             if (knownDirPrefixes.has(`${relPath}/`)) {
-                await sweepDirectory(fullPath, relPath, depth + 1, known, knownDirPrefixes, acc);
+                await sweepDirectory(fullPath, relPath, depth + 1, known, knownDirPrefixes, delegate, acc);
                 continue;
             }
             acc.scanned++;
-            try {
-                await fs.rm(fullPath, { recursive: true, force: true });
-                acc.removed.push(relPath);
-            }
-            catch (err) {
-                acc.failed.push({ name: relPath, error: err }); /* per-item isolation */
-            }
+            await dispose(fullPath, relPath, true, delegate, acc);
             continue;
         }
         acc.scanned++;
         if (known.has(relPath))
             continue;
-        try {
-            await fs.rm(fullPath, { force: true });
-            acc.removed.push(relPath);
-        }
-        catch (err) {
-            acc.failed.push({ name: relPath, error: err }); /* per-item isolation */
+        await dispose(fullPath, relPath, false, delegate, acc);
+    }
+}
+/** Hand one entry to the delegate and record the outcome; a throw from the delegate is a per-item failure. */
+async function dispose(fullPath, relPath, isDirectory, delegate, acc) {
+    try {
+        const disposition = await delegate.dispose(fullPath, isDirectory);
+        switch (disposition.outcome) {
+            case 'removed':
+                acc.removed.push(relPath);
+                break;
+            case 'failed':
+                acc.failed.push({ name: relPath, error: disposition.error });
+                break;
+            case 'moved':
+            case 'kept':
+                break;
+            default: {
+                const _exhaustive = disposition;
+                void _exhaustive;
+            }
         }
     }
+    catch (err) {
+        acc.failed.push({ name: relPath, error: err }); /* per-item isolation */
+    }
 }
 /**
  * Every directory prefix some manifest path sits under, trailing slash included:

package/dist/core/retired-shipped-names.js

@@ -0,0 +1,278 @@
+import { createPathSet } from './path-set.js';
+const names = (list) => Object.freeze([...list]);
+export const RETIRED_SHIPPED = Object.freeze({
+    commands: names([
+        'ambient',
+        'audit-claude',
+        'brainstorm',
+        'breakdown',
+        'catch-up',
+        'commit',
+        'design',
+        'devlog',
+        'get-issue',
+        'plan-next-steps',
+        'pre-commit',
+        'pre-pr',
+        'pull-request',
+        'resolve-comments',
+        'specify',
+    ]),
+    agents: names([
+        'audit-architecture',
+        'audit-complexity',
+        'audit-database',
+        'audit-dependencies',
+        'audit-documentation',
+        'audit-performance',
+        'audit-security',
+        'audit-tests',
+        'audit-typescript',
+        'brainstorm',
+        'catch-up',
+        'claude-md-auditor',
+        'code-edit',
+        'code-fix',
+        'code-review',
+        'coder',
+        'commit',
+        'diagnose',
+        'get-issue',
+        'learning',
+        'pr-comments',
+        'project-state',
+        'pull-request',
+        'release',
+        'resolver',
+        'reviewer',
+        'scrutinize',
+        'scrutinizer',
+        'shepherd',
+        'simplifier',
+        'simplify',
+        'skimmer',
+        'synthesizer',
+        'tech-debt',
+        'validator',
+    ]),
+    rules: names([]),
+    skills: names([
+        'accessibility',
+        'agent-teams',
+        'ambient-router',
+        'apply-feature-kb',
+        'apply-knowledge',
+        'architecture-patterns',
+        'code-smell',
+        'codebase-navigation',
+        'commit',
+        'complexity-patterns',
+        'consistency-patterns',
+        'core-patterns',
+        'database-patterns',
+        'debug',
+        'debug-orchestration',
+        'debug:guided',
+        'debug:orch',
+        'debug:triage',
+        'decisions-format',
+        'dependencies-patterns',
+        'devflow',
+        'devflow-accessibility',
+        'devflow-agent-teams',
+        'devflow-architecture-patterns',
+        'devflow-code-smell',
+        'devflow-codebase-navigation',
+        'devflow-commit',
+        'devflow-complexity-patterns',
+        'devflow-consistency-patterns',
+        'devflow-core-patterns',
+        'devflow-database-patterns',
+        'devflow-debug',
+        'devflow-dependencies-patterns',
+        'devflow-docs-framework',
+        'devflow-documentation-patterns',
+        'devflow-error-handling',
+        'devflow-frontend-design',
+        'devflow-git-safety',
+        'devflow-git-workflow',
+        'devflow-github-patterns',
+        'devflow-implementation-patterns',
+        'devflow-input-validation',
+        'devflow-pattern-check',
+        'devflow-performance-patterns',
+        'devflow-pull-request',
+        'devflow-react',
+        'devflow-regression-patterns',
+        'devflow-review-methodology',
+        'devflow-security-patterns',
+        'devflow-self-review',
+        'devflow-test-design',
+        'devflow-tests-patterns',
+        'devflow-typescript',
+        'devflow:agent-teams',
+        'devflow:ambient-router',
+        'devflow:apply-feature-kb',
+        'devflow:apply-knowledge',
+        'devflow:architecture-patterns',
+        'devflow:complexity-patterns',
+        'devflow:consistency-patterns',
+        'devflow:core-patterns',
+        'devflow:database-patterns',
+        'devflow:debug',
+        'devflow:debug-orchestration',
+        'devflow:debug:guided',
+        'devflow:debug:orch',
+        'devflow:debug:triage',
+        'devflow:dependencies-patterns',
+        'devflow:documentation-patterns',
+        'devflow:dream-curation',
+        'devflow:dream-decisions',
+        'devflow:dream-knowledge',
+        'devflow:dream-memory',
+        'devflow:explore',
+        'devflow:explore:guided',
+        'devflow:explore:orch',
+        'devflow:explore:triage',
+        'devflow:feature-kb',
+        'devflow:frontend-design',
+        'devflow:git-safety',
+        'devflow:git-workflow',
+        'devflow:github-patterns',
+        'devflow:implement',
+        'devflow:implement:guided',
+        'devflow:implement:orch',
+        'devflow:implement:triage',
+        'devflow:implementation-orchestration',
+        'devflow:implementation-patterns',
+        'devflow:input-validation',
+        'devflow:knowledge-persistence',
+        'devflow:performance-patterns',
+        'devflow:pipeline',
+        'devflow:pipeline-orchestration',
+        'devflow:pipeline:orch',
+        'devflow:plan',
+        'devflow:plan-orchestration',
+        'devflow:plan:guided',
+        'devflow:plan:orch',
+        'devflow:plan:triage',
+        'devflow:regression-patterns',
+        'devflow:release:guided',
+        'devflow:release:orch',
+        'devflow:release:triage',
+        'devflow:research',
+        'devflow:research:guided',
+        'devflow:research:orch',
+        'devflow:research:triage',
+        'devflow:resolve',
+        'devflow:resolve-orchestration',
+        'devflow:resolve:orch',
+        'devflow:review',
+        'devflow:review-orchestration',
+        'devflow:review:guided',
+        'devflow:review:orch',
+        'devflow:review:triage',
+        'devflow:router',
+        'devflow:search-first',
+        'devflow:security-patterns',
+        'devflow:self-review',
+        'devflow:sidecar',
+        'devflow:test-patterns',
+        'docs-framework',
+        'documentation-patterns',
+        'dream-curation',
+        'dream-decisions',
+        'dream-knowledge',
+        'dream-memory',
+        'error-handling',
+        'explore',
+        'explore:guided',
+        'explore:orch',
+        'explore:triage',
+        'feature-kb',
+        'frontend-design',
+        'git-safety',
+        'git-workflow',
+        'github-patterns',
+        'go',
+        'implement',
+        'implement:guided',
+        'implement:orch',
+        'implement:triage',
+        'implementation-orchestration',
+        'implementation-patterns',
+        'input-validation',
+        'java',
+        'knowledge-persistence',
+        'pattern-check',
+        'performance-patterns',
+        'pipeline',
+        'pipeline-orchestration',
+        'pipeline:orch',
+        'plan',
+        'plan-orchestration',
+        'plan:guided',
+        'plan:orch',
+        'plan:triage',
+        'pull-request',
+        'python',
+        'react',
+        'regression-patterns',
+        'release:guided',
+        'release:orch',
+        'release:triage',
+        'research',
+        'research:guided',
+        'research:orch',
+        'research:triage',
+        'resolve',
+        'resolve-orchestration',
+        'resolve:orch',
+        'review',
+        'review-methodology',
+        'review-orchestration',
+        'review:guided',
+        'review:orch',
+        'review:triage',
+        'router',
+        'rust',
+        'search-first',
+        'security-patterns',
+        'self-review',
+        'sidecar',
+        'test-design',
+        'test-driven-development',
+        'test-patterns',
+        'tests-patterns',
+        'typescript',
+        'worktree-support',
+    ]),
+    skillFiles: Object.freeze({
+        'devflow:agent-references': names([
+            'references/learning/maintain.md',
+        ]),
+        'devflow:git': names([
+            'references/pr/ensure-pr-ready.md',
+        ]),
+    }),
+});
+/**
+ * The files of {@link RETIRED_SHIPPED} as paths relative to the Claude dir: the command, agent and
+ * rule files, and the listed files of a skill folder. A skill folder of `skills` is not a path
+ * here, since the install moves it whole.
+ */
+export function retiredPathSet() {
+    const paths = [];
+    for (const name of RETIRED_SHIPPED.commands)
+        paths.push(`commands/devflow/${name}.md`);
+    for (const name of RETIRED_SHIPPED.agents)
+        paths.push(`agents/devflow/${name}.md`);
+    for (const name of RETIRED_SHIPPED.rules)
+        paths.push(`rules/devflow/${name}.md`);
+    for (const [skill, files] of Object.entries(RETIRED_SHIPPED.skillFiles)) {
+        for (const file of files)
+            paths.push(`skills/${skill}/${file}`);
+    }
+    return createPathSet(paths);
+}
+//# sourceMappingURL=retired-shipped-names.js.map