devflow-kit 3.10.0 → 3.11.0

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

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

@@ -24,8 +24,9 @@ import * as path from 'path';
 import { skillsDir, rulesDir } from '../../core/assets.js';
 import { ALWAYS_PRESENT_REFS, COMPLIANCE_FRAMEWORKS, normalizeFrameworks } from '../../core/compliance.js';
 import { parseComplianceFragment, composeComplianceSkill, composeComplianceRule } from '../../core/compliance-compose.js';
-import { validateSkillShadow, validateRuleShadow } from './installer.js';
-import { newLinkReport, refuseUnrealFolder, removeReportingLink, warnLinkReport, writeFileReplacingLink } from './linked-folder.js';
+import { swapFolderIn } from './folder-swap.js';
+import { copyDirectory, validateSkillShadow, validateRuleShadow } from './installer.js';
+import { newLinkReport, refuseUnrealFolder, warnLinkReport, writeFileReplacingLink } from './linked-folder.js';
 // ── Path helpers ───────────────────────────────────────────────────────────
 /** Every registry framework id — the reference set every install carries. */
 const ALL_FRAMEWORK_IDS = COMPLIANCE_FRAMEWORKS.map(fw => fw.id);
@@ -33,6 +34,14 @@ const ALL_FRAMEWORK_IDS = COMPLIANCE_FRAMEWORKS.map(fw => fw.id);
 function skillTarget(claudeDir) {
     return path.join(claudeDir, 'skills', 'devflow:compliance');
 }
+/** The folder the compliance skill is built in before it is renamed into place: {claudeDir}/skills/devflow:compliance.tmp */
+export function complianceSkillTempPath(claudeDir) {
+    return `${skillTarget(claudeDir)}.tmp`;
+}
+/** Where the compliance skill folder waits while the new one is renamed in: {claudeDir}/skills/devflow:compliance.old */
+export function complianceSkillAsidePath(claudeDir) {
+    return `${skillTarget(claudeDir)}.old`;
+}
 /** Installed compliance rule file: {claudeDir}/rules/devflow/compliance.md */
 function ruleTarget(claudeDir) {
     return path.join(claudeDir, 'rules', 'devflow', 'compliance.md');
@@ -93,14 +102,22 @@ async function loadComplianceFragments(canonicalSrc, frameworks, warn) {
  * `fragments` is loaded once by convergeComplianceArtifacts and shared with the rule
  * installer — the SKILL.md and the rule compose from the same parsed set.
  *
- * Build under a .tmp sibling, remove old target, rename. An old target that is a link is unlinked,
- * never followed, so what it points to is left as it was; the link is recorded in `links`.
+ * Build under a .tmp sibling, then swap it in: the old target waits in a .old sibling while the new one
+ * is renamed in. A file in the old target that devflow did not ship moves to the backup folder first;
+ * if one cannot move, nothing is swapped and the shipped files are written into the old target (see
+ * {@link swapFolderIn}). An old target that is a link is moved aside as the link itself, never
+ * followed, so what it points to is left as it was; the link is recorded in `links`.
  * Unexpected I/O failures are reported via warn; never thrown.
  */
-async function installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments, warn, links) {
+async function installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments, warn, links, backups) {
     const canonicalSrc = path.join(skillsDir(), 'compliance');
     const target = skillTarget(claudeDir);
-    const tmpTarget = `${target}.tmp`;
+    const tmpTarget = complianceSkillTempPath(claudeDir);
+    // A skills folder that is a link or not a folder is refused before anything is built: the swap
+    // would move and remove below it, in the folder the link points to. The refusal is recorded in
+    // `links`, and the converge is not clean.
+    if (await refuseUnrealFolder(links, path.dirname(target)))
+        return;
     // Determine SKILL.md source: prefer a valid shadow, else use canonical.
     const skillShadowDir = path.join(devflowDir, 'skills', 'compliance');
     const shadowState = await validateSkillShadow(skillShadowDir);
@@ -150,11 +167,18 @@ async function installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments
                 warn(`compliance: reference "${fw}.md" not installed — ${String(err)}`);
             }
         }
-        // Swap: remove old target, rename tmp into place (two calls, not atomic). The link is recorded
+        // Swap: the old target waits aside, the tmp folder is renamed into place. The link is recorded
         // once the real folder stands in its place, so the report matches its wording.
-        const unlinked = await removeReportingLink(target);
-        await fs.rename(tmpTarget, target);
-        links.replacedLinks.push(...unlinked);
+        await swapFolderIn({
+            backups,
+            target,
+            staged: tmpTarget,
+            aside: complianceSkillAsidePath(claudeDir),
+            links,
+            mergeInto: () => copyDirectory(tmpTarget, target, undefined, links),
+        });
+        // The tmp folder is gone after a swap; a merge leaves it behind.
+        await fs.rm(tmpTarget, { recursive: true, force: true });
     }
     catch (err) {
         // Clean up tmp on failure (best-effort) so no orphan is left behind.
@@ -219,7 +243,7 @@ async function installRuleFile(claudeDir, devflowDir, frameworks, fragments, war
  * principle in engineering.md.
  */
 export async function convergeComplianceArtifacts(opts) {
-    const { claudeDir, devflowDir, enabled, frameworks, rulesEnabled, warn } = opts;
+    const { claudeDir, devflowDir, enabled, frameworks, rulesEnabled, warn, backups } = opts;
     // S78: claudeDir precondition — reliability rule: assert invariants in production code.
     // An empty or relative claudeDir would make skillTarget/ruleTarget resolve to unexpected
     // locations. Warn and bail rather than running fs.rm with a potentially wrong path.
@@ -251,7 +275,7 @@ export async function convergeComplianceArtifacts(opts) {
     // installSkillDir is caught internally and reported via trackingWarn, so
     // execution always continues to the rule step.
     const links = newLinkReport();
-    await installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments, trackingWarn, links);
+    await installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments, trackingWarn, links, backups);
     // The rule folder is proven before the rule is written or removed: a link there sends both into
     // another place. The skill folder is swapped whole above, and a swap never follows a link.
     const finish = (removedPreexisting) => {
@@ -298,7 +322,7 @@ export async function convergeComplianceArtifacts(opts) {
  *   than the value stored in the manifest.
  */
 export async function convergeFromManifest(opts) {
-    const { claudeDir, devflowDir, manifest, warn, rulesEnabledOverride } = opts;
+    const { claudeDir, devflowDir, manifest, warn, rulesEnabledOverride, backups } = opts;
     return convergeComplianceArtifacts({
         claudeDir,
         devflowDir,
@@ -306,6 +330,7 @@ export async function convergeFromManifest(opts) {
         frameworks: manifest.features.compliance.frameworks,
         rulesEnabled: rulesEnabledOverride ?? manifest.features.rules,
         warn,
+        backups,
     });
 }
 //# sourceMappingURL=compliance-install.js.map

package/dist/targets/claude-code/compliance-off-files.js

@@ -148,9 +148,13 @@ async function sameBytes(a, b) {
         return false;
     }
 }
+/** The temp file beside `target` that {@link copyIntoPlace} writes through: `<target>.tmp.<pid>`. */
+export function copyTempPath(target) {
+    return `${target}.tmp.${process.pid}`;
+}
 /** Copy `source` over `target` through a sibling temp file and a rename, so no reader sees a partial file. */
 async function copyIntoPlace(source, target) {
-    const temp = `${target}.tmp.${process.pid}`;
+    const temp = copyTempPath(target);
     try {
         await fs.unlink(temp).catch((err) => {
             if (errno(err) !== 'ENOENT')