devflow-kit 3.10.0 → 3.12.0

package/dist/targets/claude-code/legacy-skill-hashes.js

@@ -0,0 +1,170 @@
+/**
+ * The released copies of the bare legacy skills: for each bare name of the legacy skill list that a
+ * release installed as `~/.claude/skills/<name>/`, the SHA-256 (lowercase hex) of every distinct
+ * `SKILL.md` that a release installed under that name.
+ *
+ * `devflow init` moves a bare legacy folder out of the shared skills folder only when its
+ * `SKILL.md` has one of these hashes (`sweepLegacySkillFolders`), and a full `devflow uninstall`
+ * removes one only on the same check (`judgeBareLegacySkill`). The folder name alone proves
+ * nothing: a skill of the user, or of another tool, may carry a name such as `python` or `plan`.
+ * A name with no entry here was never installed bare by a release, so no folder of that name is
+ * moved.
+ *
+ * Frozen data, made on 2026-10-30. Source: the 21 published `devflow-kit` packages 0.6.1 to 1.8.3,
+ * the releases that installed bare skill folders. (0.4.0 to 0.6.0 installed one nested folder,
+ * `skills/devflow/`; 2.0.0 and later install `devflow:`-prefixed folders.) Each package was fetched
+ * with `npm pack devflow-kit@<version> --ignore-scripts` and unpacked; no package script or code
+ * ran. Every `SKILL.md` below `src/claude/skills/devflow/<name>/` (0.6.1 to 0.9.0) or
+ * `plugins/<plugin>/skills/<name>/` (1.0.0 to 1.8.3) was hashed with `shasum -a 256`. Those
+ * installers copy a skill file byte for byte, so the installed file has the hash of the packaged
+ * file. The comment on each hash gives the first and the last release that held it.
+ *
+ * The table only grows: a release cannot be un-shipped. tests/guards/legacy-skill-hashes.test.ts
+ * proves the shape of the table and its match with tests/fixtures/released-shipped-names.ts.
+ */
+const hashes = (list) => Object.freeze([...list]);
+export const BARE_LEGACY_SKILL_HASHES = Object.freeze({
+    'accessibility': hashes([
+        '06434c13344e85bf55f4fcf45e8e794ef26ad0751e7e56cac7363661e1b7b7d4', // 1.0.0 to 1.8.3
+    ]),
+    'agent-teams': hashes([
+        '75591cef45adbc36e95910e08a0db681c56401e1c95db5226afe819dde36ce0c', // 1.0.0 to 1.8.3
+    ]),
+    'ambient-router': hashes([
+        'b4a6bfc188d720ede3afefc3802b2a9192dd67cf1a3694a5ee221b383347cc21', // 1.1.0
+        '92a3ee58a6deb50f4dbbd50913527de78f7755ed23d492c6ffc18b42d035a867', // 1.2.0
+        'd32ef0392357eff61a47a3f758d2c1674fdf029ca6e74cf465e114723db57497', // 1.3.0 to 1.4.0
+        '2d73b902b3610b42455caf6fe0dfe5725dfe92a8590def4a125b280754a6c4f0', // 1.5.0
+        'e4221f41c567b04c2785d4127a4fc7f7fe1099afa490fc03f67e537010e8b5e8', // 1.6.0
+        '3e6ed6a711dcdf1f710266065684db637d34f15f0a3b2174d4867ea35fcf613b', // 1.6.1 to 1.8.1
+        'fb3a7025ce437ca2abc8fb8a71cae10e452f335e0d99adf979c601042e16570b', // 1.8.2 to 1.8.3
+    ]),
+    'architecture-patterns': hashes([
+        'a72ea9c4dcf4083e8f3d8a70dca282a807972e70e163a3e0988a61a875db4101', // 1.0.0 to 1.2.0
+        'd5da95e223c024e31c000c0d511e845f308045ae89e5a31cfaf2a0eebf07a238', // 1.3.0 to 1.8.3
+    ]),
+    'code-smell': hashes([
+        '2917880c99f1c2febb596319900c61826f58327ac933860d18eeaf98952b2bee', // 0.6.1 to 0.9.0
+    ]),
+    'complexity-patterns': hashes([
+        '3a6f56e229b19d27938274dc788a02334e5d96d8c56a55a80661b62c431af50f', // 1.0.0 to 1.2.0
+        'fc068855bca532e1c1a87d59617d9b093db5fef98064b0a6b0c84add0a4c7163', // 1.3.0 to 1.8.3
+    ]),
+    'consistency-patterns': hashes([
+        'ed270ef6c976d109beb3fda510cc84399a884d84e26f5a5fcf420ceb878444cb', // 1.0.0 to 1.2.0
+        '493a8ae10c759bb57a44f833251e77f1c0577e19b701f917ad6474d64bb0e96c', // 1.3.0 to 1.8.3
+    ]),
+    'core-patterns': hashes([
+        '5c1c8272250c06a1e1c0b263f171b04096380385ccdda3a252b830f2179597ba', // 1.0.0 to 1.8.3
+    ]),
+    'database-patterns': hashes([
+        '3cd61ce6b8b005cb72ace5af6fa3620d57f1363166621e88b6da0bb4b9566491', // 1.0.0 to 1.2.0
+        '1d28c6cdf41154f284956883c461bc56448342f8cb8d1c1118f9f85b3f4f3486', // 1.3.0 to 1.8.3
+    ]),
+    'debug': hashes([
+        '7199af54865413f2dc4333e6dc83c63e633f98d0ad78bdbdded384b145249f21', // 0.6.1 to 0.9.0
+    ]),
+    'debug-orchestration': hashes([
+        'eb2a5fbf55fc973dff8f5206a093248fde8626c63be967fb819fce15dda8c5cd', // 1.6.0 to 1.8.3
+    ]),
+    'dependencies-patterns': hashes([
+        '7711a6225b764aea7bf4f4d14cb0fe0ec2afbb3ab106ae17595c94cb126174c0', // 1.0.0 to 1.2.0
+        '86f89ec146a451aecf320349a2ff71f1f314a43bdeab221163b60e99361e8fbf', // 1.3.0 to 1.8.3
+    ]),
+    'docs-framework': hashes([
+        '7d97aa5d1ea61d5d1a9fa0f24960468c2fd365d25d6632700fdfa5efd9b180a0', // 1.0.0
+        '7ec949848e9d73249df1785d1e5e837928062a423c7ad4ee588543bea7d89950', // 1.1.0 to 1.5.0
+        '40454b337b552064a58424bf8ea505e486d0c0849a7ff14bd499a5072eb1b168', // 1.6.0
+        'e191008ac58722d14d7dadce4d828376585d26aa676b3e74882ea8c90fa8cd2d', // 1.6.1 to 1.8.3
+    ]),
+    'documentation-patterns': hashes([
+        '2cc11fdae2924f862573ef61aba5c42390089e1973b374a181475548d2e6de88', // 1.0.0 to 1.2.0
+        'b5eaef09cd851054062f72ecbbd13e9392872ab2fd2867c7c6ee5be380b09904', // 1.3.0 to 1.8.3
+    ]),
+    'frontend-design': hashes([
+        '015bcec670df04b8793bc8ceacf42ca579e87fb4ae9cc826f17d6067f5f39b4f', // 1.0.0 to 1.8.3
+    ]),
+    'git-safety': hashes([
+        'd0af494607b6956e2a31dc27b36fe622c2b606465d012efbac5b51f3cf264efb', // 1.0.0 to 1.8.3
+    ]),
+    'git-workflow': hashes([
+        '8f696c7f8758549e6f9547bdc56cf7370841411bc34f8bfba001951034d391ef', // 1.0.0 to 1.8.3
+    ]),
+    'github-patterns': hashes([
+        '0a93eed85575836e42980ffcc1dcad8679eb41dd0db1eaf428c51f34c101b2fa', // 1.0.0 to 1.8.3
+    ]),
+    'go': hashes([
+        '80b68a2f640b16b2d6a369cfe003ed6366a4a6c6c0a71868451a1652f2ede8d6', // 1.2.0 to 1.8.3
+    ]),
+    'implementation-orchestration': hashes([
+        '023bd2b2b754945daf83b101652e8c9a7c45092d0ebc2dd56dd9f170f6ef2cf2', // 1.6.0 to 1.8.3
+    ]),
+    'implementation-patterns': hashes([
+        '484816f577cb1c2d4fe6bcbe1f8adbc8c02c8a41eff19ecfa5711e2afca0cf54', // 1.0.0 to 1.8.3
+    ]),
+    'input-validation': hashes([
+        '2ce71e678840855d271dc7418b207f50c1d1123de80b9b88488154c5697053dd', // 0.6.1 to 0.9.0
+        '2e08b78f98de0e6ae17d455f832672e0a3ddaff9fa13337597f54130f3bc1a6b', // 1.0.0 to 1.8.3
+    ]),
+    'java': hashes([
+        '17cc4b3d476bd3ac9bbd3d367d04a88f4695d0e56f58db434aaaad80d875b6c3', // 1.2.0 to 1.8.3
+    ]),
+    'knowledge-persistence': hashes([
+        '3f43892b11fb2ffefb6ff1f083872338ed5d511b6e2bf6b125fa2c610afa5c79', // 1.6.0 to 1.8.3
+    ]),
+    'performance-patterns': hashes([
+        'bc025c6908ea87fab292cfe37396ee901c7acb1cccfaa27f78d9cd6f5798eea5', // 1.0.0 to 1.2.0
+        'bdd93bb51e829460d65a1ee572d0a95f7a0246b7a26bb1034a1c981e79b5ee9d', // 1.3.0 to 1.8.3
+    ]),
+    'plan-orchestration': hashes([
+        'ce940a2d0f2f3d80e9200ca8c4294d6fb26076f4fe6a640a157ffedd8ee37491', // 1.6.0 to 1.8.3
+    ]),
+    'python': hashes([
+        'ff03facdc25a6d6dc5d6e6979d2b3e30206b687ffc064cb0bc69591027ddcbb6', // 1.2.0 to 1.8.3
+    ]),
+    'react': hashes([
+        '3df91866eec7559cbef1e48c74af9b6f23861ef703fbe2bf00822d2d2842f666', // 1.0.0 to 1.1.0
+        '671e6a38d811f1eab42a3e0e69445c8528f8222957032c166a77a2b066a1f989', // 1.2.0 to 1.8.3
+    ]),
+    'regression-patterns': hashes([
+        'c4a8cfa79007c3838d5fceab272a7c6cfd808c4f64925385dff557670380b2aa', // 1.0.0 to 1.2.0
+        'd3a1a163f20a933d8fefd78e28b602ff34c6d13829fbb99eb78b29f07591f4a5', // 1.3.0 to 1.8.3
+    ]),
+    'research': hashes([
+        '528c0fd4538df7b949a7d355e7daf7a6e96848053f112b437c26477ca2f456fe', // 0.6.1
+        '0a9f207dc8028961328521d9eafa2e4e51740cbed4f7560b71a562e480a08503', // 0.7.0 to 0.9.0
+    ]),
+    'review-methodology': hashes([
+        '5cc67590d427510bfab6ba0daca3fd05df5aae74f7efeff4230aba4ec167e053', // 1.0.0 to 1.2.0
+        '928ddf64d96488c747552216b7079a943abcb7da2c8174d75a1281c94f61c19e', // 1.3.0 to 1.8.3
+    ]),
+    'rust': hashes([
+        'efee293456d582cc38941102be4052d3a0f352253c6d913b6d1b3a92134093fa', // 1.2.0 to 1.8.3
+    ]),
+    'search-first': hashes([
+        '37d60dc1fa6ab1aa690df450747c9a9e7c9b52ff8826ff3e675e612037d04794', // 1.5.0 to 1.8.3
+    ]),
+    'security-patterns': hashes([
+        '6662d43fa607913db531f8445ceedf7dd17266e64551d59d7d91969082d7c9ac', // 1.0.0 to 1.2.0
+        'f52c3b5acc69b2d6764b3aebb955a51f7de417d065ed9c085aae31684a7b7af0', // 1.3.0 to 1.8.3
+    ]),
+    'self-review': hashes([
+        'c7f0b6557316d2abc7cc3229c403d8abb736048a47f1e8d1d993d46351c36033', // 1.0.0 to 1.2.0
+        'f405c0f368884a714be309dcc9e85389672b22a7fd8b49bd2d5fd801cc4d9c51', // 1.3.0 to 1.8.3
+    ]),
+    'test-design': hashes([
+        '9c048d74b6387143fce401f0edf271f2e02daef231ea66a6662915d7f0f25a5b', // 0.6.1 to 0.9.0
+    ]),
+    'test-driven-development': hashes([
+        '54abb24907d3cf6c20c96981b4e2d20c80fbb51fb36559a3df9d4ac749af5782', // 1.1.0 to 1.2.0
+        '0457cfe9f23d2ba7f7e1faa00d027d8c3500458fcbb9957413be7ffad4c7f874', // 1.3.0 to 1.5.0
+        '21abf6a42b294bc3c6a7f51eaf981f08ab7bd6cec2c3c50312fc5d8b37ccba4e', // 1.6.0 to 1.8.3
+    ]),
+    'test-patterns': hashes([
+        '8c75e34c3544824d1f8dc26c407909ec4bf177db583862b34e827bd1aea1f279', // 1.0.0 to 1.8.3
+    ]),
+    'typescript': hashes([
+        'd70fc7facd2bec850c0b4cfb6eeeaa673648674024236a55ee6cbab7c2689241', // 1.0.0 to 1.8.3
+    ]),
+});
+//# sourceMappingURL=legacy-skill-hashes.js.map

package/dist/targets/claude-code/linked-folder.js

@@ -39,16 +39,6 @@ export async function unlinkLinkAt(entry) {
         return 'stuck';
     }
 }
-/**
- * Remove `target` whole. A link there is unlinked instead and returned, so the caller can report it;
- * the folder it points to is left as it is. A failure of the final `rm` is thrown.
- */
-export async function removeReportingLink(target) {
-    const outcome = await unlinkLinkAt(target);
-    if (outcome === 'no-link')
-        await fs.rm(target, { recursive: true, force: true });
-    return outcome === 'unlinked' ? [target] : [];
-}
 /**
  * Prove, with {@link isUnrealFolder}, that a run may write into `dir`, and record the folder in
  * `report.refusedFolders` when it may not. Returns true for a refused folder, so the caller skips
@@ -151,6 +141,10 @@ export function warnLinkReport(report, warn) {
 }
 /** The mode of a file that replaces a link. The atomic writer would copy the mode of the link's target instead. */
 const REPLACED_LINK_FILE_MODE = 0o644;
+/** The temp file beside `file` that {@link writeFileReplacingLink} writes through: `<file>.tmp.<pid>`. */
+export function linkReplacementTempPath(file) {
+    return `${file}.tmp.${process.pid}`;
+}
 /**
  * Write `content` at `file` through a temp file beside it and one rename. A rename puts the new file
  * in the place of whatever stands at `file`, so a link there is replaced and never followed; the link
@@ -165,7 +159,7 @@ export async function writeFileReplacingLink(file, content, links) {
         await writeFileAtomicExclusive(file, content);
         return;
     }
-    const temp = `${file}.tmp.${process.pid}`;
+    const temp = linkReplacementTempPath(file);
     try {
         // A stale temp file is removed first; the exclusive open then refuses anything placed there since.
         await fs.rm(temp, { force: true });

package/dist/targets/claude-code/reference-converge.js

@@ -32,8 +32,9 @@ import { getPackageRoot } from '../../core/paths.js';
 import { prefixSkillName } from '../../core/plugins.js';
 import { removeComplianceOffFiles, restoreComplianceOffFiles } from './compliance-off-files.js';
 import { overlayGeneratedReferences, overlayUnitLabel, referencesHostState, resolveSkillSource } from './installer.js';
+import { isUnrealFolder } from './linked-folder.js';
 export async function convergeReferences(opts) {
-    const { claudeDir, devflowDir, compliance, warn } = opts;
+    const { claudeDir, devflowDir, compliance, warn, backups } = opts;
     const failures = [];
     const fail = (message) => {
         warn(`reference converge: ${message}`);
@@ -48,9 +49,18 @@ export async function convergeReferences(opts) {
     const root = opts.packageRoot ?? getPackageRoot();
     const skillsDir = path.join(claudeDir, 'skills');
     const gitSkillDir = path.join(skillsDir, prefixSkillName(SKILL_REFS_SKILL_NAME));
+    // Every step below moves, removes or writes inside the skills folder. One that is a link or not a
+    // folder sends all of them into another place, and `referencesHostState` only looks at the entries
+    // below it. It is refused once, here: nothing is converged, the removal list of compliance off
+    // included, so the result is unproven and the caller fails closed.
+    if (await isUnrealFolder(skillsDir)) {
+        fail(`${skillsDir} is a link or not a folder, so nothing in it was converged`);
+        return { converged: false, rewritten: [], removed: [], restored: [], failures, stillPosting: [], unproven: !compliance };
+    }
     const manifest = installedReferenceManifest({ compliance });
     let rewritten = [];
     let unproven = false;
+    const removed = [];
     const host = await referencesHostState(gitSkillDir);
     if (host.kind === 'refused') {
         fail(`${host.path} is not a real directory, so the references in it were not converged`);
@@ -63,6 +73,7 @@ export async function convergeReferences(opts) {
                 sourceRoot: skillRefsSourceDir(compliance, root),
                 manifest,
                 warn,
+                backups,
             });
             rewritten = overlay.overlaidRefs;
             for (const failure of overlay.overlayFailures) {
@@ -73,6 +84,9 @@ export async function convergeReferences(opts) {
                 fail(`could not prune ${failed.name} (${String(failed.error)})`);
                 unproven = true;
             }
+            // What the prune removed is named beside what the compliance-off list removes. The prune names
+            // are relative to the references folder; this list spells them from the skills folder.
+            removed.push(...overlay.pruned.removed.map(name => `${prefixSkillName(SKILL_REFS_SKILL_NAME)}/references/${name}`));
         }
         catch (err) {
             // The overlay throws for a packaging failure only: an absent source root, or a manifest entry
@@ -81,7 +95,6 @@ export async function convergeReferences(opts) {
             unproven = true;
         }
     }
-    const removed = [];
     const restored = [];
     const stillPosting = [];
     if (!compliance) {

package/dist/targets/claude-code/rules-folder.js

@@ -0,0 +1,34 @@
+import { directoryState, refusedFolderStatement, unlinkLinkAt } from './linked-folder.js';
+/**
+ * Remove the rules folder devflow installs into, without deleting a file of the user's: the files
+ * devflow did not ship move to the backup folder, the files it shipped are removed by the list the
+ * session made, and a plain `rmdir` removes the folder only when nothing is left in it.
+ *
+ * A link is unlinked and never followed, and a path that is not a folder is left as it is. Never
+ * throws.
+ */
+export async function removeRulesFolder(rulesFolder, backups) {
+    const state = await directoryState(rulesFolder);
+    switch (state) {
+        case 'absent':
+            return 'absent';
+        case 'link':
+            return (await unlinkLinkAt(rulesFolder)) === 'unlinked' ? 'unlinked' : 'refused';
+        case 'unusable':
+            return 'refused';
+        case 'real': {
+            await backups.prepass([rulesFolder]);
+            const removal = await backups.removeListed(rulesFolder);
+            return removal.folderRemoved ? 'removed' : 'kept';
+        }
+        default: {
+            const unreachable = state;
+            return unreachable;
+        }
+    }
+}
+/** The line for a rules folder that {@link removeRulesFolder} refused to touch. */
+export function rulesFolderRefusedMessage(rulesFolder) {
+    return `${refusedFolderStatement(rulesFolder)} It was left as it is.`;
+}
+//# sourceMappingURL=rules-folder.js.map

package/dist/targets/claude-code/shipped-set.js

@@ -0,0 +1,160 @@
+/**
+ * The shipped set: every file path, relative to the Claude dir, that some install of this build
+ * can write into `commands/devflow`, `agents/devflow`, `rules/devflow` and `skills/devflow:*`.
+ *
+ * The backup session moves a file out of those folders unless the set names it, so the set errs
+ * toward too large. It comes from the full registries and all four variants (compliance on and
+ * off, curation on and off), never from the selection of one run and never from what an earlier
+ * install left on disk:
+ *
+ *   - commands: every plugin command, also a workflow that ships as a skill folder, since the
+ *     old command file of such a workflow is removed as a shipped file and never moved;
+ *   - agents and rules: every plugin entry, the feature-owned rules and the tracker agent;
+ *   - skills: the files of each registry skill in the package source, the generated references
+ *     of the compliance-on manifest, the compliance skill the converge writes, and the files only
+ *     a compliance-on install writes;
+ *   - workflow folders: the files of each registered folder under all four variant keys;
+ *   - shadows: the listing of a valid skill shadow counts beside the listing it replaces.
+ *
+ * {@link buildShippedSet} is pure. {@link loadShippedSet} reads the package and the shadows from
+ * disk, within fixed bounds, and answers with a reason instead of a smaller set when it cannot.
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { skillsDir } from '../../core/assets.js';
+import { complianceSkillFiles } from '../../core/compliance.js';
+import { COMPLIANCE_OFF_REMOVED_SKILL_FILES } from '../../core/compliance-off-files.js';
+import { VARIANT_KEYS } from '../../core/curation-variants.js';
+import { SKILL_REFS_SKILL_NAME, installedReferenceManifest, workflowFolderFiles, } from '../../core/mds-variants.js';
+import { createPathSet } from '../../core/path-set.js';
+import { FEATURE_OWNED_RULES, getAllAgentNames, getAllCommandNames, getAllRuleNames, getAllSkillNames, prefixSkillName, } from '../../core/plugins.js';
+import { validateSkillShadow } from './installer.js';
+import { TRACKER_AGENT_NAME } from './tracker-install.js';
+/** The most files one listed skill folder may hold. A folder past it is a failed listing. */
+export const MAX_LISTED_FILES = 2_000;
+/** The deepest level a listed folder may reach, counting the listed root as 0. */
+export const MAX_LISTED_DEPTH = 6;
+/** The most folders one listing may visit. */
+export const MAX_LISTED_FOLDERS = 500;
+const IGNORED_FILE_NAME = '.DS_Store';
+const commandPath = (name) => `commands/devflow/${name}.md`;
+const agentPath = (name) => `agents/devflow/${name}.md`;
+const rulePath = (name) => `rules/devflow/${name}.md`;
+const skillPath = (skill, file) => `skills/${prefixSkillName(skill)}/${file}`;
+/**
+ * The file paths of the shipped set. Pure: the registries are constants, and the package and
+ * shadow listings come in as inputs.
+ */
+export function shippedPaths(inputs) {
+    const paths = new Set();
+    for (const name of getAllCommandNames(new Set()))
+        paths.add(commandPath(name));
+    for (const name of [...getAllAgentNames(), TRACKER_AGENT_NAME])
+        paths.add(agentPath(name));
+    for (const name of [...getAllRuleNames(), ...FEATURE_OWNED_RULES])
+        paths.add(rulePath(name));
+    for (const [skill, files] of inputs.packageSkillFiles) {
+        for (const file of files)
+            paths.add(skillPath(skill, file));
+    }
+    for (const [skill, files] of inputs.shadowListings ?? []) {
+        for (const file of files)
+            paths.add(skillPath(skill, file));
+    }
+    for (const rel of installedReferenceManifest({ compliance: true })) {
+        paths.add(skillPath(SKILL_REFS_SKILL_NAME, `references/${rel}`));
+    }
+    for (const entry of COMPLIANCE_OFF_REMOVED_SKILL_FILES)
+        paths.add(`skills/${entry}`);
+    for (const file of complianceSkillFiles())
+        paths.add(skillPath('compliance', file));
+    for (const folder of inputs.workflowFolders) {
+        for (const key of VARIANT_KEYS) {
+            for (const file of workflowFolderFiles(folder, key))
+                paths.add(skillPath(folder.name, file));
+        }
+    }
+    return paths;
+}
+/** The shipped set of {@link shippedPaths}, ready for the backup session. */
+export function buildShippedSet(inputs) {
+    return createPathSet(shippedPaths(inputs));
+}
+/**
+ * The files below `root` as POSIX paths, sorted per folder. Folders are entered only as real
+ * folders (a link is listed as a file and never entered). The listing is bounded by
+ * {@link MAX_LISTED_FILES}, {@link MAX_LISTED_DEPTH} and {@link MAX_LISTED_FOLDERS}; a breach or a
+ * read error is a failed listing, since a smaller listing would be a smaller set.
+ */
+async function listFiles(root) {
+    const files = [];
+    const pending = [
+        { dir: root, rel: '', depth: 0 },
+    ];
+    for (let visited = 0; visited < MAX_LISTED_FOLDERS; visited++) {
+        const next = pending.pop();
+        if (next === undefined)
+            return { ok: true, files };
+        let entries;
+        try {
+            entries = await fs.readdir(next.dir, { withFileTypes: true });
+        }
+        catch (err) {
+            const code = err.code;
+            return { ok: false, reason: `could not read ${next.dir} (${typeof code === 'string' ? code : 'error'})` };
+        }
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            const rel = next.rel === '' ? entry.name : `${next.rel}/${entry.name}`;
+            if (entry.isDirectory()) {
+                if (next.depth + 1 > MAX_LISTED_DEPTH)
+                    return { ok: false, reason: `${root} is deeper than ${MAX_LISTED_DEPTH} levels` };
+                pending.push({ dir: path.join(next.dir, entry.name), rel, depth: next.depth + 1 });
+            }
+            else if ((entry.isFile() || entry.isSymbolicLink()) && entry.name !== IGNORED_FILE_NAME) {
+                if (files.length >= MAX_LISTED_FILES)
+                    return { ok: false, reason: `${root} holds more than ${MAX_LISTED_FILES} files` };
+                files.push(rel);
+            }
+        }
+    }
+    return pending.length === 0
+        ? { ok: true, files }
+        : { ok: false, reason: `${root} holds more than ${MAX_LISTED_FOLDERS} folders` };
+}
+/**
+ * Build the shipped set from the registries, the package skill source and the skill shadows.
+ *
+ * Every registry skill is listed from `skillsDir(packageRoot)`. A skill whose source is missing is
+ * a failed load, not a smaller set: the caller then runs no scan, because a set that lacks a
+ * shipped file would send that file to the backup folder.
+ */
+export async function loadShippedSet(options) {
+    const skills = getAllSkillNames(new Set());
+    const packageSkillFiles = new Map();
+    for (const skill of skills) {
+        const listed = await listFiles(path.join(skillsDir(options.packageRoot), skill));
+        if (!listed.ok)
+            return { ok: false, reason: `skill "${skill}": ${listed.reason}` };
+        packageSkillFiles.set(skill, listed.files);
+    }
+    let shadowListings = options.shadowListings;
+    if (shadowListings === undefined) {
+        const found = new Map();
+        for (const skill of skills) {
+            const shadowDir = path.join(options.devflowDir, 'skills', skill);
+            if ((await validateSkillShadow(shadowDir)) !== 'valid')
+                continue;
+            const listed = await listFiles(shadowDir);
+            if (!listed.ok)
+                return { ok: false, reason: `shadow of skill "${skill}": ${listed.reason}` };
+            found.set(skill, listed.files);
+        }
+        shadowListings = found;
+    }
+    return {
+        ok: true,
+        shipped: buildShippedSet({ packageSkillFiles, shadowListings, workflowFolders: options.workflowFolders }),
+    };
+}
+//# sourceMappingURL=shipped-set.js.map

package/dist/targets/claude-code/workflow-folder-install.js

@@ -19,6 +19,12 @@
  *     it was moved to and the result names that path (`recoveryPath`); nothing deletes a backup
  *     that the result names as the way back. A folder that already holds the exact files is not
  *     touched, so an install that changes nothing writes nothing.
+ *   - NO LOSS of the user's files: before any rename, the backup session moves every file of the
+ *     old folder that devflow did not ship (the files of all four variant keys count as shipped)
+ *     to the backup folder. If one cannot move, the result is `failed` and the folder stays as it
+ *     is. After the swap the displaced folder is scanned again, its shipped files are removed by the
+ *     session's list, and it goes with a plain `rmdir`; no folder is removed with a recursive `rm`
+ *     except the staging folder, which holds only the copies this call wrote.
  *
  * A link at the skills folder or at the folder, or anything there that is not a folder, is refused
  * and recorded in `links.refusedFolders`; a link is never followed and never written through.
@@ -32,13 +38,17 @@ import { workflowFoldersSourceDir } from '../../core/assets.js';
 import { describeBuildIdCheckError, describeWorkflowFolderError, validateOutputName, verifyFolderBuildId, workflowFolderFiles, workflowFolderKey, } from '../../core/mds-variants.js';
 import { isContainedIn } from '../../core/paths.js';
 import { prefixSkillName } from '../../core/plugins.js';
+import { discardDisplacedFolder } from './folder-swap.js';
+import { formatCappedList } from './install-backup.js';
 import { directoryState, refuseUnrealFolder } from './linked-folder.js';
 /** The deepest level of a folder that is read or compared: `references/<file>` is level 1. */
 const MAX_FOLDER_DEPTH = 4;
 /** The folder inside the staging folder that is moved into place. */
 const STAGED_FOLDER = 'folder';
 /** Where the old folder waits while the new one is moved in: beside its staging folder. */
-const backupOf = (staging) => `${staging}.old`;
+export const backupOf = (staging) => `${staging}.old`;
+/** The prefix of the staging folder of one folder install; `mkdtemp` adds six random characters. */
+export const stagingPrefixOf = (claudeDir, name) => path.join(claudeDir, `.devflow-workflow-${name}-${process.pid}-`);
 const errorMessage = (err) => (err instanceof Error ? err.message : String(err));
 /**
  * Read the files one folder holds under the exact variant key of `switches`.
@@ -147,7 +157,8 @@ async function folderHolds(target, files) {
     return true;
 }
 /**
- * Write `skills/devflow:<name>/` as exactly `files`: stage, then swap in. See the module comment.
+ * Write `skills/devflow:<name>/` as exactly `files`: move the user's files aside, stage, then swap
+ * in. See the module comment.
  *
  * The staging folder sits under `claudeDir`, not under `skills/`, so a folder a crash leaves
  * behind never looks like a second skill to Claude Code. It is made by `mkdtemp`, an exclusive
@@ -157,7 +168,7 @@ async function folderHolds(target, files) {
  * Never throws.
  */
 export async function installWorkflowFolder(opts) {
-    const { claudeDir, name, files, links } = opts;
+    const { claudeDir, name, files, links, backups } = opts;
     if (!path.isAbsolute(claudeDir)) {
         return { name, outcome: 'failed', reason: `claudeDir is not an absolute path ("${claudeDir}")` };
     }
@@ -176,13 +187,23 @@ export async function installWorkflowFolder(opts) {
     if (await refuseUnrealFolder(links, target))
         return { name, outcome: 'refused' };
     let staging = null;
-    let keepBackup = false;
     try {
-        if ((await directoryState(target)) === 'real' && (await folderHolds(target, files))) {
-            return { name, outcome: 'unchanged' };
+        if ((await directoryState(target)) === 'real') {
+            // Before any rename: what devflow did not ship moves out of the folder, whichever key's files it holds.
+            await backups.prepass([target]);
+            const kept = backups.keptUnder(target);
+            if (kept.length > 0) {
+                return {
+                    name,
+                    outcome: 'failed',
+                    reason: `${kept.length} file(s) in ${target} could not be moved aside, so the folder was left as it is: ${formatCappedList(kept)}`,
+                };
+            }
+            if (await folderHolds(target, files))
+                return { name, outcome: 'unchanged' };
         }
         await fs.mkdir(claudeDir, { recursive: true });
-        staging = await fs.mkdtemp(path.join(claudeDir, `.devflow-workflow-${name}-${process.pid}-`));
+        staging = await fs.mkdtemp(stagingPrefixOf(claudeDir, name));
         const staged = path.join(staging, STAGED_FOLDER);
         await fs.mkdir(staged);
         for (const { file, bytes } of files) {
@@ -205,7 +226,6 @@ export async function installWorkflowFolder(opts) {
                 await fs.rename(backup, target);
             }
             catch (restoreErr) {
-                keepBackup = true;
                 return {
                     name,
                     outcome: 'failed',
@@ -215,17 +235,17 @@ export async function installWorkflowFolder(opts) {
             }
             throw err;
         }
+        // The displaced folder is scanned again, because a file can arrive after the first scan.
+        if (hadTarget)
+            await discardDisplacedFolder(backups, backup, target);
         return { name, outcome: 'installed' };
     }
     catch (err) {
         return { name, outcome: 'failed', reason: errorMessage(err) };
     }
     finally {
-        if (staging !== null) {
+        if (staging !== null)
             await fs.rm(staging, { recursive: true, force: true }).catch(() => undefined);
-            if (!keepBackup)
-                await fs.rm(backupOf(staging), { recursive: true, force: true }).catch(() => undefined);
-        }
     }
 }
 //# sourceMappingURL=workflow-folder-install.js.map

package/dist/variant-axes.json

@@ -1,6 +1,10 @@
 {
   "version": 1,
   "hosts": {
+    "agents/architect": {
+      "curation": true,
+      "compliance": false
+    },
     "agents/code": {
       "curation": true,
       "compliance": false
@@ -70,7 +74,7 @@
       "compliance": false
     },
     "commands/dynamic-profile": {
-      "curation": true,
+      "curation": false,
       "compliance": false
     },
     "commands/dynamic-tickets": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devflow-kit",
-  "version": "3.10.0",
+  "version": "3.12.0",
   "description": "A meta-harness for Claude Code — turns a single coding agent into an engineering team: orchestration, parallel review, persistent memory, curated decisions, and graph workflows",
   "type": "module",
   "bin": {

package/src/assets/agents/_partials/_code.mds

@@ -26,8 +26,7 @@ inside a define is split by the build like an arm in a host: the markers sit on
 - **TASK_DESCRIPTION**: What to do
 - **PUSH** (optional): `true` (default) | `false` — when false, commit only; orchestrator owns push/CI gate
 <!-- curation:on -->
-- **DECISIONS_CONTEXT** (optional): Compact index of active ADR/PF entries.
-  When provided, use `devflow:apply-decisions` to Read full bodies on demand.
+- **DECISIONS_CONTEXT** (optional): Compact index of active ADR/PF entries
 <!-- curation:end -->
 @end
 
@@ -61,8 +60,7 @@ Run builds, typechecks, lints and tests in the foreground, each with an explicit
 1. **Read once** - Never re-read an unchanged file. For a file over 400 lines, or a second look, `grep -n` first, then Read only that range (`offset`, `limit`)
 2. **Small, focused changes** - Don't scope creep beyond the plan
 3. **Fail honestly** - If blocked, report clearly with what was completed
-
-- Never print a large file whole; page it with offset and limit, and cap any output you print. Before printing search matches, list or count them.
+4. **Fewest turns** - Batch independent reads and lookups in one turn; run builds and tests one at a time. No Read-back after a successful Edit or Write unless a command changed the file. No narration-only turn, except the wait for an end notice
 
 ## Output
 
@@ -86,7 +84,7 @@ Run builds, typechecks, lints and tests in the foreground, each with an explicit
 {Description of blocker or failure with recommendation}
 ```
 
-Report cap: final message at most about 1,500 tokens; longer material goes to a `mktemp` file (via Bash or Write) and the message gives its path. Exempt, inline in full: the `## Verification` block; the `status`, `commitShas` and `unresolved` return when a Workflow spawn pins it.
+Report cap: final message at most about 1,500 tokens; longer material goes to a new file in a `mktemp -d` folder and the message gives its path. Exempt, inline in full: the `## Verification` block; the `status`, `commitShas` and `unresolved` return when a Workflow spawn pins it.
 
 ## Boundaries