devlyn-cli 4.2.18 → 4.2.20

package/README.md

@@ -113,15 +113,16 @@ Upgrading to 4.1.0: `npx devlyn-cli -y` in a 4.x project keeps its Claude Code i
 current and adds `AGENTS.md` + `.agents/skills/`. Earlier releases put the Codex, omp, Pi
 and Grok skills in `~/.codex/skills`, `~/.agents/skills` and `~/.grok/skills`; a project
 install no longer refreshes them and names each one it finds. Refresh them with `--global`
-or delete them; delete `~/.grok/skills`, since Grok now reads `~/.agents/skills`.
+or delete them; global installs and `update` clean Devlyn’s retired `~/.grok/skills` entries automatically.
 `npx devlyn-cli agents` was removed.
 
 <!-- legacy-surface-map:begin — retired command names below are documented as OLD, not current; lint Checks 5e and 10c skip this block -->
 Upgrading to 4.2.0: `/devlyn-resolve` and the pipeline helpers only it used are retired;
 no measured replacement ships in their place. Run the installer again where devlyn is
 installed. It removes the `devlyn-resolve` folders (and pre-4.0.0 `devlyn:resolve` ones)
-where it installs, removes the Stop hook it added to `.claude/settings.json` while keeping
-your own hooks, and names the other settings it once added for the pipeline
+by their exact retired names, including edited copies and links (link targets stay intact). It
+removes the Stop hook it added to `.claude/settings.json` while keeping your own hooks,
+and names the other settings it once added for the pipeline
 (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` and its `.devlyn` and git permissions) without
 deleting them. `/devlyn-engines` keeps only the executor pin: `pair_judge_priority` and
 `roles` in `.devlyn/engines.json` stay as written, select nothing, and `clear` removes them.
@@ -147,7 +148,7 @@ devlyn skill by its old name or path (for example Codex `[[skills.config]]` or o
 `disabledExtensions`) needs the new name. A project that committed the old `devlyn:*`
 folders checks out on Windows once that re-sync is committed.
 
-Earlier versions of devlyn-cli shipped 16+ slash commands. The iter-0034 Phase 4 cutover (2026-05-04) and the 2026-05-14 follow-up consolidated them, 4.0.0 renamed every devlyn skill to the Agent Skills naming standard (`devlyn-<name>`: lowercase, digits and hyphens, the same as its folder), and after 4.1.0 resolve and design-ui were retired and the queue moved into ideate. Upgrades automatically purge the legacy skill directories.
+Earlier versions of devlyn-cli shipped 16+ slash commands. The iter-0034 Phase 4 cutover (2026-05-04) and the 2026-05-14 follow-up consolidated them, 4.0.0 renamed every devlyn skill to the Agent Skills naming standard (`devlyn-<name>`: lowercase, digits and hyphens, the same as its folder), and after 4.1.0 resolve and design-ui were retired and the queue moved into ideate. Install/update deletes exact retired Devlyn names in its scope; generic files and old instruction text are removed only with evidence matching shipped copies. Other skills, edited generic files, and your instruction text are preserved; instruction changes keep a recovery backup.
 
 | Old command | Now use |
 |---|---|

package/bin/cleanup-history.json

@@ -0,0 +1,97 @@
+{
+  "source": "scripts/update-cleanup-history.js: LF-normalized Git blobs from first-parent config/agents-config/optional-skills history and all tags; excludes optional-addon hashes and third-party web-design-guidelines",
+  "files": {
+    ".claude/agents/evaluator.md": [
+      "146a229b0218938bca2de6b426cda642ae9826dc2dfa8c3687c6fd5de9160cf6",
+      "537c4af183aac692ff2abecfd42b4fe0854549b2ecf14fca3bc6a86ae58837fa",
+      "b8a48da212e070bab9d4818630cee2cd0de9846ad4e3a34b3a45f0a9a1a913b6",
+      "d5615e73af2401ea7418e02fc76d850506e59a64fff00f084ad272e474e138ba"
+    ],
+    ".claude/commit-conventions.md": [
+      "7e75c25d3067dba650781c57f1d94b52090badc2cb034b00759e9c6ed74a5a94"
+    ],
+    ".claude/templates/prompt-templates.md": [
+      "19029bcff7c4e9b579011d93a4f6eecfbe6a260f3cee12072252a6a7402d79e7",
+      "3fb7804dbd6e026def99829dda5daccc56a68e93997d8e6f540ee98bb288329e",
+      "7318764baa5dc7cd406bc8552848653ad6368982b43faecc6618f697a9ae059f",
+      "e583be4175366101bfa0df512b1106f65b18f215b4717eadebbc8129c3d96be5"
+    ],
+    ".claude/templates/template-feature.spec.md": [
+      "16eb59b48f062aa0894b3fe8ba1c8f9e970652fda0bdd0d9e3248acb8e40d3bc"
+    ],
+    ".claude/templates/template-product-spec.md": [
+      "42b5b2c32fd72b1324432da0cf652cf11854e3ac40e020b812ef64d894116d92"
+    ],
+    ".cursor/rules/evaluator.md": [
+      "146a229b0218938bca2de6b426cda642ae9826dc2dfa8c3687c6fd5de9160cf6",
+      "537c4af183aac692ff2abecfd42b4fe0854549b2ecf14fca3bc6a86ae58837fa",
+      "b8a48da212e070bab9d4818630cee2cd0de9846ad4e3a34b3a45f0a9a1a913b6",
+      "d5615e73af2401ea7418e02fc76d850506e59a64fff00f084ad272e474e138ba"
+    ],
+    ".github/copilot/agents/evaluator.md": [
+      "146a229b0218938bca2de6b426cda642ae9826dc2dfa8c3687c6fd5de9160cf6",
+      "537c4af183aac692ff2abecfd42b4fe0854549b2ecf14fca3bc6a86ae58837fa",
+      "b8a48da212e070bab9d4818630cee2cd0de9846ad4e3a34b3a45f0a9a1a913b6",
+      "d5615e73af2401ea7418e02fc76d850506e59a64fff00f084ad272e474e138ba"
+    ],
+    ".windsurf/rules/evaluator.md": [
+      "146a229b0218938bca2de6b426cda642ae9826dc2dfa8c3687c6fd5de9160cf6",
+      "537c4af183aac692ff2abecfd42b4fe0854549b2ecf14fca3bc6a86ae58837fa",
+      "b8a48da212e070bab9d4818630cee2cd0de9846ad4e3a34b3a45f0a9a1a913b6",
+      "d5615e73af2401ea7418e02fc76d850506e59a64fff00f084ad272e474e138ba"
+    ]
+  },
+  "skills": {
+    "code-health-standards": [
+      "962a82b5ebeafac515f81f5c68494c67dbf31c3e3e453f23c4452d4725e21355",
+      "df2838904c938aa0306ed333cc460cfc5c2cf0ffa20bb5ade57067c6e0acf9be"
+    ],
+    "code-review-standards": [
+      "3bc8587a9143487328be2470dec8df17a19cb14f94e6ec916ed58de660d0e1c4",
+      "56abe5736f505c53ca9ce14087a9891cc8661be783abaec7b5b924e3f339cc2a",
+      "586dde5014f9ac2f9a13d43fa1c8c257a3ae998a3fc1b867b23b3b2e44f77eca",
+      "9c906f2b2a88c2d0aaeec9714405945da5177de6ec433f1acf520c6c4385b875"
+    ],
+    "feature-gap-analysis": [
+      "d2328d990305280cf0d08443130cdba63eb5ed8040f5e5b6719c58050c4d3ada"
+    ],
+    "investigate": [
+      "5025c346d1e246d49681650e7b630477d1ef67f4357e5fd7f3e5f02e5a860288"
+    ],
+    "root-cause-analysis": [
+      "0eac104bfcde8bdf14d4c284be6f3f4cb243219a679bf569433c2465df84c6c3",
+      "1793dcb0f72621c78cc20c905fe5dd7a0af3115e904bf737a6a983a7b9d2c2b6",
+      "aab22d1bddc66c6a798f08cdf7be9b45fbe80ccfc928b068ef5d9e2ad951bdda",
+      "e200ddd04196435af3162a9e13595f8eb5ac68b06465026e0155e453b1bd1c93",
+      "e66d15a9585c07e819acfd89c1f6d030517130f6d8f8924bda3120307949fb2e"
+    ],
+    "ui-implementation-standards": [
+      "13c709c0e2b01ae94997c271043a685200e969192d2056534bd787c5682874e8",
+      "1ff64816454171b3f879e9e5cf3c15e3d9c5f2ffc81b73262155f6bc93a1b054",
+      "505ca42b1efd53925d51c570b21df4e05cbc6bc640dd1f7f4e03f15d2d4437c5",
+      "e2473e35474e78f2b581e225cb33a1e711bb79519a02e9780fc9606e582b878f"
+    ],
+    "workflow-routing": [
+      "7fec2bb20d808a873a975d64a6223e404bc5b328c800760bb77257ae6b2f467a",
+      "8bfdaeff2ce48d5a79b5653de3bbe0d56a61a7fd750ed3ad11149fec5a502ecf"
+    ]
+  },
+  "evaluators": [
+    {
+      "length": 3081,
+      "sha256": "01a566bbecfb7eaef16b53c2000dc58050a3348072019868fbe23cbd6503095d"
+    },
+    {
+      "length": 1559,
+      "sha256": "04403ca3008e87adbd0f75f3136a20d6d5262eb7576f8d31cec2d03686dc9898"
+    },
+    {
+      "length": 2980,
+      "sha256": "481557b50619e1d47c209b1e1c916919361031f57cf2ee8f27644c2a101cfdb6"
+    },
+    {
+      "length": 2980,
+      "sha256": "6c7066a91aa18a62b1257956f0adf4f08603034d8a6eb2fae052a1ea8d0d9a4b"
+    }
+  ]
+}

package/bin/devlyn.js

@@ -12,6 +12,7 @@ const PKG = require('../package.json');
 const { updateInstructions, InstructionError, holdsDevlynDefaults, importsAgentsMd } = require('./instructions');
 const { contentHash, fingerprint, gitEnvironment, isIgnoredEntry, trackedPaths } = require('./skill-ownership');
 const SKILL_HISTORY = require('./skill-history.json');
+const CLEANUP_HISTORY = require('./cleanup-history.json');
 
 // The devlyn skill bundle installed into every skill-capable agent's loader
 // directory. Single source of truth so codex/omp/pi stay in lockstep — adding a
@@ -39,7 +40,13 @@ const RETIRED_PERMISSIONS = ['Write(.devlyn/**)', 'Edit(.devlyn/**)', 'Bash(git
 
 // Every spelling a colon name can have on disk: its own and npm's U+F03A extraction alias.
 function legacySkillPaths(root, name) {
-  return [...new Set([name, name.replace(/:/g, '\uF03A')])].map((spelling) => path.join(root, spelling));
+  const spellings = new Set([name, name.replace(/:/g, '\uF03A')]);
+  if (fs.lstatSync(root, { throwIfNoEntry: false })?.isDirectory()) {
+    for (const entry of fs.readdirSync(root)) {
+      if ([...spellings].some((spelling) => spelling.toLowerCase() === entry.toLowerCase())) spellings.add(entry);
+    }
+  }
+  return [...spellings].map((spelling) => path.join(root, spelling));
 }
 
 // SKILL.md of the pencil skills 0.6.0-0.7.1 installed under today's names, without the
@@ -53,36 +60,8 @@ const PRE_STANDARD_SKILL_MD_SHA256 = new Set([
 // Skills devlyn-cli installed by default and later deleted or made opt-in, by SHA-256 of their
 // only file, SKILL.md (LF endings): an opted-in copy or a user's own folder of the same name is
 // never removed.
-const RETIRED_SKILL_MD_SHA256 = {
-  // 0.2.0-1.15.0; deleted in iter-0034, it still routes agents to retired commands.
-  'workflow-routing': new Set([
-    '7fec2bb20d808a873a975d64a6223e404bc5b328c800760bb77257ae6b2f467a',
-    '8bfdaeff2ce48d5a79b5653de3bbe0d56a61a7fd750ed3ad11149fec5a502ecf',
-  ]),
-  // The standards skills, 0.1.0-3.2.1; 3.3.0 (0221) made them optional addons.
-  'code-health-standards': new Set([
-    'df2838904c938aa0306ed333cc460cfc5c2cf0ffa20bb5ade57067c6e0acf9be',
-    '962a82b5ebeafac515f81f5c68494c67dbf31c3e3e453f23c4452d4725e21355',
-  ]),
-  'code-review-standards': new Set([
-    '9c906f2b2a88c2d0aaeec9714405945da5177de6ec433f1acf520c6c4385b875',
-    '3bc8587a9143487328be2470dec8df17a19cb14f94e6ec916ed58de660d0e1c4',
-    '56abe5736f505c53ca9ce14087a9891cc8661be783abaec7b5b924e3f339cc2a',
-    '586dde5014f9ac2f9a13d43fa1c8c257a3ae998a3fc1b867b23b3b2e44f77eca',
-  ]),
-  'root-cause-analysis': new Set([
-    'e200ddd04196435af3162a9e13595f8eb5ac68b06465026e0155e453b1bd1c93',
-    '1793dcb0f72621c78cc20c905fe5dd7a0af3115e904bf737a6a983a7b9d2c2b6',
-    'aab22d1bddc66c6a798f08cdf7be9b45fbe80ccfc928b068ef5d9e2ad951bdda',
-    '0eac104bfcde8bdf14d4c284be6f3f4cb243219a679bf569433c2465df84c6c3',
-    'e66d15a9585c07e819acfd89c1f6d030517130f6d8f8924bda3120307949fb2e',
-  ]),
-  'ui-implementation-standards': new Set([
-    'e2473e35474e78f2b581e225cb33a1e711bb79519a02e9780fc9606e582b878f',
-    '1ff64816454171b3f879e9e5cf3c15e3d9c5f2ffc81b73262155f6bc93a1b054',
-    '13c709c0e2b01ae94997c271043a685200e969192d2056534bd787c5682874e8',
-  ]),
-};
+const RETIRED_SKILL_MD_SHA256 = Object.fromEntries(
+  Object.entries(CLEANUP_HISTORY.skills).map(([name, hashes]) => [name, new Set(hashes)]));
 
 // Whether `dir` is a real folder whose only file, besides generated metadata, is a SKILL.md
 // with an LF-normalized SHA-256 in `hashes`: an unedited copy devlyn-cli shipped, not something
@@ -92,7 +71,7 @@ function isShippedCopy(dir, hashes) {
   return fs.lstatSync(dir, { throwIfNoEntry: false })?.isDirectory() === true
     && fs.readdirSync(dir).filter((name) => !isIgnoredEntry(path.join(dir, name))).length === 1
     && fs.lstatSync(skill, { throwIfNoEntry: false })?.isFile() === true
-    && hashes.has(contentHash(skill));
+    && hashes.has(crypto.createHash('sha256').update(fs.readFileSync(skill).toString('latin1').replace(/\r\n/g, '\n'), 'latin1').digest('hex'));
 }
 
 // Skill roots of each target. In a project, `.agents/skills` serves Codex, omp, Pi and Grok,
@@ -110,12 +89,13 @@ function hasDevlynInstall(root) {
     const stat = (name) => fs.lstatSync(name, { throwIfNoEntry: false });
     if (!stat(root)?.isDirectory()) return false;
     const optional = new Set(OPTIONAL_ADDONS.map((addon) => addon.name));
-    const names = [...DEVLYN_CORE_SKILLS, ...DEPRECATED_DIRS.map((name) => path.basename(name)),
+    const names = [...DEVLYN_CORE_SKILLS,
       ...Object.keys(RENAMED_SKILLS)].filter((name) => name.startsWith('devlyn')
         && !optional.has(name.replace(/[:\uF03A]/g, '-')));
     return !!stat(path.join(root, DEVLYN_INSTALL_LOCK))
       || names.some((name) => [...legacySkillPaths(root, name.replace(/^devlyn-/, 'devlyn:')),
         path.join(root, name.replace(/:/g, '-'))].some((full) => stat(full)?.isDirectory()))
+      || hasHistoricalRetiredSkill(root)
       || (!!stat(path.join(root, DEVLYN_INSTALL_MARKER)) && stat(path.join(root, '_shared'))?.isDirectory());
   } catch (error) {
     if (error.code === 'ENOTDIR') return false;
@@ -136,15 +116,21 @@ function hasDevlynClaude(global) {
   const optional = new Set(OPTIONAL_ADDONS.map((addon) => addon.name));
   const instructions = path.join(path.dirname(claudeDir), 'CLAUDE.md');
   const claude = fs.lstatSync(instructions, { throwIfNoEntry: false })?.isFile() ? fs.readFileSync(instructions, 'utf8') : '';
-  return names(path.join(claudeDir, 'skills')).some((name) => name === DEVLYN_INSTALL_MARKER
-      || (name.startsWith('devlyn') && !optional.has(name.replace(/[:\uF03A]/g, '-'))))
+  const root = path.join(claudeDir, 'skills');
+  const deprecated = new Set([...deprecatedSkillPaths(root)].map((full) => path.basename(full).toLowerCase()));
+  return names(root).some((name) => {
+    if (deprecated.has(name.toLowerCase())) return historicalSkill(path.join(root, name));
+    return name === DEVLYN_INSTALL_MARKER
+      || (name.startsWith('devlyn') && !optional.has(name.replace(/[:\uF03A]/g, '-')));
+  })
     || names(path.join(claudeDir, 'commands')).some((name) => name.startsWith('devlyn.'))
     || holdsDevlynDefaults('CLAUDE.md', claude) || importsAgentsDefaults(claude);
 }
 
-// Commands removed in previous versions; the project Claude install deletes them from .claude/
-// when they hold the bytes a version shipped (SKILL_HISTORY.commands).
+// Exact Devlyn command names removed by previous versions, in either scope.
 const DEPRECATED_FILES = [
+  'commands/devlyn.ui.md',
+  'commands/devlyn.team-ui.md',
   'commands/devlyn.handoff.md', // removed in v0.2.0
   'commands/devlyn.clean.md', // migrated to skills in v0.6.0
   'commands/devlyn.design-system.md',
@@ -168,7 +154,7 @@ const DEPRECATED_FILES = [
 // Skill directories renamed from devlyn-* to devlyn:* in v0.7.x, plus
 // iter-0034 Phase 4 cutover (2026-05-03): 15 user skills deleted and 3 moved
 // to optional-skills/. Listed here so post-cutover `npx devlyn-cli` upgrades
-// remove verified, unchanged legacy skill dirs from downstream `~/.claude/skills/`
+// remove these exact retired skill names from downstream skill roots
 // even though the source dirs no longer exist (the installer replaces only
 // the skills it ships — without this list, deleted-from-source skills persist
 // in user installs forever).
@@ -367,41 +353,16 @@ function listContents() {
   log('');
 }
 
-// Old and retired skills in one skill root; nothing outside it.
-function cleanupDeprecated(skillsDir, written) {
-  let removed = 0;
-  const deprecated = DEPRECATED_DIRS.flatMap((relPath) =>
-    legacySkillPaths(skillsDir, path.basename(relPath)).map((fullPath) => [relPath, fullPath]));
-  for (const [relPath, fullPath] of deprecated) {
-    if (fs.existsSync(fullPath)) {
-      fs.rmSync(fullPath, { recursive: true });
-      written.push(fullPath);
-      log(`  ✕ ${relPath}/ (removed)`, 'dim');
-      removed++;
-    }
-  }
-  for (const [name, hashes] of Object.entries(RETIRED_SKILL_MD_SHA256)) {
-    const fullPath = path.join(skillsDir, name);
-    if (isShippedCopy(fullPath, hashes)) {
-      fs.rmSync(fullPath, { recursive: true });
-      written.push(fullPath);
-      log(`  ✕ skills/${name}/ (removed)`, 'dim');
-      removed++;
-    }
-  }
-  return removed;
-}
-
 // Remove every old spelling of the renamed skills in `skillsDir`, after the new core skills
 // are in place. An optional skill found under an old spelling is installed under its new name
 // before the old copy goes, so an interrupted migration never loses it. An unedited 0.6.0-0.7.1
 // copy is refreshed in place. Any other folder under a 4.0 name is the user's own; `-y` leaves it.
-function retireRenamedSkills(skillsDir, written, installedSkills) {
+function refreshRenamedSkills(skillsDir, written, installedSkills) {
   const optional = new Set(OPTIONAL_ADDONS.filter((addon) => addon.type === 'local').map((addon) => addon.name));
   const refreshed = [];
   for (const [oldName, newName] of Object.entries(RENAMED_SKILLS)) {
     const found = legacySkillPaths(skillsDir, oldName).filter((fullPath) => fs.existsSync(fullPath));
-    if (found.length > 0 && optional.has(newName)) {
+    if (found.length > 0 && optional.has(newName) && canRefreshRenamed(skillsDir, newName)) {
       installOptionalSkillInto(skillsDir, newName, written, installedSkills);
       refreshed.push(newName);
     } else if (isShippedCopy(path.join(skillsDir, newName), PRE_STANDARD_SKILL_MD_SHA256)) {
@@ -410,11 +371,6 @@ function retireRenamedSkills(skillsDir, written, installedSkills) {
       installedSkills.set(path.join(skillsDir, newName), [path.join(skillsDir, newName, 'SKILL.md')]);
       refreshed.push(newName);
     }
-    for (const fullPath of found) {
-      fs.rmSync(fullPath, { recursive: true, force: true });
-      written.push(fullPath);
-      log(`  ✕ ${path.basename(fullPath)}/ (renamed to ${newName})`, 'dim');
-    }
   }
   return refreshed;
 }
@@ -458,44 +414,68 @@ function readInstallManifest(root) {
   return marker.skills || {};
 }
 
+// A retired optional name must not make a foreign copy under its new name an install conflict.
+function canRefreshRenamed(root, name) {
+  const dest = path.join(root, name);
+  if (!fs.lstatSync(dest, { throwIfNoEntry: false })) return true;
+  try { verifySkill(dest, name, readInstallManifest(root)); return true; }
+  catch { return false; } // No ownership proof: preserve the new-name entry without installing over it.
+}
+
 // Enumerate every directory this install may replace, migrate or remove, before
 // touching any target. Optional addons must be selected before this preflight too.
 function plannedSkills(root, optionalNames = []) {
   const names = new Set([...DEVLYN_CORE_SKILLS, ...optionalNames]);
-  for (const relative of DEPRECATED_DIRS) {
-    for (const full of legacySkillPaths(root, path.basename(relative))) names.add(path.basename(full));
-  }
   for (const [oldName, newName] of Object.entries(RENAMED_SKILLS)) {
     const oldPaths = legacySkillPaths(root, oldName);
-    oldPaths.forEach((full) => names.add(path.basename(full)));
-    if (oldPaths.some((full) => fs.lstatSync(full, { throwIfNoEntry: false }))
+    if ((oldPaths.some((full) => fs.lstatSync(full, { throwIfNoEntry: false })) && canRefreshRenamed(root, newName))
         || isShippedCopy(path.join(root, newName), PRE_STANDARD_SKILL_MD_SHA256)) names.add(newName);
   }
-  for (const [name, hashes] of Object.entries(RETIRED_SKILL_MD_SHA256)) {
-    if (isShippedCopy(path.join(root, name), hashes)) names.add(name);
-  }
   return names;
 }
 
-// `commandDir`: the project .claude/ whose DEPRECATED_FILES this install deletes, or null.
-function preflightSkills(roots, optionalNames = [], commandDir = null) {
-  const conflicts = [];
+function verifySkill(dest, name, manifest) {
+  const actual = fingerprint(dest);
+  const logicalName = name.replace(/[:\uF03A]/g, '-');
+  const source = path.join(DEVLYN_CORE_SKILLS.includes(logicalName)
+    ? path.join(CONFIG_SOURCE, 'skills') : OPTIONAL_SKILLS_SOURCE, logicalName);
+  const current = fs.existsSync(source) && fingerprint(source) === actual;
+  const historical = SKILL_HISTORY.skills[logicalName]?.includes(actual);
+  const hashes = RETIRED_SKILL_MD_SHA256[name.toLowerCase()] || PRE_STANDARD_SKILL_MD_SHA256;
+  const singleFile = isShippedCopy(dest, hashes);
+  if (!current && !historical && !singleFile && manifest[name] !== actual) {
+    throw new Error(manifest[name] ? 'modified contents (install manifest fingerprint mismatch)'
+      : fs.existsSync(source) || SKILL_HISTORY.skills[logicalName]?.length
+        ? 'fingerprint mismatch with known shipped copies'
+        : 'unknown installer ownership (no fingerprint history for this copy)');
+  }
+}
+
+// Discovery keeps its historical ownership boundary; cleanup below uses exact retired names.
+function deprecatedSkillPaths(root) {
+  return new Set(DEPRECATED_DIRS.flatMap((relative) => {
+    const name = path.basename(relative);
+    return [...legacySkillPaths(root, name.replace(/^devlyn-/, 'devlyn:')),
+      path.join(root, name.replace(/:/g, '-'))];
+  }));
+}
+
+function historicalSkill(dest) {
   try {
-    // Do not follow a commands link into another installation either.
-    const commands = commandDir && fs.lstatSync(path.join(commandDir, 'commands'), { throwIfNoEntry: false });
-    if (commands && !commands.isDirectory()) throw new Error('not a real directory');
-    const tracked = commandDir ? trackedPaths(path.join(commandDir, 'commands')) : [];
-    for (const relPath of commandDir ? DEPRECATED_FILES : []) {
-      const fullPath = path.join(commandDir, relPath);
-      const stat = fs.lstatSync(fullPath, { throwIfNoEntry: false });
-      if (!stat || (stat.isFile() && SKILL_HISTORY.commands[relPath].includes(contentHash(fullPath)))) continue;
-      const isTracked = tracked.some((file) => file.toLowerCase() === fullPath.toLowerCase());
-      conflicts.push(`${fullPath}: ${isTracked ? 'git-tracked; ' : ''}`
-        + (stat.isFile() ? 'fingerprint mismatch with known shipped copies' : 'link or special file'));
-    }
-  } catch (error) {
-    conflicts.push(`${path.join(commandDir, 'commands')}: ${error.message}`);
+    return SKILL_HISTORY.skills[path.basename(dest).toLowerCase().replace(/[:\uF03A]/g, '-')]?.includes(fingerprint(dest)) === true;
+  } catch {
+    // A link, unreadable or partial tree is not evidence of an install to refresh.
+    return false;
   }
+}
+
+function hasHistoricalRetiredSkill(root) {
+  return [...deprecatedSkillPaths(root)].some(historicalSkill);
+}
+
+// Validate only paths this run installs; removal-only names never refuse an install.
+function preflightSkills(roots, optionalNames = []) {
+  const conflicts = [];
   for (const root of roots) {
     try {
       // Do not follow an agent-directory or skill-root link into another installation.
@@ -520,19 +500,7 @@ function preflightSkills(roots, optionalNames = [], commandDir = null) {
             if (isTracked) throw new Error('missing contents; cannot verify installer ownership');
             continue;
           }
-          const actual = fingerprint(dest);
-          const logicalName = name.replace(/[:\uF03A]/g, '-');
-          const source = path.join(DEVLYN_CORE_SKILLS.includes(logicalName)
-            ? path.join(CONFIG_SOURCE, 'skills') : OPTIONAL_SKILLS_SOURCE, logicalName);
-          const current = fs.existsSync(source) && fingerprint(source) === actual;
-          const historical = SKILL_HISTORY.skills[logicalName]?.includes(actual);
-          const singleFile = isShippedCopy(dest, RETIRED_SKILL_MD_SHA256[name] || PRE_STANDARD_SKILL_MD_SHA256);
-          if (!current && !historical && !singleFile && manifest[name] !== actual) {
-            throw new Error(manifest[name] ? 'modified contents (install manifest fingerprint mismatch)'
-              : fs.existsSync(source) || SKILL_HISTORY.skills[logicalName]?.length
-                ? 'fingerprint mismatch with known shipped copies'
-                : 'unknown installer ownership (no fingerprint history for this copy)');
-          }
+          verifySkill(dest, name, manifest);
         } catch (error) {
           conflicts.push(`${dest}: ${isTracked ? 'git-tracked; ' : ''}${error.message}`);
         }
@@ -548,6 +516,7 @@ function preflightSkills(roots, optionalNames = [], commandDir = null) {
       + '\nFor tracked paths, also remove them from the Git index.'
       + '\nRerun the same command after resolving every conflict; -y does not bypass this check.');
   }
+  return {};
 }
 
 function assertCompleteSkillInstall(sourceSkillsDir, skillsDir, skillNames) {
@@ -658,16 +627,19 @@ function installLocalSkill(skillName, roots, written = [], installedSkills = new
 // copy under its name before the 4.0.0 rename goes only once the new one is complete.
 function installOptionalSkillInto(target, skillName, written, installedSkills) {
   const dest = path.join(target, skillName);
-  fs.rmSync(dest, { recursive: true, force: true });
-  installedSkills.set(dest, copyRecursive(path.join(OPTIONAL_SKILLS_SOURCE, skillName), dest, target));
-  assertCompleteSkillInstall(OPTIONAL_SKILLS_SOURCE, target, [skillName]);
-  written.push(dest);
-  const oldName = Object.keys(RENAMED_SKILLS).find((name) => RENAMED_SKILLS[name] === skillName);
-  for (const fullPath of oldName ? legacySkillPaths(target, oldName) : []) {
-    if (!fs.existsSync(fullPath)) continue;
-    fs.rmSync(fullPath, { recursive: true, force: true });
-    written.push(fullPath);
+  const stage = fs.mkdtempSync(path.join(target, '.devlyn-skill-'));
+  const stagedSkill = path.join(stage, skillName);
+  try {
+    const files = copyRecursive(path.join(OPTIONAL_SKILLS_SOURCE, skillName), stagedSkill, stage);
+    assertCompleteSkillInstall(OPTIONAL_SKILLS_SOURCE, stage, [skillName]);
+    fs.rmSync(dest, { recursive: true, force: true });
+    fs.renameSync(stagedSkill, dest);
+    installedSkills.set(dest, files.map((file) => path.join(dest, path.relative(stagedSkill, file))));
+    written.push(dest);
+  } finally {
+    fs.rmSync(stage, { recursive: true, force: true });
   }
+
 }
 
 // A 0.6.0-0.7.1 copy is one SKILL.md, the file that identifies it. A failed swap leaves
@@ -727,10 +699,6 @@ function installCoreSkills(skillsDir, written = [], installedSkills = new Map())
   fs.mkdirSync(skillsDir, { recursive: true });
   const previous = readInstallManifest(skillsDir);
   clearInstallMarker(skillsDir);
-  const removed = cleanupDeprecated(skillsDir, written);
-  if (removed > 0) {
-    log(`\n🧹 Cleaned up ${removed} deprecated file${removed > 1 ? 's' : ''}`, 'yellow');
-  }
   for (const skillName of DEVLYN_CORE_SKILLS) {
     const src = path.join(sourceSkillsDir, skillName);
     const dest = path.join(skillsDir, skillName);
@@ -741,7 +709,7 @@ function installCoreSkills(skillsDir, written = [], installedSkills = new Map())
     written.push(dest);
   }
   assertCompleteSkillInstall(sourceSkillsDir, skillsDir, DEVLYN_CORE_SKILLS);
-  const refreshed = retireRenamedSkills(skillsDir, written, installedSkills);
+  const refreshed = refreshRenamedSkills(skillsDir, written, installedSkills);
   writeInstallMarker(skillsDir, [...DEVLYN_CORE_SKILLS, ...refreshed], previous);
   written.push(path.join(skillsDir, DEVLYN_INSTALL_MARKER));
 }
@@ -866,6 +834,8 @@ function installClaudeCore(installedSkills = new Map()) {
   const settingsPath = path.join(targetDir, 'settings.json');
   const unmergeable = (reason) => new InstructionError(`Cannot merge .claude/settings.json: ${reason}. `
     + 'CLAUDE.md and .claude/ are unchanged; fix the file and rerun the same install command.');
+  const settingsStat = fs.lstatSync(settingsPath, { throwIfNoEntry: false });
+  if (settingsStat && !settingsStat.isFile()) throw unmergeable('not a regular file');
   let settings = {};
   if (fs.existsSync(settingsPath)) {
     try {
@@ -883,14 +853,6 @@ function installClaudeCore(installedSkills = new Map()) {
     throw unmergeable('env must be a JSON object');
   }
   const written = installClaudeInstructions() ? ['CLAUDE.md'] : [];
-  for (const relPath of DEPRECATED_FILES) {
-    const fullPath = path.join(targetDir, relPath);
-    if (fs.existsSync(fullPath)) {
-      fs.unlinkSync(fullPath);
-      log(`  ✕ ${relPath} (deprecated)`, 'dim');
-      written.push(`.claude/${relPath}`);
-    }
-  }
   installCoreSkills(skillsDir, written, installedSkills);
   if (updateProjectGitignore('.claude/skills/.devlyn-install.json')) written.push('.gitignore');
 
@@ -900,28 +862,17 @@ function installClaudeCore(installedSkills = new Map()) {
     settings.env = {};
     settingsChanged = true;
   }
-  if (!settings.env.ENABLE_PROMPT_CACHING_1H) {
+  if (!Object.prototype.hasOwnProperty.call(settings.env, 'ENABLE_PROMPT_CACHING_1H')) {
     settings.env.ENABLE_PROMPT_CACHING_1H = 'true';
     settingsChanged = true;
   }
-  const bashMaxTimeoutMs = Number.parseInt(settings.env.BASH_MAX_TIMEOUT_MS, 10);
-  if (!Number.isFinite(bashMaxTimeoutMs) || bashMaxTimeoutMs < 3600000) {
+  if (!Object.prototype.hasOwnProperty.call(settings.env, 'BASH_MAX_TIMEOUT_MS')) {
     settings.env.BASH_MAX_TIMEOUT_MS = '3600000';
     settingsChanged = true;
   }
-  // Remove exactly the retired Stop hook command, and its entry only when nothing else is left in it.
-  const retiredHook = (hook) => hook?.type === 'command' && hook.command === RETIRED_STOP_HOOK;
-  const stop = Array.isArray(settings.hooks?.Stop) ? settings.hooks.Stop : [];
-  for (let i = stop.length - 1; i >= 0; i--) {
-    const hooks = stop[i]?.hooks;
-    if (!Array.isArray(hooks) || !hooks.some(retiredHook)) continue;
-    stop[i].hooks = hooks.filter((hook) => !retiredHook(hook));
-    if (stop[i].hooks.length === 0 && Object.keys(stop[i]).length === 1) stop.splice(i, 1);
-    log('  ✕ settings.json Stop hook of the retired pipeline (removed)', 'dim');
-    settingsChanged = true;
-  }
+  settingsChanged = cleanRetiredSettings(settings) || settingsChanged;
   if (settingsChanged) {
-    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    replaceFile(settingsPath, JSON.stringify(settings, null, 2) + '\n');
     log('  → settings.json', 'dim');
     written.push('.claude/settings.json');
   }
@@ -936,9 +887,38 @@ function installClaudeCore(installedSkills = new Map()) {
   return written;
 }
 
+// Replace this directory entry, never a hardlink's other names.
+function replaceFile(file, text) {
+  const temp = `${file}.${crypto.randomUUID()}.tmp`;
+  try {
+    const mode = fs.lstatSync(file, { throwIfNoEntry: false })?.mode & 0o777;
+    fs.writeFileSync(temp, text, { flag: 'wx', mode: mode || 0o600 });
+    fs.renameSync(temp, file);
+  } finally {
+    fs.rmSync(temp, { force: true });
+  }
+}
+
+function cleanRetiredSettings(settings) {
+  let changed = false;
+  // Remove exactly the retired Stop hook command, and its entry only when nothing else is left in it.
+  const retiredHook = (hook) => hook?.type === 'command' && hook.command === RETIRED_STOP_HOOK;
+  const stop = Array.isArray(settings.hooks?.Stop) ? settings.hooks.Stop : [];
+  for (let i = stop.length - 1; i >= 0; i--) {
+    const hooks = stop[i]?.hooks;
+    if (!Array.isArray(hooks) || !hooks.some(retiredHook)) continue;
+    stop[i].hooks = hooks.filter((hook) => !retiredHook(hook));
+    if (stop[i].hooks.length === 0 && Object.keys(stop[i]).length === 1) stop.splice(i, 1);
+    log('  ✕ settings.json Stop hook of the retired pipeline (removed)', 'dim');
+    changed = true;
+  }
+  return changed;
+}
+
 // Shared user roots need one writer from ownership checks through the last addon write.
 // Never reap a foreign lock: PID reuse and slow installs make age/liveness unsafe evidence.
-function withUserSkillLocks(roots, action) {
+const heldSkillLocks = new Set();
+function withUserSkillLocks(roots, action, { existingOnly = false } = {}) {
   const locks = [];
   const createdDirs = [];
   try {
@@ -949,18 +929,22 @@ function withUserSkillLocks(roots, action) {
           const stat = fs.lstatSync(dir, { throwIfNoEntry: false });
           if (stat && !stat.isDirectory()) throw new Error(`not a real directory: ${dir}`);
         }
-        const missing = [];
-        for (let dir = root; !fs.existsSync(dir); dir = path.dirname(dir)) {
-          missing.push(dir);
-          if (path.dirname(dir) === dir) break;
+        if (existingOnly && !fs.lstatSync(root, { throwIfNoEntry: false })?.isDirectory()) return;
+        if (!existingOnly) {
+          const missing = [];
+          for (let dir = root; !fs.existsSync(dir); dir = path.dirname(dir)) {
+            missing.push(dir);
+            if (path.dirname(dir) === dir) break;
+          }
+          fs.mkdirSync(root, { recursive: true });
+          createdDirs.push(...missing);
         }
-        fs.mkdirSync(root, { recursive: true });
-        createdDirs.push(...missing);
         const token = crypto.randomBytes(16).toString('hex');
         const fd = fs.openSync(lock, 'wx', 0o600);
         try {
           fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, token }) + '\n');
           locks.push({ lock, token });
+          heldSkillLocks.add(root);
         } catch (error) {
           // A failed initial write may not leave parseable JSON; verify the open file's identity.
           const opened = fs.fstatSync(fd);
@@ -988,6 +972,7 @@ function withUserSkillLocks(roots, action) {
   } finally {
     const errors = [];
     for (const { lock, token } of locks.reverse()) {
+      heldSkillLocks.delete(path.dirname(lock));
       try {
         if (JSON.parse(fs.readFileSync(lock, 'utf8')).token === token) fs.unlinkSync(lock);
       } catch (error) {
@@ -1007,7 +992,7 @@ function withUserSkillLocks(roots, action) {
 }
 
 // Installs the targets in one scope; returns the skill roots written.
-function install(targets, global, optionalNames = []) {
+function install(targets, global, optionalNames = [], plan, afterInstall = () => {}) {
   // In the home folder CLAUDE.md, AGENTS.md (agents read a parent folder's too) and
   // .claude/settings.json would apply to every project. Same folder by identity, so a link or
   // another spelling of the path is caught too.
@@ -1022,23 +1007,149 @@ function install(targets, global, optionalNames = []) {
     const written = [];
     const installedSkills = new Map();
     if (!global) readProjectGitignore();
-    preflightSkills(roots, optionalNames,
-      !global && targets.includes('claude') ? path.dirname(skillRoots('claude', false)[0]) : null);
+    plan ??= preflightSkills(roots, optionalNames);
     // AGENTS.md first, whatever order the menu gave: a new CLAUDE.md holds the block only when AGENTS.md does not.
     for (const target of ['agents', 'claude'].filter((name) => targets.includes(name))) {
-      if (global) skillRoots(target, true).forEach((root) => installCoreSkills(root));
+      if (global) skillRoots(target, true).forEach((root) => installCoreSkills(root, [], installedSkills));
       else if (target === 'agents') written.push(...installAgentsProject(targets.includes('claude'), installedSkills));
       else written.push(...installClaudeCore(installedSkills));
     }
     for (const name of optionalNames) installLocalSkill(name, roots, written, installedSkills);
+    afterInstall();
     log(`\n✅ devlyn ${PKG.version} installed`, 'green');
     if (global) log('The principles block installs per project: run npx devlyn-cli in the project without --global.');
     noticeGlobalDrift(roots);
+    cleanupScope(global ? os.homedir() : projectDir(), global, written,
+      global ? [] : targets.map((target) => target === 'agents' ? 'AGENTS.md' : 'CLAUDE.md'));
     if (!global) noticeProjectChanges(written, installedSkills);
     return roots;
   });
 }
 
+// Cleanup visits existing paths in the command's scope; it never creates an install.
+function cleanupScope(base, global, written, activeInstructions = []) {
+  const warned = new Set();
+  let found = false;
+  const warning = (file, error) => {
+    if (!warned.has(file)) log(`Cannot clean up ${file}: ${error.message}`, 'yellow');
+    warned.add(file);
+  };
+  const attempt = (file, action) => {
+    try { return action(); } catch (error) { warning(file, error); return false; }
+  };
+  const realParents = (file) => {
+    let dir = base;
+    if (!fs.lstatSync(dir, { throwIfNoEntry: false })?.isDirectory()) return false;
+    for (const part of path.relative(base, path.dirname(file)).split(path.sep).filter(Boolean)) {
+      if (part === '..') return false;
+      dir = path.join(dir, part);
+      if (!fs.lstatSync(dir, { throwIfNoEntry: false })?.isDirectory()) return false;
+    }
+    return true;
+  };
+  const remove = (file) => attempt(file, () => {
+    if (!realParents(file) || !fs.lstatSync(file, { throwIfNoEntry: false })) return false;
+    found = true;
+    fs.rmSync(file, { recursive: true }); // lstat/realParents never follows a link; rm removes the link itself.
+    written.push(file);
+    log(`  ✕ ${path.relative(base, file)} (removed)`, 'dim');
+    return true;
+  });
+  const hash = (file) => crypto.createHash('sha256')
+    .update(fs.readFileSync(file).toString('latin1').replace(/\r\n/g, '\n'), 'latin1').digest('hex');
+  for (const dir of global ? ['.agents', '.codex', '.claude', '.grok'] : ['.agents', '.claude']) {
+    const root = path.join(base, dir, 'skills');
+    attempt(root, () => {
+      if (!realParents(root) || !fs.lstatSync(root, { throwIfNoEntry: false })?.isDirectory()) return;
+      const retiredRoot = dir === '.grok';
+      const clean = () => {
+        const marker = path.join(root, DEVLYN_INSTALL_MARKER);
+        let manifest;
+        if (fs.lstatSync(marker, { throwIfNoEntry: false })?.isFile()) {
+          try {
+            const data = JSON.parse(fs.readFileSync(marker, 'utf8'));
+            if (data && data.package === PKG.name && data.schemaVersion === 1
+                && (data.skills === undefined || (data.skills && typeof data.skills === 'object' && !Array.isArray(data.skills)))) manifest = data.skills || {};
+          } catch (error) {
+            if (!(error instanceof SyntaxError)) throw error;
+            // A malformed/foreign marker is not ownership evidence and stays in place.
+          }
+        }
+        const exact = new Set([...deprecatedSkillPaths(root),
+          ...Object.keys(RENAMED_SKILLS).flatMap((name) => legacySkillPaths(root, name))]
+          .map((file) => path.basename(file).toLowerCase()));
+        if (retiredRoot) for (const name of [...DEVLYN_CORE_SKILLS, ...Object.values(RENAMED_SKILLS)]
+          .filter((name) => name.startsWith('devlyn'))) exact.add(name);
+        const removed = new Set();
+        for (const name of fs.readdirSync(root)) {
+          const file = path.join(root, name);
+          attempt(file, () => {
+            const listed = manifest && Object.prototype.hasOwnProperty.call(manifest, name);
+            let owned = exact.has(name.toLowerCase()) || (retiredRoot && listed && /^devlyn[-:\uF03A]/i.test(name));
+            if (!owned && RETIRED_SKILL_MD_SHA256[name.toLowerCase()]) owned = isShippedCopy(file, RETIRED_SKILL_MD_SHA256[name.toLowerCase()]);
+            if (!owned && retiredRoot && name.toLowerCase() === '_shared') owned = historicalSkill(file);
+            if (!owned && retiredRoot && listed && fs.lstatSync(file).isDirectory()) {
+              try { owned = fingerprint(file) === manifest[name]; }
+              catch { /* Links or special files cannot prove a generic tree is an unedited copy. */ }
+            }
+            if (owned && remove(file)) removed.add(name);
+          });
+        }
+        if (retiredRoot && manifest) {
+          if (![...warned].some((file) => path.dirname(file) === root)) remove(marker);
+        } else if (manifest && [...removed].some((name) => Object.prototype.hasOwnProperty.call(manifest, name))) {
+          // Keep current markers accurate after cleaning a previously listed retired entry.
+          attempt(marker, () => {
+            const data = JSON.parse(fs.readFileSync(marker, 'utf8'));
+            for (const name of removed) delete data.skills[name];
+            replaceFile(marker, JSON.stringify(data, null, 2) + '\n');
+            written.push(marker);
+          });
+        }
+      };
+      if (heldSkillLocks.has(root)) clean();
+      else withUserSkillLocks([root], clean, { existingOnly: true });
+    });
+  }
+  const commands = path.join(base, '.claude', 'commands');
+  attempt(commands, () => {
+    if (!realParents(commands) || !fs.lstatSync(commands, { throwIfNoEntry: false })?.isDirectory()) return;
+    const names = new Set(DEPRECATED_FILES.map((file) => path.basename(file).toLowerCase()));
+    for (const name of fs.readdirSync(commands)) if (names.has(name.toLowerCase())) remove(path.join(commands, name));
+  });
+  for (const [name, hashes] of global ? [] : Object.entries(CLEANUP_HISTORY.files)) {
+    const file = path.join(base, name);
+    attempt(file, () => {
+      if (realParents(file) && fs.lstatSync(file, { throwIfNoEntry: false })?.isFile() && hashes.includes(hash(file))) remove(file);
+    });
+  }
+  const settingsFile = path.join(base, '.claude', 'settings.json');
+  attempt(settingsFile, () => {
+    if (!realParents(settingsFile) || !fs.lstatSync(settingsFile, { throwIfNoEntry: false })?.isFile()) return;
+    let settings;
+    try { settings = JSON.parse(fs.readFileSync(settingsFile, 'utf8').replace(/^\uFEFF/, '')); }
+    catch (error) { if (error instanceof SyntaxError) return; throw error; }
+    if (settings && typeof settings === 'object' && cleanRetiredSettings(settings)) {
+      found = true;
+      replaceFile(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+      written.push(settingsFile);
+      log('  ✕ .claude/settings.json retired entries (removed)', 'dim');
+    }
+  });
+  const instructions = global ? [] : ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md', '.cursorrules', '.windsurfrules', '.github/copilot-instructions.md'];
+  for (const name of instructions.filter((name) => !activeInstructions.includes(name))) {
+    const file = path.join(base, name);
+    attempt(file, () => {
+      if (!realParents(file) || !fs.lstatSync(file, { throwIfNoEntry: false })?.isFile()) return;
+      const evaluatorOnly = ['CLAUDE.md', 'AGENTS.md'].includes(name);
+      if (!updateInstructions(name, '', false, false, base, evaluatorOnly)) return;
+      found = true;
+      if (updateInstructions(name, '', false, true, base, evaluatorOnly)) written.push(file);
+    });
+  }
+  return found;
+}
+
 // Advisory only: a successful install stays successful when Git is unavailable or fails.
 function noticeProjectChanges(paths, installedSkills = new Map()) {
   if (!paths.length && !installedSkills.size) return;
@@ -1095,7 +1206,7 @@ function noticeProjectChanges(paths, installedSkills = new Map()) {
   }
   if (!pending.length && !ignored.length) return;
   const quote = (name) => /^[a-zA-Z0-9_./-]+$/.test(name) ? name : `'${name.replace(/'/g, "'\\''")}'`;
-  log('Commit these changes for teammates and /devlyn-ideate drains to use them:', 'yellow');
+  log('Optional — commit (and push) these changes if teammates or /devlyn-ideate task worktrees should use them:', 'yellow');
   if (ignored.length) log(`.gitignore hides ${ignored.length} installed files (${rule}).`, 'yellow');
   const commands = [];
   if (pending.length) commands.push(`git add -- ${pending.map(quote).join(' ')}`);
@@ -1107,7 +1218,7 @@ function noticeProjectChanges(paths, installedSkills = new Map()) {
 // A devlyn install in a user root this run does not refresh drifts and can shadow the
 // project's copy; name it without touching it.
 function noticeGlobalDrift(installed) {
-  for (const dir of ['.agents', '.codex', '.claude', '.grok']) {
+  for (const dir of ['.agents', '.codex', '.claude']) {
     const root = path.join(os.homedir(), dir, 'skills');
     const marker = path.join(root, DEVLYN_INSTALL_MARKER);
     if (installed.includes(root) || !fs.existsSync(marker)) continue;
@@ -1117,9 +1228,8 @@ function noticeGlobalDrift(installed) {
     } catch (error) {
       version = `(unreadable marker: ${error.message})`;
     }
-    if (dir !== '.grok' && version === PKG.version) continue;
-    // 4.0's Grok root; Grok now reads ~/.agents/skills, so --global never refreshes it.
-    const advice = dir === '.grok' ? 'delete it' : 'refresh it with --global, or delete it';
+    if (version === PKG.version) continue;
+    const advice = 'refresh it with --global, or delete it';
     log(`Global devlyn ${version} in ${root.replace(os.homedir(), '~')} — ${advice}.`, 'yellow');
   }
 }
@@ -1163,15 +1273,16 @@ function update() {
   const projectRoots = targets.flatMap((target) => skillRoots(target, false));
   const roots = [...userRoots, ...projectRoots];
   if (!roots.length) {
+    const written = [];
+    const userCleanup = cleanupScope(os.homedir(), true, written);
+    const projectCleanup = (home?.dev !== here.dev || home?.ino !== here.ino) && cleanupScope(projectDir(), false, written);
+    if (userCleanup || projectCleanup) { noticeProjectChanges(written.filter((file) => !path.isAbsolute(file) || file.startsWith(projectDir() + path.sep))); return; }
     throw new InstructionError(['No devlyn install here to update. Run npx devlyn-cli to install.', ...linkNotices].join('\n'));
   }
 
   return withUserSkillLocks(userRoots, () => {
-    if (targets.length) {
-      readProjectGitignore();
-      preflightSkills(projectRoots, [], targets.includes('claude') ? path.dirname(skillRoots('claude', false)[0]) : null);
-    }
-    preflightSkills(userRoots);
+    if (targets.length) readProjectGitignore();
+    const plan = preflightSkills(roots);
     // Ownership preflight has already refused unreadable or invalid markers.
     const current = PKG.version.split('.').map(BigInt);
     const newer = roots.flatMap((root) => {
@@ -1194,12 +1305,18 @@ function update() {
         + newer.join('\n') + '\nRun npx devlyn-cli@latest update.');
     }
 
-    userRoots.forEach((root) => installCoreSkills(root));
-    if (targets.length) install(targets, false);
+    userRoots.forEach((root) => installCoreSkills(root, [], new Map()));
+    if (targets.length) install(targets, false, [], plan, () => cleanupScope(os.homedir(), true, []));
     else {
+      cleanupScope(os.homedir(), true, []);
       log(`\n✅ devlyn ${PKG.version} installed`, 'green');
       noticeGlobalDrift(userRoots);
     }
+    if (!targets.length && (home?.dev !== here.dev || home?.ino !== here.ino)) {
+      const written = [];
+      cleanupScope(projectDir(), false, written);
+      noticeProjectChanges(written);
+    }
   });
 }
 

package/bin/instructions.js

@@ -3,6 +3,7 @@ const path = require('path');
 const crypto = require('crypto');
 const { Lexer } = require('marked');
 const legacyTemplates = require('./instruction-templates.json');
+const cleanupHistory = require('./cleanup-history.json');
 
 const BEGIN = '<!-- devlyn:instructions:begin';
 const END = '<!-- devlyn:instructions:end -->';
@@ -147,7 +148,7 @@ function importsAgentsMd(text) {
 
 function customInstructions(text, name, template, managed = false) {
   const known = new Set([
-    ...legacyTemplates.paragraphs[name],
+    ...(legacyTemplates.paragraphs[name] || []),
     ...instructionParagraphs(template).map((p) => p.key),
   ]);
   const bom = text.startsWith('\uFEFF') ? '\uFEFF' : '';
@@ -169,6 +170,22 @@ function customInstructions(text, name, template, managed = false) {
   return bom + paragraphs.filter((_, index) => keep.has(index)).map((p) => p.text).join('');
 }
 
+// Only the complete appended bytes are owned, including the separator added by old installers.
+// A heading inside a fenced example is not an installed instruction block.
+function removeEvaluatorBlocks(text) {
+  const headings = new Set(instructionParagraphs(text).filter((p) => p.level === 1).map((p) => p.start));
+  const ranges = [];
+  for (const match of text.matchAll(/\r?\n\r?\n---\r?\n\r?\n(?=# Devlyn Agent Instructions\r?\n)/g)) {
+    if (!headings.has(match.index + match[0].length)) continue;
+    for (const template of cleanupHistory.evaluators) {
+      const end = matchedEnd(text, match.index, template);
+      if (end !== null) { ranges.push({ start: match.index, end }); break; }
+    }
+  }
+  for (const { start, end } of ranges.reverse()) text = text.slice(0, start) + text.slice(end);
+  return text;
+}
+
 // Devlyn defaults in an instruction file: a managed block, or stock paragraphs of a template
 // that a release before managed blocks copied in whole (the evidence migration replaces).
 function holdsDevlynDefaults(name, text) {
@@ -196,22 +213,23 @@ function retainFile(file, bytes) {
 
 // `withBlock` false removes the devlyn defaults the file holds, keeping everything else. `write` false writes nothing
 // and returns whether the file needs an update, a merge included.
-function updateInstructions(name, initial = '', withBlock = true, write = true) {
-  const projectPackage = path.join(process.cwd(), 'package.json');
-  if (fs.existsSync(path.join(process.cwd(), 'bin', 'devlyn.js')) && fs.existsSync(projectPackage)
+function updateInstructions(name, initial = '', withBlock = true, write = true, directory = process.cwd(), evaluatorOnly = false) {
+  const projectPackage = path.join(directory, 'package.json');
+  if (fs.existsSync(path.join(directory, 'bin', 'devlyn.js')) && fs.existsSync(projectPackage)
       && JSON.parse(fs.readFileSync(projectPackage, 'utf8'))?.name === 'devlyn-cli') {
     console.log(`  → Skipping ${name}; shipped instruction template in devlyn-cli source checkout`);
     return false;
   }
-  const templatePath = path.join(__dirname, '..', name);
-  const template = fs.readFileSync(templatePath, 'utf8');
+  const templateName = path.basename(name);
+  const templatePath = path.join(__dirname, '..', templateName);
+  const template = ['CLAUDE.md', 'AGENTS.md'].includes(templateName) ? fs.readFileSync(templatePath, 'utf8') : '';
   if (template.includes(BEGIN) || template.includes(END)) {
     throw new Error(`Packaged instruction template contains managed markers: ${templatePath}`);
   }
-  const dest = path.join(process.cwd(), name);
+  const dest = path.join(directory, name);
   const stat = fs.lstatSync(dest, { throwIfNoEntry: false });
-  const sourceStat = fs.statSync(templatePath);
-  if (stat?.isFile() && stat.dev === sourceStat.dev && stat.ino === sourceStat.ino) {
+  const sourceStat = template ? fs.statSync(templatePath) : null;
+  if (stat?.isFile() && stat.dev === sourceStat?.dev && stat.ino === sourceStat?.ino) {
     console.log(`  → Using source ${name}; packaged template left unchanged`);
     return false;
   }
@@ -227,15 +245,16 @@ function updateInstructions(name, initial = '', withBlock = true, write = true)
   } catch (cause) {
     throw new InstructionError(`${name} must be UTF-8; original preserved. Convert its encoding and rerun installation.`, { cause });
   }
+  current = removeEvaluatorBlocks(current);
   const eol = current.match(/\r?\n/)?.[0] || '\n';
   const block = managedBlock(template, eol);
   const inserted = withBlock ? block : '';
-  const recovery = path.join(process.cwd(), '.devlyn', 'instructions');
+  const recovery = path.join(directory, '.devlyn', 'instructions');
   const conflict = (reason) => {
     if (!write) return true;
-    const incoming = path.join(recovery, `${name}.${digest(block)}.incoming`);
-    const backup = path.join(recovery, `${name}.${digest(before)}.backup`);
-    const guide = path.join(recovery, `${name}.${digest(before)}.${digest(block)}.merge.md`);
+    const incoming = path.join(recovery, `${encodeURIComponent(name)}.${digest(block)}.incoming`);
+    const backup = path.join(recovery, `${encodeURIComponent(name)}.${digest(before)}.backup`);
+    const guide = path.join(recovery, `${encodeURIComponent(name)}.${digest(before)}.${digest(block)}.merge.md`);
     retainFile(backup, before);
     retainFile(incoming, Buffer.from(block));
     retainFile(guide, Buffer.from(`# Merge ${name}\n\n`
@@ -252,7 +271,9 @@ function updateInstructions(name, initial = '', withBlock = true, write = true)
       + `Installation is incomplete; earlier selected agents may already have been updated.`);
   };
   let content;
-  if (current.includes(BEGIN) || current.includes(END)) {
+  if (evaluatorOnly) {
+    content = current;
+  } else if (current.includes(BEGIN) || current.includes(END)) {
     const starts = [...current.matchAll(/^\uFEFF?<!-- devlyn:instructions:begin sha256=([a-f0-9]{64}) -->\r?\n/gm)];
     const ends = [...current.matchAll(/^<!-- devlyn:instructions:end -->(?:\r?\n|$)/gm)];
     if (starts.length !== 1 || ends.length !== 1
@@ -265,29 +286,27 @@ function updateInstructions(name, initial = '', withBlock = true, write = true)
     if (end.index < bodyStart) return conflict('reversed managed markers');
     const previous = current.slice(bodyStart, end.index);
     const custom = digest(normalize(previous)) === start[1] ? ''
-      : customInstructions(previous, name,
+      : customInstructions(previous, templateName,
         'Project-specific instructions outside this managed block take precedence over these defaults.\n\n' + template, true);
     const after = current.slice(end.index + end[0].length);
     content = current.slice(0, start.index + (start[0].startsWith('\uFEFF') ? 1 : 0))
       + custom + (custom ? eol : '') + inserted + after;
-    // A block removed from the end takes along the blank lines that set it apart.
-    if (!inserted && !after) content = content.replace(/(\r?\n)(?:\r?\n)+$/, '$1');
   } else {
     const normalized = normalize(template);
     const bodyStart = normalized.indexOf('## North Star\n');
     const preamble = normalized.slice(0, bodyStart);
     const body = normalized.slice(bodyStart);
     const ranges = legacyRanges(current, [
-      { length: normalized.length, sha256: digest(normalized),
-        ...(bodyStart > 0 ? { preamble, body: { length: body.length, sha256: digest(body) } } : {}) },
-      ...(legacyTemplates[name] || []),
+      ...(normalized ? [{ length: normalized.length, sha256: digest(normalized),
+        ...(bodyStart > 0 ? { preamble, body: { length: body.length, sha256: digest(body) } } : {}) }] : []),
+      ...(legacyTemplates[templateName] || []),
     ]);
     if (ranges.length === 1 && !LEGACY.test(current.slice(0, ranges[0].start)
         + ranges[0].custom + current.slice(ranges[0].end))) {
       const { start, end, custom } = ranges[0];
       content = current.slice(0, start) + custom + inserted + current.slice(end);
     } else {
-      const custom = customInstructions(current, name, template);
+      const custom = customInstructions(current, templateName, template);
       content = custom + (custom && inserted ? eol + eol : '') + inserted;
     }
   }
@@ -295,7 +314,7 @@ function updateInstructions(name, initial = '', withBlock = true, write = true)
   if (bytes.equals(before)) return false;
   if (!write) return true;
   if (exists) {
-    const backup = path.join(recovery, `${name}.${digest(before)}.backup`);
+    const backup = path.join(recovery, `${encodeURIComponent(name)}.${digest(before)}.backup`);
     retainFile(backup, before);
     console.log(`  → Saved previous ${name}: ${backup}`);
   }
@@ -306,11 +325,12 @@ function updateInstructions(name, initial = '', withBlock = true, write = true)
     if (fs.existsSync(dest) !== exists || (exists && !fs.readFileSync(dest).equals(before))) {
       throw new InstructionError(`${name} changed during installation; preserved it. Rerun installation.`);
     }
-    fs.renameSync(temp, dest);
+    if (!withBlock && content === '') fs.unlinkSync(dest);
+    else fs.renameSync(temp, dest);
   } finally {
     if (fs.existsSync(temp)) fs.unlinkSync(temp);
   }
-  console.log(!exists ? `  → Created ${name}`
+  console.log(!withBlock && content === '' ? `  ✕ ${name} (removed)` : !exists ? `  → Created ${name}`
     : `  → ${withBlock ? 'Updated Devlyn defaults in' : 'Removed Devlyn defaults from'} ${name}; project-specific instructions preserved`);
   return true;
 }

package/bin/skill-history.json

@@ -1,5 +1,5 @@
 {
-  "source": "skills: config/skills/* and optional-skills/* trees from every first-parent HEAD commit touching those paths and every local tag, derived by scripts/update-skill-history.js using bin/skill-ownership.js normalization (LF, install-path stamps, OS metadata and Python bytecode); deprecated commands: commands/ and optional-commands/*/ files of devlyn-cli 0.0.1-0.5.8 (every published version that shipped them), LF-normalized SHA-256",
+  "source": "skills: config/skills/* and optional-skills/* trees from every first-parent HEAD commit touching those paths and every local tag, derived by scripts/update-skill-history.js using bin/skill-ownership.js normalization (LF, install-path stamps, OS metadata and Python bytecode)",
   "skills": {
     "_shared": [
       "015eea12cc07cfb9eb318c30855f6deacb5bf43bd508a511dffd2e48c9d82964",
@@ -619,74 +619,5 @@
       "711cd2633df2062104f12d50037a07a1012a90ab18c422cb5fdf665fcb9dc987",
       "d6a98c105a0d1952de90c39ca0734cb70cbdd116e6b4a4d45507d796bd2a9e88"
     ]
-  },
-  "commands": {
-    "commands/devlyn.handoff.md": [
-      "91d143c6305e95e4af6992eda0d127e94a394c2e91a2d409b4d41ca03c23f470"
-    ],
-    "commands/devlyn.clean.md": [
-      "918c6ae867c57a4d9748237adae0df8c78a1447c7c028a0af988b59a5fbb0d9a"
-    ],
-    "commands/devlyn.design-system.md": [
-      "f81166b5ba08d9ee1f5cff33c911ea387e5cb50141a9712a96fc4434c60a673f"
-    ],
-    "commands/devlyn.design-ui.md": [
-      "0496a6b2dd8c6bb0474b71ef9a319a6b95bb76972d0f07a01c33f8860fe83dfb",
-      "4e2aafcc0de6ce7f3022a353aaa9fb4330e76a50a91ab970b9b9a0f192f9f1f2"
-    ],
-    "commands/devlyn.discover-product.md": [
-      "a609401d29cd2bdad7a48c7c8f096b442fe03a17c6b2c3151936c47b4a16e6c6",
-      "1e66aa35bf300ec6167e1b888f43a92ebd9e60d501397ff0334c9a7809d433f5"
-    ],
-    "commands/devlyn.evaluate.md": [
-      "8f17ccc639d54adab24c49dcf471376bab97511675d00554056a4c1f67a14115"
-    ],
-    "commands/devlyn.feature-spec.md": [
-      "d442ed7ae8d14a255c37f1b120b758f69794be88e2970a8a0c0e51519344b6c7"
-    ],
-    "commands/devlyn.implement-ui.md": [
-      "a8d0813781b2f7a3df5a4751c92755bf7c84c53428cf63cea34c965939b8c478"
-    ],
-    "commands/devlyn.product-spec.md": [
-      "7a92d2df2586b44e2c4d9182eeb3d61f7adc2a13bed4d2cd26abcfe086585895"
-    ],
-    "commands/devlyn.recommend-features.md": [
-      "2b92523017e1da10c299dafb19d84736de5084b5b46693de7fd2d6df51dc56b4"
-    ],
-    "commands/devlyn.resolve.md": [
-      "48c0c3ee553f87f1f0733190effc7220c01c82837a5300ef68c9ffdf30c5d3a1",
-      "24595766e1a81a1fcacb78261b03c3665bc686bcac8b1805d1c4db379584879f",
-      "eaad5354cfc20ed378ffd2a2e1ca6bade1310bd2a47ab93e5942e9599c3ba9a8"
-    ],
-    "commands/devlyn.review.md": [
-      "55888e08bf31ead1d359f218277cfa7efc3c6cb0f96fadc665d5a2406ff115d3",
-      "22f532f587f6d2fbf2662e38d5073b85a030141573f86d92ad40b9d292836fb7",
-      "7f9ce1db4ffd3cdaf9fd949e4b07de04e0931c91cd846d4ab220ff6114a45b17",
-      "3a511fc678e599ff4b4c37fd9191399a599e1ba9ea9c40fc4afcbe29cb188d2b"
-    ],
-    "commands/devlyn.team-design-ui.md": [
-      "02485911588e9f52afb5a5082fd7804ee7a41bad44323960a2afe1a16a49d628"
-    ],
-    "commands/devlyn.team-resolve.md": [
-      "8f11fa0c3203c0dd5bf09b5243dcff5968a36275682c54b3a012262fc545859a",
-      "09fc163d34dfe8906dd8d22501a028bfbbad639499acab01e5e60f06fc520382",
-      "ccfc5083813ee50d407109616ccbc2509aa7526316cebbf7a271537abdfff3b7",
-      "72f66be3c4c27a46e76d56d13a0d381880c054a03243188f98da2faf6dc77295",
-      "54c52c3f27998998ed55cc648d071bbb10444761b819c59ed118b795596a4aee"
-    ],
-    "commands/devlyn.team-review.md": [
-      "58b36cfe2749968d697d486a104a1b139e4312730b0ac2933550634f6ece48db",
-      "7e5c2d93a23d51af7939dae29c70095dbd8a4a681cc06d4d578f2de29df346a3",
-      "c8e145955a303141af4082dae174e3b3f1681e4c9698e25ae337eadd31fb883b"
-    ],
-    "commands/devlyn.update-docs.md": [
-      "86945afccf24762a88d26eef3703fbf6c5a90a3343fd3de72a9cb26b6f62d3b5"
-    ],
-    "commands/devlyn.pencil-pull.md": [
-      "dfdd3d19ca676558bfa2bb3ce398181b0a081ab88d1feaf69c54c706a9671631"
-    ],
-    "commands/devlyn.pencil-push.md": [
-      "5f2e8b29609cbb2af72941579823bec598265ebf29cd3a375d6aa47d95b74354"
-    ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "4.2.18",
+  "version": "4.2.20",
   "description": "Loop & harness engineering for AI coding agents (Claude Code, Codex, and any AGENTS.md-driven agent) — core engineering principles for CLAUDE.md/AGENTS.md and a loop designer that splits one intent into tasks agents drain hands-free",
   "homepage": "https://github.com/fysoul17/devlyn-cli#readme",
   "bin": {